Oracle Cloud Infrastructureドキュメント

コンソールを使用したトークン認証および認可リクエスト・ポリシーの追加

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

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

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

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

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

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

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

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

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

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

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

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

      • クライアントID:イントロスペクション・エンドポイントに送信するクライアントID。クライアントIDを取得するには、クライアント・アプリケーションを作成して認可サーバーに登録します。たとえば、5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1です。トークン認証の前提条件を参照してください。
      • 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 Gateway trusts certificates from multiple Certificate Authorities issued for OCI IAM with Identity Domains, Oracle Identity Cloud Service (IDCS), Auth0, and Okta.

    2. 実行時にアイデンティティ・プロバイダから公開検証キーを取得してJWTを検証するようにAPIゲートウェイを使用するには、「タイプ」リストから「リモート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)です。
      • 最大クロック・スキュー(秒): (オプション)トークンを発行した認可サーバーのシステム・クロックとAPIゲートウェイとの間の最大時間差。ここに入力する値は、APIゲートウェイでJWTの有効終了日(nbf)クレーム(存在する場合)および有効期限(exp)クレームを使用して、JWTを検証してまだ有効かどうかを判断するときに考慮されます。最小値(およびデフォルト)は0、最大値は120です。
      • SSLの検証の無効化:アイデンティティ・プロバイダとの通信時にSSL検証を無効化かどうか。デフォルトでは、このオプションは選択されていません。JWT検証が損なわれる可能性があるため、Oracleではこのオプションを選択しないことをお薦めします。API Gateway trusts certificates from multiple Certificate Authorities issued for OCI IAM with Identity Domains, Oracle Identity Cloud Service (IDCS), Auth0, and Okta.

    3. アイデンティティ・プロバイダによってすでに発行されている公開検証キーを使用してJWTを検証するようにAPIゲートウェイを設定するには(アイデンティティ・プロバイダに接続せずに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の名前および値と完全に一致する必要があります。パターン一致およびその他のデータ型はサポートされていません。

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

      JWTで要求に値を指定せずに要求を指定できることに注意してください。これを行うには、「Claim key」フィールドに要求の名前を入力し、「Claim values」フィールドを空白のままにして、必要に応じて「Claim is required」を設定します。

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

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

      • スコープ:認可サーバーに送信されるscopeクレームに含める1つ以上のアクセス・スコープ。OpenID Connect認可フローを使用するには、スコープの1つとしてopenidを含める必要があります。たとえば、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
        • Vault:指定したコンパートメント内のボールトのリストから、イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むVaultサービス内のボールトの名前。
        • Vaultシークレット:指定されたコンパートメント内のボールト・シークレットのリストから、イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットの名前。
        • Vaultシークレット・バージョン番号:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのバージョン。

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

      • PKCEの使用: (オプション)PKCE (Proof Key for Code Exchange)を使用してセキュリティを強化するかどうかを指定します。PKCEは、CSRF (Cross-Site Request Forgery)および認可コード・インジェクション攻撃を防ぐためのOAuth 2.0セキュリティ拡張機能です。PKCEはクライアント・シークレットの代替ではなく、クライアント・シークレットを使用する場合でもPKCEをお薦めします。PKCEの詳細は、OAuth 2.0のドキュメントを参照してください。
      • セッションにCookieを使用: (オプション) OpenID Connect認可フローの最後に、新しく生成されたJWTトークンを人間が読めない文字列として格納する方法を指定します:
        • 新しい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リクエスト・ヘッダーに同じトークンを含める必要があります。

        Notes about Cross-Site Request Forgery (CSRF) Protectionを参照してください。

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

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

  10. 「ルートの追加」を選択し、1つのパスと1つ以上のメソッドをバックエンド・サービスにマップするAPIデプロイメント内の最初のルートを指定してください:

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

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

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

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

    • バックエンド・タイプ:バックエンド・サービスのタイプ。次のいずれかです:

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

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

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

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

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