Configure OIDC for identity authentication and access control - Microservices Engine

Cloud-native Gateway integrates with OpenID Connect (OIDC) to provide centralized authentication and authorization for your internal services. This eliminates repetitive per-service integration, enables single sign-on (SSO), and offers flexible security policy configurations.

Prerequisites

You must have a unified authentication service that supports the standard OIDC protocol.

Background information

As a control point for external access, a gateway must authenticate incoming requests to protect internal services. Enterprises typically maintain a unified authentication system. Cloud-native Gateway connects to such systems through the OIDC protocol, providing unified authentication for all connected services without requiring each service to integrate individually.

OIDC authentication

OIDC is an identity layer on top of OAuth 2.0. It allows third-party applications to connect to an identity provider and securely obtain user information. OIDC extends OAuth 2.0 with an ID Token, a JSON Web Token (JWT) that encapsulates basic user identity information in a self-contained, tamper-proof format for secure transmission and easy verification.

The following roles are formalized in OIDC:

Client: An application that provides services directly to the user.
Authorization server: An OpenID provider, which is an authorization server that issues ID Tokens for authentication.
Business server: The server that hosts the protected resources or services.
User: The resource owner who grants access.

The workflow is as follows:

The client sends an authentication request to the authorization server.
The user confirms the authorization on the authentication page, typically by logging in with a username and password.
The authorization server validates the request and returns an authorization code to the client.
The user is redirected to the client's callback endpoint, which receives the authorization code.
The client requests a token from the authorization server, sending the authorization code, client ID, and client secret.
The authorization server validates the request and returns an ID Token.
After successful authentication, the client receives the ID Token and can proceed with authenticated requests.
The client makes a request to the business server, including the ID Token.
The business server validates the ID Token and returns a response.

OIDC authentication flow with Cloud-native Gateway

In the standard OIDC flow, each business service (such as a user service or order service) must implement its own authentication logic. The OIDC authentication feature of Cloud-native Gateway centralizes this logic at the gateway level, eliminating per-service integration.

The workflow is as follows:

The client sends an authentication request to the gateway.
The gateway sends an authentication request to the authorization server.
The authorization server returns a code to the gateway.
The gateway returns the code to the client.
The client sends a callback request with the code to the gateway.
The gateway exchanges the code for a token with the authorization server.
The authorization server returns an ID Token to the gateway.
The gateway returns an authentication success response to the client and sets a cookie.
The client initiates a business request carrying the cookie, and the gateway verifies the token.
The gateway forwards the business request carrying the ID Token to the business service.
The business server's response is returned to the client through the gateway.

Throughout this process, Cloud-native Gateway validates requests. If a request is invalid, the gateway redirects the user to a login page and proxies the authentication with the authorization server. This is transparent to the backend services.

Create an authentication rule

Log on to the MSE console.
In the left-side navigation pane, choose Cloud-native Gateway > Gateways. In the top navigation bar, select a region.
On the Gateways page, click the ID of the gateway.
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 then click OK.

The following table describes the OIDC authentication parameters for Cloud-native Gateway.

Parameter	Description
Authentication Name	A custom name for the authentication rule.
Authentication Type	Select OIDC.
Issuer	The issuer URI of your authorization server.
Redirect URL	The URL where the user is redirected after a successful authorization. This URL must match the one registered with your OIDC identity provider. Important The URL must be in the format `http(s)://yourdomain/path`. 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 cookie. After authentication is successful, the cookie is sent to the specified domain to maintain the login state. For example, if you set `Cookie-domain=a.example.com`, the cookie is sent to the domain a.example.com. If you set `Cookie-domain=.example.com`, the cookie is sent to all subdomains of example.com.
Scope	The requested authorization scopes. Use a semicolon (`;`) to separate multiple scopes.
Grant	The authorization mode. The supported modes are Whitelist and Blacklist. Whitelist: Requests that match the hosts and paths in the whitelist bypass authentication. All other requests require authentication. Blacklist: Requests that match the hosts and paths in the blacklist require authentication. All other requests are accessed directly. Click + Rule condition to set the request domain and path. Domain Name: The requested domain name, or host. Path: The requested API path.

Create an authentication route

After creating the authentication rule, you must create a related route. For more information, see Create a route.

Configure the route parameters as follows:

Domain Name: Select the domain from the Redirect URL that you configured in the authentication rule. If no domain is configured, you can select *.
Important
If you use HTTPS, you must configure and associate a domain.
Path: Select Prefix Match and enter /oauth2.
Destination Service: Select oauth2-proxy.

View authentication details

Log on to the MSE console.
In the left-side navigation pane, choose Cloud-native Gateway > Gateways. In the top navigation bar, select a region.
On the Gateways page, click the ID of the gateway.
In the left-side navigation pane, choose Security Management > Global Authentication.
On the Global Authentication page, click the name of an authentication rule or click Details in the Actions column to view the current Authentication Configuration and manage the Authorization Information.
The authentication details page has three sections: Basic Information displays the name and source. Authentication Configuration displays fields such as Issuer, Redirect URL, Client ID, Client secret, Cookie domain, and Scope. Authorization Information displays the authorization mode, such as whitelist mode. You can click Create authorization information to add request domain and request path matching rules. Multiple rule conditions have an OR relationship.

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

Verify the results

Return to the Global Authentication page. If the new authentication rule appears in the list, it was created successfully.

Related operations

You can also perform the following operations to manage your authentication rules:

Enable an authentication rule: On the Global Authentication page, find the target rule and click Enable in the Actions column. This activates the rule.
Disable an authentication rule: On the Global Authentication page, find the target rule and click Close in the Actions column. This deactivates the rule.
Edit an authentication rule: On the Global Authentication page, find the target rule and click Edit in the Actions column to modify its configuration.
Delete an authentication rule: On the Global Authentication page, find the target rule and click Delete in the Actions column to permanently remove it.

Note

You must disable an authentication rule before you can delete it.

Microservices Engine:Configure OIDC authentication