Enforce Gateway Authentication via AddGatewayAuth API - MSE - Alibaba Cloud - Microservices Engine

Creates a gateway authentication rule.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

mse:AddGatewayAuth

create

*Gateway

acs:mse:{#regionId}:{#accountId}:instance/{#GatewayUniqueId}

None

Request parameters

Parameter	Type	Required	Description	Example
Name	string	No	The authentication name.	test
Type	string	No	The authentication method. Valid values: JWT OIDC IDaaS ExternalAuthZ (custom authentication service)	JWT
Issuer	string	No	This parameter applies when `Type` is `JWT` or `OIDC`. For JWT authentication, this specifies the issuer (`iss`) of the JWT claims. For OIDC authentication, this specifies the issuer (`iss`) of the OIDC claims.	https://example.com/auth
Jwks	string	No	The JWT public key in JSON Web Key Set (JWKS) format.	{"keys":[{"e":"AQAB","kid":"DHFbpoIUqrY8t2zpA2qXfCmr5VO5ZEr4RzHU_-envvQ","kty":"RSA","n":"xAE7eB6qugXyCAG3yhh7pkDkT65pHymX-P7KfIupjf59vsdo91bSP9C8H07pSAGQO1MV_xFj9VswgsCg4R6otmg5PV2He95lZdHtOcU5DXIg_pbhLdKXbi66GlVeK6ABZOUW3WYtnNHD-91gVuoeJT_DwtGGcp4ignkgXfkiEm4sw-4sfb4qdt5oLbyVpmW6x9cfa7vs2WTfURiCrBoUqgBo_-4WTiULmmHSGZHOjzwa8WtrtOQGsAFjIbno85jp6MnGGGZPYZbDAa_b3y5u-YpW7ypZrvD8BgtKVjgtQgZhLAGezMt0ua3DRrWnKqTZ0BJ_EyxOGuHJrLsn00fnMQ"}]}
TokenPosition	string	No	Specifies the location of the JWT. Valid value: HEADER: The token is in a request header. By default, the token is read from the `Authorization` header and must be prefixed with `Bearer` . For example: `Authorization: Bearer <token>`.	HEADER
TokenName	string	No	The name of the request header that contains the JWT. The default value is `Authorization`.	Authorization
TokenNamePrefix	string	No	The prefix for the token value in the header. The default value is `Bearer` (note the trailing space).	Bearer
TokenPass	boolean	No	Specifies whether to pass the token to the backend service after successful authentication.	true
IsWhite	boolean	No	Specifies the authorization mode. `true`: Whitelist mode. Requests that match the specified hosts and paths can bypass authentication. All other requests require authentication. `false`: Blacklist mode. Requests that match the specified hosts and paths require authentication. All other requests can bypass authentication.	true
Status	boolean	No	This parameter is for internal use and should not be configured. Upon creation, an authentication rule is disabled by default.	false
RedirectUrl	string	No	The URL to which the user is redirected after successful authentication. This parameter is required when `Type` is `OIDC` or `IDaaS`. The URL must match the redirect URL configured in the OIDC or IDaaS provider.	https://test-.com/oauth2/callback
ClientId	string	No	The client ID of the application registered with the identity provider. This parameter is required when `Type` is `OIDC` or `IDaaS`.	23460e2fdd9bf9ad106****
ClientSecret	string	No	The client secret of the application registered with the identity provider. This parameter is required when `Type` is `OIDC` or `IDaaS`.	123****
CookieDomain	string	No	The cookie domain. After successful authentication, the gateway sends a cookie to this domain to keep the user signed in. For example, if you set `Cookie-domain=a.example.com`, the cookie is sent to the `a.example.com` domain. If you set `Cookie-domain=.example.com`, the cookie is sent to `example.com` and its subdomains.	test.com
ScopesList	array	No	The OIDC scopes. This parameter is required when `Type` is `OIDC`.
	string	No	An OIDC scope.	openid
LoginUrl	string	No	The URL of the user logon page for the IDaaS instance. This parameter is required when `Type` is `IDaaS`.	https://daxxxxcn.aliyunidaas.com/
Sub	string	No	The subject (`sub`) of the JWT claims. This parameter is used when `Type` is `JWT`. Ensure that the value of this parameter matches the `sub` field in the JWT payload. If this parameter is not set or is left empty, its value defaults to the value of the `Issuer` parameter.	testing@secure.istio.io
ExternalAuthZJSON	object	No	The settings for the custom authentication service.
ServiceId	integer	No	The ID of the authentication service.	1343
PrefixPath	string	No	The path of the authentication API provided by the authentication service. The path is matched by prefix.	/auth
TokenKey	string	No	The request header that contains the token, such as `Authorization` or `Cookie`.	Authorization
AllowRequestHeaders	array	No	The request headers to pass to the custom authentication service.
	string	No	The name of an allowed request header.	x-req
AllowUpstreamHeaders	array	No	The response headers from the custom authentication service to pass to the backend service.
	string	No	The name of an allowed response header.	x-resp
Timeout	integer	No	The timeout for the custom authentication service, in seconds.	10
IsRestrict	boolean	No	Specifies the behavior when the custom authentication service is unavailable: `true`: Strict mode. If the authentication service is unavailable (for example, due to a connection failure or a 5xx error), the gateway rejects the client request. `false`: Permissive mode. If the authentication service is unavailable, the gateway allows the client request to pass through.	true
WithRequestBody	boolean	No	Specifies whether to include the request body in the request sent to the custom authentication service.	true
BodyMaxBytes	integer	No	The maximum size of the request body that can be sent to the custom authentication service, in bytes.	4000000
WithRematchRoute	boolean	No	Specifies whether to rematch the route after the authentication is complete.
GatewayUniqueId	string	No	The unique ID of the gateway.	gw-*****9b04bb4474cae9d645be850e3d7
AuthResourceMode	integer	No	The mode for configuring authorization resources. Valid values: 0: Simple mode 1: Advanced mode	1
AuthResourceConfig	string	No	The YAML configuration for the advanced mode.
AuthResourceList	array<object>	No	The list of authorization rules. Multiple rules are evaluated with a logical OR. Within a single rule, multiple match conditions are evaluated with a logical AND.
	array<object>	No	The settings for an authorization rule.
DomainId	integer	No	The ID of the domain name to which the rule applies.	1765
Path	string	No	The request path to match.	/test
MatchType	string	No	The match type for the path. Valid values: EQUAL: Exact match PRE: Prefix match REGEX: Regular expression match	EQUAL
IgnoreCase	boolean	No	Specifies whether path matching is case-sensitive. This parameter is applicable only to custom authentication rules. For other authentication methods, path matching is case-sensitive by default. `true`: Path matching is case-insensitive. `false`: Path matching is case-sensitive.	true
AuthResourceHeaderList	array<object>	No	A list of request header conditions to match. This parameter is applicable only to custom authentication rules.
	object	No
HeaderKey	string	No	The name of the request header.	x-req
HeaderMethod	string	No	The match condition. Valid values: EQUAL: Equal to NOT_EQUAL: Not equal to EXIST: Exists NOT_EXIST: Does not exist INCLUDE: Contains EXCLUDE: Does not contain PREFIX: Has prefix SUFFIX: Has suffix REGEX: Regular expression match	EQUAL
HeaderValue	string	No	The value of the request header.	123
AcceptLanguage	string	No	The language of the response. Valid values: `zh` (Chinese) and `en` (English). The default value is `zh`.	zh

Response elements

Element	Type	Description	Example
	object	The data structure.
RequestId	string	The request ID.	4279C00F-A5E1-53C6-A43B-751C1C524D0B
HttpStatusCode	integer	The HTTP status code.	200
Message	string	The response message.	OK
Code	integer	The response code. A value of `200` indicates that `Success` is `true`.	200
Success	boolean	Indicates whether the request succeeded. Valid values: `true`: The request succeeded. `false`: The request failed.	true
Data	integer	The ID of the created authentication rule.	333

Examples

Success response

JSON format

{
  "RequestId": "4279C00F-A5E1-53C6-A43B-751C1C524D0B",
  "HttpStatusCode": 200,
  "Message": "OK",
  "Code": 200,
  "Success": true,
  "Data": 333
}

Error codes

HTTP status code	Error code	Error message	Description
400	IllegalRequest	Invalid request:%s	Invalid request: %s
400	InvalidParameter	Parameter error:%s	Request parameter error: %s
500	InternalError	Console error. Try again later:%s	Console error. Try again later: %s
403	NoPermission	You are not authorized to perform this operation:%s	You do not have the permission to use this interface:%s
404	NotFound	Not found:%s	The resource does not exist:%s

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.