承認の概要

API Management の承認 (プレビュー) を使用すると、OAuth 2.0 バックエンド サービスに対する承認トークンを管理するプロセスが簡略化されます。 サポートされている ID プロバイダーのいずれかを構成し、標準化された OAuth 2.0 フローを使用して承認を作成することで、API Management では API Management 内で使用する、またはクライアントに送り返すアクセス トークンを取得および更新できます。 この機能を使用すると、サブスクリプション キーの有無にかかわらず API を公開でき、バックエンド サービスに対する承認で OAuth 2.0 が使用されます。

この機能によって可能になるシナリオの例を、いくつか次に示します。

  • Power Apps または Power Automate を使用する市民/ロー コード開発者が、OAuth 2.0 を使用する SaaS プロバイダーに簡単に接続できます。
  • タイマー トリガーを使用した Azure 関数などの無人シナリオでは、この機能を利用することで OAuth 2.0 を使用してバックエンド API に接続できます。
  • エンタープライズ企業のマーケティング チームでは、OAuth 2.0 を使用してソーシャル メディア プラットフォームと対話する場合に同じ承認を使用できます。
  • API Management で Logic Apps のカスタム コネクタとして API を公開します。この場合、バックエンド サービスに OAuth 2.0 フローが必要です。
  • Dropbox などのサービスや、OAuth 2.0 フローによって保護されたその他のサービスが複数のクライアントによって使用されるシナリオ用に使用します。
  • API Management で合成 GraphQL を使用して、OAuth 2.0 承認を必要とするさまざまなサービスに接続します。
  • サービス間承認を使用する Enterprise Application Integration (EAI) パターンでは、OAuth 2.0 を使用するバックエンド API に対してクライアント資格情報付与タイプを使用できます。
  • OAuth 2.0 を使用する API に対してクライアントの SDK で使用するアクセス トークンの取得のみを行う、シングルページ アプリケーション。

この機能は、管理とランタイムの 2 つの部分で構成されます。

  • 管理部分では、ID プロバイダーの構成、ID プロバイダーの同意フローの有効化、承認へのアクセスの管理を行います。

  • ランタイム部分では、get-authorization-context ポリシーを使用してアクセス トークンと更新トークンをフェッチおよび格納します。 API Management が呼び出され、get-authorization-context ポリシーが実行されると、まず既存の承認トークンが有効かどうかが検証されます。 承認トークンの有効期限が切れている場合は、更新トークンを使用して、構成された ID プロバイダーから新しい承認および更新トークンのフェッチが試みられます。 バックエンド プロバイダーの呼び出しが正常に行われると、新しい承認トークンが使用され、承認トークンと更新トークンの両方が暗号化されて格納されます。

    ポリシーの実行中は、アクセス ポリシーを使用してトークンへのアクセスも検証されます。

API Management で OAuth 2.0 認可に使用できる ID プロバイダーを示すスクリーンショット。

必要条件

  • API Management インスタンスに対してマネージド システム割り当て ID が有効になっている必要があります。
  • API Management インスタンスでは、ポート 443 (HTTPS) 上でインターネットへの送信接続が確立されている必要があります。

制限事項

パブリック プレビューの場合、次の制限事項が存在します。

  • 認可機能では、アクセス ポリシーとしてサービス プリンシパルとマネージド ID のみがサポートされます。
  • 認可機能では、https://.../authorizationmanager の対象ユーザーのトークンを取得するときに、/.default アプリ専用スコープのみがサポートされます。
  • 承認機能は、swedencentral、australiacentral、australiacentral2、jioindiacentral のリージョンではサポートされません。
  • 承認機能は、各国のクラウドではサポートされていません。
  • 承認機能は、セルフホステッド ゲートウェイではサポートされていません。
  • サポートされている ID プロバイダーは、こちらの GitHub リポジトリで確認できます。
  • API Management インスタンスあたりの構成済み承認プロバイダーの最大数: 1,000
  • 承認プロバイダーあたりの構成済みの承認の最大数: 10,000
  • 承認あたりの構成済みのアクセス ポリシーの最大数: 100
  • サービスあたりの最大要求数/分: 250

承認プロバイダー

承認プロバイダーの構成には、使用されている ID プロバイダーと付与タイプが含まれます。 ID プロバイダーごとに異なる構成が必要です。

  • 1 つの承認プロバイダーの構成で使用できる付与タイプは 1 つだけです。
  • 1 つの承認プロバイダーの構成に複数の承認を含めることができます。
  • パブリック プレビューでサポートされている ID プロバイダーは、こちらの GitHub リポジトリで確認できます。

Generic OAuth 2.0 プロバイダーを使用すると、OAuth 2.0 フローの標準をサポートする他の ID プロバイダーを使用できます。

[Authorizations]

承認プロバイダーを使用するには、少なくとも 1 つの "承認" が必要です。 承認を構成するプロセスは、使用されている付与タイプによって異なります。 各承認プロバイダーの構成では、1 つの付与タイプのみがサポートされます。 たとえば、両方の付与タイプを使用するように Azure AD を構成する場合は、2 つの承認プロバイダーの構成が必要です。

承認コード付与タイプ

承認コード付与タイプはユーザー コンテキストにバインドされています。つまり、ユーザーが承認に同意する必要があります。 更新トークンが有効であれば、API Management で新しいアクセス トークンと更新トークンを取得できます。 更新トークンが無効になると、ユーザーは再承認する必要があります。 承認コードはすべての ID プロバイダーでサポートされます。 承認コード付与タイプの詳細を参照してください

クライアント資格情報付与タイプ

クライアント資格情報付与タイプはユーザーにバインドされておらず、アプリケーション間のシナリオで多く使用されます。 クライアント資格情報付与タイプでは同意は不要であり、承認は無効になりません。 クライアント資格情報付与タイプの詳細を参照してください

アクセス ポリシー

アクセス ポリシーでは、そのアクセス ポリシーが関連する承認をどの ID で使用できるかを決定します。 サポートされている ID は、マネージド ID、ユーザー ID、サービス プリンシパルです。 ID は、API Management テナントと同じテナントに属している必要があります。

  • マネージド ID - 使用されている API Management インスタンスのシステム割り当てまたはユーザー割り当ての ID。
  • ユーザー ID - API Management インスタンスと同じテナント内のユーザー。
  • サービス プリンシパル - API Management インスタンスと同じ Azure AD テナント内のアプリケーション。

承認を作成するためのプロセス フロー

次の図は、付与タイプの承認コードを使用して API Management で承認を作成するためのプロセス フローを示しています。 パブリック プレビューの場合、API ドキュメントは利用できません。

承認を作成するためのプロセス フロー

  1. クライアントが、承認プロバイダーの作成要求を送信します。
  2. 承認プロバイダーが作成され、応答が返されます。
  3. クライアントが、承認の作成要求を送信します。
  4. 承認が作成され、その承認が "接続" されていないという情報を含む応答が返されます。
  5. クライアントが、ID プロバイダーで OAuth 2.0 の同意を開始するためのログイン URL の取得要求を送信します。 この要求には、直前の手順で使用されるリダイレクト後の URL が含まれます。
  6. 同意フローを開始するために使用するログイン URL を含む応答が返されます。
  7. クライアントが、前の手順で提供されたログイン URL を使用してブラウザーを開きます。 ブラウザーは、ID プロバイダーの OAuth 2.0 同意フローにリダイレクトされます。
  8. 同意が承認されると、承認コードを使用して、ID プロバイダーで構成されたリダイレクト URL にブラウザーがリダイレクトされます。
  9. API Management では、承認コードを使用してアクセス トークンと更新トークンをフェッチします。
  10. API Management では、トークンを受け取って暗号化します。
  11. API Management が、手順 5. で提供された URL にリダイレクトされます。

ランタイムのプロセス フロー

次の図は、構成された承認に基づいて承認および更新トークンをフェッチして格納するプロセス フローを示しています。 トークンが取得されると、バックエンド API への呼び出しが行われます。

ランタイムを作成するためのプロセス フローを示す図。

  1. クライアントが、API Management インスタンスに要求を送信します。
  2. ポリシー get-authorization-context によって、アクセス トークンが現在の承認に対して有効かどうかを確認します。
  3. アクセス トークンの有効期限が切れていても、更新トークンが有効な場合、API Management では、構成された ID プロバイダーから新しいアクセス トークンと更新トークンをフェッチしようとします。
  4. ID プロバイダーが、アクセス トークンと更新トークンの両方を返します。これらは暗号化されて API Management に保存されます。
  5. トークンが取得されると、set-header ポリシーを使用して、アクセス トークンがバックエンド API への送信要求に対する承認ヘッダーとしてアタッチされます。
  6. 応答が API Management に返されます。
  7. 応答がクライアントに返されます。

エラー処理

承認コンテキストを取得するとエラーが発生する場合、ポリシー get-authorization-context で属性 ignore-error がどのように構成されているかによって結果が異なります。 値が false (既定値) に設定されている場合、500 Internal Server Error というエラーが返されます。 値が true に設定されている場合、エラーは無視され、コンテキスト変数が null に設定された状態で実行が続けられます。

値が false に設定され、ポリシーの on-error セクションが構成されている場合、エラーはプロパティ context.LastError で取得できます。 on-error セクションを使用すると、クライアントに送り返されるエラーを調整できます。 API Management からのエラーは、標準の Azure アラートを使用してキャッチできます。 ポリシー内のエラーの処理に関する詳細を参照してください。

承認に関するよくあるご質問

フィードバックを送付して、この機能のロードマップに影響を及ぼすにはどうすればよいですか?

フィードバックを送付するには、こちらのフォームをお使いください。

トークンは API Management にどのように格納されますか?

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

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

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

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

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

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

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

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

はい。ただし、API Management ゲートウェイでポート 443 での送信インターネット接続が確立されている場合に限ります。

承認プロバイダーが削除された場合はどうなりますか?

基になる承認とアクセス ポリシーもすべて削除されます。

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

アクセス トークンは、そのトークンの有効期限の 3 分前まで API 管理によってキャッシュされます。

どの付与タイプがサポートされていますか?

パブリック プレビューの場合、Azure AD ID プロバイダーでは承認コードとクライアント資格情報をサポートします。

その他の ID プロバイダーでは承認コードをサポートします。 パブリック プレビュー後、ID プロバイダーと付与タイプが追加されます。

次の手順