1. Overview

After receiving a request, API Gateway invokes your third-party authentication service to authenticate the request. API Gateway does not call the backend service until a success response is returned from the authentication service. If the authentication service does not return a success response, API Gateway returns an authentication failure response to the client that initiated the request. The following features are supported by the third-party authentication plug-in:

• Allows you to define request parameters that must be sent to the authentication service.

• Allows you to cache responses that are returned from the authentication service in API Gateway for a specific period of time to ensure business smoothness.

• Allows you to set custom responses for authentication failures.

2. Configurations

2.1 Sample code when a public URL is used for the authentication service

---
parameters:                           # The definitions of parameters that are used in authentication result expressions.
  statusCode: "StatusCode"            # The HTTP status code in the authentication response.
authUriType: "HTTP"                   # The URL type of the authentication service. HTTP specifies that a public URL is used for the authentication service. HTTP-VPC specifies that an authorized URL in a virtual private cloud (VPC) is used for the authentication service.
authUri:                              # The definition of the authentication service.
  address: "http://auth.com:8080"     # The URL 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. Maximum value: 10 seconds.
  method: POST                        # The HTTP method that you want to use for the authentication service.
passThroughBody: false                # Specifies whether to pass the request body to the authentication service.
passThroughPath: true                 # Specifies whether to put the request path in the X-Ca-Remote-Auth-Raw-Path header when you send the header to the authentication service.
cachedTimeBySecond: 10                # The period of time for which API Gateway caches the responses that are returned from the authentication service. The maximum period is 10 minutes. All API UIDs and authentication parameters are cached as primary keys.
trimAuthorizationHeaderPrefix: true   # Specifies whether the system skips the prefix of the header to extract an authentication parameter value if the parameter is in the Authorization header. For example, if you extract the authentication parameter value from the Authorization:bearer hello header, the value is hello instead of bearer hello.
authParameters:                       # The mappings of the parameters that are sent to the authentication service.
  - targetParameterName: x-userId     # The name of the parameter when it is sent to the authentication service.
    sourceParameterName: userId       # The name of the parameter in the original request.
    targetLocation: query             # The position of the parameter when it is sent to the authentication service.
    sourceLocation: query             # The position of the parameter in the original request.
  - targetParameterName: x-password   # The name of the parameter when it is sent to the authentication service.
    sourceParameterName: password     # The name of the parameter in the original request.
    targetLocation: query             # The position of the parameter when it is sent to the authentication service.
    sourceLocation: query             # The position of the parameter in the original request.
  - targetParameterName: token
    sourceParameterName: Authorization
    targetLocation: query
    sourceLocation: header
successCondition: "${statusCode} = 200"  # The expression that is used to determine the authentication status based on the response that is returned from the authentication service. If the expression is True, the authentication is successful.
errorMessage: "auth failed"           # The value of the x-ca-errormessage header in the response that is received by the client when authentication fails.
errorStatusCode : 401                 # The HTTP status code that is received by the client when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2           # Specifies that the specified header of the response that is returned from the authentication service is passed to the client when authentication fails.
errorPassThroughBody: true            # Specifies that the body of the response that is returned from the authentication service is passed to the client when authentication fails.
ignoreAuthException: true             # Specifies that when an authentication exception such as a timeout error or a connection error occurs, the authentication result is ignored, and the API request is directly sent to the backend service

.

Before API Gateway processes a request to call an API to which the preceding plug-in is bound, API Gateway constructs an authentication request based on the plug-in definition and sends the authentication request to http://auth.com:8080. The authentication result is determined based on the response. If the authentication fails, you can return a custom response for the authentication failure to the client.

2.2 Sample code when a URL in a VPC is used for the authentication service

---
parameters:                           # The definitions of parameters that are used in authentication result expressions.
  statusCode: "StatusCode"            # The HTTP status code in the authentication response.
authUriType: "HTTP-VPC"               # The URL type of the authentication service. HTTP specifies that a public URL is used for the authentication service. HTTP-VPC specifies that an authorized URL in a VPC is used for the authentication service.
authUri:                              # The definition of the authentication service.
  vpcAccessName: "slbAccessForVip"    # The name of the VPC to which the URL of the authentication service belongs.
  path: "/auth"                       # The path of the authentication service.
  timeout: 7000                       # The timeout period for the authentication service. Maximum value: 10 seconds.
  method: POST                        # The HTTP method that you want to use for the authentication service.
passThroughBody: false                # Specifies whether to pass the request body to the authentication service.
cachedTimeBySecond: 10                # The period of time for which API Gateway caches the responses that are returned from the authentication service. The maximum period is 10 minutes. All API UIDs and authentication parameters are cached as primary keys.
authParameters:                       # The mappings of the parameters that are sent to the authentication service.
  - targetParameterName: x-userId     # The name of the parameter when it is sent to the authentication service.
    sourceParameterName: userId       # The name of the parameter in the original request.
    targetLocation: query             # The position of the parameter when it is sent to the authentication service.
    sourceLocation: query             # The position of the parameter in the original request.
  - targetParameterName: x-password   # The name of the parameter when it is sent to the authentication service.
    sourceParameterName: password     # The name of the parameter in the original request.
    targetLocation: query             # The position of the parameter when it is sent to the authentication service.
    sourceLocation: query             # The position of the parameter in the original request.
successCondition: "${statusCode} = 200"  # The expression that is used to determine the response from the authentication service. If the expression is True, the authentication is successful.
errorMessage: "auth failed"           # The value of the x-ca-errormessage header in the response that is received by the client when authentication fails.
errorStatusCode : 401                 # The HTTP status code that is received by the client when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2           # Specifies that the specified header of the response that is returned from the authentication service is passed to the client when authentication fails.
errorPassThroughBody: true            # Specifies that the body of the response that is returned from the authentication service is passed to the client when authentication fails.
ignoreAuthException: true             # Specifies that when an authentication exception such as a timeout error or a connection error occurs, the authentication result is ignored, and the API request is directly sent to the backend service

.

2.3 Sample code on extracting JSON fields in the body of an authentication result as the parameters in an authentication result expression

---
parameters:                           # The definitions of parameters that are used in authentication result expressions.
  clientId: "BodyJsonField:$.clientId"# The name of the parameter in the JSON struct of the authentication response body.
authUriType: "HTTP-VPC"               # The URL type of the authentication service. HTTP specifies that a public URL is used for the authentication service. HTTP-VPC specifies that an authorized URL in a VPC is used for the authentication service.
authUri:                              # The definition of the authentication service.
  vpcAccessName: "slbAccessForVip"    # The name of the VPC to which the URL of the authentication service belongs.
  vpcScheme: "https"                  # The network protocol used by 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. Maximum value: 10 seconds.
  method: POST                        # The HTTP method that you want to use for the authentication service.
passThroughBody: false                # Specifies whether to pass the request body to the authentication service.
cachedTimeBySecond: 10                # The period of time for which API Gateway caches the responses that are returned from the authentication service. The maximum period is 10 minutes. All API UIDs and authentication parameters are cached as primary keys.
authParameters:                       # The mappings of the parameters that are sent to the authentication service.
  - targetParameterName: x-userId     # The name of the parameter when it is sent to the authentication service.
    sourceParameterName: userId       # The name of the parameter in the original request.
    targetLocation: query             # The position of the parameter when it is sent to the authentication service.
    sourceLocation: query             # The position of the parameter in the original request.
  - targetParameterName: x-password   # The name of the parameter when it is sent to the authentication service.
    sourceParameterName: password     # The name of the parameter in the original request.
    targetLocation: query             # The position of the parameter when it is sent to the authentication service.
    sourceLocation: query             # The position of the parameter in the original request.
successCondition: "${clientId} = 10086"  # The expression that is used to determine the response from the authentication service. If the expression is True, the authentication is successful.
errorMessage: "auth failed"           # The value of the x-ca-errormessage header in the response that is received by the client when authentication fails.
errorStatusCode : 401                 # The HTTP status code that is received by the client when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2           # Specifies that the specified header of the response that is returned from the authentication service is passed to the client when authentication fails.
errorPassThroughBody: true            # Specifies that the body of the response that is returned from the authentication service is passed to the client when authentication fails.
ignoreAuthException: true             # Specifies that when an authentication exception such as a timeout error or a connection error occurs, the authentication result is ignored, and the API request is directly sent to the backend service

.

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

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

2.4 Sample code on using a plug-in dataset to maintain a dynamic whitelist to authenticate a caller by extracting the caller ID and comparing the ID with the whitelist

You can use a plug-in dataset to maintain a whitelist. This way, API Gateway extracts the caller identity from the response returned by your authentication service and verifies whether the caller is in the whitelist. Only callers in the whitelist can pass the authentication.

---
parameters:                           # The definitions of parameters that are used in authentication result expressions.
  statusCode: "StatusCode"            # The HTTP status code in the authentication response.
  clientId: "BodyJsonField:$.clientId"# The name of the parameter in the JSON struct of the authentication response body.
authUriType: "HTTP-VPC"               # The URL type of the authentication service. HTTP specifies that a public URL is used for the authentication service. HTTP-VPC specifies that an authorized URL in a VPC is used for the authentication service.
authUri:                              # The definition of the authentication service.
  vpcAccessName: "slbAccessForVip"    # The name of the VPC to which the URL of the authentication service belongs.
  path: "/auth"                       # The path of the authentication service.
  timeout: 7000                       # The timeout period for the authentication service. Maximum value: 10 seconds.
  method: POST                        # The HTTP method that you want to use for the authentication service.
passThroughBody: false                # Specifies whether to pass the request body to the authentication service.
cachedTimeBySecond: 10                # The period of time for which API Gateway caches the responses that are returned from the authentication service. The maximum period is 10 minutes. All API UIDs and authentication parameters are cached as primary keys.
authParameters:                       # The mappings of the parameters that are sent to the authentication service.
  - targetParameterName: x-userId     # The name of the parameter when it is sent to the authentication service.
    sourceParameterName: userId       # The name of the parameter in the original request.
    targetLocation: query             # The position of the parameter when it is sent to the authentication service.
    sourceLocation: query             # The position of the parameter in the original request.
  - targetParameterName: x-password   # The name of the parameter when it is sent to the authentication service.
    sourceParameterName: password     # The name of the parameter in the original request.
    targetLocation: query             # The position of the parameter when it is sent to the authentication service.
    sourceLocation: query             # The position of the parameter in the original request.
successCondition: "${statusCode} = 200"  # The expression that is used to determine the response from the authentication service.
accessParameterName: clientId         # The parameter that is compared with the data in the dataset.
accessByDataSet: dataset_test         # The dataset that is used in the authentication. If the value of the clientId field is included in the dataset, the authentication is successful.
errorMessage: "auth failed"           # The value of the x-ca-errormessage header in the response that is received by the client when authentication fails.
errorStatusCode : 401                 # The HTTP status code that is received by the client when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2           # Specifies that the specified header of the response that is returned from the authentication service is passed to the client when authentication fails.
errorPassThroughBody: true            # Specifies that the body of the response that is returned from the authentication service is passed to the client when authentication fails.
ignoreAuthException: true             # Specifies that when an authentication exception such as a timeout error or a connection error occurs, the authentication result is ignored, and the API request is directly sent to the backend service

.

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

2.5 Sample code on integrating the plug-in with application-based verification

---
parameters:                           # The definitions of parameters that are used in authentication result expressions.
  statusCode: "StatusCode"            # The HTTP status code in the authentication response.
authUriType: "HTTP-VPC"               # The URL type of the authentication service. HTTP specifies that a public URL is used for the authentication service. HTTP-VPC specifies that an authorized URL in a VPC is used for the authentication service.
authUri:                              # The definition of the authentication service.
  vpcAccessName: "slbAccessForVip"    # The name of the VPC to which the URL of the authentication service belongs.
  path: "/auth"                       # The path of the authentication service.
  timeout: 7000                       # The timeout period for the authentication service. Maximum value: 10 seconds.
  method: POST                        # The HTTP method that you want to use for the authentication service.
cachedTimeBySecond: 10                # The period of time for which API Gateway caches the responses that are returned from the authentication service. The maximum period is 10 minutes. All API UIDs and authentication parameters are cached as primary keys.
authParameters:                       # The mappings of the parameters that are sent to the authentication service.
  - targetParameterName: x-password   # The name of the parameter when it is sent to the authentication service.
    sourceParameterName: password     # The name of the parameter in the original request.
    targetLocation: query             # The position of the parameter when it is sent to the authentication service.
    sourceLocation: query             # The position of the parameter in the original request.
successCondition: "${statusCode} = 200"  # The expression that is used to determine the response from the authentication service.
errorMessage: "auth failed"           # The value of the x-ca-errormessage header in the response that is received by the client when authentication fails.
errorStatusCode : 401                 # The HTTP status code that is received by the client when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2           # Specifies that the specified header of the response that is returned from the authentication service is passed to the client when authentication fails.
errorPassThroughBody: true            # Specifies that the body of the response that is returned from the authentication service is passed to the client when authentication fails.
ignoreAuthException: true             # Specifies that when an authentication exception such as a timeout error or a connection error occurs, the authentication result is ignored, and the API request is directly sent to the backend service.
orAppAuth: true						  # Specifies that the authentication is considered successful when one of the application-based verification and the third-party authentication is successful.

After the orAppAuth: true parameter is configured, the authentication is considered successful when one of the application-based verification and the third-party authentication is successful.

2.6 Sample code on extracting fields from an authentication response and sending the fields to the backend service

Fields can be extracted from the response returned by the authentication service. You can use authResultPassThrough to configure the mapping of the parameters that you want to send to the backend service.

Sections in authentication responses in which fields can be extracted: StatusCode, Header, and JsonBody

Sections in requests sent to the backend service that support extracted fields: Header, Query, and Formdata

---
parameters:                           # The definitions of parameters used in authentication result expressions
  statusCode: "StatusCode"            # The HTTP status code for authentication service responses
  clientId: "BodyJsonField:$. Body"  # The response body returned in JSON format by the authentication service.
authUriType: "HTTP"                   # The URL type of the authentication service. HTTP specifies that a public URL is used for the authentication service. HTTP-VPC specifies that an authorized URL in a VPC is used for the authentication service.
authUri:                              # The definition of the authentication service.
  address: "http://127.0.0.1:8080"  # The URL 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. Unit: ms. The maximum timeout period is 10 seconds.
  method: POST                        # The HTTP method that you want to use for the authentication service.
passThroughBody: true               # Specifies whether to pass the request body to the authentication service.
cachedTimeBySecond: 10                # The period of time for which API Gateway caches the responses that are returned from the authentication service. The maximum period is 10 minutes. All API UIDs and authentication parameters are cached as primary keys.
authResultPassThrough:              # The mappings of the parameters that are sent to the backend service.
  - targetParameterName: x-echo-header-client-id  # The name of the parameter that is sent to the backend service.
    targetLocation: header                        # The position of the parameter when it is sent to the authentication service.
    sourceParameterName: clientId                 # The parameter that is extracted from the response returned by the authentication service.
  - targetParameterName: x-echo-header-status-code
    targetLocation: query
    sourceParameterName: statusCode
successCondition: "${statusCode} = 200"  # The expression that is used to determine the response from the authentication service.
errorMessage: "auth failed"           # The value of the x-ca-errormessage header in the response that is received by the client when authentication fails
errorStatusCode : 401                 # The http status value that is received by the client when authentication fails
errorPassThroughHeaderList: auth-result1,auth-result2   # The headers in the authentication response that are passed to the client when authentication fails.
errorPassThroughBody: true            # Specifies that the body of the response that is returned from the authentication service is passed to the client when authentication fails.

3. Logs

A plugin field is added to the logs that are delivered to Simple Log Service to describe third-party authentication results. "authSuccess":"0" indicates that the authentication failed, and "authSuccess":"1" indicates that the authentication is successful.

plugin:[{"context":{"authSuccess":"0"},"pluginName":"remoteAuth"}]