API 資格情報と資格情報マネージャーについて

適用対象: すべての API Management レベル

バックエンド API へのアクセスの管理がしやすいよう、API Management インスタンスには資格情報マネージャーが用意されています。 API Management インスタンスから、資格情報マネージャーを使用して API 資格情報へのアクセスを管理、格納、制御できます。

OAuth 2.0 API のマネージド接続

資格情報マネージャーを利用すると、OAuth 2.0 を使用する 1 つまたは複数のバックエンド サービスや SaaS サービスに関して横断的にユーザー、グループ、サービス プリンシパルの認証と承認を行うプロセスを大幅にシンプル化できます。 API Management の資格情報マネージャーを使用すると、1 行のコードを記述することなく、OAuth 2.0 の構成、同意、トークンの取得、資格情報ストア内のトークンのキャッシュ、トークンの更新を簡単に行うことができます。 API Management インスタンス、サービス プリンシパル、ユーザー、またはグループに認証を委任するには、アクセス ポリシーを使用します。 OAuth 2.0 に関する背景知識については、「Microsoft ID プラットフォームと OAuth 2.0 承認コード フロー」を参照してください。

この機能により、サブスクリプション キーの有無に関係なく API を公開し、バックエンド サービスに OAuth 2.0 承認を使用し、サービス統合を使用してセキュリティ機能を強化、実装、保守する際の開発コストを削減できます。

ユース ケースの例

API Management の管理下で OAuth 接続を使用することにより、お客様は、OAuth 2.0 を使用する SaaS プロバイダーやバックエンド サービスに簡単に接続できます。 次に例をいくつか示します。

• 格納されている承認トークンとプロキシ要求をアタッチすることで、SaaS バックエンドに簡単に接続できます。

• 承認トークンをアタッチすることで、Azure App Service Web アプリまたは Azure Functions バックエンドにプロキシ要求を送信します。これは後で、変換ロジックを適用する SaaS バックエンドに要求を送信できます。

• 複数のアクセス トークンをアタッチしてフェデレーションを簡単に実行することで、GraphQL フェデレーション バックエンドにプロキシ要求を送信します。

• 取得トークン エンドポイントを公開し、キャッシュされたトークンを取得し、任意のコンピューティングからユーザーに代わって SaaS バックエンドを呼び出します。たとえば、コンソール アプリや Kubernetes デーモンなどです。 サポートされている言語で、任意の SaaS SDK を組み合わせます。

• 複数の SaaS バックエンドに接続する場合の Azure Functions の無人シナリオ。

• Durable Functions を、SaaS 接続を使用する Logic Apps により近づける。

• OAuth 2.0 接続においては、API Management 内のすべての API を、それぞれ Logic Apps のカスタム コネクタとして機能させることができます。

資格情報マネージャーのしくみ

資格情報マネージャー内のトークン資格情報は、管理およびランタイムという 2 つの部分から構成されます。

• 資格情報マネージャーの 管理 パーツは、OAuth 2.0 トークンの 資格情報プロバイダー の設定と構成を行い、ID プロバイダーの同意フローを有効にし、資格情報にアクセスするための資格情報プロバイダーへの 1 つ以上の 接続 を設定します。 詳細については、接続の管理部分に関する説明を参照してください。

• ランタイム部分は、get-authorization-context ポリシーを使用し、承認のアクセス トークンおよび更新トークンのフェッチと格納を実行します。 呼び出しが API Management に入り、 get-authorization-context ポリシーが実行されると、最初に既存の承認トークンが有効かどうかを検証します。 認可トークンの有効期限が切れている場合、API Management は OAuth 2.0 フローを使用して、格納されているトークンを ID プロバイダーから更新します。 その後、アクセス トークンを使用してバックエンド サービスへのアクセスを承認します。 詳細については、接続のランタイム部分に関する説明を参照してください。

資格情報マネージャーを使用する状況

資格情報マネージャーを使用する 3 つのシナリオを次に示します。

構成のシナリオ

資格情報プロバイダーと接続を構成した後は、API マネージャーで接続をテストできます。 API マネージャーは、テスト用のバックエンド OAuth API を、インスタンスのマネージド ID で get-authorization-context ポリシーを使用するように構成します。 これにより、API マネージャーはテスト API を呼び出して接続をテストできるようになります。

無人シナリオ

既定では、接続が作成される際、API Management インスタンスのマネージド ID 用にアクセス ポリシーと接続が事前構成されます。 このような接続を使用するために、さまざまなユーザーが静的 Web アプリなどのクライアント アプリケーションにサインインし、API Management を介して公開されているバックエンド API を呼び出すことができます。 呼び出しを行うには、get-authorization-context ポリシーに基づいて接続が適用されます。 ユーザー コンテキストとの関連がない事前構成済みの接続が API 呼び出しで使用されるため、すべてのユーザーに同じデータが返されます。

有人 (ユーザー委任) シナリオ

ユーザー コンテキストを必要とするバックエンド SaaS API を呼び出すクライアント アプリケーション (静的 Web アプリなど) のユーザーに対して簡素化された認証エクスペリエンスを有効にするには、Microsoft Entra ユーザーまたはグループ ID に代わって接続へのアクセスを有効にすることができます。 この場合、構成されたユーザーはサインインして 1 回だけ同意する必要があり、その後、API Management インスタンスは接続を作成して管理します。 API Management は、外部サービスへの転送が必要な呼び出しを受けると、接続から取得したアクセス トークンを要求にアタッチします。 このしくみは、API の要求と応答が個人向けを想定したものである場合 (例: 特定のユーザーのプロファイル情報を取得する場合) に最適です。

資格情報マネージャーを構成する方法

要件

• API Management インスタンスに対してマネージド システム割り当て ID が有効になっている必要があります。

• API Management インスタンスでは、ポート 443 (HTTPS) 上でインターネットへの送信接続が確立されている必要があります。

可用性

• すべての API Management サービス レベル

• セルフホステッド ゲートウェイではサポートされていません

• ソブリン クラウド、および australiacentral、australiacentral2、jioindiacentral リージョンではサポートされていません

手順の例

• 資格情報マネージャーの構成 - GitHub API
• 資格情報マネージャーの構成 - Microsoft Graph API
• 資格情報マネージャーの構成 - バックエンド API へのユーザー委任アクセス

セキュリティに関する考慮事項

アクセス トークンとその他のシークレット (クライアント シークレットなど) は、エンベロープ暗号化で暗号化され、内部のマルチテナント ストレージに格納されます。 データは、データごとに一意のキーを使用して AES-128 で暗号化されます。 これらのキーは、Azure Key Vault に格納されて毎月ローテーションされる、マスター証明書で非対称に暗号化されます。

制限

よく寄せられる質問 (FAQ)

アクセス トークンはいつ更新されますか?

型承認コードの接続の場合、アクセス トークンは次のように更新されます。

get-authorization-context ポリシーが実行時に実行されると、API Management は、格納されているアクセス トークンが有効かどうかを確認します。 トークンの有効期限が切れているか有効期限が近い場合、API Management では更新トークンを使用して、構成された ID プロバイダーから新しいアクセス トークンと新しい更新トークンをフェッチします。 更新トークンが期限切れの場合はエラーがスローされ、接続が機能するためには再承認が必要になります。

ID プロバイダーでクライアント シークレットの有効期限が切れた場合はどうなりますか?

実行時に、API Management は新しいトークンをフェッチできないため、エラーが発生します。

• 接続の種類が 承認コードの場合は、資格情報プロバイダー レベルでクライアント シークレットを更新する必要があります。

• 接続の種類が クライアント資格情報の場合は、接続レベルでクライアント シークレットを更新する必要があります。

この機能は VNet 内で実行されている API Management を使用する場合はサポートされますか?

はい。ただし、ポート 443 で AzureConnectors サービス タグへの送信接続が有効になっている必要があります。 詳細については、仮想ネットワークの構成のリファレンスを参照してください。

資格情報プロバイダーが削除された場合、何が起きますか?

その基になる接続やアクセス ポリシーもすべて削除されます。

アクセス トークンは API Management によってキャッシュされますか?

クラシック サービス レベルと v2 サービス レベルでは、アクセス トークンは、トークンの有効期限の 3 分前まで API Management インスタンスによってキャッシュされます。 アクセス トークンが有効期限から 3 分未満の場合、キャッシュされた時間はアクセス トークンの有効期限が切れるまでになります。

アクセス トークンは従量課金レベルではキャッシュされません。

関連するコンテンツ

• 接続の資格情報プロバイダーを構成する
• Microsoft Graph API または GitHub API 用の接続を構成して使用する
• ユーザー委任アクセスの接続を構成する
• 1 つの資格情報プロバイダーに対して複数の接続を構成する