All Products
Search
Document Center

API Gateway:Third-party authentication plug-in

Last Updated:Dec 07, 2022

You can configure your own authentication plug-in to authenticate API requests.

1. Overview

After receiving an API request, API Gateway invokes the authentication service to authenticate the request. API Gateway does not send the request to the backend service unless API Gateway receives a success response from the authentication service. If no success response is received within the configured period of time, API Gateway returns an authentication failure message to the client that initiated the request. API Gateway supports the following features for third-party authentication plug-ins :

  • You can set custom parameters for requests that are sent to the authentication service.

  • You can cache the responses from the authentication service in API Gateway for a certain period of time. This helps alleviate service burden.

  • You can set custom responses for authentication failures.

2. Configurations

2.1 Configuration example for requests from the Internet

---
parameters:                           # The definitions of parameters used in authentication result expressions.
  statusCode: "StatusCode"            # The HTTP status code for authentication service responses.
authUriType: "HTTP"                   # The authentication service type. Specify this parameter as HTTP for an Internet address and HTTP-VPC for a VPC address.
authUri:                              # The authentication service definition.
  address: "http://auth.com:8080"     # The address of the authentication server, including the port number.
  path: "/auth"                       # The path of the authentication service.
  timeout: 7000                       # The timeout period of the authentication service. The maximum period is 10 seconds.
  method: POST                        # The HTTP method of the authentication service.
passThroughBody: false                # Whether to pass the request body to the authentication service.
passThroughPath: true                 # Whether to pass the path as a header parameter, which is X-Ca-Remote-Auth-Raw-Path, to the authentication service. Default value: false.
trimAuthorizationHeaderPrefix: true   # Set this parameter to true. This enables the third-party authentication plug-in to extract the value of the Authorization header parameter and ignore the prefix. For example, for Authorization:Basic YWRtaW46YWRtaW4=, the plug-in extracts the value YWRtaW46YWRtaW4= and ignores the prefix Basic. The plug-in can ignore any type of prefix, such as Basic, Bearer, and AppCode.
cachedTimeBySecond: 10                # The period for which API Gateway caches the response from the authentication service. The maximum period is 10 minutes.
authParameters:                       # The mappings of the parameters that are sent to the authentication service.
  - targetParameterName: x-userId     # The names of the parameters that are sent to the authentication service.
    sourceParameterName: userId       # The names of the parameters in the original request.
    targetLocation: query             # The locations of the parameters that are sent to the authentication service.
    sourceLocation: query             # The locations of the parameters in the original request.
  - targetParameterName: x-passwoed   # The names of the parameters that are sent to the authentication service.
    sourceParameterName: password     # The names of the parameters in the original request.
    targetLocation: query             # The locations of the parameters that are sent to the authentication service.
    sourceLocation: query             # The locations of the parameters 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 value that is received by the client when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2           # Specifies that the specified header of the response from the authentication service is passed to the client when authentication fails.
errorPassThroughBody: true            # Specifies that the body of the response from the authentication service is passed to the client when authentication fails.
ignoreAuthException: true             # Specifies that the API access request is directly sent to the backend service when an authentication exception occurs, such as a timeout or connection error, regardless of the authentication result.

.

2.2 Configuration example for requests from within VPCs (if the authentication service runs in a VPC resource, you must first create a VPC authorization for the authentication service)

---
parameters:                           # The definitions of parameters used in authentication result expressions.
  statusCode: "StatusCode"            # The HTTP status code for authentication service responses.
authUriType: "HTTP"                   # The authentication service type. Set this parameter to HTTP for an Internet address and HTTP-VPC for a VPC address.
authUri:                              # The authentication service definition.
  vpcAccessName: "slbAccessForVip"    # The VPC authorization name for the authentication service
  path: "/auth"                       # The path of the authentication service.
  timeout: 7000                       # The timeout period of the authentication service. The maximum period is 10 seconds.
  method: POST                        # The HTTP method of the authentication service.
passThroughBody: false                # Whether to pass the request body to the authentication service.
passThroughPath: true                 # Whether to pass the path as a header parameter, which is X-Ca-Remote-Auth-Raw-Path, to the authentication service. Default value: false.
trimAuthorizationHeaderPrefix: true   # Set this parameter to true. This enables the third-party authentication plug-in to extract the value of the Authorization header parameter and ignore the prefix. For example, for Authorization:Basic YWRtaW46YWRtaW4=, the plug-in extracts the value YWRtaW46YWRtaW4= and ignores the prefix Basic. The plug-in can ignore any type of prefix, such as Basic, Bearer, and AppCode.
cachedTimeBySecond: 10                # The period for which API Gateway caches the response from the authentication service. The maximum period is 10 minutes.
authParameters:                       # The mappings of the parameters that are sent to the authentication service.
  - targetParameterName: x-userId     # The names of the parameters that are sent to the authentication service.
    sourceParameterName: userId       # The names of the parameters in the original request.
    targetLocation: query             # The locations of the parameters that are sent to the authentication service.
    sourceLocation: query             # The locations of the parameters in the original request.
  - targetParameterName: x-passwoed   # The names of the parameters that are sent to the authentication service.
    sourceParameterName: password     # The names of the parameters in the original request.
    targetLocation: query             # The locations of the parameters that are sent to the authentication service.
    sourceLocation: query             # The locations of the parameters 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 value that is received by the client when authentication fails.
errorPassThroughHeaderList: auth-result1,auth-result2           # Specifies that the specified header of the response from the authentication service is passed to the client when authentication fails.
errorPassThroughBody: true            # Specifies that the body of the response from the authentication service is passed to the client when authentication fails.
ignoreAuthException: true             # Specifies that the API access request is directly sent to the backend service when an authentication exception occurs, such as a timeout or connection error, regardless of the authentication result.

.

3. Logs

A plugin field is added to the logs that are delivered to Log Service (SLS) to describe the third-party authentication result. "authSuccess":"0" indicates that authentication failed, and "authSuccess":"1" indicates that authentication succeeded.

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