Microsoft ID プラットフォームと OAuth 2.0 クライアント資格情報フロー

[アーティクル]
04/08/2024

OAuth 2.0 クライアント資格情報付与フローでは、Web サービス (Confidential クライアント) が別の Web サービスを呼び出すときに、ユーザーを偽装する代わりに、独自の資格情報を使用して認証することができます。 RFC 6749 に明記されている許可は、2 本足の OAuth とも呼ばれ、アプリケーションの ID を使用した Web ホストのリソースへのアクセスに使用できます。この型は、ユーザーとの即時の相互動作が必要ではなく、一般的にバックグラウンドでの実行が必要なサーバー間の相互作用に使用され、多くの場合、デーモンまたはサービスアカウントと呼ばれます。

クライアント資格情報フローでは、アクセス許可は管理者によってアプリケーション自体に直接付与されます。アプリがリソースにトークンを提示するとき、リソースはアプリ自体がアクションの実行を承認されていることを求めます。これは、認証に関与しているユーザーが存在しないためです。この記事では、次の場合に必要な両方の手順について説明します。

API を呼び出すアプリケーションを承認する
その API を呼び出すために必要なトークンを取得する方法。

この記事では、アプリケーションでプロトコルに対して直接プログラミングする方法について説明します。可能な場合は、トークンを取得してセキュリティで保護された Web API を呼び出す代わりに、サポートされている Microsoft 認証ライブラリ (MSAL) を使用することをお勧めします。 MSAL を使用するサンプルアプリも参照してください。補足として、このフローでは更新トークンは許可されません。client_id と client_secret (更新トークンを取得するために必要です) を使用して、代わりにアクセストークンを取得できるためです。

より高いレベルの保証のために、Microsoft ID プラットフォーム呼び出し元のサービスが共有シークレットではなく証明書またはフェデレーション資格情報を使用して認証することもできます。アプリケーション独自の資格情報が使用されているため、これらの資格情報は安全に保つ必要があります。ソースコードで資格情報を絶対に公開しないでください。Web ページに資格情報を埋め込んだり、広範囲に配布されるネイティブアプリケーションで使用したりしないでください。

プロトコルのダイアグラム

全体的なクライアント資格情報フローは、次の図のようになります。それぞれの手順については、この記事で後述します。

Diagram showing the client credentials flow

直接承認を取得する

アプリは通常、次の 2 つの方法のいずれかで、直接承認を受信してリソースにアクセスします。

リソースのアクセス制御リスト (ACL) を利用する
Microsoft Entra ID のアプリケーション許可の割り当てによる

これらの 2 つの方法は、Microsoft Entra ID で最も一般的であり、クライアント資格情報フローを実行するクライアントとリソースに対して推奨されています。リソースは、他の方法でそのクライアントを承認することもできます。各リソースサーバーでは、そのアプリケーションに最も適した方法を選択できます。

アクセス制御リスト

リソースプロバイダーは、アプリケーション (クライアント) ID 一覧に基づいて承認チェックを適用する場合があります。この一覧はリソースプロバイダーによって認識され、一定レベルのアクセス許可が付与されます。リソースは Microsoft ID プラットフォームからトークンを受け取るときに、トークンをデコードし、appid と iss の要求からクライアントアプリケーション ID を抽出できます。その後、リソースは、保持しているアクセス制御リスト (ACL) とアプリケーションを比較します。 ACL の粒度と方法は、リソース間で大幅に異なる場合があります。

一般的なユースケースでは、ACL を使用して Web アプリケーションまたは Web API のテストを実行します。 Web API は、特定のクライアントに完全なアクセス許可のサブセットのみを与える可能性があります。 API でエンドツーエンドテストを実行するには、Microsoft ID プラットフォームからトークンを取得し、その後それらを API に送信する必要があるテストクライアントを作成します。 API は、API のすべての機能にフルアクセスを持つテストクライアントのアプリケーション ID が ACL にあるかどうかを確認します。この種類の ACL を使用する場合、必ず呼び出し元の appid 値を検証するだけでなく、トークンの iss 値が信頼されていることも検証します。

この種類の承認は、デーモンおよび個人の Microsoft アカウントを持つコンシューマーユーザーが所有するデータにアクセスする必要があるサービスアカウントに共通しています。組織が所有するデータでは、アプリケーションのアクセス許可を介して必要な承認を取得することをお勧めします。

`roles` 要求なしのトークンの制御

この ACL ベースの認証パターンを有効にするために、Microsoft Entra ID では、アプリケーションが別のアプリケーションのトークンを取得することを認可されている必要はありません。そのため、roles 要求なしにアプリ専用トークンを発行できます。 API を公開するアプリケーションは、トークンを受け入れるために、アクセス許可チェックを実装する必要があります。

アプリケーションに対するロールのないアプリケーション専用のアクセストークンをアプリケーションで取得できないようにするには、割り当て要件がアプリに対して有効になるようにします。これにより、ロールが割り当てられていないユーザーとアプリケーションは、このアプリケーションのトークンを取得できなくなります。

アプリケーションのアクセス許可

ACL を使用する代わりに、API を使用してアプリケーションのアクセス許可のセットを公開することができます。これらは、組織の管理者によってアプリケーションに付与され、その組織と従業員が所有するデータにアクセスする場合にのみ使用されます。たとえば、Microsoft Graph は次の操作を行うアクセス許可を公開しています:

すべてのメールボックスのメールの読み取り
すべてのメールボックスのメールの読み書き
任意のユーザーとしてのメールの送信
ディレクトリデータの読み取り

独自の API でアプリロール (アプリケーションのアクセス許可) を使用するには (Microsoft Graph の場合と異なり)、まず、Microsoft Entra 管理センターでの API のアプリ登録で、アプリロールを公開する必要があります。次に、クライアントアプリケーションのアプリ登録でこれらのアクセス許可を選択して、必要なアプリロールを構成します。 API のアプリ登録でアプリロールを公開していない場合は、Microsoft Entra 管理センターでのクライアントアプリケーションのアプリ登録で、その API に対するアプリケーションのアクセス許可を指定できません。

アプリケーションとして認証する場合は (ユーザーの場合と異なり)、"委任されたアクセス許可" を使用できません。アプリに代わって動作するユーザーが存在しないためです。管理者または API の所有者によって付与されるアプリケーションのアクセス許可 (アプリロールとも呼ばれる) を使用する必要があります。

アプリケーションのアクセス許可の詳細については、アクセス許可と同意に関するセクションを参照してください。

推奨: アプリのロールを割り当てられるように管理者でアプリにサインインする

通常、アプリケーションのアクセス許可を使用するアプリケーションを構築する場合は、アプリ側に管理者がアプリのアクセス許可を承認するページまたはビューが必要です。このページは、アプリケーションのサインインフローやアプリの設定の一部、または専用の接続フローにすることができます。職場または学校の Microsoft アカウントでユーザーがサインインした後にのみ、アプリで接続ビューが表示されることが普通です。

ユーザーをアプリにサインインさせると、アクセス許可の承認をユーザーに依頼する前に、ユーザーが所属する組織を識別できます。必須ではありませんが、ユーザーに向けたより直観的なエクスペリエンスの作成に役立ちます。ユーザーをサインインさせるには、Microsoft ID プラットフォームプロトコルのチュートリアルに従ってください。

ディレクトリ管理者にアクセス許可を要求する

組織の管理者にアクセス許可を要求する準備ができたら、Microsoft ID プラットフォームの管理者の同意エンドポイントにユーザーをリダイレクトできます。

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&state=12345
&redirect_uri=http://localhost/myapp/permissions

Pro ヒント:ブラウザーで次の要求を貼り付けてみてください。

https://login.microsoftonline.com/common/adminconsent?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&state=12345&redirect_uri=http://localhost/myapp/permissions

パラメーター	Condition	説明
`tenant`	必須	アクセス許可を要求するディレクトリテナント。これは GUID またはフレンドリ名の形式で指定できます。ユーザーが所属するテナントがわからず、任意のテナントでサインインを行う場合は、`common` を使用します。
`client_id`	必須	[Microsoft Entra 管理センター - アプリの登録] エクスペリエンスからアプリに割り当てられたアプリケーション (クライアント) ID。
`redirect_uri`	必須	処理するアプリの応答の送信先となるリダイレクト URI。ポータルで登録したリダイレクト URI の 1 つと完全に一致する必要があります。ただし、URL でエンコードする必要がある点と、追加のパスセグメントを持つ場合があります。
`state`	推奨	トークンの応答でも返される要求に含まれる値。任意の文字列を指定することができます。この状態は、認証要求の前にアプリ内でユーザーの状態 (表示中のページやビューなど) に関する情報をエンコードする目的に使用されます。

現時点で、Microsoft Entra ID では、テナント管理者のみがサインインして、要求を完了することができます。管理者は、アプリケーション登録ポータルでユーザーがアプリに要求したすべての直接のアプリケーションアクセス許可への承認を求められます。

成功応答

管理者がアプリケーションにアクセス許可を承認すると、成功応答は次のようになります。

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True

パラメーター	説明
`tenant`	アプリケーションが要求したアクセス許可を GUID 形式で付与するディレクトリテナント。
`state`	要求に含まれ、かつトークンの応答として返される値。任意の文字列を指定することができます。この状態は、認証要求の前にアプリ内でユーザーの状態 (表示中のページやビューなど) に関する情報をエンコードする目的に使用されます。
`admin_consent`	True に設定します。

エラー応答

管理者がアプリケーションにアクセス許可を承認しない場合、失敗した応答は次のようになります。

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request

パラメーター	説明
`error`	エラーの種類を分類したりエラーに対処したりする際に使用できるエラーコード文字列。
`error_description`	エラーの根本的な原因を特定しやすいように記述した具体的なエラーメッセージ。

エンドポイントをプロビジョニングしたアプリから成功応答を受信した後に、アプリは要求した直接のアプリケーションアクセス許可を獲得しています。これで、必要なリソースのトークンを要求することができます。

トークンを取得する

アプリケーションに必要な承認を獲得後、API のアクセストークンの取得を開始します。クライアント資格情報の許可を使用してトークンを取得するには、/token Microsoft ID プラットフォームに POST 要求を送信します。以下のようにいくつかの異なるケースがあります。

共有シークレットを使ったアクセストークン要求
証明書を使ったアクセストークン要求
フェデレーション資格情報を使用したアクセストークン要求

最初のケース:共有シークレットを使ったアクセストークン要求

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials

# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=00001111-aaaa-2222-bbbb-3333cccc4444&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=A1bC2dE3f...&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'

パラメーター	Condition	説明
`tenant`	必須	GUID またはドメイン名形式で示すディレクトリテナント。これに対してアプリケーションが動作する予定です。
`client_id`	必須	お使いのアプリに割り当てられたアプリケーション ID。アプリを登録したポータルで、この情報を確認できます。
`scope`	必須	この要求の `scope` パラメーターに渡される値は、`.default` サフィックスが付いた目的のリソースのリソース識別子 (アプリケーション ID URI) である必要があります。含まれるスコープは、すべて 1 つのリソース用である必要があります。複数のリソースのスコープを含めると、エラーが発生します。 Microsoft Graph の場合は、値は `https://graph.microsoft.com/.default` です。この値は、アプリ用に構成したすべての直接のアプリケーションアクセス許可のうち、目的のリソースに関連付けられたトークンを発行するように、Microsoft ID プラットフォームに命じます。 `/.default` スコープの詳細については、同意に関するドキュメントを参照してください。
`client_secret`	必須	アプリケーション登録ポータルでアプリ用に生成したクライアントシークレット。クライアントシークレットは、送信前に URL エンコードされる必要があります。 RFC 6749 に従って、代わりに Authorization ヘッダーで資格情報を提供する基本認証パターンもサポートされています。
`grant_type`	必須	`client_credentials` に設定する必要があります。

2 番目のケース:証明書を使ったアクセストークン要求

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

パラメーター	Condition	説明
`tenant`	必須	GUID またはドメイン名形式で示すディレクトリテナント。これに対してアプリケーションが動作する予定です。
`client_id`	必須	お使いのアプリに割り当てられるアプリケーション (クライアント) ID。
`scope`	必須	この要求の `scope` パラメーターに渡される値は、`.default` サフィックスが付いた目的のリソースのリソース識別子 (アプリケーション ID URI) である必要があります。含まれるスコープは、すべて 1 つのリソース用である必要があります。複数のリソースのスコープを含めると、エラーが発生します。 Microsoft Graph の場合は、値は `https://graph.microsoft.com/.default` です。この値は、アプリ用に構成したすべての直接のアプリケーションアクセス許可のうち、目的のリソースに関連付けられたトークンを発行するように、Microsoft ID プラットフォームに命じます。 `/.default` スコープの詳細については、同意に関するドキュメントを参照してください。
`client_assertion_type`	必須	この値は `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` に設定する必要があります。
`client_assertion`	必須	作成する必要があるアサーション (JSON Web トークン) です。このアサーションは、アプリケーションの資格情報として登録した証明書で署名する必要があります。証明書の登録方法とアサーションの形式の詳細については、証明書資格情報に関する記事を参照してください。
`grant_type`	必須	`client_credentials` に設定する必要があります。

証明書ベースの要求のパラメーターが共有シークレットベースの要求と異なるのは 1 箇所だけであり、client_secret パラメーターが client_assertion_type パラメーターと client_assertion パラメーターに置き換えられています。

3 番目のケース: フェデレーション資格情報を使用したアクセストークン要求

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

パラメーター	Condition	説明
`client_assertion`	必須	アプリケーションが Kubernetes など、外部の別の ID プロバイダーから取得するアサーション (JWT Microsoft ID プラットフォーム JSON Web トークン)。この JWT の詳細は、フェデレーション ID 資格情報としてアプリケーションに登録する必要があります。他の ID プロバイダーから生成されたアサーションを設定して使用する方法については、ワークロード ID フェデレーションに関するページを参照してください。

要求内のすべては、証明書ベースのフローと同じです。ただし、client_assertion のソースの重要な例外を除きます。このフローでは、アプリケーションは JWT アサーション自体を作成しません。代わりに、アプリは別の ID プロバイダーによって作成された JWT を使用します。これは、ワークロード ID フェデレーション と呼ばれます。この場合、Microsoft ID プラットフォーム内のトークンを取得するために、別の ID プラットフォームのアプリ ID が使用されます。これは、Azure の外部でコンピューティングをホストするが、azure によって保護されている API にアクセスするなどのクラウド間のシナリオにMicrosoft ID プラットフォーム。他の ID プロバイダーによって作成される JWT の指定の形式については、「アサーションの形式」を参照してください。

成功応答

任意のメソッドからの正常な応答は次のように表示されます：

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}

パラメーター	説明
`access_token`	要求されたアクセストークン。アプリはこのトークンを使用して、保護されたリソース (Web API など) に対し、認証することができます。
`token_type`	トークンタイプ値を指定します。 Microsoft ID プラットフォームでサポートされる種類は `bearer` のみです。
`expires_in`	アクセストークンが有効な時間 (秒単位)。

警告

この例のトークンを含めて、自分が所有していないすべての API について、トークンの検証や読み取りを行わないでください。 Microsoft サービスのトークンには、JWT として検証されない特殊な形式を使用できます。また、コンシューマー (Microsoft アカウント) ユーザーに対して暗号化される場合もあります。トークンの読み取りは便利なデバッグおよび学習ツールですが、コード内でこれに対する依存関係を取得したり、自分で制御する API 用ではないトークンについての詳細を想定したりしないでください。

エラー応答

エラー応答 (400 無効な要求) は次のように表示されます。

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/.default is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "YYYY-MM-DD HH:MM:SSZ",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

パラメーター	説明
`error`	発生したエラーの種類を分類したりエラーに対処したりする際に使用できるエラーコード文字列。
`error_description`	認証エラーの根本的な原因を特定しやすいように記述した具体的なエラーメッセージ。
`error_codes`	STS 固有のエラーコードの一覧。診断に役立つ可能性がある。
`timestamp`	エラーが発生した時刻。
`trace_id`	診断に役立つ、要求の一意の識別子。
`correlation_id`	コンポーネント間での診断に役立つ、要求の一意の識別子。

トークンを使用する

トークンを獲得したら、そのトークンを使用してリソースへの要求を作成します。トークンの有効期限が切れたときは、/token エンドポイントへの要求を繰り返し、新しいアクセストークンを取得します。

GET /v1.0/users HTTP/1.1
Host: graph.microsoft.com:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...

トークンを自分のものと置き換えて、ターミナルで次のコマンドを試してください。

curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG..." 'https://graph.microsoft.com/v1.0/users'

コードサンプルとその他のドキュメント

Microsoft 認証ライブラリのクライアントの資格情報の概要に関するドキュメントを参照してください。

サンプル	プラットフォーム	説明
active-directory-dotnetcore-daemon-v2	.NET 6.0+	ユーザーの代理ではなく、アプリケーションの ID を使用して Microsoft Graph へのクエリを実行するテナントのユーザーを表示する ASP.NET Core アプリケーション。このサンプルは、認証に証明書を使用するバリエーションも示しています。
active-directory-dotnet-daemon-v2	ASP.NET MVC	ユーザーの代理ではなく、アプリケーションの ID を使用して Microsoft Graph のデータを同期する Web アプリケーション。
ms-identity-javascript-nodejs-console	Node.js コンソール	アプリケーションの ID を使用して Microsoft Graph へのクエリを実行することでテナントのユーザーを表示する Node.js アプリケーション

次の方法で共有

Microsoft ID プラットフォームと OAuth 2.0 クライアント資格情報フロー

プロトコルのダイアグラム

直接承認を取得する

アクセス制御リスト

`roles` 要求なしのトークンの制御

アプリケーションのアクセス許可

推奨: アプリのロールを割り当てられるように管理者でアプリにサインインする

ディレクトリ管理者にアクセス許可を要求する

成功応答

エラー応答

トークンを取得する

最初のケース:共有シークレットを使ったアクセストークン要求

2 番目のケース:証明書を使ったアクセストークン要求

3 番目のケース: フェデレーション資格情報を使用したアクセストークン要求

成功応答

エラー応答

トークンを使用する

コードサンプルとその他のドキュメント

フィードバック

その他のリソース

次の方法で共有

Microsoft ID プラットフォームと OAuth 2.0 クライアント資格情報フロー

プロトコルのダイアグラム

直接承認を取得する

アクセス制御リスト

roles 要求なしのトークンの制御

アプリケーションのアクセス許可

推奨: アプリのロールを割り当てられるように管理者でアプリにサインインする

ディレクトリ管理者にアクセス許可を要求する

成功応答

エラー応答

トークンを取得する

最初のケース:共有シークレットを使ったアクセス トークン要求

2 番目のケース:証明書を使ったアクセス トークン要求

3 番目のケース: フェデレーション資格情報を使用したアクセス トークン要求

成功応答

エラー応答

トークンを使用する

コード サンプルとその他のドキュメント

フィードバック

その他のリソース

`roles` 要求なしのトークンの制御

最初のケース:共有シークレットを使ったアクセストークン要求

2 番目のケース:証明書を使ったアクセストークン要求

3 番目のケース: フェデレーション資格情報を使用したアクセストークン要求

コードサンプルとその他のドキュメント