認可プロバイダ・ファンクションの作成

ユーザー定義の複数引数のアクセス・トークンを受け入れる認可プロバイダ・ファンクションを作成するには:

1. APIゲートウェイからの入力として、次の形式のJSONを受け入れる認可プロバイダ・ファンクションのコードを記述します:

   
   {
     "type": "USER_DEFINED",
     "data": {
       "<argument-n>": "<context-variable-value>",
       "<argument-n>": "<context-variable-value>",
       "<argument-n>": "<context-variable-value>"
     }
   }

   ここでは:

   • "type": "USER_DEFINED"は、認可プロバイダ・ファンクションに渡される引数および値がAPIデプロイメント仕様で定義されていることを示します。
   • "<argument-n>"は、APIデプロイメント仕様のparametersセクションで指定されたユーザー定義の引数名に対応する引数名です。例: "state"、"xapikey"
   • "<context-variable-value>"は、APIデプロイメント仕様のparametersセクションで指定されたコンテキスト変数の値です。たとえば、request.query[state]問合せパラメータ・コンテキスト変数の値、request.headers[X-Api-Key]ヘッダー・パラメータ・コンテキスト変数の値です。リクエスト・ヘッダーおよび問合せパラメータから認可プロバイダ・ファンクションに複数の値を渡す場合、"<context-variable-value>"が認可プロバイダ・ファンクションに配列として渡されることに注意してください。また、コンテキスト変数の値がAPIゲートウェイへの元のリクエストに存在しない場合、コンテキスト変数は認可プロバイダ・ファンクションに渡されません。

   たとえば、認可プロバイダ・ファンクションで、request.query[state]問合せパラメータ・コンテキスト変数の値とrequest.headers[X-API-Key]ヘッダー・パラメータ・コンテキスト変数の値をAPIゲートウェイからの入力として受け入れることができます。したがって、たとえば、request.query[state]問合せパラメータ・コンテキスト変数およびrequest.headers[X-Api-Key]ヘッダー・パラメータ・コンテキスト変数の値がそれぞれcaliforniaおよびabc123def456fhi789の場合、認可プロバイダ・ファンクションは次のJSON入力を受け入れる必要があります。

   
   {
     "type": "USER_DEFINED",
     "data": {
       "state": "california",
       "xapikey": "abc123def456fhi789"
     }
   }

   X-API-KeyヘッダーがAPIゲートウェイへの元のリクエストに存在しない場合、xapikeyコンテキスト変数は(null値で渡されるのではなく)認可プロバイダ・ファンクションに渡されません。

2. ユーザー定義の複数引数アクセス・トークンがアイデンティティ・プロバイダで正常に検証され、アイデンティティ・プロバイダがトークンが有効であると判断したときに、次のJSONをHTTP 200レスポンスとしてAPIゲートウェイに戻す認可プロバイダ・ファンクションのコードを記述します:

   {
     "active": true,
     "scope": ["<scopes>"],
     "expiresAt": "<date-time>",
     "context": {
       "<key>": "<value>", ... 
     }
   }

   ここでは:

   • "active": trueは、アイデンティティ・プロバイダが、認可プロバイダ・ファンクションに最初に渡されたアクセス・トークンが有効であると判断したことを示します。このブール・フィールドはオプションですが、JSONレスポンスに含まれていない場合は、デフォルトでfalseになります。
   • "scope": ["<scopes>"]は、オプションで、アイデンティティ・プロバイダの認可プロバイダ・ファンクションによって取得されるアクセス・スコープです。["<scopes>"]には、["list:hello", "read:hello", "create:hello"]などのカンマ区切り文字列のJSON配列、または"list:hello read:hello create:hello"などの空白区切りの文字列を指定できます。認可リクエスト・ポリシーのtypeプロパティがANY_OFに設定されている場合、このフィールドは必須です。
   • "expiresAt": "<date-time>"は、オプションで、ISO-8601フォーマットの日時文字列で、最初に認可プロバイダ・ファンクションに渡されるアクセス・トークンの期限を示します。この値は、認可プロバイダ・ファンクションのコール後に結果のキャッシュ期間を決定する際に使用されます。結果は60秒以上、最大1時間キャッシュできます。このフィールドがJSONレスポンスに含まれていない場合、または"<date-time>"が無効な場合、結果は60秒間キャッシュされることに注意してください。
   • "context": {"<key>": "<value>", ... }は、APIゲートウェイに戻るための、JSONフォーマットのキーと値のペアのオプションのカンマ区切りリストです。認可プロバイダ・ファンクションは、APIデプロイメントで使用する任意のキーと値のペア(たとえば、エンド・ユーザーのユーザー名や電子メール・アドレス)を返すことができます。認可プロバイダ・ファンクションによって返されるキーと値のペアでの値をHTTPバック・エンド定義のコンテキスト変数として使用する際の詳細は、ポリシーおよびHTTPバック・エンド定義へのコンテキスト変数の追加を参照してください。

   例:

   {
     "active": true,
     "scope": ["list:hello", "read:hello", "create:hello", "update:hello", "delete:hello", "someScope"],
     "expiresAt": "2019-05-30T10:15:30+01:00",
     "context": {
       "email": "john.doe@example.com"
     }
   }

   認可プロバイダ・ファンクションがレスポンスのJSON本文でHTTP 200レスポンスおよびactive: trueを返すと、APIゲートウェイはAPIクライアントにHTTP 200レスポンスを返します。

3. Write code in the authorizer function that returns the following JSON to API Gateway as an HTTP 200 response when the user-defined, multi-argument access token has been successfully verified with an identity provider, but the identity provider has determined the token is invalid:

   {
     "active": false,
     "wwwAuthenticate": "<directive>"
   }

   ここでは:

   • "active": falseは、アイデンティティ・プロバイダが、認可プロバイダ・ファンクションに最初に渡されたアクセス・トークンが無効であると判断したことを示します。このフィールドはオプションですが、JSONレスポンスに存在しない場合はデフォルトでfalseになります。
   • "wwwAuthenticate": "<directive>"は、オプションで、アクセス・トークンが無効な場合に認可プロバイダ・ファンクションによって戻されるWWW-Authenticateヘッダーの値で、必要な認証のタイプ(BasicやBearerなど)を示します。たとえば、"wwwAuthenticate": "Bearer realm=\"example.com\""です。詳細は、RFC 2617 HTTP Authentication: Basic and Digest Access Authenticationを参照してください。

   例:

   {
     "active": false,
     "wwwAuthenticate": "Bearer realm=\"example.com\""
   }

   オプションで、APIデプロイメント仕様にvalidationFailurePolicyセクションを含めて、APIクライアントに返されるレスポンス・コード、レスポンス・メッセージおよびレスポンス・ヘッダーを変更できます。validationFailurePolicyセクションを含めない場合、APIゲートウェイは、WWW-AuthenticateヘッダーをAPIクライアントへのレスポンスで返し、401ステータス・コードも返します。「検証失敗ポリシーのノートおよび複数引数認可プロバイダ・ファンクションからの失敗した認証レスポンスの処理」を参照してください。

4. トークンをアイデンティティ・プロバイダで検証できなかった場合(トークンが有効か無効かは不明)、または認可プロバイダ・ファンクションまたはOCIファンクションでエラーが発生した場合に、HTTP 5xxレスポンスを返す認可プロバイダ・ファンクションにコードを記述します。

   認可プロバイダ・ファンクションがHTTP 5xxレスポンスを返すと、APIゲートウェイはAPIクライアントにHTTP 502レスポンスを返します。レスポンスの本文内のJSONは無視されます。

リクエスト・ヘッダーまたは問合せパラメータに含まれる単一値で構成される単一引数アクセス・トークンを受け入れる認可プロバイダ・ファンクションを作成するには:

1. APIゲートウェイからの次のJSON入力を受け入れる認可プロバイダ・ファンクションのコードを記述します:

   
   {
     "type": "TOKEN",
     "token": "<token-value>"
   }

   ここでは:

   • "type": "TOKEN"は、認可プロバイダ・ファンクションに渡される値が認証トークンであることを示します。
   • "token": "<token-value>"は、認可プロバイダ・ファンクションに渡される認証トークンです。

   例:

   
   {
     "type": "TOKEN",
     "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1nHyDtTwR3SEJ3z489..."
   }

2. アクセス・トークンがアイデンティティ・プロバイダで正常に検証され、アイデンティティ・プロバイダがトークンが有効であると判断したときに、次のJSONをHTTP 200レスポンスとしてAPIゲートウェイに戻す認可プロバイダ・ファンクションのコードを記述します:

   {
     "active": true,
     "scope": ["<scopes>"],
     "expiresAt": "<date-time>",
     "context": {
       "<key>": "<value>", ... 
     }
   }

   ここでは:

   • "active": trueは、アイデンティティ・プロバイダが、認可プロバイダ・ファンクションに最初に渡されたアクセス・トークンが有効であると判断したことを示します。このブール・フィールドはオプションですが、JSONレスポンスに含まれていない場合は、デフォルトでfalseになります。
   • "scope": ["<scopes>"]は、オプションで、アイデンティティ・プロバイダの認可プロバイダ・ファンクションによって取得されるアクセス・スコープです。Note that ["<scopes>"] can be either a JSON array of comma-delimited strings, such as ["list:hello", "read:hello", "create:hello"], or a space-separated string such as "list:hello read:hello create:hello" .認可リクエスト・ポリシーのtypeプロパティがANY_OFに設定されている場合、このフィールドは必須です。
   • "expiresAt": "<date-time>" is optionally a date-time string in ISO-8601 format indicating when the access token originally passed to the authorizer function will expire.この値は、認可プロバイダ・ファンクションのコール後に結果のキャッシュ期間を決定する際に使用されます。結果は60秒以上、最大1時間キャッシュできます。Note that if this field is not included in the JSON response, or if "<date-time>" is invalid, results are cached for 60 seconds.
   • "context": {"<key>": "<value>", ... }は、APIゲートウェイに戻るための、JSONフォーマットのキーと値のペアのオプションのカンマ区切りリストです。The authorizer function can return any key-value pair for use by the API deployment (for example, the username or email address of an end user).認可プロバイダ・ファンクションによって返されるキーと値のペアでの値をHTTPバック・エンド定義のコンテキスト変数として使用する際の詳細は、ポリシーおよびHTTPバック・エンド定義へのコンテキスト変数の追加を参照してください。

   例:

   {
     "active": true,
     "scope": ["list:hello", "read:hello", "create:hello", "update:hello", "delete:hello", "someScope"],
     "expiresAt": "2019-05-30T10:15:30+01:00",
     "context": {
       "email": "john.doe@example.com"
     }
   }

   When the authorizer function returns an HTTP 200 response and active: true in the JSON body of the response, API Gateway returns an HTTP 200 response to the API client.

   単一引数認可プロバイダ・ファンクションからのレスポンスの形式は、複数引数認可プロバイダ・ファンクションからのレスポンスと同じであることに注意してください(「複数引数認可プロバイダ・ファンクションの作成(推奨)」を参照)。

3. Write code in the authorizer function that returns the following JSON to API Gateway as an HTTP 200 response when the access token has been successfully verified with an identity provider, but the identity provider has determined the token is invalid:

   {
     "active": false,
     "wwwAuthenticate": "<directive>"
   }

   ここでは:

   • "active": falseは、アイデンティティ・プロバイダが、認可プロバイダ・ファンクションに最初に渡されたアクセス・トークンが無効であると判断したことを示します。Note that this field is optional, but defaults to false if not present in the JSON response.
   • "wwwAuthenticate": "<directive>" is optionally the value of the WWW-Authenticate header to be returned by the authorizer function if the access token is invalid, indicating the type of authentication that is required (such as Basic or Bearer).たとえば、"wwwAuthenticate": "Bearer realm=\"example.com\""です。詳細は、RFC 2617 HTTP Authentication: Basic and Digest Access Authenticationを参照してください。

   例:

   {
     "active": false,
     "wwwAuthenticate": "Bearer realm=\"example.com\""
   }

   APIゲートウェイは、WWW-AuthenticateヘッダーをAPIクライアントへのレスポンスで返し、401ステータス・コードも返します。

   単一引数認可プロバイダ・ファンクションからのレスポンスの形式は、複数引数認可プロバイダ・ファンクションからのレスポンスと同じであることに注意してください(「複数引数認可プロバイダ・ファンクションの作成(推奨)」を参照)。

4. Write code in the authorizer function that returns an HTTP 5xx response if the token could not be verified with the identity provider (so it is not known whether the token is valid or invalid), or in the event of an error in the authorizer function or in OCI Functions.

   When the authorizer function returns an HTTP 5xx response, API Gateway returns an HTTP 502 response to the API client. Any JSON in the body of the response is ignored.

認可プロバイダ・ファンクションの例が示された関連する開発者チュートリアルについては、ファンクション: APIゲートウェイを使用したAPIキーの検証を参照してください。