このハウツー ガイドでは、Web API を Microsoft ID プラットフォームに登録し、スコープを追加してクライアント アプリに公開します。 Web API を登録し、スコープを介して公開し、所有者とアプリ ロールを割り当てると、API にアクセスする承認済みのユーザーおよびクライアント アプリに、リソースに対するアクセス許可ベースのアクセス権を付与できます。
前提条件
- アクティブなサブスクリプションを持つ Azure アカウント。 お持ちでない場合は、無料のアカウントを作成してください。
- Microsoft Entra 管理センターに登録されているアプリケーション。 まだ登録していない場合は、今すぐ登録してください。
Web API を登録する
API へのアクセスには、アクセス スコープとロールの構成が必要です。 リソース アプリケーション Web API をクライアント アプリケーションに公開する場合は、API のアクセス スコープとアクセス ロールを構成します。 クライアント アプリケーションから Web API にアクセスする場合は、アプリの登録で API にアクセスするためのアクセス許可を構成します。 Web API 内のリソースへのスコープ付きアクセス権を付与するには、まず API を Microsoft ID プラットフォームに登録する必要があります。
- クラウド アプリケーション管理者以上として Microsoft Entra 管理センターにサインインします。
- 複数のテナントにアクセスできる場合は、上部のメニューの [設定] アイコン
を使用し、[ディレクトリとサブスクリプション] メニューからアプリケーション登録が含まれるテナントに切り替えます。 - アプリケーションの登録の手順を実行し、[リダイレクト URI (省略可能)] セクションをスキップします。 ユーザーは対話的にログインしないため、Web API のリダイレクト URI を構成する必要はありません。
アプリケーションの所有者を割り当てる
- [アプリの登録] の [管理] で、[所有者]、[所有者の追加] の順に選びます。
- 新しいウィンドウで、アプリケーションに割り当てる所有者を見つけて選びます。 選択した所有者が右側のパネルに表示されます。 完了したら、[選択] で確定します。 これで、アプリ所有者が所有者の一覧に表示されます。
注記
API アプリケーションとアクセス許可を追加するアプリケーションの両方に所有者が割り当てられていることを確認します。そうしないと、API のアクセス許可を要求するときに API は一覧表示されません。
アプリ ロールを割り当てる
[アプリの登録] の [管理] で、[アプリ ロール]、[アプリ ロールの作成] の順に選びます。
次に、[アプリ ロールの作成] ペインでアプリ ロールの属性を指定します。 このチュートリアルでは、例の値を使用するか、独自の値を指定できます。
フィールド 説明 例 表示名 アプリ ロールの名前 "従業員レコード" Allowed member types (許可されるメンバーの種類) アプリ ロールを、ユーザー/グループまたはアプリケーションのどちらに割り当てることができるかを指定します アプリケーション 価値 トークンの "ロール" 要求に表示される値 Employee.Records説明 アプリ ロールの詳しい説明 "アプリケーションは、従業員レコードにアクセスできる" アプリ ロールを有効にするチェックボックスをオンにし、[適用] を選択します。
スコープを追加する
Web API を登録し、アプリ ロールと所有者を割り当てると、API のコードにスコープを追加して、コンシューマーに詳細なアクセス許可を付与できます。
クライアント アプリケーションのコードによって、保護されたリソース (Web API) への要求と共にアクセス トークンを渡すことにより、Web API で定義された操作を実行するアクセス許可が要求されます。 Web API では、操作に必要なスコープが受け取ったアクセス トークンに含まれている場合にのみ、要求された操作が実行されます。
管理者とユーザーの同意が必要なスコープを追加する
まず、次の手順で Employees.Read.All という名前のスコープの例を作成します。
API を公開する を選択します。
ページの上部で、アプリケーション ID URI の横にある [追加] を選択します。 既定値は
api://<application-client-id>です。 アプリ ID URI は、API のコードで参照するスコープのプレフィックスとして機能し、グローバルに一意である必要があります。 [保存] を選択します。[Add a scope] (スコープの追加) を選択します。
![Azure portal のアプリ登録の [API の公開] ペイン](media/quickstart-configure-app-expose-web-apis/portal-02-expose-api.png)
次に、 [スコープの追加] ペインでスコープの属性を指定します。 このチュートリアルでは、例の値を使用するか、独自の値を指定できます。
フィールド 説明 例 スコープ名 スコープの名前。 一般的なスコープの名前付け規則は resource.operation.constraintです。Employees.Read.All同意できるユーザー このスコープにユーザーが同意できるかどうかと、管理者の同意が必要かどうか。 [管理者のみ] は、より高い特権のアクセス許可にするために使用する必要があります。 管理者とユーザー 管理者の同意の表示名 管理者のみに表示される、スコープの目的についての簡単な説明。 従業員レコードへの読み取り専用アクセス 管理者の同意の説明 管理者のみに表示される、スコープによって付与されるアクセス許可の詳細な説明。 すべての従業員データへの読み取り専用アクセスをアプリケーションに許可します。 ユーザーの同意の表示名 スコープの目的に関する簡単な説明。 [同意できるユーザー] を [管理者とユーザー] に設定した場合にのみユーザーに表示されます。 従業員レコードへの読み取り専用アクセス ユーザーの同意の説明 スコープによって付与されるアクセス許可の詳細な説明。 [同意できるユーザー] を [管理者とユーザー] に設定した場合にのみユーザーに表示されます。 従業員データへの読み取り専用アクセスをアプリケーションに許可します。 状態 スコープが有効になっているか、無効になっているか。 有効 [スコープの追加] を選択します。
(省略可能) 定義されているスコープに対してアプリのユーザーによる同意を求めるメッセージを表示しないようにするには、クライアント アプリケーションによる Web API へのアクセスを "事前承認" することができます。 ユーザーには同意を拒否する機会がないため、信頼できるクライアント アプリケーション "だけ" を事前承認します。
- [ 承認されたクライアント アプリケーション] で、[ クライアント アプリケーションの追加] を選択します。
- 事前承認するクライアント アプリケーションの [アプリケーション (クライアント) ID] を入力します。 たとえば、以前に登録した Web アプリケーションのそれです。
- [承認済みのスコープ] で、同意を求めるメッセージを表示しないスコープを選択し、 [アプリケーションの追加] を選択します。
この省略可能な手順を行った場合、クライアント アプリは承認済みのクライアント アプリ (PCA) になり、ユーザーはアプリにサインインするときに同意を求められません。
管理者の同意が必要なスコープを追加する
次に、管理者だけが同意できる Employees.Write.All という名前の別のスコープの例を追加します。 通常、管理者の同意が必要なスコープは、より高い特権の操作に対するアクセス権を付与するために使用され、多くの場合、ユーザーが対話的にサインインしないバックエンド サービスまたはデーモンとして実行されるクライアント アプリケーションに使用されます。
Employees.Write.All のスコープの例を追加するには、「スコープの追加」セクションの手順を行い、[スコープの追加] ペインでこれらの値を指定します。 終了したら [スコープの追加] を選択します。
| フィールド | 値の例 |
|---|---|
| スコープ名 | Employees.Write.All |
| 同意できるユーザー | 管理者のみ |
| 管理者の同意の表示名 | 従業員レコードへの書き込みアクセス |
| 管理者の同意の説明 | すべての従業員データへの書き込みアクセスをアプリケーションに許可します。 |
| ユーザーの同意の表示名 | なし (空のまま) |
| ユーザーの同意の説明 | なし (空のまま) |
| 状態 | 有効 |
公開されたスコープを確認する
前のセクションで説明した両スコープ例を追加すると、次の画像のように、それらが Web API のアプリ登録の [API の公開] ペインに表示されます。
![2 つの公開されたスコープを示す [API の公開] ペインのスクリーンショット。](media/quickstart-configure-app-expose-web-apis/portal-03-scopes-list.png)
スコープの完全な文字列は、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 を公開したので、これらのスコープにアクセスするためのアクセス許可でクライアント アプリの登録を構成します。