Configure the oauth plug-in - Microservices Engine - Alibaba Cloud Documentation Center

The oauth plug-in is used to issue OAuth 2.0 access tokens based on JSON web tokens (JWTs). The oauth plug-in complies with the RFC9068 specification. This topic describes how to configure the oauth plug-in.

Plug-in type

Authentication plug-in.

Plug-in configuration description

Fields

Authorization configuration

Name	Data type	Required	Default Value	Description
consumers	array of object	Yes	-	The names of consumers that are the callers of a service. This field is used to authenticate requests.
issuer	string	No	Higress-Gateway	The JWT issuer.
auth_path	string	No	/oauth2/token	The suffix of the specified path. The suffix is used to issue tokens. When you configure this field at the route level, you must make sure that the specified route can be matched. When you use the API management feature to create an API, you must create an API that has the same path.
global_credentials	bool	No	true	Specifies whether to use credentials issued by any route for access if the consumer authentication is passed.
auth_header_name	string	No	Authorization	The request header from which you can obtain the JWT.
token_ttl	number	No	7200	The time to live (TTL) duration of the token after it is issued. Unit: seconds.
clock_skew_seconds	number	No	60	The clock skew allowed when the exp and iat fields in the JWT are verified. Unit: seconds.
keep_token	bool	No	true	Specifies whether to retain the JWT in the request when the request is forwarded to the backend service.
global_auth	array of string	No (Required only for instance-level configurations)	-	This field can be configured only at the instance level. If this field is set to true, the authentication mechanism globally takes effect. If this field is set to false, the authentication mechanism takes effect only for the configured domain names and routes. If this field is not configured, the authentication mechanism globally takes effect only when no domain names and routes are configured. This is in consideration of the usage habits of old users.

The following table describes the configuration items in the consumers field.

Name	Data type	Required	Default Value	Description
name	string	Yes	-	The name of the consumer.
client_id	string	Yes	-	The ID of the OAuth 2.0 client.
client_secret	string	Yes	-	The secret of the OAuth 2.0 client.

Important

For a route for which the preceding configurations are enabled, if the path suffix and auth_path are matched, the system does not forward the route information to the destination service, but uses the route to generate a token.
If the global_credentials field is set to false, you must make sure that the route with the plug-in enabled does not use exact match. If another route exists and uses prefix match, an unexpected issue may occur.
For an authenticated request, an X-Mse-Consumer field is added to the request header to identify the name of the caller.

Authentication configuration (optional)

Name	Data type	Required	Default Value	Description
allow	array of string	No (Non-instance-level configurations)	-	You can only configure this field at a fine granularity such as route or domain name. For requests that meet the matching conditions, you can configure consumers that are allowed for access. This implements fine-grained permission control.

Important

The authorization configuration and authentication configuration cannot coexist in a rule.

Configuration examples

Route-level authorization configuration

Apply the following plug-in configurations to the route-a and route-b routes:

consumers:
- name: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Although the same configurations are used, the credentials issued by route-a cannot be used to access route-b. Similarly, the credentials issued by route-b cannot be used to access route-a.

If you want to share the credential access permissions based on the same configurations, you can apply the following configurations:

global_credentials: true
consumers:
- name: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Global authorization configuration and route-level authentication configuration

The following configurations enable JWT authentication for a specific route or domain name of the gateway. If a JWT matches multiple JSON Web Key Sets (JWKSs), the first consumer that is matched is hit based on the configuration sequence.

Apply the following plug-in configurations at the instance level:

global_auth: false
consumers:
- name: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- name: consumer2
  client_id: 87654321-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: hgfedcba-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Apply the following plug-in configurations to the route-a and route-b routes:

allow:
- consumer1

Apply the following plug-in configurations to the *.example.com and test.com domain names:

allow:
- consumer2

Note

In this example, the route-a and route-b routes are those specified when the gateway routes are created. If a client request matches the two routes, the caller whose name is consumer1 is allowed to access the gateway. Other callers are not allowed to access the gateway.
In this example, the *.example.com and test.com domain names are used to match domain names in requests. If a client request matches the two domain names, the caller whose name is consumer2 is allowed to access the gateway. Other callers are not allowed to access the gateway.

Enable authentication at the gateway level

The following configurations enable OAuth2 authentication at the gateway level. All requests must be authenticated before they access the gateway.

global_auth: true
consumers:
- name: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- name: consumer2
  client_id: 87654321-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: hgfedcba-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Sample requests

Use the Client Credential grant type

Obtain an access token

# Obtain an access token by using the GET method. We recommend that you use this method.
curl 'http://test.com/oauth2/token?grant_type=client_credentials&client_id=12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

# Obtain an access token by using the POST method. To perform this operation, you need to match a route that points to a real destination service. Otherwise, the gateway does not read request bodies.
curl 'http://test.com/oauth2/token' -H 'content-type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

# Obtain the value of the access_token field from the response.
{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFwcGxpY2F0aW9uXC9hdCtqd3QifQ.eyJhdWQiOiJkZWZhdWx0IiwiY2xpZW50X2lkIjoiMTIzNDU2NzgteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4IiwiZXhwIjoxNjg3OTUxNDYzLCJpYXQiOjE2ODc5NDQyNjMsImlzcyI6IkhpZ3Jlc3MtR2F0ZXdheSIsImp0aSI6IjEwOTU5ZDFiLThkNjEtNGRlYy1iZWE3LTk0ODEwMzc1YjYzYyIsInN1YiI6ImNvbnN1bWVyMSJ9.NkT_rG3DcV9543vBQgneVqoGfIhVeOuUBwLJJ4Wycb0",
  "expires_in": 7200
}

Use the access token to initiate a request

curl 'http://test.com' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6ImFwcGxpY2F0aW9uXC9hdCtqd3QifQ.eyJhdWQiOiJkZWZhdWx0IiwiY2xpZW50X2lkIjoiMTIzNDU2NzgteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4IiwiZXhwIjoxNjg3OTUxNDYzLCJpYXQiOjE2ODc5NDQyNjMsImlzcyI6IkhpZ3Jlc3MtR2F0ZXdheSIsImp0aSI6IjEwOTU5ZDFiLThkNjEtNGRlYy1iZWE3LTk0ODEwMzc1YjYzYyIsInN1YiI6ImNvbnN1bWVyMSJ9.NkT_rG3DcV9543vBQgneVqoGfIhVeOuUBwLJJ4Wycb0'

HTTP status codes

HTTP status code	Error message	Reason
401	Invalid Jwt token.	No JWT is provided in the request header, the JWT format is invalid, or the JWT expires.
403	Access Denied.	The consumer is not authorized to access the current route.