トークンの検証によるAPIデプロイメントへの認証および認可の追加

JWTを使用してAPIデプロイメントの認証および認可を有効化する前に:

• OAuth2準拠のアイデンティティ・プロバイダ(たとえば、アイデンティティ・ドメインを使用するOCI IAM、Oracle Identity Cloud Service (IDCS)、Auth0)が、APIデプロイメントへのアクセスを許可されたユーザーに対してJWTを発行するようにすでに設定されている必要があります。
• 認可ポリシーでカスタム・クレームを使用する場合は、発行するJWTにカスタム・クレームを追加するようにアイデンティティ・プロバイダを設定する必要があります。

詳細は、アイデンティティ・プロバイダ・ドキュメント(たとえば、アイデンティティ・ドメインのあるOCI IAMドキュメント、Oracle Identity Cloud Service (IDCS)ドキュメント、Auth0ドキュメント)を参照してください)。

発行元のアイデンティティ・プロバイダによって提供された対応する公開検証キーを使用してJWTを検証するには:

• JWTの署名の生成に使用される署名アルゴリズムは、RS256、RS384またはRS512のいずれかである必要があります
• 公開検証キーの最小長は2048ビットで、4096ビットを超えることはできません

認可サーバーのイントロスペクション・エンドポイントを使用してトークンを検証するには:

• クライアント資格証明(クライアントIDとクライアント・シークレット)を取得するには、すでにクライアント・アプリケーションを作成して認可サーバーに登録している必要があります。詳細は、認可サーバーのドキュメント(たとえば、アイデンティティ・ドメインのあるOCI IAMドキュメント、Oracle Identity Cloud Service (IDCS)ドキュメント、Auth0ドキュメント)を参照してください)。
• 認可サーバーから取得したクライアント・シークレットをシークレットとしてVaultサービスのボールトにすでに格納している必要があり(Vaultでのシークレットの作成を参照)、シークレットのOCIDおよびバージョン番号を知っている必要があります。
• クライアント・シークレットを含むボールト・シークレットにアクセスするには、動的グループ内のAPIゲートウェイに権限を付与するポリシーをすでに設定しておく必要があります(Vaultサービスでシークレットとして格納された資格証明にAPIゲートウェイへのアクセス権を付与するポリシーの作成を参照)。

コンソールを使用してAPIデプロイメント仕様に認証および認可リクエスト・ポリシーを追加するには:

1. コンソールを使用してAPIデプロイメントを作成し、「最初から」オプションを選択して、「基本情報」ページで詳細を入力します。

   詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイの更新を参照してください。

2. 「次へ」を選択して、「認証」ページを表示します。

3. 「単一認証」を選択して、すべてのリクエストに単一の認証サーバーを使用することを指定します。

   これらの手順では、単一の認証サーバーを使用することを前提としています。または、複数の認証サーバーを使用する場合は、「複数認証」を選択し、コンソールを使用した同じAPIデプロイメントへの複数の認証サーバーの追加の手順に従います。

4. 「匿名アクセスの有効化」チェック・ボックスを選択または選択解除して、未認証(つまり匿名)エンド・ユーザーがAPIデプロイメントのルートにアクセスできるかどうかを指定します。

   デフォルトでは、このオプションは選択されていません。匿名のユーザーがルートにアクセスできないようにする場合は、このオプションを選択しないでください。このオプションを選択した場合は、各ルートの認可ポリシーで「匿名」を「認可タイプ」として選択することで、匿名アクセスを許可する各ルートを明示的に指定する必要もあります。

5. 「認証タイプ」オプション・リストからOAuth 2.0 / OpenID Connectを選択し、次を指定します:
   • トークンの場所:トークンがリクエスト・ヘッダーまたは問合せパラメータに含まれるかどうか。

   • 認証トークンの詳細:トークンがリクエスト・ヘッダーに含まれているか問合せパラメータに含まれているかに応じて、次を指定します:

     • トークン・ヘッダー名:および認証スキーム:トークンがリクエスト・ヘッダーに含まれている場合は、ヘッダーの名前(たとえば、Authorization)およびHTTP認証スキーム(Bearerのみが現在サポートされています)。
     • トークン・パラメータ名:トークンが問合せパラメータに含まれる場合は、問合せパラメータの名前を入力します。
6. APIゲートウェイでトークンを検証する方法を指定します:

   1. APIゲートウェイで、クライアント資格証明(Vaultサービスのボールトから取得されたクライアント・シークレットを含む)を使用して、OAuth 2.0認可サーバーのイントロスペクション・エンドポイントを使用してJWTトークンと非JWTトークンの両方を検証する場合は、「タイプ」リストからOAuth 2.0イントロスペクション・エンドポイントを選択し、次を指定します:

      • クライアントID:イントロスペクション・エンドポイントに送信するクライアントID。クライアントIDを取得するには、クライアント・アプリケーションを作成して認可サーバーに登録します。たとえば、5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1です。トークン認証の前提条件を参照してください。
      • <compartment-name>のVault:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むVaultサービス内のボールトの名前。クライアント・シークレットを取得するには、クライアント・アプリケーションを作成して認可サーバーに登録します。トークン認証の前提条件を参照してください。
      • <compartment name>のVaultシークレット:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットの名前。
      • Vaultシークレット・バージョン番号:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのバージョン。
      • 検出URL: APIゲートウェイが認可メタデータ・エンドポイントを取得する認可サーバーの既知のURL。たとえば、https://my-idp/oauth2/default/.well-known/openid-configurationです。

        URLは、APIがデプロイされているAPIゲートウェイを含むサブネットからルーティングできる必要があることに注意してください。

      • 最大キャッシュ期間(時間): APIゲートウェイがイントロスペクション・エンドポイントからレスポンスをキャッシュする時間数(1から24)。
      • 最大クロック・スキュー(秒): (オプション)トークンを発行した認可サーバーのシステム・クロックとAPIゲートウェイ間の最大時間差。ここに入力した値は、APIゲートウェイがJWTの有効期限(nbf)クレーム(ある場合)および有効期限(exp)クレームを使用して、JWTを検証して有効かどうかを判断するときに考慮されます。最小値(およびデフォルト)は0、最大値は120です。
      • SSL検証の無効化:認可サーバーとの通信時にSSL検証を無効化するかどうか。デフォルトでは、このオプションは選択されていません。このオプションは、トークン検証が損なわれる可能性があるため、Oracleでは選択しないでください。APIゲートウェイは、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaを使用して、OCI IAMに対して発行された複数の認証局からの証明書を信頼します。

   2. 実行時にアイデンティティ・プロバイダから公開検証キーを取得してAPIゲートウェイでJWTを検証する場合は、「タイプ」リストから「リモートJWKS」を選択し、次を指定します:

      • JWKS URI: JWTの署名の検証に使用するJSON Web Key Set (JWKS)の取得元のURI。たとえば、https://www.somejwksprovider.com/oauth2/v3/certsです。指定するURIの詳細は、issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。

        次に注意してください:

        • URIは、APIがデプロイされているAPIゲートウェイを含むサブネットからルーティングできる必要があります。

        • APIゲートウェイがJWKSの取得に失敗した場合、APIデプロイメントへのすべてのリクエストはHTTP 500レスポンス・コードを返します。エラーの詳細は、APIゲートウェイの実行ログを参照してください(APIデプロイメントへのロギングの追加を参照)。
        • JWTの署名を検証するには、JWKSに特定のキー・パラメータが存在する必要があります(JWT署名の検証に必要なキー・パラメータを参照)。
        • JWKSには最大10個のキーを含めることができます。
      • 最大キャッシュ期間(時間): APIゲートウェイがJWKSを取得後にキャッシュする時間数(1から24)。
      • SSL検証の無効化:アイデンティティ・プロバイダとの通信時にSSL検証を無効にします。デフォルトでは、このオプションは選択されていません。JWT検証が損なわれる可能性があるため、Oracleではこのオプションを選択しないことをお薦めします。APIゲートウェイは、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaを使用して、OCI IAMに対して発行された複数の認証局からの証明書を信頼します。

   3. APIゲートウェイで、アイデンティティ・プロバイダによってすでに発行されている公開検証キーを使用してJWTを検証する場合(アイデンティティ・プロバイダに接続せずにAPIゲートウェイでJWTをローカルに検証できるようにする場合)は、「タイプ」リストから「静的キー」を選択して、最大10個の静的キーを指定します:

      • キーID: JWTの署名に使用される静的キーの識別子。値はJWTヘッダーのkidクレームと一致する必要があります。たとえば、master_keyです。

      • キー形式: JSON WebキーまたはPEMエンコードされた公開キーとしての静的キーの形式。

        • JSON Webキー:静的キーがJSON Webキーの場合は、このフィールドにキーを貼り付けます。

          例:

          {
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
          

          JWTの署名を検証するには、静的キーに特定のキー・パラメータが存在する必要があります(JWT署名の検証に必要なキー・パラメータを参照)。また、現在サポートされているキー・タイプ(kty)はRSAのみであることにも注意してください。

        • PEMでエンコードされたパブリック・キー:静的キーがPEMでエンコードされたパブリック・キーの場合は、このフィールドにキーを貼り付けます。例:

          -----BEGIN PUBLIC KEY-----
          XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH
          -----END PUBLIC KEY-----
          

          -----BEGIN PUBLIC KEY-----および-----END PUBLIC KEY-----マーカーが必要です。

      • 別のキー:キーを追加する場合に選択します(最大10個)。
7. (オプション)JWTトークン検証の追加詳細を指定します:

   1. 「発行者」セクションで、APIデプロイメントへのアクセスに使用されるJWTの発行者(iss)クレームで許可される値を指定します:

      • 許可される発行者: APIデプロイメントへのアクセスに使用されるJWTの発行者(iss)クレームで許可されるアイデンティティ・プロバイダのURL (またはテキスト文字列)を指定します。たとえば、アイデンティティ・ドメインを持つOCI IAMによって発行されたJWTをAPIデプロイメントへのアクセスに使用できるようにするには、https://identity.oraclecloud.com/と入力します。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
      • 別の発行者:アイデンティティ・プロバイダを追加する場合に選択します(最大5人)。

   2. 「オーディエンス」セクションで、APIデプロイメントへのアクセスに使用されるJWTのオーディエンス(aud)クレームで許可される値を指定します:

      • 許可されるオーディエンス: JWTのオーディエンス(aud)クレームで許可される値を指定して、トークンの目的の受信者を識別します。たとえば、オーディエンスはAPIゲートウェイのホスト名である場合がありますが、必ずしもそうである必要はありません。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
      • 別のオーディエンス:オーディエンスを追加する場合に選択します(最大5人)。

   3. クレーム検証: (オプション)指定したオーディエンスaudおよび発行者issクレームの値に加えて、JWTで検証する1つ以上の追加クレームの名前と値を指定できます。入力するキーの名前と値は単純に文字列として扱われ、JWTの名前および値と完全に一致する必要があります。パターン一致およびその他のデータ型はサポートされていません。

      • Claim is required: 「Claim key」フィールドのクレームをJWTに含めるかどうかを指定します。
      • クレーム・キー: (オプション) JWTに含めることができる、またはJWTに含める必要があるクレームの名前を指定します。JWTにクレームを含める必要がある場合は、「必須」を選択します。指定するクレーム名には、サブジェクト(sub)クレームなどの予約済クレーム名、または特定のアイデンティティ・プロバイダによって発行されたカスタム・クレーム名を指定できます。
      • クレーム値: (オプション)クレームの許容値を「クレーム・キー」フィールドに指定します。プラス記号(+)を選択して、別の許容値を入力します。クレームに1つ以上の許容値を指定すると、APIゲートウェイは指定した値のいずれかがクレームにあることを検証します。

      JWTでは、値を指定せずにクレームを指定できます。そのためには、「要求キー」フィールドに要求の名前を入力し、「要求値」フィールドを空白のままにして、必要に応じて「要求は必須」を設定します。

8. 検証失敗ポリシーを設定して、失敗した認証レスポンスをAPIゲートウェイで処理する方法(欠落または無効なトークンを検証しようとして失敗した後に戻される)を指定します:
   1. APIゲートウェイでHTTP 401ステータス・コードおよびレスポンスのWWW-Authenticateヘッダー(欠落または無効なトークンに対するデフォルトのレスポンス)を送信する場合は、「デフォルト(HTTP 401 Unauthorized)」を選択します。

   2. APIゲートウェイでOpenID Connect認可フローを使用して新しいJWTアクセス・トークンを取得する場合は、OAuth 2.0を選択します。このオプションは、前の「検証タイプ」リストからOAuth 2.0イントロスペクション・エンドポイントを選択した場合にのみ使用できます。次を指定します:

      • スコープ:認可サーバーに送信されるscopeクレームに含める1つ以上のアクセス・スコープ。OpenID Connect認可フローを使用するには、openidをスコープの1つとして含める必要があります。たとえば、openid、email:read、profileです。
      • レスポンス・タイプ:認可フローから必要なレスポンスのタイプ。レスポンス・タイプとしてcodeと入力します。
      • フォールバック・リダイレクト・パス: (オプション)元のリクエストがPUTリクエストまたはPOSTリクエストであった場合にAPIクライアントをリダイレクトする、現在のAPIデプロイメントの相対パス。例: /home

        元のリクエストがGETリクエストの場合、リクエスト処理は新しいJWTアクセス・トークンで再開されるため、フォールバック・パスは使用されません。

      • ログアウト・パス: (オプション)現在のAPIデプロイメントのログアウト・バック・エンドへの相対パス。指定するパスは、ログアウト・バック・エンドに定義されているルート・パスと一致する必要があります。たとえば、/revokeです。

        APIクライアントは、ログアウト・バック・エンドをコールしてトークンを取り消すことができます。ログアウト・バック・エンドのコールには、postLogoutUrlという名前の問合せパラメータとしてログアウト後のURLを含めることができます。「APIゲートウェイ・バック・エンドとしてのログアウトの追加」を参照してください。

      • レスポンス有効期限(時間): (オプション)認可フローによって生成されたJWTトークンをキャッシュする時間の長さ。デフォルトは1時間です。
      • OAuth2イントロスペクション・エンドポイント・クライアント資格証明の使用: OAuth 2.0イントロスペクション・エンドポイントで以前に指定したものと同じクライアント詳細を使用して、新しいJWTアクセス・トークンを取得するかどうかを指定します(通常はそうです)。以前に指定した詳細を使用しない場合は、次のように、認可サーバーから新しいJWTアクセス・トークンを取得するために使用する別のクライアント詳細を入力します。
        • クライアントID:イントロスペクション・エンドポイントに送信するクライアントID。たとえば、5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1です。
        • <compartment-name>のVault:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むVaultサービス内のボールトの名前。
        • <compartment name>のVaultシークレット:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットの名前。
        • Vaultシークレット・バージョン番号:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのバージョン。

      オプションで、OpenID認可フロー中に取得されたトークンおよび値をCookieに格納するように選択するには、「拡張オプションの表示」を選択し、次を選択します。

      • セッションにCookieを使用: (オプション)新しく生成されたJWTトークンを、OpenID Connect認可フローの最後に人間が読めない文字列として格納する方法を指定します:
        • 新しいJWTトークンをセッションCookieに格納する場合は、このオプションを選択します。潜在的なCSRF攻撃を防ぐために、APIゲートウェイがトークンをセッションCookieに格納すると、X-CSRF-TOKENレスポンス・ヘッダーにCSRFトークンも返されます。APIゲートウェイへの後続のリクエスト(GETリクエストを除く)では、自動的に含まれるセッションCookieのJWTトークンに加えて、X-CSRF-TOKENリクエスト・ヘッダーにCSRFトークンを含める必要があります。
        • 新しいJWTトークンをセッションCookieに格納しない場合は、このオプションを選択しないでください。かわりに、APIゲートウェイは、X-APIGW-TOKENレスポンス・ヘッダーに人間が読めないトークンを返します。APIゲートウェイへの後続のリクエストでは、X-APIGW-TOKENリクエスト・ヘッダーに同じトークンを含める必要があります。

        Cross-Site Request Forgery (CSRF) Protectionに関するノートを参照してください。

      • 中間ステップにCookieを使用: (オプション)認可フロー中間ステップ値(リクエスト・パラメータなど)の格納方法を指定します。ブラウザCookieに値を格納するには、このオプションを選択します。APIゲートウェイで値を格納するには、このオプションの選択を解除します。
      • PKCEの使用: (オプション)追加のセキュリティのためにPKCE (コード交換の証明キー)を使用するかどうかを指定します。PKCEは、CSRF (クロスサイト・リクエスト・フォージェリ)および認可コード・インジェクション攻撃を防ぐためのOAuth 2.0セキュリティ拡張です。PKCEはクライアント・シークレットの代わりにはなりません。また、クライアント・シークレットが使用されている場合でもPKCEをお薦めします。PKCEの詳細は、OAuth 2.0のドキュメントを参照してください。
   3. 欠落または無効なトークンを検証しようとして失敗したレスポンスをカスタマイズする場合は、「カスタム・レスポンス」を選択し、ステータス・コード(およびオプションのメッセージ本文)を指定してAPIクライアントに戻ります。
      • HTTPステータス・コード:代替HTTPステータス・コードを入力します。例: 500
      • メッセージ本文:メッセージ本文を入力します。たとえば、Unfortunately, authentication failed.メッセージ本文には、任意のコンテキスト変数(request.bodyを除く)を含めることができます。
      • オプションで、ヘッダー変換レスポンス・ポリシーを指定して、APIゲートウェイがAPIクライアントに返すレスポンスのヘッダーを変更します。ヘッダー変換ポリシーの詳細は、「ヘッダー変換レスポンス・ポリシーの追加」を参照してください。

9. 「次」を選択して、「ルート」ページのAPIデプロイメント内の個々のルートの詳細を入力します。

10. 「ルート1」セクションで、1つのパスと1つ以上のメソッドをバックエンド・サービスにマップするAPIデプロイメントの最初のルートを指定します:

    • パス: リストされたメソッドを使用したバックエンド・サービスへのAPIコールのパス。指定するルート・パスで次の点に注意してください:

      • デプロイメント・パス接頭辞に対して相対的です
      • 先頭にスラッシュ(/)を付ける必要があります。単一のスラッシュのみも可能です
      • スラッシュは複数使用でき(連続していない場合)、スラッシュで終了できます
      • 英数字の大文字と小文字を使用できます
      • 特殊文字$ - _ . + ! * ' ( ) , % ; : @ & = を使用できます
      • パラメータおよびワイルドカードを使用できます(ルート・パスへのパス・パラメータおよびワイルドカードの追加を参照)
    • メソッド: バックエンド・サービスが受け入れる1つ以上のメソッド(カンマ区切り)。たとえば、GET, PUTです。

    • 単一のバックエンドの追加または複数のバックエンドの追加: すべてのリクエストを同じバックエンドにルーティングするか、入力したコンテキスト変数およびルールに従ってリクエストを異なるバックエンドにルーティングするか。

      これらの手順では、単一のバックエンドを使用することを想定しているため、「単一のバックエンドの追加」を選択します。または、異なるバック・エンドを使用する場合は、「複数のバックエンドの追加」を選択し、コンソールを使用したAPIデプロイメント仕様への動的バック・エンド選択の追加の手順に従います。

    • バックエンド・タイプ:バックエンド・サービスのタイプ。次のいずれかです:
      • HTTP: HTTPバック・エンドの場合、URL、タイムアウト詳細、およびSSL検証を無効にするかどうかを指定する必要もあります(APIゲートウェイ・バック・エンドとしてのHTTPまたはHTTPS URLの追加を参照)。
      • Oracle Functions: OCIファンクション・バック・エンドの場合、アプリケーションとファンクションを指定することもできます(APIゲートウェイ・バック・エンドとしてのOCIファンクションでのファンクションの追加を参照)。
      • 標準レスポンス: 標準レスポンス・バック・エンドの場合、HTTPステータス・コード、レスポンス本文のコンテンツ、および1つ以上のHTTPヘッダー・フィールドを指定する必要もあります(APIゲートウェイ・バック・エンドとしての標準レスポンスの追加を参照)。
      • ログアウト: ログアウト・バック・エンドの場合、トークンを取り消すためにリクエストをリダイレクトできる許可されたURLのリスト、およびオプションでログアウトURLに渡すデータ(APIゲートウェイ・バック・エンドとしてのログアウトの追加を参照)も指定する必要があります。

11. 個々のルートに適用する認可ポリシーを指定するには、「リクエスト・ポリシーのルーティングを表示」を選択し、「認可」の横にある「追加」ボタンを選択して、次を指定します:

    • 認可タイプ: ルートへのアクセス権を付与する方法。次を指定します:

      • 任意: JWTで「許可されるスコープ」フィールドに指定したアクセス・スコープの少なくとも1つを含むscopeクレームがある場合にのみ、正常に認証されたエンド・ユーザーにアクセス権を付与します。この場合、認証ポリシーの「匿名アクセスの有効化」オプションは無効です。
      • 匿名: JWTを使用して正常に認証されていない場合でも、すべてのエンド・ユーザーにアクセス権を付与します。この場合、認証ポリシーの「匿名アクセスの有効化」オプションを選択しておく必要があります。
      • 認証のみ: JWTを使用して正常に認証されたエンド・ユーザーにのみアクセス権を付与します。この場合、認証ポリシーの「匿名アクセスの有効化」オプションは無効です。
    • 許可されるスコープ: 「認可タイプ」として「任意」を選択した場合は、JWTのアクセス・スコープに対応する1つ以上の文字列のカンマ区切りリストを入力します。アクセス権は、指定したアクセス・スコープのいずれかを含むscopeクレームがJWTにある場合に、正常に認証されたエンド・ユーザーにのみ付与されます。たとえば、read:helloです
    ノート
    
    

    特定のルートの認可ポリシーを含めない場合、そのようなポリシーが存在するかのようにアクセスが付与され、「認可タイプ」が「認証のみ」に設定されます。つまり、認証ポリシーの「匿名アクセスの有効化」オプションの設定に関係なく、次のようになります:

    • ルートにアクセスできるのは、認証されたエンド・ユーザーのみです
    • JWTのscopeクレームのアクセス・スコープに関係なく、すべての認証済エンド・ユーザーがルートにアクセスできます
    • 匿名のエンド・ユーザーはルートにアクセスできません
12. 「変更の適用」を選択し、「次」を選択してAPIデプロイメントに入力した詳細を確認します。
13. APIデプロイメントを作成または更新するには、「作成」または「変更の保存」を選択します。
14. (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

JSONファイルのAPIデプロイメント仕様に認証および認可リクエスト・ポリシーを追加するには:

1. 任意のJSONエディタを使用して、認証および認可機能を追加する既存のAPIデプロイメント仕様を編集するか、新しいAPIデプロイメント仕様を作成します(APIデプロイメント仕様の作成を参照)。

   APIデプロイメント仕様には、少なくとも次の内容を含むroutesセクションが含まれます:

   • パス。たとえば、/helloです
   • 1つ以上のメソッド。たとえば、GETです
   • バック・エンドの定義。たとえば、URLまたはOCIファンクション内のファンクションのOCIDです。

   たとえば、次の基本的なAPIデプロイメント仕様では、OCI Functionsの単純なHello Worldサーバーレス・ファンクションを単一のバック・エンドとして定義しています:

   コピー

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

2. APIデプロイメント仕様のすべてのルートに適用されるauthenticationリクエスト・ポリシーを作成するには、routesセクションの前にrequestPoliciesセクションを挿入します(まだ存在しない場合)。例:

   コピー

   
   {
     "requestPolicies": {},
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

3. 次のようにauthenticationリクエスト・ポリシーを追加します。

   コピー

   
   {
     "requestPolicies": {
       "authentication": {
         "type": "TOKEN_AUTHENTICATION",
         <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">,
         "tokenAuthScheme": "<authentication-scheme>",
         "isAnonymousAccessAllowed": <true|false>,
         "maxClockSkewInSeconds": <seconds-difference>,
         "validationPolicy": {<validation-policy-config>},
       }
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

   ここでは:

   • "authentication": {"type": "TOKEN_AUTHENTICATION"...は、認証にトークンを使用することを指定します。
   • <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">は、トークンを含むリクエスト・ヘッダーであるか(そうであれば、ヘッダーの名前)またはトークンを含む問合せパラメータであるか(そうであれば、問合せパラメータの名前)を示します。"tokenHeader": "<token-header-name>"または"tokenQueryParam": "<token-query-param-name>">のいずれかを指定できますが、両方を指定することはできません。たとえば、"tokenHeader": "Authorization"です。
   • <tokenAuthScheme>は、トークンがリクエスト・ヘッダーに含まれる場合に使用する認証スキームの名前です。たとえば、"Bearer"です。
   • "isAnonymousAccessAllowed": <true|false>は、オプションで、未証(つまり、匿名)のエンド・ユーザーがAPIデプロイメント仕様のルートにアクセスできるかどうかを示します。匿名のエンド・ユーザーがルートにアクセスできないようにする場合は、このプロパティをfalseに設定します。このプロパティをauthenticationポリシーに含めない場合、デフォルトのfalseが使用されます。このプロパティを使用してtrueに設定する場合は、各ルートのauthorizationポリシーでtypeプロパティを"ANONYMOUS"に設定することで、匿名アクセスが許可されているすべてのルートを明示的に指定する必要もあります。
   • maxClockSkewInSeconds: <seconds-difference>では、JWTを発行したアイデンティティ・プロバイダのシステム・クロックとAPIゲートウェイの間の最大時間差をオプションで指定します。指定した値は、APIゲートウェイがJWTの有効開始日(nbf)クレーム(存在する場合)および有効期限(exp)クレームを使用して、JWTを検証して有効かどうかを判断するときに考慮されます。最小(およびデフォルト)は0、最大は120です。
   • "validationPolicy": {<validation-policy-config>}は、次のステップで説明するように、トークンを検証する検証ポリシーを指定します。
4. APIゲートウェイで、クライアント資格証明(Vaultサービスのボールトから取得されたクライアント・シークレットを含む)を使用して、OAuth 2.0認可サーバーのイントロスペクション・エンドポイントを使用してJWTトークンと非JWTトークンの両方を検証する場合は、空のvalidationPolicyセクションに次の検証ポリシーを追加します。

         "validationPolicy": {
           "type": "REMOTE_DISCOVERY",          
           "clientDetails": {
             "type": "CUSTOM",
             "clientId": "<client-id>",
             "clientSecretId": "<secret-ocid>",
             "clientSecretVersionNumber": <secret-version-number>
           },          
           "sourceUriDetails": {
             "type": "DISCOVERY_URI",
             "uri": "<well-known-uri>"
           },
           "isSslVerifyDisabled": <true|false>,
           "maxCacheDurationInHours": <cache-time>,
           "additionalValidationPolicy": {
             "issuers": ["<issuer-url>", "<issuer-url>"],
             "audiences": ["<intended-audience>"],
             "verifyClaims": [{
               "key": "<claim-name>",
               "values": ["<acceptable-value>", "<acceptable-value>"],
               "isRequired": <true|false>
             }]
           }
         }

   ここでは:

   • "validationPolicy": {"type": "REMOTE_DISCOVERY"...}は、クライアント資格証明(Vaultサービスのボールトから取得されたクライアント・シークレットを含む)を使用して、OAuth 2.0認可サーバーのイントロスペクション・エンドポイントでトークンを検証することを指定します。
   • clientDetails": {"type": "CUSTOM"...}は、Vaultサービスのボールトから取得するクライアント・シークレットの詳細を指定します:
     • "clientId": "<client-ID>"は、イントロスペクション・エンドポイントに送信するクライアントIDを指定します。クライアントIDを取得するには、クライアント・アプリケーションを作成して認可サーバーに登録します。たとえば、5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1です。トークン認証の前提条件を参照してください。
     • "clientSecretId": "<secret-OCID>"は、イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのOCIDを指定します。たとえば、ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3qです。
     • "clientSecretVersionNumber": <secret-version-number>は、イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのバージョンを指定します。例: 1
   • "uri": "<well-known-uri>"は、APIゲートウェイが認可メタデータ・エンドポイントを取得する認可サーバーの既知のURLを指定します。たとえば、https://my-idp/oauth2/default/.well-known/openid-configurationです。URLは、APIがデプロイされているAPIゲートウェイを含むサブネットからルーティングできる必要があることに注意してください。
   • "isSslVerifyDisabled": <true|false>は、認可サーバーとの通信時にSSL検証を無効にするかどうかを示します。JWT検証が低下する可能性があるため、Oracleではこのオプションをtrueに設定しないことをお薦めします。APIゲートウェイは、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaを含むOCI IAMに対して発行された複数の認証局からの証明書を信頼します。
   • "maxCacheDurationInHours": <cache-time>は、APIゲートウェイがイントロスペクション・エンドポイントからレスポンスをキャッシュする時間(1から24)を指定します。
   • "additionalValidationPolicy": {"issuers": ...}は、トークン検証の追加詳細を指定します:
     • <issuer-url>は、APIデプロイメントへのアクセスに使用されるJWTの発行者(iss)クレームで許可される認可サーバーのURL (またはテキスト文字列)です。たとえば、アイデンティティ・ドメインを持つOCI IAMによって発行されたJWTをAPIデプロイメントへのアクセスに使用できるようにするには、https://identity.oraclecloud.com/を指定します。1台または複数の承認サーバーを指定できます(最大5台)。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
     • <intended-audience>は、トークンの目的の受信者を識別するためにJWTのオーディエンス(aud)クレームで許可される値です。たとえば、オーディエンスはAPIゲートウェイのホスト名である場合がありますが、必ずしもそうである必要はありません。1人のオーディエンスまたは複数のオーディエンス(最大5人)を指定できます。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
     • "verifyClaims": {...}では、JWTで検証する1つ以上の追加クレームの追加クレーム名および値をオプションで指定します(最大10個)。
       • "key": "<claim-name>"は、JWTに含めることができるクレーム、またはJWTに含める必要があるクレームの名前です。指定するクレーム名には、サブジェクト(sub)クレームなどの予約済クレーム名、または特定の認可サーバーによって発行されたカスタムクレーム名を指定できます。
       • "values": ["<acceptable-value>", "<acceptable-value>"]は、(オプションで)クレームに使用できる1つ以上の値を示します。
       • "isRequired": <true|false>は、JWTにクレームを含める必要があるかどうかを示します。

       入力するキーの名前と値は単純に文字列として扱われ、JWTの名前および値と完全に一致する必要があります。パターン一致およびその他のデータ型はサポートされていません

   たとえば、次のauthenticationポリシーは、OAuth 2.0イントロスペクション・エンドポイントに渡されるクライアント資格証明(Vaultサービスのボールトから取得されたクライアント・シークレットを含む)を使用して、認可リクエスト・ヘッダーのトークンを検証するようにAPIゲートウェイを構成します:

   コピー

   {
     "requestPolicies": {
       "authentication": {
         "type": "TOKEN_AUTHENTICATION",
         "tokenHeader": "Authorization",
         "tokenAuthScheme": "Bearer",
         "isAnonymousAccessAllowed": false,
         "maxClockSkewInSeconds": 10,
         "validationPolicy": {
           "type": "REMOTE_DISCOVERY",
           "clientDetails": {
             "type": "CUSTOM",
             "clientId": "5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1",
             "clientSecretId": "ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q",
             "clientSecretVersionNumber": 1
           },          
           "sourceUriDetails": {
             "type": "DISCOVERY_URI",
             "uri": "https://my-idp/oauth2/default/.well-known/openid-configuration"
           },
           "isSslVerifyDisabled": false,
           "maxCacheDurationInHours": 2,
           "additionalValidationPolicy": {
             "issuers": ["https://identity.oraclecloud.com/"],
             "audiences": ["api.dev.io"],
             "verifyClaims": [{
               "key": "is_admin",
               "values": ["service:app", "read:hello"],
               "isRequired": true
             }]
           }
         }
       }
     },
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

5. 実行時にアイデンティティ・プロバイダから公開検証キーを取得してAPIゲートウェイでJWTを検証する場合は、空のvalidationPolicyセクションに次の検証ポリシーを追加します:

   コピー

         "validationPolicy": {
           "type": "REMOTE_JWKS",
           "uri": "<uri-for-jwks>",
           "isSslVerifyDisabled": <true|false>,
           "maxCacheDurationInHours": <cache-time>,
           "additionalValidationPolicy": {
             "issuers": ["<issuer-url>", "<issuer-url>"],
             "audiences": ["<intended-audience>"],
             "verifyClaims": [{
               "key": "<claim-name>",
               "values": ["<acceptable-value>", "<acceptable-value>"],
               "isRequired": <true|false>
             }]
           }
         }
   

   ここでは:

   • "validationPolicy": {"type": "REMOTE_JWKS"...は、実行時にアイデンティティ・プロバイダから最大10個の公開検証キーを取得するようにAPIゲートウェイを構成することを指定します。
   • "uri": "<uri-for-jwks>"は、JWTの署名の検証に使用するJSON Web Key Set (JWKS)の取得元のURIを指定します。指定するURIの詳細は、issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。次に注意してください:
     • URIは、APIがデプロイされているAPIゲートウェイを含むサブネットからルーティングできる必要があります。
     • APIゲートウェイがJWKSの取得に失敗した場合、APIデプロイメントへのすべてのリクエストはHTTP 500レスポンス・コードを返します。エラーの詳細は、APIゲートウェイの実行ログを参照してください(APIデプロイメントへのロギングの追加を参照)。
     • JWTの署名を検証するには、JWKSに特定のキー・パラメータが存在する必要があります(JWT署名の検証に必要なキー・パラメータを参照)。
     • JWKSには最大10個のキーを含めることができます。
   • "isSslVerifyDisabled": <true|false>は、アイデンティティ・プロバイダとの通信時にSSL検証を無効にするかどうかを示します。JWT検証が低下する可能性があるため、Oracleではこのオプションをtrueに設定しないことをお薦めします。APIゲートウェイは、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaを含むOCI IAMに対して発行された複数の認証局からの証明書を信頼します。
   • "maxCacheDurationInHours": <cache-time>は、取得後にAPIゲートウェイがJWKSをキャッシュする時間数(1から24)を指定します。
   • "additionalValidationPolicy": {"issuers": ...}は、トークン検証の追加詳細を指定します:
     • <issuer-url>は、APIデプロイメントへのアクセスに使用されるJWTの発行者(iss)クレームで許可されるアイデンティティ・プロバイダのURL (またはテキスト文字列)です。たとえば、アイデンティティ・ドメインを持つOCI IAMによって発行されたJWTをAPIデプロイメントへのアクセスに使用できるようにするには、https://identity.oraclecloud.com/と入力します。1つまたは複数のアイデンティティ・プロバイダを指定できます(最大5つ)。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
     • <intended-audience>は、トークンの目的の受信者を識別するためにJWTのオーディエンス(aud)クレームで許可される値です。たとえば、オーディエンスはAPIゲートウェイのホスト名である場合がありますが、必ずしもそうである必要はありません。1人のオーディエンスまたは複数のオーディエンス(最大5人)を指定できます。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
     • verifyClaimsでは、JWTで検証する1つ以上の追加クレームの追加クレーム名および値をオプションで指定します(最大10個)。
       • "key": "<claim-name>"は、JWTに含めることができるクレーム、またはJWTに含める必要があるクレームの名前です。指定するクレーム名には、サブジェクト(sub)クレームなどの予約済クレーム名、または特定のアイデンティティ・プロバイダによって発行されたカスタム・クレーム名を指定できます。
       • "values": ["<acceptable-value>", "<acceptable-value>"]は、(オプションで)クレームに使用できる1つ以上の値を示します。
       • "isRequired": <true|false>は、JWTにクレームを含める必要があるかどうかを示します。

       入力するキーの名前と値は単純に文字列として扱われ、JWTの名前および値と完全に一致する必要があります。パターン一致およびその他のデータ型はサポートされていません

   たとえば、次のauthenticationポリシーは、実行時にアイデンティティ・プロバイダから公開検証キーを取得して、認可リクエスト・ヘッダーのJWTを検証するようにAPIゲートウェイを構成します:

   コピー

   {
     "requestPolicies": {
       "authentication": {
         "type": "TOKEN_AUTHENTICATION",
         "tokenHeader": "Authorization",
         "tokenAuthScheme": "Bearer",
         "isAnonymousAccessAllowed": false,
         "validationPolicy": {
           "type": "REMOTE_JWKS",
           "uri": "https://my-tenant-id.identity.oraclecloud.com/admin/v1/SigningCert/jwk",
           "isSslVerifyDisabled": false,
           "maxCacheDurationInHours": 2,
           "additionalValidationPolicy": {
             "issuers": ["https://identity.oraclecloud.com/"],
             "audiences": ["api.dev.io"],
             "verifyClaims": [{
               "key": "is_admin",
               "values": ["service:app", "read:hello"],
               "isRequired": true
             }]
           }
         }
       }
     },
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

6. APIゲートウェイで、アイデンティティ・プロバイダによってすでに発行されている公開検証キーを使用してJWTを検証する場合(アイデンティティ・プロバイダに接続せずにAPIゲートウェイでJWTをローカルに検証できるようにする)は、空のvalidationPolicyセクションに次の検証ポリシーを追加します:

   コピー

         "validationPolicy": {
           "type": "STATIC_KEYS",
           "keys": [{<key-config>}],
           "isSslVerifyDisabled": <true|false>,
           "maxCacheDurationInHours": <cache-time>,
           "additionalValidationPolicy": {
             "issuers": ["<issuer-url>", "<issuer-url>"],
             "audiences": ["<intended-audience>"],
             "verifyClaims": [{
               "key": "<claim-name>",
               "values": ["<acceptable-value>", "<acceptable-value>"],
               "isRequired": <true|false>
             }]
           }
         }

   ここでは:

   • "validationPolicy": {"type": "STATIC_KEYS"...は、アイデンティティ・プロバイダによってすでに発行されている最大10個の公開検証キーを使用してAPIゲートウェイを構成することを指定します(APIゲートウェイは、アイデンティティ・プロバイダに接続することなくローカルでJWTを検証できるようになります)。
   • "keys": [{<key-config>}]は、JWTの署名に使用される静的キーの識別子を指定します。指定する詳細は、アイデンティティ・プロバイダによってすでに発行されているキーの形式によって異なります(形式に関係なく、最大10個のキーを指定できます)。

     • 静的キーがJSON Webキーの場合は、"format": "JSON_WEB_KEY"を指定し、JWTの署名に使用される静的キーの識別子を"kid"パラメータの値として指定し、JWTの署名を検証するための他のパラメータの値を指定します。

       例:

       コピー

               "keys": [
                 {
                   "format": "JSON_WEB_KEY",
                   "kid": "master_key",
                   "kty": "RSA",
                   "n": "0vx7agoebGc...KnqDKgw",
                   "e": "AQAB",
                   "alg": "RS256",
                   "use": "sig"
                 }
               ]

       JWTの署名を検証するには、静的キーに特定のキー・パラメータが存在する必要があります(JWT署名の検証に必要なキー・パラメータを参照)。また、現在サポートされているキー・タイプ(kty)はRSAのみであることにも注意してください。

     • 静的キーがPEMでエンコードされた公開キーの場合は、"format": "PEM"を指定し、JWTの署名に使用される静的キーの識別子を"kid"の値として指定し、キーを"key"の値として指定します。

       例:

       コピー

               "keys": [
                 {
                   "format": "PEM",
                   "kid": "master_key"
                   "key": -----BEGIN PUBLIC KEY-----XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH-----END PUBLIC KEY-----
                 }
               ]

       -----BEGIN PUBLIC KEY-----および-----END PUBLIC KEY-----マーカーが必要です。

   • "isSslVerifyDisabled": <true|false>は、アイデンティティ・プロバイダとの通信時にSSL検証を無効にするかどうかを示します。JWT検証が低下する可能性があるため、Oracleではこのオプションをtrueに設定しないことをお薦めします。APIゲートウェイは、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaを含むOCI IAMに対して発行された複数の認証局からの証明書を信頼します。
   • "maxCacheDurationInHours": <cache-time>は、取得後にAPIゲートウェイがJWKSをキャッシュする時間数(1から24)を指定します。
   • "additionalValidationPolicy": {"issuers": ...}は、トークン検証の追加詳細を指定します:
     • <issuer-url>は、APIデプロイメントへのアクセスに使用されるJWTの発行者(iss)クレームで許可されるアイデンティティ・プロバイダのURL (またはテキスト文字列)です。たとえば、アイデンティティ・ドメインを持つOCI IAMによって発行されたJWTをAPIデプロイメントへのアクセスに使用できるようにするには、https://identity.oraclecloud.com/と入力します。1つまたは複数のアイデンティティ・プロバイダを指定できます(最大5つ)。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
     • <intended-audience>は、トークンの目的の受信者を識別するためにJWTのオーディエンス(aud)クレームで許可される値です。たとえば、オーディエンスはAPIゲートウェイのホスト名である場合がありますが、必ずしもそうである必要はありません。1人のオーディエンスまたは複数のオーディエンス(最大5人)を指定できます。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
     • verifyClaimsでは、JWTで検証する1つ以上の追加クレームの追加クレーム名および値をオプションで指定します(最大10個)。
       • "key": "<claim-name>"は、JWTに含めることができるクレーム、またはJWTに含める必要があるクレームの名前です。指定するクレーム名には、サブジェクト(sub)クレームなどの予約済クレーム名、または特定のアイデンティティ・プロバイダによって発行されたカスタム・クレーム名を指定できます。
       • "values": ["<acceptable-value>", "<acceptable-value>"]は、(オプションで)クレームに使用できる1つ以上の値を示します。
       • "isRequired": <true|false>は、JWTにクレームを含める必要があるかどうかを示します。

       入力するキーの名前と値は単純に文字列として扱われ、JWTの名前および値と完全に一致する必要があります。パターン一致およびその他のデータ型はサポートされていません

   たとえば、次のauthenticationポリシーは、アイデンティティ・プロバイダによってすでに発行された公開検証キーを使用してAPIゲートウェイを構成し、認可リクエスト・ヘッダーでJWTを検証します:

   コピー

   {
     "requestPolicies": {
       "authentication": {
         "type": "TOKEN_AUTHENTICATION",
         "tokenHeader": "Authorization",
         "tokenAuthScheme": "Bearer",
         "isAnonymousAccessAllowed": false,
         "validationPolicy": {
           "type": "STATIC_KEYS",
           "keys": [
             {
               "format": "JSON_WEB_KEY",
               "kid": "master_key",
               "kty": "RSA",
               "n": "0vx7agoebGc...KnqDKgw",
               "e": "AQAB",
               "alg": "RS256",
               "use": "sig"
             }
           ],
           "isSslVerifyDisabled": false,
           "maxCacheDurationInHours": 2,
           "additionalValidationPolicy": {
             "issuers": ["https://identity.oraclecloud.com/"],
             "audiences": ["api.dev.io"],
             "verifyClaims": [{
               "key": "is_admin",
               "values": ["service:app", "read:hello"],
               "isRequired": true
             }]
           }
         }
       }
     },
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

7. (オプション)検証失敗ポリシーを設定して、失敗した認証レスポンスをAPIゲートウェイで処理する方法を指定できます(欠落または無効なトークンを検証しようとして失敗した後に返されます)。
   1. APIゲートウェイでHTTP 401ステータス・コードおよびレスポンスのWWW-Authenticateヘッダー(欠落または無効なトークンに対するデフォルトのレスポンス)を送信する場合は、検証失敗ポリシーを定義しないでください。

   2. APIゲートウェイでOpenID Connect認可フローを使用して新しいJWTアクセス・トークンを取得する場合は、OAUTH2タイプの検証失敗ポリシーを定義します。このオプションは、以前にREMOTE_DISCOVERY型のvalidationPolicyを指定した場合にのみ使用できます。次を指定します:

      コピー

      {
        "requestPolicies": {
          "authentication": {
            "type": "TOKEN_AUTHENTICATION",
            ...
            "validationPolicy": {
              "type": "REMOTE_DISCOVERY",
              ...
            },
            "validationFailurePolicy": {
              "type": "OAUTH2",
              "scopes": ["<scope>", "<scope"],
              "clientDetails": {
                "type": "<VALIDATION_BLOCK|CUSTOM>",
                "clientId": "<client-id>",
                "clientSecretId": "<secret-ocid>",
                "clientSecretVersionNumber": <secret-version-number>
                },
              "sourceUriDetails": {
                "type": "VALIDATION_BLOCK"
                },
              "maxExpiryDurationInHours": <number-of-hours>,
              "useCookiesForSession": <true|false>,
              "useCookiesForIntermediateSteps": <true|false>,
              "usePkce": <true|false>,
              "responseType": "code",
              "fallbackRedirectPath": "<redirect-path>",
              "logoutPath": "<logout-path>"
            }
          }
        },
        "routes": [
          ...
        ]
      }

      ここでは:

      • "scopes": ["<scope>", "<scope"]は、認可サーバーに送信されるscopeクレームに含める1つ以上のアクセス・スコープを指定します。OpenID Connect認可フローを使用するには、スコープの1つとしてopenidを含める必要があります。たとえば、"scopes": ["openid", "email:read", "profile"]です。
      • clientDetails": {...}は、認可サーバーから新しいJWTアクセス・トークンを取得するために使用するクライアントの詳細を次のように指定します。
        • "type": "<VALIDATION_BLOCK|CUSTOM>"は、前のvalidationPolicyで指定されたクライアントの詳細と同じ詳細を使用するか、異なる詳細を使用するかを指定します。前と同じクライアント詳細を使用する場合(通常はそうです)、"type": "VALIDATION_BLOCK"を指定し、追加の詳細を指定しないでください。異なるクライアント詳細を使用する場合は、"type": "CUSTOM"を指定し、"clientId"、"clientSecretId"および"clientSecretVersionNumber"の値を設定します。
        • "clientId": "<client-ID>"は、イントロスペクション・エンドポイントに送信するクライアントIDを指定します。"type": "CUSTOM"の場合にのみ使用されます。たとえば、5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1です。
        • "clientSecretId": "<secret-OCID>"は、イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのOCIDを指定します。"type": "CUSTOM"の場合にのみ使用されます。たとえば、ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3qです。
        • "clientSecretVersionNumber": <secret-version-number>は、イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのバージョンを指定します。"type": "CUSTOM"の場合にのみ使用されます。例: 1
      • "sourceUriDetails": {"type": "VALIDATION_BLOCK"}は、APIゲートウェイが認可メタデータ・エンドポイントを取得する認可サーバーの既知のURLとして、以前のvalidationPolicyで指定されたものと同じURLを使用することを指定します。
      • "maxExpiryDurationInHours": <number-of-hours>は、認可フローによって生成されたJWTトークンをキャッシュする時間の長さを指定します。デフォルトは1です。
      • "useCookiesForSession": <true|false>は、新しく生成されたJWTトークンをOpenID Connect認可フローの最後に人間が読めない文字列として格納する方法を指定します:
        • セッションCookieに新しいJWTトークンを格納する場合は、このオプションをtrueに設定します。潜在的なCSRF攻撃を防ぐために、APIゲートウェイがトークンをセッションCookieに格納すると、X-CSRF-TOKENレスポンス・ヘッダーにCSRFトークンも返されます。後続のリクエスト(GETリクエスト以外)では、自動的に含まれるセッションCookieのJWTトークンに加えて、X-CSRF-TOKENリクエスト・ヘッダーにCSRFトークンを含める必要があります。
        • 新しいJWTトークンをセッションCookieに格納しない場合は、このオプションをfalseに設定します。かわりに、APIゲートウェイは、X-APIGW-TOKENレスポンス・ヘッダーに人間が読めないトークンを返します。APIゲートウェイへの後続のリクエストでは、X-APIGW-TOKENリクエスト・ヘッダーに同じトークンを含める必要があります。

        Cross-Site Request Forgery (CSRF) Protectionに関するノートを参照してください。

      • "useCookiesForIntermediateSteps": <true|false>は、認可フローの中間ステップ値(リクエスト・パラメータなど)を格納する方法を指定します。ブラウザCookieに値を格納するには、このオプションをtrueに設定します。APIゲートウェイで値を格納するには、このオプションをfalseに設定します。
      • "usePkce": <true|false>は、追加のセキュリティのためにPKCE (コード交換のプルーフ・キー)を使用するかどうかを指定します。PKCEは、CSRF (クロスサイト・リクエスト・フォージェリ)および認可コード・インジェクション攻撃を防ぐためのOAuth 2.0セキュリティ拡張です。PKCEはクライアント・シークレットの代わりにはなりません。また、クライアント・シークレットが使用されている場合でもPKCEをお薦めします。PKCEの詳細は、OAuth 2.0のドキュメントを参照してください。
      • "responseType": "code"は、認可フローから必要なレスポンスのタイプを指定します。レスポンス・タイプとしてcodeを指定します。
      • "fallbackRedirectPath": "/home"では、オプションで、元のリクエストがPUTリクエストまたはPOSTリクエストの場合にAPIクライアントをリダイレクトする現在のAPIデプロイメントの相対パスを指定します。たとえば、/homeです。

        元のリクエストがGETリクエストの場合、リクエスト処理は新しいJWTアクセス・トークンで再開されるため、フォールバック・パスは使用されません。

      • "logoutPath": "<revoke-path>"オプションで、現在のAPIデプロイメントのログアウト・バック・エンドへの相対パスを指定します。指定するパスは、ログアウト・バック・エンドに定義されているルート・パスと一致する必要があります。たとえば、"logoutPath": "/revoke"です。

        APIクライアントは、ログアウト・バック・エンドをコールしてトークンを取り消すことができます。ログアウト・バック・エンドのコールには、postLogoutUrlという名前の問合せパラメータとしてログアウト後のURLを含めることができます。「APIゲートウェイ・バック・エンドとしてのログアウトの追加」を参照してください。

      例:

      コピー

      {
        "requestPolicies": {
          "authentication": {
            "type": "TOKEN_AUTHENTICATION",
            ...
            "validationPolicy": {
              "type": "REMOTE_DISCOVERY",
              ...
            },
            "validationFailurePolicy": {
              "type": "OAUTH2",
              "scopes": ["openid", "email:read", "profile"],
              "clientDetails": {
                "type": "VALIDATION_BLOCK"
                },
              "sourceUriDetails": {
                "type": "VALIDATION_BLOCK"
              },
              "maxExpiryDurationInHours": 2,
              "useCookiesForSession": true,
              "useCookiesForIntermediateSteps": true,
              "usePkce": true,
              "responseType": "code",
              "fallbackRedirectPath": "/home",
              "logoutPath": "/revoke"
            }
          }
        },
        "routes": [
          ...
        ]
      }

   3. 欠落または無効なトークンを検証する失敗した試行に対するレスポンスをカスタマイズする場合は、次のように、MODIFY_RESPONSEタイプの検証失敗ポリシーを定義し、APIクライアントに戻るステータス・コード(およびオプションのメッセージ本文)を指定します。
      コピー

      {
        "requestPolicies": {
          "authentication": {
            "type": "TOKEN_AUTHENTICATION",
            ...
            "validationPolicy": {
              ...
            },
            "validationFailurePolicy": {
              "type": "MODIFY_RESPONSE",
              "responseCode": "<alternative-response-code>",
              "responseMessage": "<custom-message-body>",
              "responseTransformations": {
                "headerTransformations": {
                  <valid-header-transformation-response-policy>
                }
              }
            }
          }
        },
        "routes": [
          ...
        ]
      }

      ここでは:

      • responseCode: 代替HTTPステータス・コードを指定します。たとえば、500です。
      • responseMessage: (オプション)メッセージ本文を指定します。たとえば、Unfortunately, authentication failed.です。メッセージ本文には、任意のコンテキスト変数を含めることができます(request.bodyを除く)。
      • responseTransformations: (オプション)ヘッダー変換レスポンス・ポリシーを指定して、APIゲートウェイがAPIクライアントに返すレスポンスのヘッダーを変更します。ヘッダー変換ポリシーの詳細は、「ヘッダー変換レスポンス・ポリシーの追加」を参照してください。

      例:

      コピー

      {
        "requestPolicies": {
          "authentication": {
            "type": "TOKEN_AUTHENTICATION",
            ...
            "validationPolicy": {
              ...
            },
            "validationFailurePolicy": {
              "type": "MODIFY_RESPONSE",
              "responseCode": "500",
              "responseMessage": "Unfortunately, authentication failed.",
            }
          }
        },
        "routes": [
          ...
        ]
      }

8. APIデプロイメント仕様の各ルートに、authorizationリクエスト・ポリシーを追加します:

   1. 最初のルートのbackendセクションの後にrequestPoliciesセクションを挿入します(まだ存在しない場合)。例:

      コピー

      {
        "requestPolicies": {
          "authentication": {
            "type": "TOKEN_AUTHENTICATION",
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "isAnonymousAccessAllowed": false,
            "validationPolicy": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ],
              "isSslVerifyDisabled": false,
              "maxCacheDurationInHours": 2,
              "additionalValidationPolicy": {
                "issuers": ["https://identity.oraclecloud.com/"],
                "audiences": ["api.dev.io"],
                "verifyClaims": [{
                  "key": "is_admin",
                  "values": ["service:app", "read:hello"],
                  "isRequired": true
                }]
              }
            }
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {}
          }
        ]
      }

   2. 次のauthorizationポリシーを新しいrequestPoliciesセクションに追加します:

      コピー

            "requestPolicies": {
              "authorization": {
                "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, 
                "allowedScope": [ "<scope>" ]
              }
            }

      ここでは:

      • "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">は、ルートへのアクセス権を付与する方法を示します:

        • "AUTHENTICATION_ONLY": 正常に認証されたエンド・ユーザーにのみアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーの"isAnonymousAccessAllowed"プロパティは無効です。
        • "ANY_OF": JWTのscopeクレームに、allowedScopeプロパティで指定したアクセス・スコープのいずれかが含まれる場合に、正常に認証されたエンド・ユーザーにのみアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーの"isAnonymousAccessAllowed"プロパティは無効です。
        • "ANONYMOUS": 正常に認証されていない場合でも、すべてのエンド・ユーザーにアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーで"isAnonymousAccessAllowed"プロパティを明示的にtrueに設定する必要があります。
      • "allowedScope": [ "<scope>" ]は、JWTのscopeクレームに含まれるアクセス・スコープに対応する1つ以上の文字列のカンマ区切りリストです。この場合、typeプロパティを"ANY_OF"に設定する必要があります(typeプロパティが"AUTHENTICATION_ONLY"または"ANONYMOUS"に設定されている場合、"allowedScope"プロパティは無視されます)。また、複数のスコープを指定した場合、指定したスコープのいずれかがJWTのscopeクレームに含まれると、ルートへのアクセス権が付与されることにも注意してください。

      たとえば、次のリクエスト・ポリシーは、read:helloスコープを持つ認証されたエンド・ユーザーのみにアクセスを許可する/helloルートを定義します:

      コピー

      {
        "requestPolicies": {
          "authentication": {
            "type": "TOKEN_AUTHENTICATION",
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "isAnonymousAccessAllowed": false,
            "validationPolicy": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ],
              "isSslVerifyDisabled": false,
              "maxCacheDurationInHours": 2,
              "additionalValidationPolicy": {
                "issuers": ["https://identity.oraclecloud.com/"],
                "audiences": ["api.dev.io"],
                "verifyClaims": [{
                  "key": "is_admin",
                  "values": ["service:app", "read:hello"],
                  "isRequired": true
                }]
              }
            }
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "authorization": {
                "type": "ANY_OF",
                "allowedScope": [ "read:hello" ]
              }
            }
          }
        ]
      }

   3. APIデプロイメント仕様内の残りのすべてのルートに、authorizationリクエスト・ポリシーを追加します。
   ノート
   
   

   特定のルートのauthorizationポリシーを含めない場合、そのようなポリシーが存在し、typeプロパティが"AUTHENTICATION_ONLY"に設定されているかのように、アクセス権が付与されます。つまり、APIデプロイメント仕様のauthenticationポリシーでのisAnonymousAccessAllowedプロパティの設定に関係なく、次のようになります:

   • ルートにアクセスできるのは、認証されたエンド・ユーザーのみです
   • JWTのscopeクレームのアクセス・スコープに関係なく、すべての認証済エンド・ユーザーがルートにアクセスできます
   • 匿名のエンド・ユーザーはルートにアクセスできません
9. APIデプロイメント仕様を含むJSONファイルを保存します。

10. APIデプロイメント仕様は、次の方法でAPIデプロイメントを作成または更新するときに使用します:

    • JSONファイルをコンソールで「既存のAPIのアップロード」オプションで指定します
    • APIゲートウェイREST APIへのリクエストでJSONファイルを指定します

    詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイの更新を参照してください。

11. (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

JWTを発行したアイデンティティ・プロバイダによって、JWTで発行者(iss)およびオーディエンス(aud)クレームに指定する必要がある許容値が決まります。JWTを発行したアイデンティティ・プロバイダによって、JWTの署名を検証するためにJSON Web Key Set (JWKS)を取得するURIも決まります。

アイデンティティ・プロバイダに関係なく、JWKSには最大10個のキーを含めることができます。

次の表を使用して、アイデンティティ・ドメインを使用するOCI IAM、Oracle Identity Cloud Service (IDCS)、OktaおよびAuth0アイデンティティ・プロバイダによって発行されるJWTに指定する内容を確認します。

JWTの署名を検証するには、APIゲートウェイで、URIから返されたJWKSまたは指定した静的JSON Webキーのいずれかに次のキー・パラメータが存在する必要があります。

JWT_AUTHENTICATIONタイプの認証リクエスト・ポリシーを使用する場合、エンド・ユーザーは、認証および認可にJWTを使用するAPIデプロイメントにアクセスする前に、アイデンティティ・プロバイダからJWTを取得する必要があります。

APIゲートウェイにデプロイされたAPIをコールする場合、APIクライアントはJWTを問合せパラメータまたはリクエストのヘッダーとして指定します。APIゲートウェイは、発行アイデンティティ・プロバイダが提供する対応する公開検証キーを使用してJWTを検証します。APIデプロイメントのJWT_AUTHENTICATION認証リクエスト・ポリシーを使用して、APIゲートウェイがJWTをどのように検証するかを構成できます:

• 実行時にアイデンティティ・プロバイダから公開検証キーを取得するようにAPIゲートウェイを構成できます。この場合、アイデンティティ・プロバイダは認可サーバーとして機能します。
• APIゲートウェイは、アイデンティティ・プロバイダによってすでに発行されている公開検証キー(「静的キー」と呼ばれる)を使用して事前に構成できるため、APIゲートウェイはアイデンティティ・プロバイダに接続しなくても実行時にJWTをローカルで検証できます。その結果、トークン検証が高速になります。

JSONファイルのAPIデプロイメント仕様に新しいJWT_AUTHENTICATION認証および認可リクエスト・ポリシーを追加するには:

1. APIデプロイメント仕様のすべてのルートに適用するauthenticationリクエスト・ポリシーを追加します:

   1. routesセクションの前にrequestPoliciesセクションを挿入します(まだ存在しない場合)。例:

      コピー

      
      {
        "requestPolicies": {},
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
               "type": "ORACLE_FUNCTIONS_BACKEND",
               "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

   2. 次のauthenticationポリシーを新しいrequestPoliciesセクションに追加します。

      コピー

      {
        "requestPolicies": {
          "authentication": {
            "type": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": <true|false>,
            "issuers": ["<issuer-url>", "<issuer-url>"],
            <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">,
            "tokenAuthScheme": "<authentication-scheme>",
            "audiences": ["<intended-audience>"],
            "publicKeys": {
              "type": <"REMOTE_JWKS"|"STATIC_KEYS">,
              <public-key-config>
            },
            "verifyClaims": [
              {"key": "<claim-name>",
               "values": ["<acceptable-value>", "<acceptable-value>"],
               "isRequired": <true|false>
              }
            ],
            "maxClockSkewInSeconds": <seconds-difference>
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      ここでは:

      • "isAnonymousAccessAllowed": <true|false>は、オプションで、未証(つまり、匿名)のエンド・ユーザーがAPIデプロイメント仕様のルートにアクセスできるかどうかを示します。匿名のエンド・ユーザーがルートにアクセスできないようにする場合は、このプロパティをfalseに設定します。このプロパティをauthenticationポリシーに含めない場合、デフォルトのfalseが使用されます。このプロパティを使用してtrueに設定する場合は、各ルートのauthorizationポリシーでtypeプロパティを"ANONYMOUS"に設定することで、匿名アクセスが許可されているすべてのルートを明示的に指定する必要もあります。
      • <issuer-url>は、APIデプロイメントへのアクセスに使用されるJWTの発行者(iss)クレームで許可されるアイデンティティ・プロバイダのURL (またはテキスト文字列)です。たとえば、アイデンティティ・ドメインを持つOCI IAMによって発行されたJWTをAPIデプロイメントへのアクセスに使用できるようにするには、https://identity.oraclecloud.com/と入力します。1つまたは複数のアイデンティティ・プロバイダを指定できます(最大5つ)。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
      • <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">は、JWTを含むリクエスト・ヘッダーか(そうであれば、ヘッダーの名前)またはJWTを含む問合せパラメータか(そうであれば、問合せパラメータの名前)を示します。"tokenHeader": "<token-header-name>"または"tokenQueryParam": "<token-query-param-name>">のいずれかを指定できますが、両方を指定することはできません。
      • <tokenAuthScheme>は、JWTがリクエスト・ヘッダーに含まれる場合に使用する認証スキームの名前です。たとえば、"Bearer"です。
      • <intended-audience>は、トークンの目的の受信者を識別するためにJWTのオーディエンス(aud)クレームで許可される値です。たとえば、オーディエンスはAPIゲートウェイのホスト名である場合がありますが、必ずしもそうである必要はありません。1人のオーディエンスまたは複数のオーディエンス(最大5人)を指定できます。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
      • "type": <"REMOTE_JWKS"|"STATIC_KEYS">は、APIゲートウェイで公開検証キーを使用してJWTを検証する方法を示します。REMOTE_JWKSを指定して、実行時にアイデンティティ・プロバイダから最大10個の公開検証キーを取得するようにAPIゲートウェイを構成します。STATIC_KEYSを指定すると、アイデンティティ・プロバイダによってすでに発行されている最大10個の公開検証キーでAPIゲートウェイを構成できます(APIゲートウェイは、アイデンティティ・プロバイダに接続しなくてもローカルでJWTを検証できるようになります)。

      • <public-key-config>は、次のように、"type":の値として"REMOTE_JWKS"または"STATIC_KEYS"を指定したかどうかに応じてJWT検証の詳細を示します:

        • 実行時にアイデンティティ・プロバイダから公開検証キーを取得してJWTを検証するようにAPIゲートウェイを構成するために"type": "REMOTE_JWKS"を指定した場合は、次のように詳細を指定します:

          コピー

                "publicKeys": {
                  "type": "REMOTE_JWKS",
                  "uri": "<uri-for-jwks>",
                  "maxCacheDurationInHours": <cache-time>,
                  "isSslVerifyDisabled": <true|false>
                }
          

          ここでは:

          • "uri": "<uri-for-jwks>"は、JWTの署名の検証に使用するJSON Web Key Set (JWKS)の取得元のURIを指定します。指定するURIの詳細は、issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。次に注意してください:
            • URIは、APIがデプロイされているAPIゲートウェイを含むサブネットからルーティングできる必要があります。
            • APIゲートウェイがJWKSの取得に失敗した場合、APIデプロイメントへのすべてのリクエストはHTTP 500レスポンス・コードを返します。エラーの詳細は、APIゲートウェイの実行ログを参照してください(APIデプロイメントへのロギングの追加を参照)。
            • JWTの署名を検証するには、JWKSに特定のキー・パラメータが存在する必要があります(JWT署名の検証に必要なキー・パラメータを参照)。
            • JWKSには最大10個のキーを含めることができます。
          • "maxCacheDurationInHours": <cache-time>は、取得後にAPIゲートウェイがJWKSをキャッシュする時間数(1から24)を指定します。
          • "isSslVerifyDisabled": <true|false>は、アイデンティティ・プロバイダとの通信時にSSL検証を無効にするかどうかを示します。JWT検証が損なわれる可能性があるため、Oracleではこのオプションをtrueに設定しないことをお薦めします。APIゲートウェイは、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaを含むOCI IAMに対して発行された複数の認証局からの証明書を信頼します。

          例:

          コピー

                "publicKeys": {
                  "type": "REMOTE_JWKS",
                  "uri": "https://www.somejwksprovider.com/oauth2/v3/certs",
                  "maxCacheDurationInHours": 3,
                  "isSslVerifyDisabled": false
                }
          

        • "type": "STATIC_KEYS"を指定した場合、指定する詳細は、アイデンティティ・プロバイダによってすでに発行されているキーの形式(形式に関係なく、最大10個のキーを指定できます):

          • 静的キーがJSON Webキーの場合は、"format": "JSON_WEB_KEY"を指定し、JWTの署名に使用される静的キーの識別子を"kid"パラメータの値として指定し、JWTの署名を検証するための他のパラメータの値を指定します。

            例:

            コピー

                            
                  "publicKeys": {
                    "type": "STATIC_KEYS",
                    "keys": [
                      {
                        "format": "JSON_WEB_KEY",
                        "kid": "master_key",
                        "kty": "RSA",
                        "n": "0vx7agoebGc...KnqDKgw",
                        "e": "AQAB",
                        "alg": "RS256",
                        "use": "sig"
                      }
                    ]

            JWTの署名を検証するには、静的キーに特定のキー・パラメータが存在する必要があります(JWT署名の検証に必要なキー・パラメータを参照)。また、現在サポートされているキー・タイプ(kty)はRSAのみであることにも注意してください。

          • 静的キーがPEMでエンコードされた公開キーの場合は、"format": "PEM"を指定し、JWTの署名に使用される静的キーの識別子を"kid"の値として指定し、キーを"key"の値として指定します。

            例:

            コピー

                            
                  "publicKeys": {
                    "type": "STATIC_KEYS",
                    "keys": [
                      {
                        "format": "PEM",
                        "kid": "master_key"
                        "key": -----BEGIN PUBLIC KEY-----XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH-----END PUBLIC KEY-----
                      }
                    ]

            -----BEGIN PUBLIC KEY-----および-----END PUBLIC KEY-----マーカーが必要です。

      • verifyClaimsでは、JWTで検証する1つ以上の追加クレームの追加クレーム名および値をオプションで指定します(最大10個)。
        • "key": "<claim-name>"は、JWTに含めることができるクレーム、またはJWTに含める必要があるクレームの名前です。指定するクレーム名には、サブジェクト(sub)クレームなどの予約済クレーム名、または特定のアイデンティティ・プロバイダによって発行されたカスタム・クレーム名を指定できます。
        • "values": ["<acceptable-value>", "<acceptable-value>"]は、(オプションで)クレームに使用できる1つ以上の値を示します。
        • "isRequired": <true|false>は、JWTにクレームを含める必要があるかどうかを示します。

        入力するキーの名前と値は単純に文字列として扱われ、JWTの名前および値と完全に一致する必要があります。パターン一致およびその他のデータ型はサポートされていません

      • maxClockSkewInSeconds: <seconds-difference>では、JWTを発行したアイデンティティ・プロバイダのシステム・クロックとAPIゲートウェイの間の最大時間差をオプションで指定します。指定した値は、APIゲートウェイがJWTの有効開始日(nbf)クレーム(存在する場合)および有効期限(exp)クレームを使用して、JWTを検証して有効かどうかを判断するときに考慮されます。最小値(およびデフォルト)は0、最大値は120です。

      たとえば、次のauthenticationポリシーは、アイデンティティ・プロバイダによってすでに発行された公開検証キーを使用してAPIゲートウェイを構成し、認可リクエスト・ヘッダーでJWTを検証します:

      コピー

      {
        "requestPolicies": {
          "authentication": {
            "type": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "issuers": ["https://identity.oraclecloud.com/"],
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "audiences": ["api.dev.io"],
            "publicKeys": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ]
            },
            "verifyClaims": [
              {
                "key": "is_admin",
                "values": ["service:app", "read:hello"],
                "isRequired": true
              }
            ],
            "maxClockSkewInSeconds": 10
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

2. APIデプロイメント仕様の各ルートに、authorizationリクエスト・ポリシーを追加します:

   1. 最初のルートのbackendセクションの後にrequestPoliciesセクションを挿入します(まだ存在しない場合)。例:

      コピー

      {
        "requestPolicies": {
          "authentication": {
            "type": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "issuers": ["https://identity.oraclecloud.com/"],
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "audiences": ["api.dev.io"],
            "publicKeys": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ]
            },
            "verifyClaims": [
              {
                "key": "is_admin",
                "values": ["service:app", "read:hello"],
                "isRequired": true
              }
            ],
            "maxClockSkewInSeconds": 10
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
               "type": "ORACLE_FUNCTIONS_BACKEND",
               "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {}
          }
        ]
      }

   2. 次のauthorizationポリシーをrequestPoliciesセクションに追加します:

      コピー

      {
        "requestPolicies": {
          "authentication": {
            "type": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "issuers": ["https://identity.oraclecloud.com/"],
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "audiences": ["api.dev.io"],
            "publicKeys": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ]
            },
            "verifyClaims": [
              {
                "key": "is_admin",
                "values": ["service:app", "read:hello"],
                "isRequired": true
              }
            ],
            "maxClockSkewInSeconds": 10
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "authorization": {
                "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, 
                "allowedScope": [ "<scope>" ]
              }
            }
          }
        ]
      }

      ここでは:

      • "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">は、ルートへのアクセス権を付与する方法を示します:

        • "AUTHENTICATION_ONLY": 正常に認証されたエンド・ユーザーにのみアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーの"isAnonymousAccessAllowed"プロパティは無効です。
        • "ANY_OF": JWTのscopeクレームに、allowedScopeプロパティで指定したアクセス・スコープのいずれかが含まれる場合に、正常に認証されたエンド・ユーザーにのみアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーの"isAnonymousAccessAllowed"プロパティは無効です。
        • "ANONYMOUS": 正常に認証されていない場合でも、すべてのエンド・ユーザーにアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーで"isAnonymousAccessAllowed"プロパティを明示的にtrueに設定する必要があります。
      • "allowedScope": [ "<scope>" ]は、JWTのscopeクレームに含まれるアクセス・スコープに対応する1つ以上の文字列のカンマ区切りリストです。この場合、typeプロパティを"ANY_OF"に設定する必要があります(typeプロパティが"AUTHENTICATION_ONLY"または"ANONYMOUS"に設定されている場合、"allowedScope"プロパティは無視されます)。また、複数のスコープを指定した場合、指定したスコープのいずれかがJWTのscopeクレームに含まれると、ルートへのアクセス権が付与されることにも注意してください。

      たとえば、次のリクエスト・ポリシーは、read:helloスコープを持つ認証されたエンド・ユーザーのみにアクセスを許可する/helloルートを定義します:

      コピー

      {
        "requestPolicies": {
          "authentication": {
            "type": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "issuers": ["https://identity.oraclecloud.com/"],
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "audiences": ["api.dev.io"],
            "publicKeys": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ]
            },
            "verifyClaims": [
              {
                "key": "is_admin",
                "values": ["service:app", "read:hello"],
                "isRequired": true
              }
            ],
            "maxClockSkewInSeconds": 10
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "authorization": {
                "type": "ANY_OF",
                "allowedScope": [ "read:hello" ]
              }
            }
          }
        ]
      }

   3. APIデプロイメント仕様内の残りのすべてのルートに、authorizationリクエスト・ポリシーを追加します。
   ノート
   
   

   特定のルートのauthorizationポリシーを含めない場合、そのようなポリシーが存在し、typeプロパティが"AUTHENTICATION_ONLY"に設定されているかのように、アクセス権が付与されます。つまり、APIデプロイメント仕様のauthenticationポリシーでのisAnonymousAccessAllowedプロパティの設定に関係なく、次のようになります:

   • ルートにアクセスできるのは、認証されたエンド・ユーザーのみです
   • JWTのscopeクレームのアクセス・スコープに関係なく、すべての認証済エンド・ユーザーがルートにアクセスできます
   • 匿名のエンド・ユーザーはルートにアクセスできません
3. APIデプロイメント仕様を含むJSONファイルを保存します。

4. APIデプロイメント仕様は、次の方法でAPIデプロイメントを作成または更新するときに使用します:

   • JSONファイルをコンソールで「既存のAPIのアップロード」オプションで指定します
   • APIゲートウェイREST APIへのリクエストでJSONファイルを指定します

   詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイの更新を参照してください。

5. (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。