すべてのプロダクト
Search

このプロダクト

    API Gateway:サードパーティ认证プラグイン

    ドキュメントセンター

    API Gateway:サードパーティ认证プラグイン

    最終更新日:Aug 13, 2024

    このトピックでは、API Gatewayが提供するサードパーティ認証プラグインについて説明します。 このプラグインを設定して、APIリクエストを認証する独自の認証サービスを開発できます。

    1. 概要

    リクエストを受信すると、API Gatewayはサードパーティ認証サービスを呼び出してリクエストを認証します。 API Gatewayは、認証サービスから成功応答が返されるまで、バックエンドサービスを呼び出しません。 認証サービスが成功応答を返さない場合、API Gatewayはリクエストを開始したクライアントに認証失敗応答を返します。 サードパーティ認証プラグインでは、次の機能がサポートされています。

    • 認証サービスに送信する必要があるリクエストパラメーターを定義できます。

    • API Gatewayの認証サービスから返された応答を特定の期間キャッシュして、ビジネスの円滑性を確保できます。

    • 認証失敗に対するカスタム応答を設定できます。

    p540686.png

    2. 設定

    2.1 認証サービスにパブリックURLを使用する場合のサンプルコード

    ---
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

    に直接送信されることを指定します。

    API Gatewayは、前のプラグインがバインドされているAPIの呼び出し要求を処理する前に、プラグイン定義に基づいて認証要求を作成し、認証要求を http://auth.com:8080 に送信します。 認証結果は、応答に基づいて判定される。 認証が失敗した場合は、認証の失敗に対するカスタム応答をクライアントに返すことができます。

    2.2 VPCのURLを認証サービスに使用する場合のサンプルコード

    ---
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 認証結果の本文のJSONフィールドを認証結果式のパラメーターとして抽出するためのサンプルコード

    ---
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

    に直接送信されることを指定します。

    認証サービスによって返される応答のclientIdフィールドの値が10086の場合、認証は成功です。 

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

    2.4 プラグインデータセットを使用して動的ホワイトリストを維持し、発信者IDを抽出してそのIDをホワイトリストと比較して発信者を認証するためのサンプルコード

    プラグインデータセットを使用して、ホワイトリストを維持できます。 このように、API Gatewayは、認証サービスから返された応答から発信者IDを抽出し、発信者がホワイトリストにあるかどうかを検証します。 ホワイトリスト内の発信者のみが認証に合格できます。 

    ---
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

    に直接送信されることを指定します。

    認証サービスによって返されたレスポンスのclientIdフィールドの値がdataset_testという名前のプラグインデータセットに存在する場合、認証は成功です。

    2.5 プラグインとアプリケーションベースの検証の統合に関するサンプルコード

    ---
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.

    orAppAuth: trueパラメーターを設定した後、アプリケーションベースの検証とサードパーティ認証のいずれかが成功した場合、認証は成功と見なされます。

    2.6 認証応答からフィールドを抽出してバックエンドサービスに送信するサンプルコード

    フィールドは、認証サービスによって返される応答から抽出することができる。 authResultPassThroughを使用して、バックエンドサービスに送信するパラメーターのマッピングを設定できます。

    フィールドを抽出できる認証応答のセクション: StatusCode、Header、およびJsonBody

    抽出されたフィールドをサポートするバックエンドサービスに送信されるリクエストのセクション: Header、Query、および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.
    重要

    2023年5月9日より前に購入した専用インスタンスで設定が有効にならない場合は、チケットを起票してインスタンスのバージョンをアップグレードする必要があります。

    3。 ログ

    Simple Log Serviceに配信されるログに、サードパーティの認証結果を記述するプラグインフィールドが追加されます。 "authSuccess":"0" は認証に失敗したことを示し、"authSuccess":"1" は認証に成功したことを示します。

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