保護された 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 にできます。
アプリケーションを作成した後、これらの手順に従って、承認済みトークンのバージョンを決定または変更できます。
- Microsoft Entra 管理センターで、アプリを選択した後、[マニフェスト] を選択します。
- マニフェストで accessTokenAcceptedVersion プロパティを見つけます。
- その値により、Web API で受け入れられるトークンのバージョンが Microsoft Entra に対して指定されます。
- 値が 2 の場合、Web API では v2.0 トークンが受け入れられます。
- 値が null の場合、Web API では v1.0 トークンが受け入れられます。
- トークンのバージョンを変更した場合は、 [保存] を選択します。
Web API で受け入れられるトークンのバージョンを指定します。 クライアントで、Microsoft ID プラットフォームに Web API 用のトークンを要求すると、クライアントは Web API が受け入れるトークンのバージョンを示すトークンを受け取ります。
ユーザーが対話形式でサインインすることがないため、Web API ではリダイレクト URI を登録する必要がありません。
Web API に固有の他の設定は、公開されている API と公開されているスコープまたはアプリのロールです。
通常、スコープの形式は 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
- 同意できるユーザー: "管理者とユーザー"
- 管理者の同意の表示名: Access TodoListService as a user
- 管理者の同意の説明: Accesses the TodoListService web API as a user
- ユーザーの同意の表示名: Access TodoListService as a user
- ユーザーの同意の説明: Accesses the TodoListService web API as a user
- [状態] :有効
ヒント
アプリケーション ID URI については、API の物理的な権限に設定するオプションがあります (例: https://graph.microsoft.com)。 これは、呼び出す必要がある API の URL がわかっている場合に便利です。
API にデーモン、サービス、またはその他の (人間による) 非対話型アプリケーションからアクセスする必要がある場合は、委任されたアクセス許可ではなく、"アプリケーションのアクセス許可" を公開します。 デーモンおよびサービス タイプのアプリケーションは無人で実行され、独自の ID で認証されるため、アクセス許可を "委任" するユーザーはいません。
アプリケーションのアクセス許可を公開するには、アプリ ロールのアプリへの追加に関する記事の手順に従います。
[許可されたメンバーの種類] の [アプリ ロールの作成] ペインで、[アプリケーション] を選択します。 または、この記事の説明に従って、アプリケーション マニフェスト エディターを使用してロールを追加します。
アプリ ロールは、アプリケーション開発者がアプリのアクセス許可を公開するために使用するメカニズムです。 Web API のコードでは、呼び出し元から受け取るアクセス トークン内のアプリ ロールを確認する必要があります。
別のセキュリティ層を追加するために、Microsoft Entra テナント管理者は、Microsoft ID プラットフォームが API アクセスを承認したクライアント アプリにのみセキュリティ トークンを発行するようにテナントを構成できます。
アプリ ロールが割り当てられているクライアント アプリのみにトークンの発行を制限してセキュリティを強化するには、以下の手順を実行します。
- Microsoft Entra 管理センターで、[ID]、>、[アプリの登録] を選択します。
- アプリケーションの [概要] ページの [基本] で、[ローカル ディレクトリ内のマネージド アプリケーション] リンクを見つけて選択し、[エンタープライズ アプリケーションの概要] ページに移動します。
- [管理] の下で、 [プロパティ] を選択します。
- [割り当てが必要ですか?] を [いいえ] に設定します。
- [保存] を選択します。
これで、Microsoft Entra ID は、Web API のアクセス トークンを要求するクライアント アプリケーションのアプリ ロールの割り当てを確認するようになりました。 クライアント アプリにアプリ ロールが割り当てられていない場合、Microsoft Entra ID は _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_ のようなエラー メッセージをクライアントに返します。
警告
アプリケーションのコードでは、AADSTS エラー コードやそのメッセージ文字列をリテラルとして使用しないでください。 Microsoft Entra ID によって返される "AADSTS" エラー コードとエラー メッセージ文字列は不変ではなく、Microsoft によっていつでも知らないうちに変更される可能性があります。 AADSTS コードまたはそのメッセージ文字列の値に基づいてコード内で分岐の決定を行うと、アプリケーションの機能と安定性が危険にさらされます。
このシリーズの次の記事は、アプリ コードの構成です。