OIDC Authentication

Prerequisites

• The backend service supports the standard OIDC protocol.
• The IDP service has been deployed.
• Three APIs have been created in the same group, which are the authentication API, redirection API, and logout API. For details, see Creating an API.

Constraints

• An API can be bound to only one OIDC authentication policy for a given environment, but each OIDC authentication policy can be bound to multiple APIs.
• You can create a maximum of five OIDC authentication policies for an APIG gateway. To adjust the quota, submit a service ticket.
• Token_endpoint_auth_methods_supported of the IDP must support client_secret_basic.
• When a request carries access_token for OIDC authentication, the request header name of the access_token must be Authorization.
• API request paths bound to an OIDC policy must differ from the policy's redirection and logout API paths.
• These APIs solely handle OIDC authentication logic (IDP redirection, user logout). Direct invocation is prohibited and will result in an error.
• The redirection and logout APIs must match the following criteria: exact match, public, GET method, HTTPS protocol, no authentication, and mock backend (no backend service is called in the actual request).
• Token verification supports the following encryption algorithms: RS256, RS384, and RS512. Obtain the public key via JWKS from the IDP or configure it directly.
• The maximum size of an access token is 5 KB.
• The IDP and APIG gateway must be able to communicate with each other. After the redirection URL (domain name + path) is configured on the IDP, the IDP must be able to resolve the domain name of the redirection URL.
• Policies are independent of APIs. A policy takes effect for an API only after they are bound to each other. When binding a policy to an API, you must specify an environment where the API has been published. The policy takes effect for the API only in the specified environment.
• After you bind a policy to an API, unbind the policy from the API, or update the policy, you do not need to publish the API again.
• Taking an API offline does not affect the policies bound to it. The policies are still bound to the API if the API is published again.
• Policies that have been bound to APIs cannot be deleted.
• Currently, OIDC is available only in CN South-Guangzhou-InvitationOnly, CN South-Singapore, AF-Johannesburg, CN East-Shanghai1, and CN Southwest-Guiyang1.

Creating an OIDC Authentication Policy

1. Go to the APIG console.
2. Select a dedicated gateway at the top of the navigation pane.

3. In the navigation pane, choose API Management > API Policies.
4. On the Policies tab, click Create Policy.
5. In the Select Policy Type box, select OIDC Authentication in the Plug-ins area.
6. Set the policy information based on the following table.

   Table 1 OIDC authentication parameters

   Parameter	Description
   Name	Enter a policy name. Using naming rules facilitates future search.
   Type	The value is fixed as OIDC Authorization.
   Description	Enter the description of the policy. The value can contain 1 to 255 characters.
   Policy Content	Content of the plug-in, which can be configured in a form or using a script.
   client_id	Client ID in the IDP.
   client_secret	Client secret in the IDP.
   discovery	Service discovery address opened by the IDP.
   redirect_api	Redirection API. This API is bound to the policy and functions as the entry for IDP redirection. You need to set the URL of the API to the redirection address of the IDP client, for example, the Valid redirect URIs parameter in the client of Keycloak. The path of other service APIs bound to the policy cannot be the same as the path of this API. Otherwise, the API fails to be called. The redirection API is a part of the OIDC authentication policy and cannot be deleted within the policy lifecycle.
   Advanced Settings
   scope	Authentication user information that needs to be returned in the authorization code process. The default value is openid email profile. You can add other ranges and separate them with spaces, for example, openid email profile phone.
   logout_api	Logout API. This API serves as the logout path for this policy; invoking it logs the user out. The path of other service APIs bound to this policy must be different from that of the logout API. Otherwise, the API cannot be called. The logout API is a part of the OIDC authentication policy and cannot be deleted during the policy lifecycle.
   public_key	Public key of the asymmetric algorithm used by the token. The policy uses public_key or the JWK of the IDP to verify the token. That is, at least one of public_key and jwks_enable must be configured. Otherwise, the token cannot be verified. If both are configured, the policy uses public_key for verification.
   jwt_cache_enabled	Whether to cache the token authentication result in APIG.
   jwks_enabled	Whether to use jwks_uri in the discovery service address to obtain the public key for token verification. If the IDP provides related JWK configuration, set this parameter to true. Otherwise, configure public_key to verify the token.
   auth_header_name	Name of the token request header used for JWT authentication. Default: Authorization.
   access_token_expires_in	Expiration time of the access token, in seconds. If the token response information obtained from the IDP does not contain the expiration time, the value of this parameter is used as the token expiration time. The default value is 3,600 seconds.
   redirect_after_logout_uri	When a user invokes logout_api of the plug-in, the page is redirected to this address.
   slient_renew_access_token_enabled	Whether APIG silently updates the access token when it expires.
   set_access_token_header_enabled	Whether to set the access token as the Authorization request header and transparently transmit it to the backend.
   set_userinfo_header_enabled	Whether to set the user information to the X-Userinfo request header and transparently transmit it to the service backend in the authorization code process.

7. Click OK.
8. After the policy is created, perform the operations described in Binding the Policy to APIs to apply the policy for the API.

Example Script

{
  "discovery": "https://example.com/realms/myrealm/.well-known/openid-configuration",
  "redirect_api_id": "8aa097****9843e****9c593d11b****",
  "scope": "openid email profile",
  "client_id": "myclient",
  "client_secret": "N9TX****wo4Lt****6iRYMDoCSux****",
  "logout_api_id": "8aa0****0e984****bc9c593d11b****",
  "access_token_expires_in":3000
  }

Binding the Policy to APIs

1. Click the policy name to go to the policy details page.
2. Select an environment and click Select APIs.
3. Select the API group, environment, and required APIs.

   APIs can be filtered by API name or tag. The tag is defined during API creation.

4. Click OK.
   • If an API no longer needs this policy, click Unbind in the row that contains the API.
   • If there are multiple APIs that no longer need this policy, select these APIs, and click Unbind above the API list. You can unbind a policy from a maximum of 1000 APIs at a time.