SylviaBABY commented on code in PR #1187: URL: https://github.com/apache/apisix-website/pull/1187#discussion_r913323171
########## website/blog/2022/07/04/apisix-integrates-with-hydra.md: ########## @@ -0,0 +1,286 @@ +--- +title: "APISIX integrates with Ory Hydra" +authors: + - name: "Fei Han" + title: "Technical Writer" + url: "https://github.com/hf400159"; + image_url: "https://github.com/hf400159.png"; +keywords: +- Apache APISIX +- API Gateway +- Authentication +- Hydra +- Openid connect +- OIDC +description: This article describes the API gateway Apache APISIX for centralized authentication via the OpenID Connect plugin Hydra integration. +tags: [Authentication] +--- + +> This article describes how Apache APISIX integrates with Ory Hydra to implement centralized authentication. + +<!--truncate--> + +## Background Information + +### Apache APISIX + +[Apache APISIX](https://github.com/apache/apisix) is an open source cloud native API gateway. As an API gateway, it has the characteristics of dynamic, real-time, and high performance. It provides rich traffic management functions such as load balancing, dynamic upstream, gray-scale publishing, service fusing, identity authentication and observability. You can use APISIX to handle the traditional north-south traffic and the east-west traffic between services. It can also be used as a K8s ingress controller. Thanks to the full dynamic design of APISIX, configuration changes can be made at any time without restarting the service. + +The `openid-connect` plugin of APISIX supports the OpenID Connect protocol. Users can use this plugin to allow Apache APISIX to connect with many authentication service providers and deploy it in enterprises as a centralized authentication gateway. + +### ORY Hydra + +[Ory Hydra](https://github.com/ory/hydra) is one of the identity providers that supports the OAuth 2.0 and OpenID Connect protocols, based on the OAuth 2.0 authorization framework and the Open ID Connect Core 1.0 framework, with both open source and cloud native features. It can be integrated with any login system, and through OAuth 2.0 Access, Refresh, and ID Tokens, third parties can easily access your API, enabling users to interact with any application anytime, anywhere. + +Ory Hydra is written in Go language and provides SDKs for almost all languages, including Dart, .NET, Go, Java, PHP, Python, Ruby, Rust, and Typescript. It works with any login system, and the login experience can be easily customized. + +## Introduction + +OpenID is a centralized authentication mode, and it is a decentralized identity authentication system. The advantage of using OpenID is that users only need to register and log in on one OpenID identity provider's website and use one account and password information to access different applications. + +With the `openid-connect` plugin supported by APISIX, we can integrate with authenticators supporting the OpenID Connect protocol. For example: Ory Hydra. For more information, please refer to: [Centralized Identity Authentication](https://apisix.apache.org/blog/2021/08/25/using-the-apache-apisix-openid-connect-plugin-for-centralized-authentication/#what-is-authentication). + +One of the biggest advantages of Ory Hydra is that it implements the OAuth and OpenID Connect standards instead of forcing you to use "Hydra user management" (login, logout, profile management, registration), a specific template engine, or a predefined front end. + +It allows to use the authentication mechanisms required by your program (token-based 2FA, SMS 2FA, etc.) and implement user management and login in your technology stack. Of course, you can also use existing solutions, such as [authboss](https://github.com/go-authboss/authboss). It gives you all the great features of OAuth 2.0 and OpenID Connect while being minimally intrusive to your business logic and technology stack. + +OAuth 2.0 can be used in many environments for various purposes. This list might help you decide if OAuth 2.0 and Hydra are the right fit for a use case: + +1. enable third-party solutions to access your APIs. +2. be an Identity Provider like Google, Facebook, or Microsoft: OpenID Connect, and thus Hydra is a perfect fit. +3. enable your browser, mobile, or wearable applications to access your APIs: Running an OAuth2 Provider can work great for this. You don't have to store passwords on the device and can revoke access tokens at any time. +4. you want to limit what type of information your backend services can read from each other. For example, the comment service should only be allowed to fetch user profile updates but shouldn't be able to read user passwords. + +## Operation steps + +Next, I will show you how APISIX integrates with Hydra using a real example. In this example, Docker will be used to running the required environment. Please install [Docker](https://docs.docker.com/engine/install/) before doing this. + +### Step 1: Create and deploy the database + +For quick deployment of the test environment, we will use Docker to run PostgreSQL as Hydra's database. Using Docker to run the database in production is not recommended. + +```shell +docker network create hydraguide && \ +docker run \ + --network hydraguide \ + --name ory-hydra-example--postgres \ + -e POSTGRES_USER=hydra \ + -e POSTGRES_PASSWORD=secret \ + -e POSTGRES_DB=hydra \ + -d postgres:9.6 +``` + +The above command will create a network named hydraguide and start a Postgres instance named ory-hydra-example--postgres which creates the database hydra, the user hydra, and the user password secret. + +### Step 2: Deploy Hydra + +This step will map `4444` to `5444` and `4445` to `5445` ports, please make sure that these ports are not used. + +1. The system key can only be set for the new database, and does not support key rotation. This key is used to encrypt the database and needs to be set to the same value each time the process restarts. You can use `/dev/urandom` to generate keys. But make sure that the key must be the same when you define it. For example, you can store the value somewhere: + +```shell +export SECRETS_SYSTEM=$(export LC_CTYPE=C; cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1) +``` + +Set Hydra's database URL to point to your Postgres instance by configuring an environment variable. + +```shell +export DSN=postgres://hydra:secret@ory-hydra-example--postgres:5432/hydra?sslmode=disable +``` + +2. Ory Hydra does not migrate SQL automatically, so you need to manually perform the database migration. + +```shell +docker pull oryd/hydra:v1.10.6 && \ +docker run -it --rm \ + --network hydraguide \ + oryd/hydra:v1.10.6 \ + migrate sql --yes $DSN +``` + +3. Run the Hydra server with the following command. For more information, please refer to [deploy-ory-hydra](https://www.ory.sh/docs/hydra/configure-deploy#deploy-ory-hydra). + +```shell +docker run -d \ + --name ory-hydra-example--hydra \ + --network hydraguide \ + -p 5444:4444 \ + -p 5445:4445 \ + -e SECRETS_SYSTEM=$SECRETS_SYSTEM \ + -e DSN=$DSN \ + -e URLS_SELF_ISSUER=https://localhost:5444/ \ + -e URLS_CONSENT=http://localhost:9020/consent \ + -e URLS_LOGIN=http://localhost:9020/login \ + oryd/hydra:v1.10.6 serve all +``` + +You can view Hydra logs using the following command: + +```shell +docker logs ory-hydra-example--hydra +``` + +:::note + +If the Hydra password is not specified, you can find the password information in the log. If you forget your password, you will not be able to restart Hydra. + +::: + +You can also use the following commands to view Hydra related introductions and operation commands. + +```shell +docker run -it --rm --entrypoint hydra oryd/hydra:v1.10.6 help serve +``` + +### Step 3: Deploy login and authentication programs + +Login Provider and Consent Provider can be two separate web services. Hydra provides sample programs that combine both functions in one application. Next, we'll deploy the application using Docker. + +```shell +docker pull oryd/hydra-login-consent-node:v1.10.6 && \ +docker run -d \ + --name ory-hydra-example--consent \ + -p 9020:3000 \ + --network hydraguide \ + -e HYDRA_ADMIN_URL=https://ory-hydra-example--hydra:4445 \ + -e NODE_TLS_REJECT_UNAUTHORIZED=0 \ + oryd/hydra-login-consent-node:v1.10.6 +``` + +You can check if the program is working properly with the command: Review Comment: ```suggestion You can use the following command to check whether the program runs normally: ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@apisix.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
![https://github.com/hf400159.png"](https://github.com/hf400159.png"){kind=link}