保護された Web API: アプリの登録

適用対象: ワークフォース テナント 外部テナント (詳細)

この記事では、保護された Web API にアプリケーションを登録する方法について説明します。

アプリを登録する一般的な手順については、「 クイック スタート: アプリケーションを Microsoft ID プラットフォームに登録する」を参照してください。

承認済みトークンのバージョン

Microsoft ID プラットフォームでは、v1.0 トークンと v2.0 トークンを発行できます。 これらのトークンの詳細については、「 アクセス トークン」を参照してください。

API が受け入れるトークンのバージョンは、Azure portal で Web API アプリケーションの登録を作成するときに サポートされているアカウントの種類 の選択によって異なります。

• サポートされているアカウントの種類の値が任意の組織のディレクトリ内のアカウントと個人用 Microsoft アカウント (Skype、Xbox、Outlook.com など) の場合、受け入れ可能なトークンのバージョンは v2.0 である必要があります。
• それ以外の場合は、承認済みトークンのバージョンを v1.0 にできます。

アプリケーションを作成した後、これらの手順に従って、承認済みトークンのバージョンを決定または変更できます。

1. Microsoft Entra 管理センターで、アプリを選択し、[マニフェスト] を選択 します。
2. マニフェストで プロパティ accessTokenAcceptedVersion を見つけます。
3. その値により、Web API で受け入れられるトークンのバージョンが Microsoft Entra に対して指定されます。
   • 値が 2 の場合、Web API では v2.0 トークンが受け入れられます。
   • 値が null の場合、Web API は v1.0 トークンを受け入れます。
4. トークンのバージョンを変更した場合は、[ 保存] を選択します。

Web API で受け入れられるトークンのバージョンを指定します。 クライアントで、Microsoft ID プラットフォームに Web API 用のトークンを要求すると、クライアントは Web API が受け入れるトークンのバージョンを示すトークンを受け取ります。

リダイレクト URI なし

ユーザーが対話形式でサインインすることがないため、Web API ではリダイレクト URI を登録する必要がありません。

公開される API

Web API に固有の他の設定は、公開されている API と公開されているスコープまたはアプリのロールです。

スコープとアプリケーション ID URI

通常、スコープの形式は resourceURI/scopeName です。 Microsoft Graph の場合、スコープにはショートカットがあります。 たとえば、User.Read は https://graph.microsoft.com/user.read のショートカットです。

アプリの登録時に、これらのパラメーターを定義します。

• リソース URI
• 1 つまたは複数のスコープ
• 1 つまたは複数のアプリ ロール

既定では、アプリケーションの登録ポータルでは、リソース URI api://{clientId} を使用することをお勧めします。 この URI は一意ですが、人間が判読できるものではありません。 URI を変更する場合は、新しい値が一意になるようにしてください。 アプリケーション登録ポータルでは、 構成済みのパブリッシャー ドメインが確実に使用されます。

クライアント アプリケーションでは、スコープは 委任されたアクセス許可 として表示され、アプリ ロールは Web API の アプリケーションアクセス許可 として表示されます。

スコープは、アプリのユーザーに提示される同意ウィンドウにも表示されます。 そのため、次の場合にスコープについて説明する、対応する文字列を指定します。

• ユーザーに表示される場合。
• 管理者の同意を許可できる、テナント管理者に表示される場合。

(アプリ ロールは代理で Web API を呼び出すアプリケーションによって使用されるため) アプリ ロールの同意の付与をユーザーが行うことはできません。 テナント管理者は、アプリのロールを公開する Web API のクライアント アプリケーションに同意する必要があります。 詳細については、 管理者の同意 を参照してください。

委任されたアクセス許可 (スコープ) を公開する

委任されたアクセス許可または スコープを公開するには、「 Web API を公開するようにアプリケーションを構成する」の手順に従います。

この一連の記事で説明されている Web API シナリオに従っている場合は、次の設定を使用します。

• アプリケーション ID URI: 提案されたアプリケーション ID URI (api://<clientId>) を受け入れます (メッセージが表示された場合)
• スコープ名: access_as_user
• 同意できるユーザー: 管理者とユーザー
• 管理者の同意の表示名: ユーザーとしての TodoListService へのアクセス
• 管理者の同意の説明: ユーザーとして TodoListService Web API にアクセスします
• ユーザーの同意の表示名: ユーザーとしての TodoListService へのアクセス
• ユーザーの同意の説明: ユーザーとして TodoListService Web API にアクセスします
• 状態: 有効

サービスまたはデーモン アプリで Web API が呼び出される場合

API にデーモン、サービス、またはその他の (人間による) 非対話型アプリケーションからアクセスする必要がある場合は、委任されたアクセス許可ではなく、"アプリケーションのアクセス許可" を公開します。 デーモンおよびサービス タイプのアプリケーションは無人で実行され、独自の ID で認証されるため、アクセス許可を "委任" するユーザーはいません。

アプリケーションのアクセス許可 (アプリ ロール) を公開する

アプリケーションのアクセス許可を公開するには、「アプリロールを アプリに追加する」の手順に従います。

[許可されるメンバーの種類] の [アプリ ロールの作成] ウィンドウで、[アプリケーション] を選択します。 または、この記事の説明に従って 、アプリケーション マニフェスト エディター を使用してロールを追加します。

アクセス トークンを特定のクライアント アプリに制限する

アプリ ロールは、アプリケーション開発者がアプリのアクセス許可を公開するために使用するメカニズムです。 Web API のコードでは、呼び出し元から受け取るアクセス トークン内のアプリ ロールを確認する必要があります。

別のセキュリティ層を追加するために、Microsoft Entra テナント管理者は、MICROSOFT ID プラットフォームが API アクセスを承認したクライアント アプリ にのみ セキュリティ トークンを発行するようにテナントを構成できます。

アプリ ロールが割り当てられているクライアント アプリのみにトークンの発行を制限してセキュリティを強化するには、以下の手順を実行します。

1. Microsoft Entra 管理センターで、[Entra ID>App registrations] でアプリを選択します。
2. アプリケーションの [概要 ] ページの [Essentials] で、 ローカル ディレクトリでマネージド アプリケーション を見つけて選択し、[ エンタープライズ アプリケーションの概要 ] ページに移動します。
3. [ 管理] で [プロパティ] を選択 します。
4. [ 割り当てが必要] を [ はい] に設定します。
5. [保存] を選択します。

これで、Microsoft Entra ID は、Web API のアクセス トークンを要求するクライアント アプリケーションのアプリ ロールの割り当てを確認するようになりました。 クライアント アプリにアプリ ロールが割り当てられていない場合、Microsoft Entra ID は _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_ のようなエラー メッセージをクライアントに返します。

次のステップ

このシリーズの次の記事は、 アプリ コードの構成です。