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」ヘッダーから値を抽出する場合、抽出される値は「hello」であり、「bearer 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 認可名。
  vpcTargetHostName: "a.b.com" # 認証サービスのホスト。
  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 ${constantParam1} = 'test'"