Azure Active Directory と API Management で OAuth 2.0 を使用して API を保護するProtect an API by using OAuth 2.0 with Azure Active Directory and API Management

このガイドでは、Azure API Management インスタンスを構成して、Azure Active Directory (Azure AD) で OAuth 2.0 プロトコルを使用して API を保護する方法について説明します。This guide shows you how to configure your Azure API Management instance to protect an API, by using the OAuth 2.0 protocol with Azure Active Directory (Azure AD).

注意

この機能は、API Management の DeveloperStandardPremium レベルで使用できます。This feature is available in Developer, Standard and Premium tiers of API Management.

前提条件Prerequisites

この記事の手順を実行するには、以下が必要です。To follow the steps in this article, you must have:

  • API Management インスタンスAn API Management instance
  • API Management インスタンスを使用する API が公開されているAn API being published that uses the API Management instance
  • Azure AD テナントAn Azure AD tenant

概要Overview

手順の概要は次のとおりです。Here is a quick overview of the steps:

  1. API を表すアプリケーション (バックエンドアプリ) を Azure AD に登録します。Register an application (backend-app) in Azure AD to represent the API.
  2. API を呼び出す必要があるクライアント アプリケーションを表す別のアプリケーション (クライアントアプリ) を Azure AD に登録します。Register another application (client-app) in Azure AD to represent a client application that needs to call the API.
  3. Azure AD で、クライアントアプリがバックエンドアプリを呼び出すことができるようにアクセス許可を付与します。In Azure AD, grant permissions to allow the client-app to call the backend-app.
  4. OAuth 2.0 のユーザー承認を使用する API を呼び出すように Developer Console を設定します。Configure the Developer Console to call the API using OAuth 2.0 user authorization.
  5. validate-jwt ポリシーを追加して、すべての着信要求に対して OAuth トークンを検証します。Add the validate-jwt policy to validate the OAuth token for every incoming request.

API を表すアプリケーションを Azure AD に登録するRegister an application in Azure AD to represent the API

Azure AD で API を保護するには、まず API を表すアプリケーションを Azure AD に登録します。To protect an API with Azure AD, the first step is to register an application in Azure AD that represents the API.

  1. Azure portal の [アプリの登録] に移動します。Navigate to the Azure portal - App registrations page.

  2. [新規登録] を選択します。Select New registration.

  3. [アプリケーションの登録] ページが表示されたら、以下のアプリケーションの登録情報を入力します。When the Register an application page appears, enter your application's registration information:

    • [名前] セクションに、アプリのユーザーに表示されるわかりやすいアプリケーション名を入力します (例: backend-app)。In the Name section, enter a meaningful application name that will be displayed to users of the app, for example backend-app.
    • [サポートされているアカウントの種類] セクションで、シナリオに適したオプションを選択します。In the Supported account types section, select an option that suits your scenario.
  4. [リダイレクト URI] セクションは空のままにします。Leave the Redirect URI section empty.

  5. [登録] を選択して、アプリケーションを作成します。Select Register to create the application.

  6. アプリの [概要] ページで、 [アプリケーション (クライアント) ID] の値を見つけ、後で使用するために記録します。On the app Overview page, find the Application (client) ID value and record it for later.

アプリケーションが作成されたら、次の手順で使用する [アプリケーション ID] をメモします。When the application is created, make a note of the Application ID, for use in a subsequent step.

  1. [API の公開] を選択し、 [保存してから続ける] をクリックして、アプリケーション ID URI を作成します。Select Expose an API and click on Save and continue to create an Application ID URI.

  2. [スコープの追加] ページで、APIIn the Add a scope page, create a new scope supported by the API. (たとえば Read) によってサポートされる新しいスコープを作成し、 [スコープの追加] をクリックしてスコープを追加します。(e.g., Read) then click on Add scope to create the scope. この手順を繰り返して、API でサポートされるすべてのスコープを追加します。Repeat this step to add all scopes supported by your API.

  3. スコープが作成されたら、後の手順で使用するために、そのスコープを書き留めておきます。When the scope is created, make a note of it, for use in a subsequent step.

クライアント アプリケーションを表す別のアプリケーションを Azure AD に登録するRegister another application in Azure AD to represent a client application

API を呼び出すすべてのクライアント アプリケーションも、Azure AD にアプリケーションとして登録する必要があります。Every client application that calls the API needs to be registered as an application in Azure AD as well. この例のクライアント アプリケーションは、API Management 開発者ポータルの Developer Console です。In this example, the client application is the Developer Console in the API Management developer portal. Developer Console を表す別のアプリケーションを Azure AD に登録する方法は次のとおりです。Here's how to register another application in Azure AD to represent the Developer Console.

  1. Azure portal の [アプリの登録] に移動します。Navigate to the Azure portal - App registrations page.

  2. [新規登録] を選択します。Select New registration.

  3. [アプリケーションの登録] ページが表示されたら、以下のアプリケーションの登録情報を入力します。When the Register an application page appears, enter your application's registration information:

    • [名前] セクションに、アプリのユーザーに表示されるわかりやすいアプリケーション名を入力します (例: client-app)。In the Name section, enter a meaningful application name that will be displayed to users of the app, for example client-app.
    • [サポートされているアカウントの種類] セクションで、 [任意の組織のディレクトリ内のアカウント] を選択します。In the Supported account types section, select Accounts in any organizational directory.
  4. [リダイレクト URI] セクションで、Web を選択し、URL https://contoso5.portal.azure-api.net/signin を入力します。In the Redirect URI section, select Web and enter the URL https://contoso5.portal.azure-api.net/signin

  5. [登録] を選択して、アプリケーションを作成します。Select Register to create the application.

  6. アプリの [概要] ページで、 [アプリケーション (クライアント) ID] の値を見つけ、後で使用するために記録します。On the app Overview page, find the Application (client) ID value and record it for later.

次に、以降の手順で使用するこのアプリケーションのクライアント シークレットを作成します。Now, create a client secret for this application, for use in a subsequent step.

  1. クライアント アプリのページの一覧から、 [証明書とシークレット] を選択し、 [新しいクライアント シークレット] を選択します。From the list of pages for your client app, select Certificates & secrets, and select New client secret.

  2. [クライアント シークレットの追加][説明] を入力します。Under Add a client secret, provide a Description. キーの有効期限を選択し、 [追加] を選択します。Choose when the key should expire, and select Add.

シークレットが作成されたら、後の手順で使用するために、そのキー値を書き留めておきます。When the secret is created, make a note of the key value, for use in a subsequent step.

Azure AD でアクセス許可を付与するGrant permissions in Azure AD

API と Developer Console を表す 2 つのアプリケーションを登録したら、次はクライアントアプリがバックエンドアプリを呼び出すことができるようにアクセス許可を付与する必要があります。Now that you have registered two applications to represent the API and the Developer Console, you need to grant permissions to allow the client-app to call the backend-app.

  1. [アプリの登録] に移動します。Navigate to App registrations.

  2. client-app を選択し、アプリのページの一覧で [API のアクセス許可] に移動します。Select client-app, and in the list of pages for the app go to API permissions.

  3. [アクセス許可の追加] を選択します。Select Add a Permission.

  4. [API の選択]backend-app を見つけて選択します。Under Select an API, find and select backend-app.

  5. [委任されたアクセス許可] で、backend-app に最適なアクセス許可を選択し、 [アクセス許可の追加] をクリックします。Under Delegated Permissions, select the appropriate permissions to backend-app then click on Add permissions.

  6. 必要に応じて、 [API のアクセス許可] ページでページの下部にある [に管理者の同意を与えます ] をクリックし、このディレクトリのすべてのユーザーに代わって同意を付与します。Optionally, on the API permissions page, click on Grant admin consent for in the bottom of the page to grant consent on behalf of all users in this directory.

Developer Console で OAuth 2.0 のユーザー承認を有効にするEnable OAuth 2.0 user authorization in the Developer Console

これまでの手順では、Azure AD でアプリケーションを作成し、クライアントアプリがバックエンドアプリを呼び出すことができる適切なアクセス許可を付与しました。At this point, you have created your applications in Azure AD, and have granted proper permissions to allow the client-app to call the backend-app.

この例では、Developer Console はクライアントアプリです。In this example, the Developer Console is the client-app. 次の手順では、Developer Console で OAuth 2.0 のユーザー承認を有効にする方法について説明します。The following steps describe how to enable OAuth 2.0 user authorization in the Developer Console.

  1. Azure portal で API Management インスタンスに移動します。In Azure portal, browse to your API Management instance.

  2. [OAuth 2.0] > [追加] の順に選択します。Select OAuth 2.0 > Add.

  3. [表示名][説明] を入力します。Provide a Display name and Description.

  4. [クライアント登録ページの URL] に、「http://localhost」などのプレースホルダーの値を入力します。For the Client registration page URL, enter a placeholder value, such as http://localhost. [クライアント登録ページ URL] では、この機能をサポートする OAuth 2.0 プロバイダーについて、ユーザーが自身のアカウントを作成および構成するために使用できるページを指定します。The Client registration page URL points to a page that users can use to create and configure their own accounts for OAuth 2.0 providers that support this. この例では、ユーザーは自身のアカウントを作成も構成もしないため、代わりにプレースホルダーを使用します。In this example, users do not create and configure their own accounts, so you use a placeholder instead.

  5. [承認許可の種類] として [承認コード] を選択します。For Authorization grant types, select Authorization code.

  6. [承認エンドポイントの URL][トークン エンドポイントの URL] を指定します。Specify the Authorization endpoint URL and Token endpoint URL. これらの値は、Azure AD テナントの [エンドポイント] ページから取得します。Retrieve these values from the Endpoints page in your Azure AD tenant. [アプリの登録] ページにもう一度移動し、 [エンドポイント] を選択します。Browse to the App registrations page again, and select Endpoints.

  7. [OAuth 2.0 承認エンドポイント] をコピーし、 [承認エンドポイントの URL] テキストボックスに貼り付けます。Copy the OAuth 2.0 Authorization Endpoint, and paste it into the Authorization endpoint URL text box. [承認要求方法] の下で [POST] を選択します。Select POST under Authorization request method.

  8. [OAuth 2.0 トークン エンドポイント] をコピーし、 [トークン エンドポイントの URL] テキストボックスに貼り付けます。Copy the OAuth 2.0 Token Endpoint, and paste it into the Token endpoint URL text box.

    重要

    v1 または v2 エンドポイントを使用できます。You can use either v1 or v2 endpoints. ただし、選択するバージョンによって以下の手順は異なります。However, depending on which version you choose, the below step will be different. v2 エンドポイントの使用をお勧めします。We recommend using v2 endpoints.

  9. v1 エンドポイントを使用する場合は、resource という名前の本文パラメーターを追加します。If you use v1 endpoints, add a body parameter named resource. このパラメーターの値には、バックエンド アプリのアプリケーション ID を使用します。For the value of this parameter, use Application ID of the back-end app.

  10. v2 エンドポイントを使用する場合は、 [既定のスコープ] フィールドでバックエンド アプリ用に作成したスコープを使用します。If you use v2 endpoints, use the scope you created for the backend-app in the Default scope field.

  11. 次に、クライアントの資格情報を指定します。Next, specify the client credentials. これらはクライアントアプリの資格情報です。These are the credentials for the client-app.

  12. [クライアント ID] には、クライアントアプリのアプリケーション ID を使用します。For Client ID, use the Application ID of the client-app.

  13. [クライアント シークレット] には、先ほどクライアントアプリ用に作成したキーを使用します。For Client secret, use the key you created for the client-app earlier.

  14. クライアント シークレットの直後には、承認コード付与タイプの redirect_url があります。Immediately following the client secret is the redirect_url for the authorization code grant type. この URL をメモします。Make a note of this URL.

  15. 作成 を選択します。Select Create.

  16. クライアントアプリの [設定] ページに戻ります。Go back to the Settings page of your client-app.

  17. [応答 URL] を選択し、最初の行に redirect_url を貼り付けます。Select Reply URLs, and paste the redirect_url in the first row. この例では、最初の行の https://localhost を URL に置き換えました。In this example, you replaced https://localhost with the URL in the first row.

OAuth 2.0 承認サーバーを設定したので、Developer Console で Azure AD からアクセス トークンを取得できるようになりました。Now that you have configured an OAuth 2.0 authorization server, the Developer Console can obtain access tokens from Azure AD.

次の手順では、API について OAuth 2.0 のユーザー承認を有効にします。The next step is to enable OAuth 2.0 user authorization for your API. こうすることで、Developer Console は API を呼び出す前に、ユーザーの代わりにアクセス トークンを取得する必要があることを把握できるようになります。This enables the Developer Console to know that it needs to obtain an access token on behalf of the user, before making calls to your API.

  1. API Management インスタンスに移動し、 [API] に移動します。Browse to your API Management instance, and go to APIs.

  2. 保護する API を選択します。Select the API you want to protect. たとえば、Echo API を使用できます。For example, you can use the Echo API.

  3. [設定] に移動します。Go to Settings.

  4. [セキュリティ][OAuth 2.0] を選択し、先ほど構成した OAuth 2.0 サーバーを選択します。Under Security, choose OAuth 2.0, and select the OAuth 2.0 server you configured earlier.

  5. [保存] を選択します。Select Save.

開発者ポータルから適切に API を呼び出すSuccessfully call the API from the developer portal

注意

このセクションは、開発者ポータルをサポートしていない従量課金レベルには適用されません。This section does not apply to the Consumption tier, which does not support the developer portal.

ご使用の API で OAuth 2.0 ユーザー承認が有効になると、Developer Console は API を呼び出す前にユーザーの代理でアクセス トークンを取得するようになります。Now that the OAuth 2.0 user authorization is enabled on your API, the Developer Console will obtain an access token on behalf of the user, before calling the API.

  1. 開発者ポータルの API の下にある任意の操作に移動し、試してみてくださいBrowse to any operation under the API in the developer portal, and select Try it. この操作で Developer Console が表示されます。This brings you to the Developer Console.

  2. [承認] セクションの新しい項目は、先ほど追加した承認サーバーに対応しています。Note a new item in the Authorization section, corresponding to the authorization server you just added.

  3. 承認ドロップダウン リストから [承認コード] を選択します。Azure AD テナントにサインインするように求められます。Select Authorization code from the authorization drop-down list, and you are prompted to sign in to the Azure AD tenant. 既にアカウントでサインインしている場合、確認メッセージは表示されません。If you are already signed in with the account, you might not be prompted.

  4. サインインに成功すると、Azure AD のアクセス トークンを使用する要求に Authorization ヘッダーが追加されます。After successful sign-in, an Authorization header is added to the request, with an access token from Azure AD. 以下はサンプル トークン (Base64 エンコード) です。The following is a sample token (Base64 encoded):

    Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IlNTUWRoSTFjS3ZoUUVEU0p4RTJnR1lzNDBRMCIsImtpZCI6IlNTUWRoSTFjS3ZoUUVEU0p4RTJnR1lzNDBRMCJ9.eyJhdWQiOiIxYzg2ZWVmNC1jMjZkLTRiNGUtODEzNy0wYjBiZTEyM2NhMGMiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC80NDc4ODkyMC05Yjk3LTRmOGItODIwYS0yMTFiMTMzZDk1MzgvIiwiaWF0IjoxNTIxMTUyNjMzLCJuYmYiOjE1MjExNTI2MzMsImV4cCI6MTUyMTE1NjUzMywiYWNyIjoiMSIsImFpbyI6IkFWUUFxLzhHQUFBQUptVzkzTFd6dVArcGF4ZzJPeGE1cGp2V1NXV1ZSVnd1ZXZ5QU5yMlNkc0tkQmFWNnNjcHZsbUpmT1dDOThscUJJMDhXdlB6cDdlenpJdzJLai9MdWdXWWdydHhkM1lmaDlYSGpXeFVaWk9JPSIsImFtciI6WyJyc2EiXSwiYXBwaWQiOiJhYTY5ODM1OC0yMWEzLTRhYTQtYjI3OC1mMzI2NTMzMDUzZTkiLCJhcHBpZGFjciI6IjEiLCJlbWFpbCI6Im1pamlhbmdAbWljcm9zb2Z0LmNvbSIsImZhbWlseV9uYW1lIjoiSmlhbmciLCJnaXZlbl9uYW1lIjoiTWlhbyIsImlkcCI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0LzcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0Ny8iLCJpcGFkZHIiOiIxMzEuMTA3LjE3NC4xNDAiLCJuYW1lIjoiTWlhbyBKaWFuZyIsIm9pZCI6IjhiMTU4ZDEwLWVmZGItNDUxMS1iOTQzLTczOWZkYjMxNzAyZSIsInNjcCI6InVzZXJfaW1wZXJzb25hdGlvbiIsInN1YiI6IkFGaWtvWFk1TEV1LTNkbk1pa3Z3MUJzQUx4SGIybV9IaVJjaHVfSEM1aGciLCJ0aWQiOiI0NDc4ODkyMC05Yjk3LTRmOGItODIwYS0yMTFiMTMzZDk1MzgiLCJ1bmlxdWVfbmFtZSI6Im1pamlhbmdAbWljcm9zb2Z0LmNvbSIsInV0aSI6ImFQaTJxOVZ6ODBXdHNsYjRBMzBCQUEiLCJ2ZXIiOiIxLjAifQ.agGfaegYRnGj6DM_-N_eYulnQdXHhrsus45QDuApirETDR2P2aMRxRioOCR2YVwn8pmpQ1LoAhddcYMWisrw_qhaQr0AYsDPWRtJ6x0hDk5teUgbix3gazb7F-TVcC1gXpc9y7j77Ujxcq9z0r5lF65Y9bpNSefn9Te6GZYG7BgKEixqC4W6LqjtcjuOuW-ouy6LSSox71Fj4Ni3zkGfxX1T_jiOvQTd6BBltSrShDm0bTMefoyX8oqfMEA2ziKjwvBFrOjO0uK4rJLgLYH4qvkR0bdF9etdstqKMo5gecarWHNzWi_tghQu9aE3Z3EZdYNI_ZGM-Bbe3pkCfvEOyA
    
  5. [送信] を選択すると、API を適切に呼び出すことができます。Select Send, and you can call the API successfully.

要求を事前承認する JWT 検証ポリシーを構成するConfigure a JWT validation policy to pre-authorize requests

この時点でユーザーが Developer Console から電話をかけようとすると、ユーザーにはログインが求められます。At this point, when a user tries to make a call from the Developer Console, the user is prompted to sign in. Developer Console は、ユーザーに代わってアクセス トークンを取得し、API に対して行う要求にトークンを含めます。The Developer Console obtains an access token on behalf of the user, and includes the token in the request made to the API.

ただし、誰かがトークンを使用せず、または無効なトークンを使用して API を呼び出すとどうなるでしょうか。However, what if someone calls your API without a token or with an invalid token? たとえば、API を Authorization ヘッダーなしで呼び出してみても、呼び出しは処理されます。For example, try to call the API without the Authorization header, the call will still go through. 理由は、API Management がこの時点でアクセス トークンを検証していないためです。The reason is that API Management does not validate the access token at this point. Authorization ヘッダーはバックエンド API に渡されます。It simply passes the Authorization header to the back-end API.

JWT を検証するポリシーを使用して、各受信要求のアクセス トークンを検証することで API Management で要求を事前承認できます。You can use the Validate JWT policy to pre-authorize requests in API Management, by validating the access tokens of each incoming request. 要求に有効なトークンがない場合、API Management はその要求をブロックします。If a request does not have a valid token, API Management blocks it. たとえば、以下のポリシーを Echo API<inbound> ポリシー セクションに追加します。For example, add the following policy to the <inbound> policy section of the Echo API. これは、アクセス トークンの受信者要求をチェックし、トークンが有効でない場合にエラー メッセージを返します。It checks the audience claim in an access token, and returns an error message if the token is not valid. ポリシーの構成方法については、ポリシーの設定と編集に関する記事をご覧ください。For information on how to configure policies, see Set or edit policies.

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration" />
    <required-claims>
        <claim name="aud">
            <value>{Application ID of backend-app}</value>
        </claim>
    </required-claims>
</validate-jwt>

アプリケーションをビルドして API を呼び出すBuild an application to call the API

このガイドでは、サンプル クライアント アプリケーションとして API Management で Developer Console を使用して、OAuth 2.0 によって保護された Echo API を呼び出します。In this guide, you used the Developer Console in API Management as the sample client application to call the Echo API protected by OAuth 2.0. アプリケーションのビルドと OAuth 2.0 の実装の詳細については、「Azure Active Directory のコード例」を参照してください。To learn more about how to build an application and implement OAuth 2.0, see Azure Active Directory code samples.

次の手順Next steps