Configure OIDC authentication and authorization-API Gateway(API Gateway)-阿里云帮助中心

By integrating with your enterprise's authentication and authorization system using the OIDC (OpenID Connect) protocol, you can achieve unified authentication and authorization management for your internal services. This approach simplifies the authentication process and eliminates repetitive integration work. Cloud-native API Gateway provides centralized authentication and authorization. This enhances system security and allows for more flexible security policy configuration. OIDC integration also enables single sign-on (SSO), letting you access multiple services with a single login.

Prerequisites

You have a unified authorization server that supports the standard OIDC (OpenID Connect) protocol.

Background information

As the entry point for external access to your internal services, the API gateway must perform authentication and authorization on incoming requests to ensure the security of your backend services. Enterprises typically build a unified authentication and authorization system. Cloud-native API Gateway supports integration with your self-managed system through the OIDC protocol. This enables unified authentication and authorization for all connected internal services, avoiding the need to integrate each service with the authentication and authorization system individually.

OIDC authentication

OIDC (OpenID Connect) is a security authentication mechanism that allows third-party applications to connect to an identity provider to obtain end user information. The identity provider then securely returns this information to the application. OIDC extends the OAuth 2.0 protocol by adding an ID Token field. The ID Token, encapsulated in the JWT (JSON Web Token) format, provides basic user identity information. The ID Token is self-contained and tamper-proof, allowing it to be securely transmitted to and easily verified by third-party applications.

A typical OIDC flow involves the following four roles:

client: An application that provides services directly to the end user.
authorization server: An OpenID provider that issues ID Tokens to third-party applications for authentication.
business server: A server that provides business services.
end user: The resource owner who grants access to their information.

The workflow is as follows:

The client sends an authentication request to the authorization server.
The end user grants authorization on the authentication page, typically by logging in with a username and password.
The authorization server validates the authentication request and returns an authorization code to the client.
The client sends a request to a callback endpoint on the business server, including the authorization code.
The business server requests a token from the authorization server. The request includes the authorization code, client ID, and client secret.
The authorization server validates the request and returns an ID Token.
After successful authentication, the business server returns the ID Token to the client.
The client makes a business request that includes the ID Token.
The business server validates the ID Token and returns a business response.

Gateway OIDC authentication flow

In the preceding OIDC authentication flow, if you have multiple business servers, such as a user service and an order service, each service must implement its own authentication and authorization logic. This includes validating requests and integrating with the authorization server. By using the OIDC authentication feature of Cloud-native API Gateway, you can centralize authentication and authorization at the gateway level.

The workflow is as follows:

The client sends an authentication request to the gateway.
The gateway forwards the authentication request to the authorization server.
The authorization server validates the credentials in the request, such as the username and password. After successful validation, it returns an authorization code to the gateway.
The gateway returns a response containing the authorization code to the client.
The client sends a request to a callback endpoint on the gateway, including the authorization code.
The gateway requests a token from the authorization server. The request includes the authorization code, client ID, and client secret.
The authorization server validates the request and returns an ID Token.
After successful authentication, the gateway returns a response containing the ID Token to the client.
The client sends a business request to the gateway, including the ID Token. The gateway verifies that the request contains a valid ID Token.
After validating the client's business request, the gateway forwards the request to the business server.
The business server processes the request and returns a response.
The gateway forwards the business response to the client.

Throughout this authentication and authorization process, Cloud-native API Gateway validates requests. If a request is invalid, the gateway redirects the end user to a login page and acts as a proxy to the authorization server to handle the login process. This process makes the authorization server transparent to the backend business server.

Create an authentication and authorization rule

Log on to the API Gateway console.
In the left-side navigation pane, click Cloud-native API Gateway > Instance. In the top navigation bar, select a region.
On the Instance page, click the name of the target gateway instance.
In the left-side navigation pane, choose Security Management > Global Authentication.

In the upper-left corner of the page, click Create Authentication. Configure the gateway authentication parameters and click OK.

The following table describes the parameters for OIDC authentication.

Parameter	Description
Enable	Specifies whether to enable authentication for the Cloud-native API Gateway instance.
Authentication Name	The custom name for the authentication rule.
Authentication Type	Select OIDC.
Domain Name	The domain name to which the authentication rule applies.
Issuer	The issuer URL of the authorization server.
Redirect URL	The URL where the end user is redirected after successful authorization. This URL must match the one configured in your OIDC identity provider. Important The URL must be in the format`http(s)://yourdomain/path` and the path must be`/oauth2/callback`.
Client ID	The client ID of your application registered with the identity provider.
Client secret	The client secret of your application registered with the identity provider.
Cookie domain	The domain for the session cookie. After the end user is authenticated, the cookie is sent to this domain to maintain the login session. For example, if you set the cookie domain to`a.example.com`, the cookie is sent to the `a.example.com` domain. If you set the cookie domain to`.example.com`, the cookie is sent to all subdomains of `example.com`.
Cookie secret	A secret used to digitally sign the session cookie to prevent it from being tampered with.
Scope	Specify the scopes of authorization. You can add multiple scopes, separated by semicolons (;).
Authorization	Select the authorization mode. You can choose either Whitelist Mode or Blacklist Mode. whitelist: Requests to hosts and paths in the whitelist can bypass authentication. All other requests require it. blacklist: Only requests to hosts and paths in the blacklist require authentication. All other requests can pass through without it. Click Rule Condition to set the request domain names and paths. Domain Name: The request host. Path: The request API path.

Authentication and authorization details

Log on to the API Gateway console.
In the left-side navigation pane, click Cloud-native API Gateway > Instance. In the top navigation bar, select a region.
On the Instance page, click the name of the target gateway instance.
In the left-side navigation pane, choose Security Management > Global Authentication.
On the Global Authentication page, click an authentication rule name, or click Description in the Actions column. You can view the current Authentication Configuration and Authorization Information.

The details page contains three sections. Basic Information displays the name and source. Authentication Configuration displays fields such as issuer, client ID, Cookie domain, redirect URL, client secret, and scope. Authorization Information displays the current authorization mode (whitelist or blacklist). Multiple rule conditions have an OR relationship. Multiple matching items within a single rule condition have an AND relationship.

In the Authorization Information section, you can click Create Authorization. In the dialog box that appears, enter a Request Domain Name and Request Path, select a Match Mode, then click OK to add a new authorization rule.

Verify the result

Return to the Global Authentication page to view the list of authentication rules. If the rule you created is displayed, the rule was created successfully.

Related operations

You can also perform the following operations to manage gateway authentication:

Enable authentication: On the Global Authentication page, find the target authentication rule and click Enable in the Actions column to apply the authentication rule.
Disable authentication: On the Global Authentication page, find the target authentication rule and click Close in the Actions column to disable the gateway authentication rule.
Edit authentication: On the Global Authentication page, find the target authentication rule and click Edit in the Actions column to edit the gateway authentication rule.
Delete authentication: On the Global Authentication page, find the target authentication rule and click Delete in the Actions column to delete the gateway authentication rule.

Note

The delete operation can be performed only if authentication is disabled.

References

For information about other authentication mechanisms, see Global authentication.