API Gateway:サードパーティ認証プラグイン

2.1 認証サービスがインターネットエンドポイントを使用する場合

---
parameters:                           # 認証結果の式で使用されるパラメーターの定義。
  statusCode: "StatusCode"            # HTTP 応答コード。
authUriType: "HTTP"                   # 認証サービスのタイプ。HTTP: インターネット上のエンドポイント。HTTP-VPC: VPC 内の承認済みアドレス。
authUri:                              # 認証サービスの定義。
  address: "http://auth.com:8080"     # 認証サービスのエンドポイント (ポート番号を含む)。
  path: "/auth"                       # 認証サービスのパス。
  timeout: 7000                       # 認証サービスのタイムアウト期間。最大値は 10 秒です。
  method: POST                        # 認証サービスの HTTP メソッド。
passThroughBody: false                # リクエストボディを認証サービスに渡すかどうかを指定します。
passThroughPath: true                 # このパラメーターを true に設定すると、リクエストパスが X-Ca-Remote-Auth-Raw-Path ヘッダーに配置され、認証サービスに送信されます。
cachedTimeBySecond: 10                # API Gateway が認証応答をキャッシュする期間。最大期間は 10 分です。現在、キャッシュは API UID とすべての認証パラメーターの組み合わせをプライマリキーとして使用します。
trimAuthorizationHeaderPrefix: true   # 認証パラメーターが Authorization ヘッダーにある場合、この機能はプレフィックスをインテリジェントにスキップしてパラメーター値を抽出します。たとえば、「Authorization: bearer hello」ヘッダーから値を抽出する場合、抽出される値は「bearer hello」ではなく「hello」になります。
authParameters:                       # 認証サービスに送信されるパラメーターのマッピング。
  - targetParameterName: x-userId     # 認証サービスに送信されるパラメーターの名前。
    sourceParameterName: userId       # 元のリクエストのパラメーターの名前。
    targetLocation: query             # 認証サービスに送信されるパラメーターの場所。
    sourceLocation: query             # 元のリクエストのパラメーターの場所。
  - targetParameterName: x-password   # 認証サービスに送信されるパラメーターの名前。
    sourceParameterName: password     # 元のリクエストのパラメーターの名前。
    targetLocation: query             # 認証サービスに送信されるパラメーターの場所。
    sourceLocation: query             # 元のリクエストのパラメーターの場所。
  - targetParameterName: token
    sourceParameterName: Authorization
    targetLocation: query
    sourceLocation: header
successCondition: "${statusCode} = 200"  # 応答に基づいて認証が成功したかどうかを判断する式。式が True と評価された場合、認証は成功です。
errorMessage: "auth failed"           # 認証が失敗したときにクライアントが受信する x-ca-errormessage ヘッダーの値。
errorStatusCode : 401                 # 認証が失敗したときにクライアントが受信する HTTP ステータスコード。
errorPassThroughHeaderList: auth-result1,auth-result2           # 認証が失敗したときに、認証応答からクライアントに渡すように指定されたヘッダー。
errorPassThroughBody: true            # 認証が失敗したときに、認証応答の本文をクライアントに渡すかどうかを指定します。
ignoreAuthException: true             # 認証中にタイムアウトや接続エラーなどの例外が発生した場合、認証結果は無視され、バックエンドサービスに直接アクセスされます。

API Gateway がこのプラグインがバインドされている API のリクエストを処理するとき、まずプラグインの構成に基づいて認証リクエストをアセンブルし、「http://auth.com:8080」に送信します。次に、API Gateway は応答に基づいて認証が成功したかどうかを判断します。認証が失敗した場合、クライアントに返される失敗応答をカスタマイズできます。

2.2 認証サービスが VPC 内にある場合

---
parameters:                           # 認証結果の式で使用されるパラメーターの定義。
  statusCode: "StatusCode"            # HTTP 応答コード。
authUriType: "HTTP-VPC"               # 認証サービスのタイプ。HTTP: インターネット上のエンドポイント。HTTP-VPC: VPC 内の承認済みアドレス。
authUri:                              # 認証サービスの定義。
  vpcAccessName: "slbAccessForVip"    # 認証サービスの VPC 権限付与の名前。
  path: "/auth"                       # 認証サービスのパス。
  timeout: 7000                       # 認証サービスのタイムアウト期間。最大値は 10 秒です。
  method: POST                        # 認証サービスの HTTP メソッド。
passThroughBody: false                # リクエストボディを認証サービスに渡すかどうかを指定します。
cachedTimeBySecond: 10                # API Gateway が認証応答をキャッシュする期間。最大期間は 10 分です。現在、キャッシュは API UID とすべての認証パラメーターの組み合わせをプライマリキーとして使用します。
authParameters:                       # 認証サービスに送信されるパラメーターのマッピング。
  - targetParameterName: x-userId     # 認証サービスに送信されるパラメーターの名前。
    sourceParameterName: userId       # 元のリクエストのパラメーターの名前。
    targetLocation: query             # 認証サービスに送信されるパラメーターの場所。
    sourceLocation: query             # 元のリクエストのパラメーターの場所。
  - targetParameterName: x-password   # 認証サービスに送信されるパラメーターの名前。
    sourceParameterName: password     # 元のリクエストのパラメーターの名前。
    targetLocation: query             # 認証サービスに送信されるパラメーターの場所。
    sourceLocation: query             # 元のリクエストのパラメーターの場所。
successCondition: "${statusCode} = 200"  # 応答に基づいて認証が成功したかどうかを判断する式。式が True と評価された場合、認証は成功です。
errorMessage: "auth failed"           # 認証が失敗したときにクライアントが受信する x-ca-errormessage ヘッダーの値。
errorStatusCode : 401                 # 認証が失敗したときにクライアントが受信する HTTP ステータスコード。
errorPassThroughHeaderList: auth-result1,auth-result2           # 認証が失敗したときに、認証応答からクライアントに渡すように指定されたヘッダー。
errorPassThroughBody: true            # 認証が失敗したときに、認証応答の本文をクライアントに渡すかどうかを指定します。
ignoreAuthException: true             # 認証中にタイムアウトや接続エラーなどの例外が発生した場合、認証結果は無視され、バックエンドサービスに直接アクセスされます。

2.3 認証応答の JSON 本文からフィールドを抽出する

---
parameters:                           # 認証結果の式で使用されるパラメーターの定義。
  clientId: "BodyJsonField:$.clientId"# 認証応答本文の JSON 構造内の clientId という名前のパラメーター。
authUriType: "HTTP-VPC"               # 認証サービスのタイプ。HTTP: インターネット上のエンドポイント。HTTP-VPC: VPC 内の承認済みアドレス。
authUri:                              # 認証サービスの定義。
  vpcAccessName: "slbAccessForVip"    # 認証サービスの VPC 権限付与の名前。
  vpcScheme: "https"                  # 認証サービスのプロトコル。このパラメーターを指定しない場合、デフォルトで HTTP が使用されます。
  path: "/auth"                       # 認証サービスのパス。
  timeout: 7000                       # 認証サービスのタイムアウト期間。最大値は 10 秒です。
  method: POST                        # 認証サービスの HTTP メソッド。
passThroughBody: false                # リクエストボディを認証サービスに渡すかどうかを指定します。
cachedTimeBySecond: 10                # API Gateway が認証応答をキャッシュする期間。最大期間は 10 分です。現在、キャッシュは API UID とすべての認証パラメーターの組み合わせをプライマリキーとして使用します。
authParameters:                       # 認証サービスに送信されるパラメーターのマッピング。
  - targetParameterName: x-userId     # 認証サービスに送信されるパラメーターの名前。
    sourceParameterName: userId       # 元のリクエストのパラメーターの名前。
    targetLocation: query             # 認証サービスに送信されるパラメーターの場所。
    sourceLocation: query             # 元のリクエストのパラメーターの場所。
  - targetParameterName: x-password   # 認証サービスに送信されるパラメーターの名前。
    sourceParameterName: password     # 元のリクエストのパラメーターの名前。
    targetLocation: query             # 認証サービスに送信されるパラメーターの場所。
    sourceLocation: query             # 元のリクエストのパラメーターの場所。
successCondition: "${clientId} = 10086"  # 応答に基づいて認証が成功したかどうかを判断する式。式が True と評価された場合、認証は成功です。
errorMessage: "auth failed"           # 認証が失敗したときにクライアントが受信する x-ca-errormessage ヘッダーの値。
errorStatusCode : 401                 # 認証が失敗したときにクライアントが受信する HTTP ステータスコード。
errorPassThroughHeaderList: auth-result1,auth-result2           # 認証が失敗したときに、認証応答からクライアントに渡すように指定されたヘッダー。
errorPassThroughBody: true            # 認証が失敗したときに、認証応答の本文をクライアントに渡すかどうかを指定します。
ignoreAuthException: true             # 認証中にタイムアウトや接続エラーなどの例外が発生した場合、認証結果は無視され、バックエンドサービスに直接アクセスされます。

認証サービスから返された応答の clientId フィールドの値が 10086 の場合、認証は成功です。

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

2.4 ID 認証と動的ホワイトリストにプラグインデータセットを使用する

プラグインデータセットにホワイトリストを保存できます。API Gateway は、サードパーティの認証応答からユーザー ID フィールドを抽出し、ユーザーがホワイトリストに含まれているかどうかを確認します。認証は、ホワイトリストに含まれているユーザーに対してのみ成功します。

---
parameters:                           # 認証結果の式で使用されるパラメーターの定義。
  statusCode: "StatusCode"            # HTTP 応答コード。
  clientId: "BodyJsonField:$.clientId"# 認証応答本文の JSON 構造内の clientId という名前のパラメーター。
authUriType: "HTTP-VPC"               # 認証サービスのタイプ。HTTP: インターネット上のエンドポイント。HTTP-VPC: VPC 内の承認済みアドレス。
authUri:                              # 認証サービスの定義。
  vpcAccessName: "slbAccessForVip"    # 認証サービスの VPC 権限付与の名前。
  path: "/auth"                       # 認証サービスのパス。
  timeout: 7000                       # 認証サービスのタイムアウト期間。最大値は 10 秒です。
  method: POST                        # 認証サービスの HTTP メソッド。
passThroughBody: false                # リクエストボディを認証サービスに渡すかどうかを指定します。
cachedTimeBySecond: 10                # API Gateway が認証応答をキャッシュする期間。最大期間は 10 分です。現在、キャッシュは API UID とすべての認証パラメーターの組み合わせをプライマリキーとして使用します。
authParameters:                       # 認証サービスに送信されるパラメーターのマッピング。
  - targetParameterName: x-userId     # 認証サービスに送信されるパラメーターの名前。
    sourceParameterName: userId       # 元のリクエストのパラメーターの名前。
    targetLocation: query             # 認証サービスに送信されるパラメーターの場所。
    sourceLocation: query             # 元のリクエストのパラメーターの場所。
  - targetParameterName: x-password   # 認証サービスに送信されるパラメーターの名前。
    sourceParameterName: password     # 元のリクエストのパラメーターの名前。
    targetLocation: query             # 認証サービスに送信されるパラメーターの場所。
    sourceLocation: query             # 元のリクエストのパラメーターの場所。
successCondition: "${statusCode} = 200"  # 認証応答を決定する式。
accessParameterName: clientId         # データセット内のデータと比較するパラメーターの名前。
accessByDataSet: dataset_test         # 認証に使用されるデータセット。データセット内のデータに clientId の値が含まれている場合、認証は成功です。
errorMessage: "auth failed"           # 認証が失敗したときにクライアントが受信する x-ca-errormessage ヘッダーの値。
errorStatusCode : 401                 # 認証が失敗したときにクライアントが受信する HTTP ステータスコード。
errorPassThroughHeaderList: auth-result1,auth-result2           # 認証が失敗したときに、認証応答からクライアントに渡すように指定されたヘッダー。
errorPassThroughBody: true            # 認証が失敗したときに、認証応答の本文をクライアントに渡すかどうかを指定します。
ignoreAuthException: true             # 認証中にタイムアウトや接続エラーなどの例外が発生した場合、認証結果は無視され、バックエンドサービスに直接アクセスされます。

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

2.5 アプリ認証との統合

---
parameters:                           # 認証結果の式で使用されるパラメーターの定義。
  statusCode: "StatusCode"            # HTTP 応答コード。
authUriType: "HTTP-VPC"               # 認証サービスのタイプ。HTTP: インターネット上のエンドポイント。HTTP-VPC: VPC 内の承認済みアドレス。
authUri:                              # 認証サービスの定義。
  vpcAccessName: "slbAccessForVip"    # 認証サービスの VPC 権限付与の名前。
  path: "/auth"                       # 認証サービスのパス。
  timeout: 7000                       # 認証サービスのタイムアウト期間。最大値は 10 秒です。
  method: POST                        # 認証サービスの HTTP メソッド。
cachedTimeBySecond: 10                # API Gateway が認証応答をキャッシュする期間。最大期間は 10 分です。現在、キャッシュは API UID とすべての認証パラメーターの組み合わせをプライマリキーとして使用します。
authParameters:                       # 認証サービスに送信されるパラメーターのマッピング。
  - targetParameterName: x-password   # 認証サービスに送信されるパラメーターの名前。
    sourceParameterName: password     # 元のリクエストのパラメーターの名前。
    targetLocation: query             # 認証サービスに送信されるパラメーターの場所。
    sourceLocation: query             # 元のリクエストのパラメーターの場所。
successCondition: "${statusCode} = 200"  # 認証応答を決定する式。
errorMessage: "auth failed"           # 認証が失敗したときにクライアントが受信する x-ca-errormessage ヘッダーの値。
errorStatusCode : 401                 # 認証が失敗したときにクライアントが受信する HTTP ステータスコード。
errorPassThroughHeaderList: auth-result1,auth-result2           # 認証が失敗したときに、認証応答からクライアントに渡すように指定されたヘッダー。
errorPassThroughBody: true            # 認証が失敗したときに、認証応答の本文をクライアントに渡すかどうかを指定します。
ignoreAuthException: true             # 認証中にタイムアウトや接続エラーなどの例外が発生した場合、認証結果は無視され、バックエンドサービスに直接アクセスされます。
orAppAuth: true						  # アプリ認証またはサードパーティ認証のいずれかが成功した場合、全体的な認証は成功です。

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

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

認証サービスから返された応答からフィールドを抽出し、それらをバックエンドサービスに送信するには、authResultPassThrough パラメーターを使用してパラメーターマッピングを構成します。

パラメーターは、応答の次のソースの場所から抽出できます: StatusCode、Header、および JsonBody。

バックエンドサービスリクエストでサポートされているターゲットの場所には、Header、Query、および Formdata が含まれます。

---
parameters:                         # 認証結果の式で使用されるパラメーターの定義。
  statusCode: "StatusCode"          # HTTP 応答コード。
  clientId: "BodyJsonField:$.Body"  # 認証サービスによって返される JSON 本文。
authUriType: "HTTP"                 # 認証サービスのタイプ。HTTP: インターネット上のエンドポイント。HTTP-VPC: VPC 内の承認済みアドレス。
authUri:                            # 認証サービスの定義。
  address: "http://127.0.0.1:8080"  # 認証サービスのエンドポイント (ポート番号を含む)。
  path: "/web"                      # 認証サービスのパス。
  timeout: 7000                     # 認証サービスのタイムアウト期間 (ミリ秒単位)。最大値は 10 秒です。
  method: POST                      # 認証サービスの HTTP メソッド。
passThroughBody: true               # リクエストボディを認証サービスに渡すかどうかを指定します。
cachedTimeBySecond: 10              # API Gateway が認証応答をキャッシュする期間。最大期間は 10 分です。現在、キャッシュは API UID とすべての認証パラメーターの組み合わせをプライマリキーとして使用します。
authResultPassThrough:              # バックエンドサービスに送信されるパラメーターのマッピング。
  - targetParameterName: x-echo-header-client-id  # バックエンドサービスに送信されるパラメーターの名前。
    targetLocation: header                        # バックエンドサービスリクエスト内のパラメーターの場所。
    sourceParameterName: clientId                 # 認証サービス応答から抽出されたパラメーター。
  - targetParameterName: x-echo-header-status-code
    targetLocation: query
    sourceParameterName: statusCode
successCondition: "${statusCode} = 200"  # 認証応答を決定する式。
errorMessage: "auth failed"              # 認証が失敗したときにクライアントが受信する x-ca-errormessage ヘッダーの値。
errorStatusCode: 401                     # 認証が失敗したときにクライアントが受信する HTTP ステータスコード。
errorPassThroughHeaderList: auth-result1,auth-result2   # 認証が失敗したときに、認証応答からクライアントに渡すように指定されたヘッダー。
errorPassThroughBody: true               # 認証が失敗したときに、認証応答の本文をクライアントに渡すかどうかを指定します。

parameters:                    # スロットリングなどの機能に使用できるパラメーターのリスト。
  clientId: "Parameter:x-echo-header-client-id"  # バックエンドサービスに送信されるパラメーターの名前。

2.7 認証応答のキャッシュ

サービスの可用性を向上させ、認証サービスの負荷を軽減するために、API Gateway は認証応答のキャッシュをサポートしています。キャッシュは、API UID とすべての認証パラメーターの組み合わせをプライマリキーとして使用し、認証応答を値として使用します。最大キャッシュ期間は 10 分です。

2.8 パラメーター値に基づいてサードパーティ認証をスキップする

この機能は、リクエストパラメーター値に基づく条件付き認証ルーティングをサポートします。これにより、事前定義されたルールに基づいて認証ポリシーを動的に選択できます。この機能は、一部のリクエストがサードパーティ認証を必要とし、他のリクエストがアプリ認証を必要とするシナリオで役立ちます。

skipRemoteAuthOnRequestParametersCondition 構成ブロックは、サードパーティ認証をスキップするために使用されます。すべてのパラメーター条件が満たされると、サードパーティ認証はスキップされます。sourceParameterConditionValues パラメーターには、値のリストを指定できます。リクエストフィールドがリスト内のいずれかの値と一致する場合、サブ条件が満たされます。sourceParameterConditionValues が null に設定されている場合、サブ条件はフィールドが欠落している場合にのみ満たされます。sourceParameterConditionValues が * に設定されている場合、サブ条件はフィールドの任意の値で満たされます。次のコードに構成例を示します。

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:    // 以下のすべての条件が満たされた場合、サードパーティ認証をスキップします。
  - sourceParameterName: userId   // リクエストパラメーターの名前。
    sourceLocation: Query   // リクエストパラメーターの場所。
    sourceParameterConditionValues: admin1,admin2   // パラメーター値のリスト。このリクエストパラメーターの値がリストにある場合、サブ条件が満たされます。
  - sourceParameterName: password  // リクエストパラメーターの名前。
    sourceLocation: Query  // リクエストパラメーターの場所。
    sourceParameterConditionValues: null  // このリクエストパラメーターが欠落している場合、サブ条件が満たされます。

2.9 サードパーティ認証サービスに定数パラメーターを送信する

この機能を使用すると、サードパーティ認証サービスに送信されるリクエストに定数パラメーターを挿入できます。認証パラメーターを構成するときに、sourceLocation および sourceParameterName プロパティを指定せずに targetParameterValue プロパティを直接設定すると、システムはこのパラメーターを自動的に定数パラメーターとして扱います。

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  // 認証定数パラメーター。パラメーター値を設定するだけで、ソースパラメーターを構成する必要はありません。
    targetParameterValue: "test"  
    targetLocation: Header
successCondition: "${userId} = 'A101' and ${constantParam} = 'test'"