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

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

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

   {
     "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>"]は、オプションで、アイデンティティ・プロバイダの認可プロバイダ・ファンクションによって取得されるアクセス・スコープです。["<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. アクセス・トークンがアイデンティティ・プロバイダで正常に検証されたが、アイデンティティ・プロバイダがトークンが無効であると判断した場合、次のJSONをHTTP 200レスポンスとしてAPIゲートウェイに戻す認可プロバイダ・ファンクションのコードを記述します:

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

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

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

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

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