クイック スタート:Web API を公開するようにアプリケーションを構成する

  • [アーティクル]

このクイックスタートでは、Microsoft ID プラットフォームに Web API を登録し、スコープを追加してそれをクライアント アプリに公開します。 Web API を登録し、スコープを介して公開し、所有者とアプリ ロールを割り当てると、API にアクセスする承認済みのユーザーおよびクライアント アプリに、リソースに対するアクセス許可ベースのアクセス権を付与できます。

前提条件

Web API を登録する

API にアクセスするには、アクセス スコープとアクセス ロールを構成する必要があります。 リソース アプリケーション Web API をクライアント アプリケーションに公開する場合は、API のアクセス スコープとアクセス ロールを構成します。 クライアント アプリケーションから Web API にアクセスする場合は、アプリの登録で API にアクセスするためのアクセス許可を構成します。

Web API 内のリソースへのスコープ付きアクセス権を付与するには、まず API を Microsoft ID プラットフォームに登録する必要があります。

「アプリケーションを登録する」(「クイックスタート: Microsoft ID プラットフォームにアプリを登録する」) の手順を行います。

[リダイレクト URI (省略可能)] セクションをスキップします。 ユーザーは対話的にログインしないため、Web API のリダイレクト URI を構成する必要はありません。

アプリケーション所有者を割り当てる

  1. [アプリの登録] の [管理] で、[所有者]、[所有者の追加] の順に選びます。
  2. 新しいウィンドウで、アプリケーションに割り当てる所有者を見つけて選びます。 選択した所有者が右側のパネルに表示されます。 完了したら、[選択] で確定します。 これで、アプリ所有者が所有者の一覧に表示されます。

Note

必ず、API アプリケーションと、アクセス許可を追加するアプリケーションの両方に所有者を設定してください。そうしなければ、API のアクセス許可を要求するときに API が一覧表示されません。

アプリ ロールを割り当てる

  1. [アプリの登録] の [管理] で、[アプリ ロール]、[アプリ ロールの作成] の順に選びます。

  2. 次に、[アプリ ロールの作成] ペインでアプリ ロールの属性を指定します。 このチュートリアルでは、例の値を使用するか、独自の値を指定できます。

    フィールド Description 例
    [表示名] アプリ ロールの名前 "従業員レコード"
    Allowed member types (許可されるメンバーの種類) アプリ ロールを、ユーザー/グループまたはアプリケーションのどちらに割り当てることができるかを指定します アプリケーション
    Value トークンの "ロール" 要求に表示される値 Employee.Records
    説明 アプリ ロールの詳しい説明 "アプリケーションは、従業員レコードにアクセスできる"

  3. チェックボックスをオンにしてアプリ ロールを有効にします。

Web API を登録し、アプリ ロールと所有者を割り当てると、API のコードにスコープを追加して、コンシューマーに詳細なアクセス許可を付与できます。

スコープを追加する

ヒント

この記事の手順は、開始するポータルによって若干異なる場合があります。

クライアント アプリケーションのコードによって、保護されたリソース (Web API) への要求と共にアクセス トークンを渡すことにより、Web API で定義された操作を実行するアクセス許可が要求されます。 Web API では、操作に必要なスコープが受け取ったアクセス トークンに含まれている場合にのみ、要求された操作が実行されます。

まず、次の手順で Employees.Read.All という名前のスコープの例を作成します。

  1. クラウド アプリケーション管理者以上として Microsoft Entra 管理センターにサインインします。

  2. 複数のテナントにアクセスできる場合は、上部のメニューの [設定] アイコン を使用し、[ディレクトリとサブスクリプション] メニューからアプリケーション登録が含まれるテナントに切り替えます。

  3. [ID]>[アプリケーション]>[アプリの登録] の順に移動し、API のアプリの登録を選びます。

  4. [API の公開] を選択します。

  5. まだ構成していない場合は、[アプリケーション ID URI] の横の [追加] を選択します。

    既定値 api://<application-client-id> または別の[supported App ID URI pattern] (サポートされるアプリ ID の URI パターン) を使用します。 アプリ ID URI は、API のコードで参照するスコープのプレフィックスとして機能し、グローバルに一意である必要があります。

  6. [Add a scope] (スコープの追加) を選択します。

    An app registration's Expose an API pane in the Azure portal

  7. 次に、[スコープの追加] ペインでスコープの属性を指定します。 このチュートリアルでは、例の値を使用するか、独自の値を指定できます。

    フィールド Description 例
    スコープ名 スコープの名前。 一般的なスコープの名前付け規則は resource.operation.constraint です。 Employees.Read.All
    同意できるユーザー このスコープにユーザーが同意できるかどうかと、管理者の同意が必要かどうか。 より高い特権のアクセス許可にするには、 [管理者のみ] を選択します。 管理者とユーザー
    管理者の同意の表示名 管理者のみに表示される、スコープの目的についての簡単な説明。 Read-only access to Employee records
    管理者の同意の説明 管理者のみに表示される、スコープによって付与されるアクセス許可の詳細な説明。 Allow the application to have read-only access to all Employee data.
    ユーザーの同意の表示名 スコープの目的に関する簡単な説明。 [同意できるユーザー] を [管理者とユーザー] に設定した場合にのみユーザーに表示されます。 Read-only access to your Employee records
    ユーザーの同意の説明 スコープによって付与されるアクセス許可の詳細な説明。 [同意できるユーザー] を [管理者とユーザー] に設定した場合にのみユーザーに表示されます。 Allow the application to have read-only access to your Employee data.

  8. [状態] を [有効] に設定し、 [スコープの追加] を選択します。

  9. (省略可能) 定義されているスコープに対してアプリのユーザーによる同意を求めるメッセージを表示しないようにするには、クライアント アプリケーションによる Web API へのアクセスを "事前承認" することができます。 ユーザーには同意を拒否する機会がないため、信頼できるクライアント アプリケーション "だけ" を事前承認します。

    1. [承認済みのクライアント アプリケーション] で、 [クライアント アプリケーションの追加] を選択します
    2. 事前承認するクライアント アプリケーションの [アプリケーション (クライアント) ID] を入力します。 たとえば、以前に登録した Web アプリケーションのそれです。
    3. [承認済みのスコープ] で、同意を求めるメッセージを表示しないスコープを選択し、 [アプリケーションの追加] を選択します。

    この省略可能な手順を行った場合、クライアント アプリは承認済みのクライアント アプリ (PCA) になり、ユーザーはアプリにサインインするときに同意を求められません。

次に、管理者だけが同意できる Employees.Write.All という名前の別のスコープの例を追加します。 通常、管理者の同意が必要なスコープは、より高い特権の操作に対するアクセス権を付与するために使用され、多くの場合、ユーザーが対話的にサインインしないバックエンド サービスまたはデーモンとして実行されるクライアント アプリケーションに使用されます。

Employees.Write.All のスコープの例を追加するには、「Employees.Write.All」セクションの手順を行い、[スコープの追加] ペインでこれらの値を指定します。

フィールド 値の例
スコープ名 Employees.Write.All
同意できるユーザー 管理者のみ
管理者の同意の表示名 Write access to Employee records
管理者の同意の説明 Allow the application to have write access to all Employee data.
ユーザーの同意の表示名 なし (空のまま)
ユーザーの同意の説明 なし (空のまま)

[状態] を [有効] に設定し、 [スコープの追加] を選択します。

公開されたスコープを確認する

前のセクションで説明した両スコープ例を追加すると、次の画像のように、それらが Web API のアプリ登録の [API の公開] ペインに表示されます。

Screenshot of the Expose an API pane showing two exposed scopes.

この画像に示すように、スコープの完全な文字列は、Web API の [アプリケーション ID URI] とスコープの [スコープ名] を連結したものです。

たとえば、Web API のアプリケーション ID URI が https://contoso.com/api で、スコープ名が Employees.Read.All である場合、完全なスコープは次のようになります。

https://contoso.com/api/Employees.Read.All

公開されたスコープを使用する

このシリーズの次の記事では、この記事の手順で定義した Web API へのアクセスとスコープを使用して、クライアント アプリの登録を構成します。

クライアント アプリの登録に Web API へのアクセス許可が付与されると、ID プラットフォームはクライアントに OAuth 2.0 アクセス トークンを発行します。 クライアントから Web API を呼び出すと、アクセス トークンが表示されます。そのスコープ (scp) 要求は、クライアントのアプリ登録で指定したアクセス許可に設定されています。

公開するスコープは、必要に応じて後から追加することもできます。 Web API を使用すると、複数の操作に関連付けられた複数のスコープを公開できることを考慮してください。 リソースは、受け取った OAuth 2.0 アクセス トークンのスコープ (scp) 要求を評価することによって、実行時に Web API へのアクセスを制御します。

次のステップ

スコープを構成して Web API を公開したので、これらのスコープにアクセスするためのアクセス許可でクライアント アプリの登録を構成します。

Web API アクセスのためにアプリ登録を構成する