クイック スタート:Web API を公開するようにアプリケーションを構成するQuickstart: Configure an application to expose web APIs

自ら Web API を開発し、クライアント アプリケーションで利用できるようにすることもできます。そのためには、アクセス許可/スコープロールを公開する必要があります。You can develop a web API and make it available to client applications by exposing permissions/scopes and roles. Web API を適切に構成すれば、Graph API や Office 365 API など、他の Microsoft Web API と同じように利用できるようになります。A correctly configured web API is made available just like the other Microsoft web APIs, including the Graph API and the Office 365 APIs.

このクイック スタートでは、クライアント アプリケーションが使用できるようにするために、新しいスコープを公開するようにアプリケーションを構成する方法について説明します。In this quickstart, you'll learn how to configure an application to expose a new scope to make it available to client applications.

前提条件Prerequisites

最初に、以下の前提条件を完了していることを確認します。To get started, make sure you complete these prerequisites:

Azure portal にサインインしてアプリを選択するSign in to the Azure portal and select the app

アプリを構成する前に、次の手順を実行します。Before you can configure the app, follow these steps:

  1. 職場または学校アカウントか、個人の Microsoft アカウントを使用して、Azure portal にサインインします。Sign in to the Azure portal using either a work or school account or a personal Microsoft account.
  2. ご利用のアカウントで複数のテナントにアクセスできる場合は、右上隅でアカウントを選択し、ポータルのセッションを目的の Azure AD テナントに設定します。If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the desired Azure AD tenant.
  3. 左側のナビゲーション ウィンドウで、 [Azure Active Directory] サービスを選択し、 [アプリの登録] を選択します。In the left-hand navigation pane, select the Azure Active Directory service and then select App registrations.
  4. 構成するアプリケーションを探して選択します。Find and select the application you want to configure. アプリを選択すると、アプリケーションの [概要] またはメイン登録ページが表示されます。Once you've selected the app, you'll see the application's Overview or main registration page.
  5. 新しいスコープを公開するために、UI とアプリケーション マニフェストのどちらの方法を使用するかを選択します。Choose which method you want to use, UI or application manifest, to expose a new scope:

UI を通じて新しいスコープを公開するExpose a new scope through the UI

UI を使用して API を公開する方法の画像Shows how to expose an API using the UI

UI を通じて新しいスコープを公開するには:To expose a new scope through the UI:

  1. アプリの [概要] ページで、 [API の公開] セクションを選択します。From the app's Overview page, select the Expose an API section.

  2. [Scope の追加] を選択します。Select Add a scope.

  3. [アプリケーション ID URI] を設定していない場合は、入力を求めるメッセージが表示されます。If you have not set an Application ID URI, you will see a prompt to enter one. アプリケーション ID URI を入力するか、提供されるものの 1 つを使用し、 [保存してから続ける] を選択します。Enter your application ID URI or use the one provided and then select Save and continue.

  4. [Scope の追加] ページが表示されたら、以下のスコープの情報を入力します。When the Add a scope page appears, enter your scope's information:

    フィールドField 説明Description
    スコープ名Scope name スコープのわかりやすい名前を入力します。Enter a meaningful name for your scope.

    たとえば、「 Employees.Read.All 」のように入力します。For example, Employees.Read.All.
    同意できるユーザーWho can consent このスコープにユーザーが同意できるかどうかと、管理者の同意が必要かどうかを選択します。Select whether this scope can be consented to by users, or if admin consent is required. より高い特権のアクセス許可にするには、 [管理者のみ] を選択します。Select Admins only for higher-privileged permissions.
    管理者の同意の表示名Admin consent display name スコープのわかりやすい説明を入力します。説明は管理者に表示されます。Enter a meaningful description for your scope, which admins will see.

    たとえば、Read-only access to Employee records のように指定します。For example, Read-only access to Employee records
    管理者の同意の説明Admin consent description スコープのわかりやすい説明を入力します。説明は管理者に表示されます。Enter a meaningful description for your scope, which admins will see.

    たとえば、Allow the application to have read-only access to all Employee data. のように指定します。For example, Allow the application to have read-only access to all Employee data.

    ユーザーがスコープに同意できる場合は、以下のフィールドにも値を追加します。If users can consent to your scope, also add values for the following fields:

    フィールドField 説明Description
    ユーザーの同意の表示名User consent display name スコープのわかりやすい名前を入力します。名前はユーザーに表示されます。Enter a meaningful name for your scope, which users will see.

    たとえば、Read-only access to your Employee records のように指定します。For example, Read-only access to your Employee records
    ユーザーの同意の説明User consent description スコープのわかりやすい説明を入力します。説明はユーザーに表示されます。Enter a meaningful description for your scope, which users will see.

    たとえば、Allow the application to have read-only access to your Employee data. のように指定します。For example, Allow the application to have read-only access to your Employee data.
  5. 完了したら、 [状態] を設定し、 [スコープの追加] を選択します。Set the State and select Add scope when you're done.

  6. 他のアプリケーションに Web API が公開されていることを確認するための手順を実行します。Follow the steps to verify that the web API is exposed to other applications.

アプリケーション マニフェストを通じて新しいスコープまたはロールを公開するExpose a new scope or role through the application manifest

マニフェストで oauth2Permissions コレクションを使用して新しいスコープを公開するExpose a new scope using the oauth2Permissions collection in the manifest

アプリケーション マニフェストを通じて新しいスコープを公開するには:To expose a new scope through the application manifest:

  1. アプリの [概要] ページで、 [マニフェスト] セクションを選択します。From the app's Overview page, select the Manifest section. Web ベースのマニフェスト エディターが開き、ポータルでマニフェストを編集できます。A web-based manifest editor opens, allowing you to Edit the manifest within the portal. 必要があれば、 [ダウンロード] を選択してローカルでマニフェストを編集します。その後、 [アップロード] を使用して、アプリケーションにマニフェストを再適用します。Optionally, you can select Download and edit the manifest locally, and then use Upload to reapply it to your application.

    次の例では、oauth2Permissions コレクションに以下の JSON 要素を追加して、リソース/API の Employees.Read.All という新しいスコープを公開する方法を示しています。The following example shows how to expose a new scope called Employees.Read.All in the resource/API by adding the following JSON element to the oauth2Permissions collection.

    {
      "adminConsentDescription": "Allow the application to have read-only access to all Employee data.",
      "adminConsentDisplayName": "Read-only access to Employee records",
      "id": "2b351394-d7a7-4a84-841e-08a6a17e4cb8",
      "isEnabled": true,
      "type": "User",
      "userConsentDescription": "Allow the application to have read-only access to your Employee data.",
      "userConsentDisplayName": "Read-only access to your Employee records",
      "value": "Employees.Read.All"
    }
    

    注意

    id の値は、プログラムによって、または guidgen などの GUID 生成ツールを使って作成する必要があります。The id value must be generated programmatically or by using a GUID generation tool such as guidgen. id は、Web API によって公開されるスコープの一意の識別子となります。The id represents a unique identifier for the scope as exposed by the web API. クライアントに対して Web API にアクセスするためのアクセス許可が適切に構成されていると、そのクライアントには、Azure AD によって OAuth 2.0 アクセス トークンが発行されます。Once a client is appropriately configured with permissions to access your web API, it is issued an OAuth 2.0 access token by Azure AD. クライアントが Web API を呼び出すときには、このアクセス トークンを提示することになります。そして、このアクセス トークンでは、スコープ (scp) 要求がアプリケーションの登録時に要求されたアクセス許可のとおりに設定されています。When the client calls the web API, it presents the access token that has the scope (scp) claim set to the permissions requested in its application registration.

    公開するスコープは、必要に応じて後から追加することもできます。You can expose additional scopes later as necessary. たとえば、Web API で、さまざまな機能が関連付けられたスコープをいくつも公開しているとします。Consider that your web API might expose multiple scopes associated with a variety of different functions. リソースは、受け取った OAuth 2.0 アクセス トークンのスコープ (scp) 要求を評価することによって、実行時に Web API へのアクセスを制御します。Your resource can control access to the web API at runtime by evaluating the scope (scp) claim(s) in the received OAuth 2.0 access token.

  2. 完了したら、 [保存] をクリックします。When finished, click Save. これで Web API の構成が終わり、ディレクトリ内の他のアプリケーションが利用できるようになりました。Now your web API is configured for use by other applications in your directory.

  3. 他のアプリケーションに Web API が公開されていることを確認するための手順を実行します。Follow the steps to verify that the web API is exposed to other applications.

他のアプリケーションに Web API が公開されているかどうかを確認するVerify the web API is exposed to other applications

  1. Azure AD テナントに戻って、 [アプリの登録] を選択し、構成するクライアント アプリケーションを見つけて選択します。Go back to your Azure AD tenant, select App registrations, find and select the client application you want to configure.
  2. Web API にアクセスするためのクライアント アプリケーションの構成に関するページで説明されている手順をもう一度実行します。Repeat the steps outlined in Configure a client application to access web APIs.
  3. API の選択の手順で、リソースを選択します。When you get to the step to select an API, select your resource. 新しいスコープが表示されていれば、クライアントのアクセス許可の要求で利用できる状態です。You should see the new scope, available for client permission requests.

アプリケーション マニフェストの詳細More on the application manifest

アプリケーション マニフェストは、アプリケーション エンティティを更新するためのメカニズムとしての役割を果たすものです。Azure AD アプリケーションの ID 構成の属性はすべて、このアプリケーション エンティティで定義されています。The application manifest serves as a mechanism for updating the application entity, which defines all attributes of an Azure AD application's identity configuration. アプリケーション エンティティとそのスキーマの詳細については、Graph API のアプリケーション エンティティに関するドキュメントを参照してください。For more information on the Application entity and its schema, see the Graph API Application entity documentation. このドキュメントでは、API のアクセス許可を指定するために使用するアプリケーション エンティティのメンバーについて、詳細な参照情報を確認できます。たとえば、次のような情報です。The article contains complete reference information on the Application entity members used to specify permissions for your API, including:

アプリケーション マニフェストの概念一般の詳細については、Azure Active Directory のアプリケーション マニフェストに関するページを参照してください。For more information on application manifest concepts in general, see Understanding the Azure Active Directory application manifest.

次のステップNext steps

以下のその他のアプリ管理関連のクイック スタートを学習します。Learn about these other related app management quickstarts for apps:

登録されたアプリケーションを表す 2 つの Azure AD オブジェクトと、両者間の関係については、Application objects and service principal objects(アプリケーション オブジェクトとサービス プリンシパル オブジェクト) を参照してください。To learn more about the two Azure AD objects that represent a registered application and the relationship between them, see Application objects and service principal objects.

Azure Active Directory でアプリケーションを開発するときに使用するブランド化ガイドラインについては、アプリケーションのブランド化ガイドラインを参照してください。To learn more about the branding guidelines you should use when developing applications with Azure Active Directory, see Branding guidelines for applications.