AddGatewayAuth - Microservices Engine - Alibaba Cloud Documentation Center

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.	jwt
Type	string	No	The authentication method. Valid values: JWT OIDC IDaaS ExternalAuthZ (custom authentication service)	JWT
Issuer	string	No	This parameter is valid if Type is set to JWT or OIDC: If Type is set to JWT, this parameter indicates the issuer of JWT claims. If Type is set to OIDC, this parameter indicates the issuer of OIDC claims.	testing@secure.istio.io
Jwks	string	No	The JWT public key in JSON format.	{"keys":[{"e":"AQAB","kid":"DHFbpoIUqrY8t2zpA2qXfCmr5VO5ZEr4RzHU_-envvQ","kty":"RSA","n":"xAE7eB6qugXyCAG3yhh7pkDkT65pHymX-P7KfIupjf59vsdo91bSP9C8H07pSAGQO1MV_xFj9VswgsCg4R6otmg5PV2He95lZdHtOcU5DXIg_pbhLdKXbi66GlVeK6ABZOUW3WYtnNHD-91gVuoeJT_DwtGGcp4ignkgXfkiEm4sw-4sfb4qdt5oLbyVpmW6x9cfa7vs2WTfURiCrBoUqgBo_-4WTiULmmHSGZHOjzwa8WtrtOQGsAFjIbno85jp6MnGGGZPYZbDAa_b3y5u-YpW7ypZrvD8BgtKVjgtQgZhLAGezMt0ua3DRrWnKqTZ0BJ_EyxOGuHJrLsn00fnMQ"}]}
TokenPosition	string	No	The type of the JWT token: If this parameter is set to HEADER, the token is specified in the header. The token parameter information to be verified. By default, the token is prefixed with Bearer in the Authorization header, for example: Authorization: Bearer token.	HEADER
TokenName	string	No	The position where the JWT token is stored. The token parameter information to be verified. By default, the token is prefixed with Bearer in the Authorization header, for example: `Authorization: Bearer token`.	Authorization
TokenNamePrefix	string	No	The prefix of the JWT token. The token parameter information to be verified. By default, the token is prefixed with Bearer in the Authorization header, for example: `Authorization: Bearer token`.	Bearer
TokenPass	boolean	No	Specifies whether to pass through the token.	true
IsWhite	boolean	No	Specifies whether to use a whitelist. Valid values: true: A whitelist is used. Only requests with the hostnames and paths that you specify in the whitelist can access the cloud-native gateway without authentication. false: A blacklist is used. Only requests with the hostnames and paths that you specify in the blacklist require authentication.	true
Status	boolean	No	The parameter is not publicly available and does not need to be passed. By default, the parameter is disabled after the authentication is created.	true
RedirectUrl	string	No	The URL for redirection after authentication is successful. This parameter is valid if Type is set to OIDC or IDaaS. The redirect URL must be the same as the redirect URL that you configured in OIDC or IDaaS.	https://test-.com/oauth2/callback
ClientId	string	No	The ID of the application in the service registration information. This parameter is valid if Type is set to OIDC or IDaaS.	23460e2fdd9bf9ad106****
ClientSecret	string	No	The application secret in the service registration information. This parameter is valid if Type is set to OIDC or IDaaS.	123****
CookieDomain	string	No	The domain name of the cookie. After the authentication is successful, the cookie is sent to the specified domain name to maintain the logon status. For example: If you set `Cookie-domain=a.example.com`, the cookie is sent to the domain name `a.example.com`. If you set `Cookie-domain=.example.com`, the cookie is sent to all subdomains of `example.com`.	test.com
ScopesList	array	No	The OIDC scopes. The related parameter is valid if Type is set to OIDC.
	string	No	The information about the OIDC scope.	Separate multiple values with semicolons (;).
LoginUrl	string	No	The URL that is used to log on to the IDaaS instance. This parameter is valid if Type is set to IDaaS.	***
Sub	string	No	The subject of JWT claims. You must make sure that the value of this parameter is the same as the sub value in the payload of JWT claims. This parameter is valid if Type is set to JWT. If this parameter is not specified or is left empty, it is set to be the same as the Issuer parameter by default	testing@secure.istio.io
ExternalAuthZJSON	object	No	The custom authentication information.
ServiceId	integer	No	The ID of the authentication service.	1
PrefixPath	string	No	The path of the authentication API provided by the authentication service. The path supports the prefix match method.	/auth
TokenKey	string	No	The header in which the token is in the request message. Common header types include Authorization and Cookie.	Authorization
AllowRequestHeaders	array	No	The header that can be carried in an authentication request.
	string	No	The name of the allowed request header.	x-req
AllowUpstreamHeaders	array	No	The header that can be retained in an authentication response.
	string	No	The name of the allowed response header.	x-resp
Timeout	integer	No	The timeout period of the authentication service. Unit: seconds.	100
IsRestrict	boolean	No	Indicates whether the strict authentication mode is used. Valid values: true: The strict mode is used. If the authentication service is unavailable when a connection to the authentication service fails to be established or a 5xx error code is returned, the gateway rejects requests from the client. false: The loose mode is used. If the authentication service is unavailable when a connection to the authentication service fails to be established or a 5xx error code is returned, the gateway still accepts requests from the client.	true
WithRequestBody	boolean	No	Specifies whether to allow bodies in requests.	true
BodyMaxBytes	integer	No	The maximum number of bytes in a body.	4000000
WithRematchRoute	boolean	No
GatewayUniqueId	string	No	The unique ID of the gateway.	gw-492af9b04bb4474cae9d645be850e3d7
AuthResourceMode	integer	No	The authentication resource mode. Valid values: 0: simple mode 1: complex mode	1
AuthResourceConfig	string	No	YAML configuration in complex mode.
AuthResourceList	array	No	The authorization rules. The relationship among multiple rule conditions is OR, and the relationship among multiple match items in a rule condition is AND.
	array	No	The data structure.
DomainId	integer	No	The ID of the domain name in the rule.	1
Path	string	No	The match path in the rule.	/test
MatchType	string	No	The method that is used to match requests based on paths. Valid values: EQUAL: exact match PRE: prefix match ERGULAR: regular expression match	EQUAL
IgnoreCase	boolean	No	Specifies whether to enable case sensitivity for request paths. This parameter is valid when Type is set to ExternalAuthZ. In other scenarios, request paths are case-sensitive by default. true: enables case sensitivity. false: disables case sensitivity.	true
AuthResourceHeaderList	array	No	The request headers in the rule. The related parameters are valid when Type is set to ExternalAuthZ.
	object	No
HeaderKey	string	No	The name of the request header.	x-req
HeaderMethod	string	No	The matching condition. Valid values: EQUAL NOT_EQUAL EXIST NOT_EXIST INCLUDE EXCLUDE PREFIX SUFFIX REGREX	EQUAL
HeaderValue	string	No	The value of the request header.	123
AcceptLanguage	string	No	The language in which the returned results are displayed. Valid values: zh and en. zh indicates Chinese, which is the default value. en indicates English.	zh

Response elements

Parameter	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 message.	You are not authorized to perform this operation.
Code	integer	The response code. The status code 200 indicates that the request was successful.	200
Success	boolean	Indicates whether the call was successful. Valid values: `true`: The request was successful. `false`: The request failed.	true
Data	integer	The ID of the created authentication rule.	3

Examples

Success response

JSON format

{
  "RequestId": "4279C00F-A5E1-53C6-A43B-751C1C524D0B",
  "HttpStatusCode": 200,
  "Message": "You are not authorized to perform this operation.",
  "Code": 200,
  "Success": true,
  "Data": 3
}

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.