API Gateway:Third-party authentication plug-in

2.1 When the authentication service uses an Internet endpoint

---
parameters:                           # The definitions of parameters used in authentication result expressions.
  statusCode: "StatusCode"            # The HTTP response code.
authUriType: "HTTP"                   # The type of the authentication service. HTTP: an endpoint on the Internet. HTTP-VPC: an authorized address in a VPC.
authUri:                              # The definition of the authentication service.
  address: "http://auth.com:8080"     # The endpoint of the authentication service, including the port number.
  path: "/auth"                       # The path of the authentication service.
  timeout: 7000                       # The timeout period for the authentication service. The maximum value is 10 seconds.
  method: POST                        # The HTTP method of the authentication service.
passThroughBody: false                # Specifies whether to pass through the request body to the authentication service.
passThroughPath: true                 # If this parameter is set to true, the request path is placed in the X-Ca-Remote-Auth-Raw-Path header and sent to the authentication service.
cachedTimeBySecond: 10                # The period of time for which API Gateway caches the authentication response. The maximum period is 10 minutes. Currently, the cache uses a combination of the API UID and all authentication parameters as the primary key.
trimAuthorizationHeaderPrefix: true   # If the authentication parameter is in the Authorization header, this feature intelligently skips the prefix to extract the parameter value. For example, if you extract the value from the "Authorization: bearer hello" header, the extracted value is "hello", not "bearer hello".
authParameters:                       # The mappings of parameters sent to the authentication service.
  - targetParameterName: x-userId     # The name of the parameter sent to the authentication service.
    sourceParameterName: userId       # The name of the parameter in the original request.
    targetLocation: query             # The location of the parameter sent to the authentication service.
    sourceLocation: query             # The location of the parameter in the original request.
  - targetParameterName: x-password   # The name of the parameter sent to the authentication service.
    sourceParameterName: password     # The name of the parameter in the original request.
    targetLocation: query             # The location of the parameter sent to the authentication service.
    sourceLocation: query             # The location of the parameter in the original request.
  - targetParameterName: token
    sourceParameterName: Authorization
    targetLocation: query
    sourceLocation: header
successCondition: "${statusCode} = 200"  # The expression that determines whether the authentication is successful based on the response. If the expression evaluates to True, the authentication is successful.
errorMessage: "auth failed"           # The value of the x-ca-errormessage header that the client receives when authentication fails.
errorStatusCode : 401                 # The HTTP status code that the client receives when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2           # The specified headers from the authentication response to pass through to the client when authentication fails.
errorPassThroughBody: true            # Specifies whether to pass through the body of the authentication response to the client when authentication fails.
ignoreAuthException: true             # If an exception, such as a timeout or connection error, occurs during authentication, the authentication result is ignored and the backend service is accessed directly.

When API Gateway processes a request for an API to which this plug-in is bound, it first assembles an authentication request based on the plug-in configuration and sends it to "http://auth.com:8080". API Gateway then determines whether the authentication is successful based on the response. If the authentication fails, you can customize the failure response that is returned to the client.

2.2 If the authentication service is in a VPC

---
parameters:                           # The definitions of parameters used in authentication result expressions.
  statusCode: "StatusCode"            # The HTTP response code.
authUriType: "HTTP-VPC"               # The type of the authentication service. HTTP: an endpoint on the Internet. HTTP-VPC: an authorized address in a VPC.
authUri:                              # The definition of the authentication service.
  vpcAccessName: "slbAccessForVip"    # The name of the VPC authorization for the authentication service.
  path: "/auth"                       # The path of the authentication service.
  timeout: 7000                       # The timeout period for the authentication service. The maximum value is 10 seconds.
  method: POST                        # The HTTP method of the authentication service.
passThroughBody: false                # Specifies whether to pass through the request body to the authentication service.
cachedTimeBySecond: 10                # The period of time for which API Gateway caches the authentication response. The maximum period is 10 minutes. Currently, the cache uses a combination of the API UID and all authentication parameters as the primary key.
authParameters:                       # The mappings of parameters sent to the authentication service.
  - targetParameterName: x-userId     # The name of the parameter sent to the authentication service.
    sourceParameterName: userId       # The name of the parameter in the original request.
    targetLocation: query             # The location of the parameter sent to the authentication service.
    sourceLocation: query             # The location of the parameter in the original request.
  - targetParameterName: x-password   # The name of the parameter sent to the authentication service.
    sourceParameterName: password     # The name of the parameter in the original request.
    targetLocation: query             # The location of the parameter sent to the authentication service.
    sourceLocation: query             # The location of the parameter in the original request.
successCondition: "${statusCode} = 200"  # The expression that determines whether the authentication is successful based on the response. If the expression evaluates to True, the authentication is successful.
errorMessage: "auth failed"           # The value of the x-ca-errormessage header that the client receives when authentication fails.
errorStatusCode : 401                 # The HTTP status code that the client receives when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2           # The specified headers from the authentication response to pass through to the client when authentication fails.
errorPassThroughBody: true            # Specifies whether to pass through the body of the authentication response to the client when authentication fails.
ignoreAuthException: true             # If an exception, such as a timeout or connection error, occurs during authentication, the authentication result is ignored and the backend service is accessed directly.

2.3 Extract fields from the JSON body of an authentication response

---
parameters:                           # The definitions of parameters used in authentication result expressions.
  clientId: "BodyJsonField:$.clientId"# The parameter named clientId in the JSON structure of the authentication response body.
authUriType: "HTTP-VPC"               # The type of the authentication service. HTTP: an endpoint on the Internet. HTTP-VPC: an authorized address in a VPC.
authUri:                              # The definition of the authentication service.
  vpcAccessName: "slbAccessForVip"    # The name of the VPC authorization for the authentication service.
  vpcScheme: "https"                  # The protocol of the authentication service. If you do not specify this parameter, HTTP is used by default.
  path: "/auth"                       # The path of the authentication service.
  timeout: 7000                       # The timeout period for the authentication service. The maximum value is 10 seconds.
  method: POST                        # The HTTP method of the authentication service.
passThroughBody: false                # Specifies whether to pass through the request body to the authentication service.
cachedTimeBySecond: 10                # The period of time for which API Gateway caches the authentication response. The maximum period is 10 minutes. Currently, the cache uses a combination of the API UID and all authentication parameters as the primary key.
authParameters:                       # The mappings of parameters sent to the authentication service.
  - targetParameterName: x-userId     # The name of the parameter sent to the authentication service.
    sourceParameterName: userId       # The name of the parameter in the original request.
    targetLocation: query             # The location of the parameter sent to the authentication service.
    sourceLocation: query             # The location of the parameter in the original request.
  - targetParameterName: x-password   # The name of the parameter sent to the authentication service.
    sourceParameterName: password     # The name of the parameter in the original request.
    targetLocation: query             # The location of the parameter sent to the authentication service.
    sourceLocation: query             # The location of the parameter in the original request.
successCondition: "${clientId} = 10086"  # The expression that determines whether the authentication is successful based on the response. If the expression evaluates to True, the authentication is successful.
errorMessage: "auth failed"           # The value of the x-ca-errormessage header that the client receives when authentication fails.
errorStatusCode : 401                 # The HTTP status code that the client receives when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2           # The specified headers from the authentication response to pass through to the client when authentication fails.
errorPassThroughBody: true            # Specifies whether to pass through the body of the authentication response to the client when authentication fails.
ignoreAuthException: true             # If an exception, such as a timeout or connection error, occurs during authentication, the authentication result is ignored and the backend service is accessed directly.

If the value of the clientId field in the response returned by the authentication service is 10086, the authentication is successful.

{"code":200,"clientId":10086}

2.4 Use a plug-in dataset for identity authentication and dynamic whitelisting

You can store a whitelist in a plug-in dataset. API Gateway extracts the user identity field from the third-party authentication response and checks if the user is in the whitelist. Authentication succeeds only for users who are in the whitelist.

---
parameters:                           # The definitions of parameters used in authentication result expressions.
  statusCode: "StatusCode"            # The HTTP response code.
  clientId: "BodyJsonField:$.clientId"# The parameter named clientId in the JSON structure of the authentication response body.
authUriType: "HTTP-VPC"               # The type of the authentication service. HTTP: an endpoint on the Internet. HTTP-VPC: an authorized address in a VPC.
authUri:                              # The definition of the authentication service.
  vpcAccessName: "slbAccessForVip"    # The name of the VPC authorization for the authentication service.
  path: "/auth"                       # The path of the authentication service.
  timeout: 7000                       # The timeout period for the authentication service. The maximum value is 10 seconds.
  method: POST                        # The HTTP method of the authentication service.
passThroughBody: false                # Specifies whether to pass through the request body to the authentication service.
cachedTimeBySecond: 10                # The period of time for which API Gateway caches the authentication response. The maximum period is 10 minutes. Currently, the cache uses a combination of the API UID and all authentication parameters as the primary key.
authParameters:                       # The mappings of parameters sent to the authentication service.
  - targetParameterName: x-userId     # The name of the parameter sent to the authentication service.
    sourceParameterName: userId       # The name of the parameter in the original request.
    targetLocation: query             # The location of the parameter sent to the authentication service.
    sourceLocation: query             # The location of the parameter in the original request.
  - targetParameterName: x-password   # The name of the parameter sent to the authentication service.
    sourceParameterName: password     # The name of the parameter in the original request.
    targetLocation: query             # The location of the parameter sent to the authentication service.
    sourceLocation: query             # The location of the parameter in the original request.
successCondition: "${statusCode} = 200"  # The expression that determines the authentication response.
accessParameterName: clientId         # The name of the parameter to compare with the data in the dataset.
accessByDataSet: dataset_test         # The dataset used for authentication. If the data in the dataset contains the value of clientId, the authentication is successful.
errorMessage: "auth failed"           # The value of the x-ca-errormessage header that the client receives when authentication fails.
errorStatusCode : 401                 # The HTTP status code that the client receives when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2           # The specified headers from the authentication response to pass through to the client when authentication fails.
errorPassThroughBody: true            # Specifies whether to pass through the body of the authentication response to the client when authentication fails.
ignoreAuthException: true             # If an exception, such as a timeout or connection error, occurs during authentication, the authentication result is ignored and the backend service is accessed directly.

If the value of the clientId field in the response returned by the authentication service exists in the plug-in dataset named dataset_test, the authentication is successful.

2.5 Integrate with app authentication

---
parameters:                           # The definitions of parameters used in authentication result expressions.
  statusCode: "StatusCode"            # The HTTP response code.
authUriType: "HTTP-VPC"               # The type of the authentication service. HTTP: an endpoint on the Internet. HTTP-VPC: an authorized address in a VPC.
authUri:                              # The definition of the authentication service.
  vpcAccessName: "slbAccessForVip"    # The name of the VPC authorization for the authentication service.
  path: "/auth"                       # The path of the authentication service.
  timeout: 7000                       # The timeout period for the authentication service. The maximum value is 10 seconds.
  method: POST                        # The HTTP method of the authentication service.
cachedTimeBySecond: 10                # The period of time for which API Gateway caches the authentication response. The maximum period is 10 minutes. Currently, the cache uses a combination of the API UID and all authentication parameters as the primary key.
authParameters:                       # The mappings of parameters sent to the authentication service.
  - targetParameterName: x-password   # The name of the parameter sent to the authentication service.
    sourceParameterName: password     # The name of the parameter in the original request.
    targetLocation: query             # The location of the parameter sent to the authentication service.
    sourceLocation: query             # The location of the parameter in the original request.
successCondition: "${statusCode} = 200"  # The expression that determines the authentication response.
errorMessage: "auth failed"           # The value of the x-ca-errormessage header that the client receives when authentication fails.
errorStatusCode : 401                 # The HTTP status code that the client receives when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2           # The specified headers from the authentication response to pass through to the client when authentication fails.
errorPassThroughBody: true            # Specifies whether to pass through the body of the authentication response to the client when authentication fails.
ignoreAuthException: true             # If an exception, such as a timeout or connection error, occurs during authentication, the authentication result is ignored and the backend service is accessed directly.
orAppAuth: true						  # If either app authentication or third-party authentication succeeds, the overall authentication is successful.

After you configure the orAppAuth: true parameter, the authentication is considered successful if either the app authentication or the third-party authentication succeeds.

2.6 Extract fields from the authentication service response and send them to the backend service

To extract fields from the response returned by the authentication service and send them to the backend service, use the authResultPassThrough parameter to configure the parameter mappings.

Parameters can be extracted from the following source locations in the response: StatusCode, Header, and JsonBody.

The supported target locations in the backend service request include Header, Query, and Formdata.

---
parameters:                         # The definitions of parameters used in authentication result expressions.
  statusCode: "StatusCode"          # The HTTP response code.
  clientId: "BodyJsonField:$.Body"  # The JSON body returned by the authentication service.
authUriType: "HTTP"                 # The type of the authentication service. HTTP: an endpoint on the Internet. HTTP-VPC: an authorized address in a VPC.
authUri:                            # The definition of the authentication service.
  address: "http://127.0.0.1:8080"  # The endpoint of the authentication service, including the port number.
  path: "/web"                      # The path of the authentication service.
  timeout: 7000                     # The timeout period for the authentication service, in milliseconds (ms). The maximum value is 10s.
  method: POST                      # The HTTP method of the authentication service.
passThroughBody: true               # Specifies whether to pass through the request body to the authentication service.
cachedTimeBySecond: 10              # The period of time for which API Gateway caches the authentication response. The maximum period is 10 minutes. Currently, the cache uses a combination of the API UID and all authentication parameters as the primary key.
authResultPassThrough:              # The mappings of parameters sent to the backend service.
  - targetParameterName: x-echo-header-client-id  # The name of the parameter sent to the backend service.
    targetLocation: header                        # The location of the parameter in the backend service request.
    sourceParameterName: clientId                 # The parameter extracted from the authentication service response.
  - targetParameterName: x-echo-header-status-code
    targetLocation: query
    sourceParameterName: statusCode
successCondition: "${statusCode} = 200"  # The expression that determines the authentication response.
errorMessage: "auth failed"              # The value of the x-ca-errormessage header that the client receives when authentication fails.
errorStatusCode: 401                     # The HTTP status code that the client receives when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2   # The specified headers from the authentication response to pass through to the client when authentication fails.
errorPassThroughBody: true               # Specifies whether to pass through the body of the authentication response to the client when authentication fails.

parameters:                    # A list of parameters that can be used for features such as throttling.
  clientId: "Parameter:x-echo-header-client-id"  # The name of the parameter sent to the backend service.

2.7 Cache authentication responses

To improve service availability and reduce the load on your authentication service, API Gateway supports caching authentication responses. The cache uses a combination of the API UID and all authentication parameters as the primary key and the authentication response as the value. The maximum cache duration is 10 minutes.

2.8 Skip third-party authentication based on parameter values

This feature supports conditional authentication routing based on request parameter values. This lets you dynamically select an authentication policy based on predefined rules. This feature is useful in scenarios where some requests require third-party authentication and others require app authentication.

The skipRemoteAuthOnRequestParametersCondition configuration block is used to skip third-party authentication. Third-party authentication is skipped when all parameter conditions are met. For the sourceParameterConditionValues parameter, you can specify a list of values. The sub-condition is met if the request field matches any value in the list. If sourceParameterConditionValues is set to null, the sub-condition is met only if the field is missing. If sourceParameterConditionValues is set to *, the sub-condition is met for any value of the field. The following code provides a configuration example.

parameters:
  statusCode: "StatusCode"
  userId: "BodyJsonField:$.Headers.tokenUserId"
authUriType: "HTTP"
authUri:
  address: "https://auth.com"
  path: "/auth"
  timeout: 7000
  method: POST
passThroughBody: false
cachedTimeBySecond: 1
authParameters:
  - targetParameterName: tokenUserId
    sourceParameterName: userId
    targetLocation: Header
    sourceLocation: Query
successCondition: "${userId} = 'admin'"
skipRemoteAuthOnRequestParametersCondition:    // Skips third-party authentication if all the following conditions are met.
  - sourceParameterName: userId   // The name of the request parameter.
    sourceLocation: Query   // The location of the request parameter.
    sourceParameterConditionValues: admin1,admin2   // A list of parameter values. The sub-condition is met if the value of this request parameter is in the list.
  - sourceParameterName: password  // The name of the request parameter.
    sourceLocation: Query  // The location of the request parameter.
    sourceParameterConditionValues: null  // The sub-condition is met if this request parameter is missing.

2.9 Send constant parameters to the third-party authentication service

This feature lets you inject constant parameters into requests sent to the third-party authentication service. When you configure an authentication parameter, if you set the targetParameterValue property directly without specifying the sourceLocation and sourceParameterName properties, the system automatically treats this parameter as a constant parameter.

parameters:
  userId: "BodyJsonField:$.Headers.tokenUserId"
authUriType: "HTTP"
authUri:
  address: "https://auth.com"
  path: "/auth"
  timeout: 7000
  method: POST
passThroughBody: false
cachedTimeBySecond: 1
authParameters:
  - targetParameterName: tokenUserId
    sourceParameterName: userId
    targetLocation: Header
    sourceLocation: Query
  - targetParameterName: constantParam1  // An authentication constant parameter. You only need to set the parameter value. You do not need to configure the source parameter.
    targetParameterValue: "test"  
    targetLocation: Header
successCondition: "${userId} = 'A101' and ${constantParam} = 'test'"