Microsoft ID プラットフォームと OAuth 2.0 認証コード フロー
OAuth 2.0 認可コード付与タイプ ("認可コード フロー") を使用すると、クライアント アプリケーションは Web API などの保護されたリソースへの認可されたアクセスを取得できます。 認可コード フローには、認可サーバー (Microsoft ID プラットフォーム) からアプリケーションへのリダイレクトをサポートするユーザー エージェントが必要です。 たとえば、ユーザーがアプリにサインインしてデータにアクセスするために操作する Web ブラウザー、デスクトップ、モバイル アプリケーションなどです。
この記事では、フローを実行するために生の HTTP 要求を手動で作成して発行する場合にのみ必要な低レベルのプロトコルの詳細について説明します。これはお勧めしません。 代わりに、Microsoft が構築し、サポートされている認証ライブラリを使用してセキュリティ トークンを取得し、アプリで保護された Web API を呼び出します。
認可コード フローをサポートするアプリケーション
Proof Key for Code Exchange (PKCE) および OpenID Connect (OIDC) とペアになっている認可コード フローを使用して、次の種類のアプリのアクセス トークンと ID トークンを取得します。
プロトコルの詳細
OAuth 2.0 承認コード フローは、 OAuth 2.0 仕様のセクション 4.1で規定されています。 OAuth 2.0 認可コード フローを使用するアプリは、Microsoft ID プラットフォームによって保護されたリソース (通常は API) への要求に含める access_token を取得します。 アプリでは、更新メカニズムを使用して、以前に認証されたエンティティの新しい ID とアクセス トークンを要求することもできます。
次の図は、認証フローの概要を示しています。
単一ページ アプリ (SPA) のリダイレクト URI
認可コード フローを使用する SPA のリダイレクト URI には、特別な構成が必要です。
- PKCE とクロス オリジン リソース共有 (CORS) を使用して認可コード フローをサポートするリダイレクト URI を追加する:「リダイレクト URI: MSAL.js 2.0 と認証コード フロー」の手順に従います。
- リダイレクト URI を更新する: Microsoft Entra 管理センターのアプリケーション マニフェスト エディターを使用し、リダイレクト URI の
typeをspaに設定します。
spa のリダイレクトの種類は、暗黙的なフローと下位互換性があります。 トークンを取得するために暗黙的なフローを現在使用しているアプリは、問題なく spa のリダイレクト URI の種類に移行し、暗黙的なフローを引き続き使用することができます。 この下位互換性にもかかわらず、SPA 用の PKCE で認証コード フローを使用することをお勧めします。
リダイレクト URI に CORS を設定せずに認可コード フローを使用しようとすると、コンソールに次のエラーが表示されます。
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
その場合は、アプリの登録にアクセスし、アプリのリダイレクト URI を更新して spa の種類を使用するようにします。
アプリケーションが SPA 以外のフロー (ネイティブ アプリケーションまたはクライアント資格情報フローなど) で spa リダイレクト URI を使用することはできません。 セキュリティとベスト プラクティスを確保するために、Origin ヘッダーなしで spa リダイレクト URI を使用しようとすると、Microsoft ID プラットフォームからエラーが返されます。 同様に、Microsoft ID プラットフォームでは、シークレットがブラウザー内から使用されないようにするために、Origin ヘッダーが存在するすべてのフローでクライアント資格情報を使用することもできません。
承認コードを要求する
承認コード フローは、クライアントがユーザーを /authorize エンドポイントにリダイレクトさせることから始まります。 この要求の例では、クライアントはユーザーの openid、offline_access、https://graph.microsoft.com/mail.read のアクセス許可を要求します。
Directory.ReadWrite.All を使用した組織のディレクトリへのデータの書き込みなど、一部のアクセス許可は管理者によって制限されます。 アプリケーションが組織のユーザーにこれらのアクセス許可のいずれかへのアクセスを要求すると、ユーザーは、アプリのアクセス許可に同意する権限がないという内容のエラー メッセージを受け取ります。 管理者によって制限されるスコープへのアクセスを要求するには、全体管理者から直接要求する必要があります。 詳細については、「管理者によって制限されるアクセス許可」を参照してください。
特に指定しない限り、省略可能なパラメーターには既定値はありません。 ただし、省略可能なパラメーターを省略する要求の既定の動作があります。 既定の動作では、現在のユーザーのみにサインインしたり、複数のユーザーがいる場合はアカウント選択を表示したり、サインインしたユーザーがいない場合はログインページを表示したりします。
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| パラメーター | 必須/省略可能 | 内容 |
|---|---|---|
tenant |
required | 要求パスの {tenant} の値を使用して、アプリケーションにサインインできるユーザーを制御します。 有効な値は、common、organizations、consumers、およびテナント識別子です。 あるテナントから別のテナントにユーザーをサインインさせるゲスト シナリオでは、ユーザーをリソース テナントにサインインさせるためにテナント識別子を指定する "必要があります"。 詳しくは、「エンドポイント」をご覧ください。 |
client_id |
必須 | [Microsoft Entra 管理センター - アプリの登録] エクスペリエンスからアプリに割り当てられたアプリケーション (クライアント) ID。 |
response_type |
必須 | 承認コード フローでは code を指定する必要があります。 id_tokenを使用する場合は、id_token または token を含めることもできます。 |
redirect_uri |
必須 | アプリの redirect_uri。ここでは、認証応答をアプリで送受信できます。 これは、Microsoft Entra 管理センターに登録したリダイレクト URI のいずれかと完全に一致する必要があります。ただし、URL エンコードが行われている必要があります。 ネイティブまたはモバイル アプリの場合は、推奨される値 (埋め込みのブラウザーを使用するアプリの場合は https://login.microsoftonline.com/common/oauth2/nativeclient、システム ブラウザーを使用するアプリの場合は http://localhost) のいずれかを使用します。 |
scope |
required | ユーザーに同意を求める スコープ の、スペースで区切られたリスト。 要求の /authorize 段階では、このパラメーターは複数のリソースを対象にすることができます。 この値を指定すると、呼び出す複数の Web API に対してアプリで同意を得ることができます。 |
response_mode |
推奨 | ID プラットフォームが要求されたトークンをアプリにどのように返すかを指定します。 サポートされる値: - query: アクセス トークンを要求する場合の既定値。 リダイレクト URI でクエリ文字列パラメーターとしてコードを提供します。 query パラメーターは、暗黙的なフローを使用して ID トークンを要求する場合はサポートされません。 - fragment: 暗黙的なフローを使用して ID トークンを要求する場合の既定値。 また、コード のみ を要求する場合サポートされます。- form_post: リダイレクト URI に対するコードを含んだ POST が実行されます。 コードを要求するときにサポートされます。 |
state |
推奨 | 要求に含まれ、トークンの応答としても返される値。 任意の文字列を指定することができます。 クロスサイト リクエスト フォージェリ攻撃を防ぐために通常、ランダムに生成された一意の値が使用されます。 また、この値で、認証要求の発生前のアプリにおけるユーザーの状態に関する情報のエンコードができます。 たとえば、表示していたページまたはビューをエンコードできます。 |
prompt |
省略可能 | ユーザーとの必要な対話の種類を指定します。 有効な値は、login、none、consent、select_account です。- prompt=login を指定すると、ユーザーはその要求に対して自分の資格情報の入力を強制され、シングル サインオンが無効になります。- prompt=none はその逆です。 これを指定すると、ユーザーに対して対話形式のプロンプトは表示されません。 シングル サインオンを使用して確認なしで要求を完了できない場合は、Microsoft ID プラットフォームから interaction_required エラーが返されます。- prompt=consent を指定すると、ユーザーがサインインした後で OAuth 同意ダイアログが表示され、アプリへのアクセス許可の付与をユーザーは求められます。- prompt=select_account を指定すると、シングル サインオンは中断され、まったく別のアカウントの使用を選択するためのオプションとして、セッション内または記憶されているアカウント内のいずれかにある全アカウントを一覧表示するアカウント選択エクスペリエンスが提供されます。 |
login_hint |
省略可能 | このパラメーターを使用すると、ユーザーに代わって、サインイン ページのユーザー名およびメール アドレス フィールドに事前入力できます。 アプリでは、以前のサインインから login_hint オプション クレームを抽出した後、再認証時にこのパラメーターが使用されます。 |
domain_hint |
オプション | これが含まれていると、サインイン ページでユーザーが経由するメール ベースの検出プロセスがアプリでスキップされ、多少効率化されたユーザー エクスペリエンスが提供されます。 たとえば、フェデレーション ID プロバイダーにユーザーを送信するなどです。 アプリでは、前回のサインインから tid を抽出することで、再認証時にこのパラメーターを使用できます。 |
code_challenge |
推奨/必須 | Proof Key for Code Exchange (PKCE) を使用して認可コード付与をセキュリティ保護するために使用されます。 code_challenge_method が含まれている場合は必須です。 詳細については、「PKCE RFC」を参照してください。 このパラメーターは、すべての種類のアプリケーション (パブリックと機密の両方のクライアント) で推奨されるようになり、認可コード フローを使用するシングル ページ アプリの場合は、Microsoft ID プラットフォームにより必須となりました。 |
code_challenge_method |
推奨/必須 | code_challenge パラメーターの code_verifier をエンコードするために使用されるメソッド。 これは S256 である "べき" ですが、クライアントで SHA256 がサポートできない場合、仕様では plain の使用が許可されています。 除外されていると、 code_challenge が含まれている場合、code_challenge はプレーンテキストであると見なされます。 Microsoft ID プラットフォームは plain と S256 の両方をサポートします。 詳細については、「PKCE RFC」を参照してください。 このパラメーターは、認可コード フローを使用するシングル ページ アプリには必須です。 |
この時点で、ユーザーに資格情報の入力と認証が求められます。 また、Microsoft ID プラットフォームでは、ユーザーが scope クエリ パラメーターに示されたアクセス許可に同意していることも確認されます。 いずれのアクセス許可にもユーザーが同意しなかった場合、必要なアクセス許可に同意するようユーザーは求められます。 詳細については、「Microsoft ID プラットフォーム エンドポイントでのアクセス許可と同意」を参照してください。
ユーザーが認証され、同意すると、Microsoft ID プラットフォームは response_mode パラメーターで指定されたメソッドを使用して、指定された redirect_uri でアプリに応答を返します。
成功応答
この例では、response_mode=query を使用した正常な応答を示します。
GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| パラメーター | 説明 |
|---|---|
code |
アプリが要求した authorization_code。 アプリは認証コードを使用して、ターゲット リソースのアクセス トークンを要求できます。 認可コードの有効期間は短時間です。 通常、約 10 分で期限が切れます。 |
state |
要求に state パラメーターが含まれている場合、同じ値が応答にも含まれることになります。 要求と応答に含まれる状態値が同一であることをアプリ側で確認する必要があります。 |
また、ID トークンを要求し、アプリケーションの登録で暗黙的な許可が有効になっている場合には、その ID トークンを受け取ることができます。 この動作は、"ハイブリッド フロー" と呼ばれる場合があります。 これは、ASP.NET のようなフレームワークによって使用されます。
エラー応答
アプリ側でエラーを適切に処理できるよう、 redirect_uri にはエラー応答も送信されます。
GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
| パラメーター | 説明 |
|---|---|
error |
エラーの種類を分類し、エラーに対処するために使用できるエラー コード文字列。 エラーのこの部分は、アプリがエラーに適切に対処できるよう提供されますが、エラーが発生した理由を詳しく説明するものではありません。 |
error_description |
認証エラーの原因を開発者が特定するのに役立つ具体的なエラー メッセージ。 エラーのこの部分には、エラーが発生した"理由" に関する有用な情報のほとんどが含まれています。 |
承認エンドポイント エラーのエラー コード
次の表で、エラー応答の error パラメーターで返される可能性のあるさまざまなエラー コードを説明します。
| エラー コード | 説明 | クライアント側の処理 |
|---|---|---|
invalid_request |
必要なパラメーターが不足しているなどのプロトコル エラーです。 | 要求を修正し再送信します。 このエラーは、開発エラーであり、通常は初期テスト中に発生します。 |
unauthorized_client |
クライアント アプリケーションは、承認コードの要求を許可されていません。 | 通常、このエラーは、クライアント アプリケーションが Microsoft Entra ID に登録されていない、またはユーザーの Microsoft Entra テナントに追加されていないときに発生します。 アプリケーションでは、アプリケーションのインストールと Microsoft Entra ID への追加を求める指示をユーザーに表示できます。 |
access_denied |
リソースの所有者が同意を拒否しました。 | クライアント アプリケーションは、ユーザーが同意しないと続行できないことを、ユーザーに通知できます。 |
unsupported_response_type |
承認サーバーでは、要求に含まれる応答の種類がサポートされていません。 | 要求を修正し再送信します。 このエラーは、開発エラーであり、通常は初期テスト中に発生します。 ハイブリッド フローでは、このエラーは、クライアント アプリの登録で ID トークンの暗黙的な許可設定を有効にする必要があることを示します。 |
server_error |
サーバーで予期しないエラーが発生しました。 | 要求をやり直してください。 これらのエラーは一時的な状況によって発生します。 クライアント アプリケーションは、一時的なエラーのため応答が遅れることをユーザーに説明する場合があります。 |
temporarily_unavailable |
サーバーが一時的にビジー状態であるため、要求を処理できません。 | 要求をやり直してください。 クライアント アプリケーションは、一時的な状況が原因で応答が遅れることをユーザーに説明する場合があります。 |
invalid_resource |
ターゲット リソースは、存在しない、Microsoft Entra ID で見つけられない、または正しく構成されていないために無効です。 | このエラーは、リソース (存在する場合) がテナントで構成されていないことを示します。 アプリケーションでは、アプリケーションのインストールと Microsoft Entra ID への追加を求める指示をユーザーに表示できます。 |
login_required |
ユーザーが多すぎるか、見つかりません。 | クライアントからサイレント認証が要求されましたが (prompt=none)、ユーザーは 1 人も見つかりませんでした。 このエラーは、セッションで複数のユーザーがアクティブになっているか、ユーザーがいないことを意味する可能性があります。 このエラーでは、選択したテナントが考慮されます。 たとえば、2 つのアクティブな Microsoft Entra アカウントと 1 つの Microsoft アカウントがあり、consumers が選択されている場合、サイレント認証は機能します。 |
interaction_required |
要求にユーザーの介入が必要です。 | 別の認証手順または同意が必要になります。 prompt=none なしで要求を再試行してください。 |
ID トークンも要求する (ハイブリッド フロー)
認可コードの引き換え前にユーザーが誰であるかを確認するには、一般的に、アプリケーションで認可コードを要求するときに ID トークンも要求します。 この手法は、OIDC と OAuth2 の認可コードフローが混在するため、ハイブリッド フロー と呼ばれます。
ハイブリッド フローは、コードの引き換え時にブロックなしでユーザーにページをレンダリングする ために Web アプリで一般的に使用されます (特に ASP.NET)。 シングルページ アプリも従来の Web アプリも、このモデルの待機時間短縮のメリットを得ることができます。
ハイブリッド フローは、前述の認可コード フローと同じですが、3 つの追加があります。 ID トークンを要求するためには、これらの追加 (新しいスコープ、新しい response_type、新しい nonce クエリ パラメーター) のすべてが必要です。
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| 更新対象パラメーター | 必須/省略可能 | 内容 |
|---|---|---|
response_type |
required | id_token の追加により、アプリケーションが /authorize エンドポイントからの応答で ID トークンを要求していることがサーバーに示されます。 |
scope |
必須 | ID トークンの場合、このパラメーターを更新して ID トークン スコープ (openid と、省略可能な profile および email) を含める必要があります。 |
nonce |
required | アプリによって生成された、要求に含まれる値。この値が、最終的な id_token に要求として含まれます。 アプリでこの値を確認することにより、トークン再生攻撃を緩和することができます。 通常、この値はランダム化された一意の文字列であり、要求の送信元を特定する際に使用できます。 |
response_mode |
推奨 | 結果として得られたトークンをアプリに返す際に使用するメソッドを指定します。 既定値は、認可コードのみ向けに query ですが、OpenAI 仕様で指定されているように、要求に id_token response_type を含める場合は fragment に設定します。特にリダイレクト URI として http://localhost を使用する場合は、アプリで form_post を使用することをお勧めします。 |
fragment を応答モードとして使用すると、リダイレクトからコードを読み取る Web アプリに問題が発生します。 このフラグメントはブラウザーから Web サーバーに渡されません。 このような状況では、すべてのデータがサーバーに送信されるようにするために、アプリで form_post 応答モードを使用してください。
成功応答
この例では、response_mode=fragment を使用した正常な応答を示します。
GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
| パラメーター | 説明 |
|---|---|
code |
アプリが要求した承認コード。 アプリは承認コードを使用して、対象リソースのアクセス トークンを要求します。 認可コードは有効期間が短く、通常 10 分後には期限切れとなります。 |
id_token |
"暗黙的な許可" を使用して発行された、ユーザーの ID トークン。 同じ要求に code のハッシュである特別な c_hash 要求が含まれます。 |
state |
要求に state パラメーターが含まれている場合、同じ値が応答にも含まれることになります。 アプリは、要求と応答の state 値が同じであることを検証します。 |
アクセス トークンのコードを引き換える
すべての機密クライアントでは、クライアント シークレットまたは証明書資格情報の使用を選択できます。 対称共有シークレットは、Microsoft ID プラットフォームによって生成されます。 証明書の資格情報は、開発者によってアップロードされた非対称キーです。 詳細については、「Microsoft ID プラットフォーム アプリケーションの認証証明書資格情報」を参照してください。
最高のセキュリティのために、証明書資格情報を使用することをお勧めします。 ネイティブ アプリケーションとシングル ページ アプリを含むパブリック クライアントでは、認可コードの引き換え時にシークレットも証明書も使用しないでください。 リダイレクト URI がアプリケーションの種類を含み、一意であることを必ず確認してください。
client_secret を使用してアクセス トークンを要求する
authorization_code を取得し、ユーザーからアクセス許可を得たら、リソースに対する access_token の code を引き換えることができます。 code を引き換えるには、POST 要求を /token エンドポイントに送信します。
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
| パラメーター | 必須/省略可能 | 内容 |
|---|---|---|
tenant |
required | 要求パスの {tenant} の値を使用して、アプリケーションにサインインできるユーザーを制御します。 有効な値は、common、organizations、consumers、およびテナント識別子です。 詳しくは、「エンドポイント」をご覧ください。 |
client_id |
必須 | [Microsoft Entra管理センター - アプリの登録] ページからアプリに割り当てられたアプリケーション (クライアント) ID。 |
scope |
省略可能 | スペースで区切られたスコープのリスト。 このスコープはすべて、OIDC スコープ (profile、openid、email) に沿って、1 つのリソースからである必要があります。 詳細については、「Microsoft ID プラットフォーム エンドポイントでのアクセス許可と同意」を参照してください。 このパラメーターは、認可コード フローに対する Microsoft 拡張機能であり、トークンの引き換え時にトークンが必要なリソースをアプリで宣言できるようにするためのものです。 |
code |
必須 | フローの最初の段階で取得した authorization_code。 |
redirect_uri |
必須 | authorization_code を取得するために使用されたものと同じ redirect_uri 値。 |
grant_type |
required | 承認コード フローでは authorization_code を指定する必要があります。 |
code_verifier |
推奨 | authorization_code を取得するために使用されたのと同じ code_verifier。 承認コード付与要求で PKCE が使用された場合は必須です。 詳細については、「PKCE RFC」を参照してください。 |
client_secret |
機密 Web アプリには必須 | アプリ登録ポータルで作成した、アプリケーションのシークレット。 client_secret をデバイスや Web ページに確実に保存することはできないため、ネイティブ アプリやシングル ページ アプリではアプリケーション シークレットを使用しないでください。 サーバー側で client_secret を安全に保存できる Web アプリや Web API では、これは必須です。 ここにあるすべてのパラメーターと同様に、クライアン トシークレットは、送信前に URL エンコードする必要があります。 この手順は、SDK によって行われます。 URI エンコードの詳細については、URI の一般構文の仕様に関する記事を参照してください。 RFC 6749 に従って、代わりに Authorization ヘッダーで資格情報を提供する基本認証パターンもサポートされています。 |
証明書資格情報を使用してアクセス トークンを要求する
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
| パラメーター | 必須/省略可能 | 内容 |
|---|---|---|
tenant |
required | 要求パスの {tenant} の値を使用して、アプリケーションにサインインできるユーザーを制御します。 有効な値は、common、organizations、consumers、およびテナント識別子です。 詳細については、「エンドポイント」を参照してください。 |
client_id |
必須 | [Microsoft Entra管理センター - アプリの登録] ページからアプリに割り当てられたアプリケーション (クライアント) ID。 |
scope |
省略可能 | スペースで区切られたスコープのリスト。 このスコープはすべて、OIDC スコープ (profile、openid、email) に沿って、1 つのリソースからである必要があります。 詳細については、アクセス許可、同意、スコープに関する記事を参照してください。 このパラメーターは、認可コード フローに対する Microsoft 拡張機能です。 この拡張機能により、トークンの引き換え時に、トークンを必要とするリソースをアプリで宣言できるようになります。 |
code |
必須 | フローの最初の段階で取得した authorization_code。 |
redirect_uri |
必須 | authorization_code を取得するために使用されたものと同じ redirect_uri 値。 |
grant_type |
required | 承認コード フローでは authorization_code を指定する必要があります。 |
code_verifier |
推奨 | authorization_code を取得するために使用されたものと同じ code_verifier。 承認コード付与要求で PKCE が使用された場合は必須です。 詳細については、「PKCE RFC」を参照してください。 |
client_assertion_type |
機密 Web アプリには必須 | 証明書資格情報を使用するには、この値を urn:ietf:params:oauth:client-assertion-type:jwt-bearer に設定する必要があります。 |
client_assertion |
機密 Web アプリには必須 | JSON Web トークン (JWT) であるアサーション。これを作成し、アプリケーションの資格情報として登録した証明書で署名する必要があります。 証明書の登録方法とアサーションの形式の詳細については、証明書資格情報に関する記事を参照してください。 |
パラメーターは共有シークレットによる要求の場合と同じです。ただし、client_secret パラメーターが client_assertion_type と client_assertion の 2 つのパラメーターに置き換えられている点を除きます。
成功応答
次の例は、正常なトークンの応答を示しています。
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| パラメーター | 説明 |
|---|---|
access_token |
要求されたアクセス トークン。 アプリはこのトークンを使用して、Web API など、保護されたリソースに対して認証できます。 |
token_type |
トークン タイプ値を指定します。 Microsoft Entra ID でサポートされる種類は Bearer のみです。 |
expires_in |
アクセス トークンの有効期間 (秒)。 |
scope |
access_token が有効である範囲。 省略可能。 これは非標準です。省略した場合、トークンはフローの最初の段階で要求されたスコープ用になります。 |
refresh_token |
OAuth 2.0 更新トークン。 現在のアクセス トークンの有効期限が切れた後に他のアクセス トークンを取得するために、アプリでこのトークンを使用できます。 更新トークンの有効期間は長期です。 これは、リソースへのアクセスを長期間維持できます。 アクセス トークンの更新の詳細については、この記事で後述する「アクセス トークンを更新する」を参照してください。 注: offline_access スコープが要求された場合のみ提供されます。 |
id_token |
JSON Web トークン。 アプリは、このトークンのセグメントをデコードして、サインインしたユーザーに関する情報を要求することができます。 アプリではこの値をキャッシュして表示できます。また、機密クライアントでは認可にこのトークンを使用できます。 id_token の詳細については、id_token referenceを参照してください。 注: openid スコープが要求された場合のみ提供されます。 |
エラー応答
この例は、エラー応答です。
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read 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": "2016-01-09 02:02:12Z",
"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 |
コンポーネント間での診断に役立つ、要求の一意の識別子。 |
トークン エンドポイント エラーのエラー コード
| エラー コード | 説明 | クライアント側の処理 |
|---|---|---|
invalid_request |
必要なパラメーターが不足しているなどのプロトコル エラーです。 | 要求またはアプリの登録を修正し、要求を再送信します。 |
invalid_grant |
承認コードまたは PKCE コード検証機能が無効か、有効期限切れです。 | /authorize エンドポイントに対する新しい要求を試し、code_verifier パラメーターが正しいことを確認します。 |
unauthorized_client |
認証されたクライアントは、この承認付与の種類を使用する権限がありません。 | 通常、このエラーは、クライアント アプリケーションが Microsoft Entra ID に登録されていない、またはユーザーの Microsoft Entra テナントに追加されていないときに発生します。 アプリケーションでは、アプリケーションのインストールと Microsoft Entra ID への追加を求める指示をユーザーに表示できます。 |
invalid_client |
クライアント認証に失敗しました。 | クライアント資格情報が有効ではありません。 修正するには、アプリケーション管理者が資格情報を更新します。 |
unsupported_grant_type |
認可付与タイプが承認サーバーでサポートされていません。 | 要求の付与の種類を変更します。 この種のエラーは、開発時にのみ発生し、初期テスト中に検出する必要があります。 |
invalid_resource |
ターゲット リソースは、存在しない、Microsoft Entra ID で見つけられない、または正しく構成されていないために無効です。 | このコードは、リソース (存在する場合) がテナントで構成されていないことを示します。 アプリケーションでは、アプリケーションのインストールと Microsoft Entra ID への追加を求める指示をユーザーに表示できます。 |
interaction_required |
このコードは、OIDC 仕様では /authorize エンドポイントでのみ必要になるため、非標準です。 要求にユーザーの介入が必要です。 たとえば、別の認証手順が必要です。 |
同じスコープで /authorize 要求を再試行します。 |
temporarily_unavailable |
サーバーが一時的にビジー状態であるため、要求を処理できません。 | 短い遅延後に要求を再試行します。 クライアント アプリケーションは、一時的な状況が原因で応答が遅れることをユーザーに説明する場合があります。 |
consent_required |
要求にはユーザーの同意が必要です。 このエラーは非標準です。 これは通常、OIDC の仕様に従って /authorize エンドポイントでのみ返されます。 要求するアクセス許可がクライアント アプリにないコード引き換えフローで scope パラメーターが使用された場合に返されます。 |
クライアントでは、同意をトリガーするために、正しいスコープの /authorize エンドポイントにユーザーを返信する必要があります。 |
invalid_scope |
アプリによって要求されたスコープが無効です。 | 認証要求の scope パラメーターの値を有効な値に更新します。 |
注意
シングル ページ アプリで invalid_request エラーが発生することがあります。これは、クロスオリジン トークンの使用が、"シングル ページ アプリケーション" クライアント タイプにしか許可されないことを示します。 これは、トークンを要求するために使用されるリダイレクト URI が spa リダイレクト URI としてマークされていないことを示します。 このフローを有効にする方法については、アプリケーションの登録手順に関する記事を参照してください。
アクセス トークンを使用する
access_token を無事取得したら、そのトークンを Authorization ヘッダーに追加することによって、Web API への要求に使用することができます。
GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
アクセス トークンを更新する
アクセス トークンの有効期間は短時間です。 リソースへのアクセスを継続するには、有効期限が切れた後に更新してください。 トークンを更新するには、もう一度 POST 要求を /token エンドポイントに送信します。 code の代わりに refresh_token を指定します。 更新トークンは、クライアントが既に同意を受け取ったすべてのアクセス許可に対して有効です。 たとえば、scope=mail.read の要求に対して発行された更新トークンを使用して、scope=api://contoso.com/api/UseResource の新しいアクセス トークンを要求できます。
Web アプリとネイティブ アプリの更新トークンには、指定された有効期間はありません。 通常、更新トークンの有効期間は比較的長いです。 ただし、場合によっては、更新トークンの有効期限が切れる、失効する、または操作のための十分な特権がないことがあります。 アプリケーションでは、トークン発行エンドポイントから返されるエラーを想定し、処理する必要があります。 シングル ページ アプリでは有効期間が 24 時間のトークンを取得するため、新しい認証が毎日必要になります。 このアクションは、サードパーティの Cookie が有効になっている場合に iframe でサイレントに実行できます。 これは、Safari などのサードパーティの Cookie を使用しないブラウザーで、最上位フレーム (ページ 全体のナビゲーションまたはポップアップ ウィンドウ) で実行される必要があります。
更新トークンは、新しいアクセス トークンの取得に使用されたときに取り消されません。 ご自分で古い更新トークンを破棄することが求められます。 OAuth 2.0 仕様には次のようにあります。"承認サーバーで新しい更新トークンが発行される場合があります。この場合、クライアントは古い更新トークンを破棄し、新しい更新トークンに置き換える必要があります。 承認サーバーは新しい更新トークンをクライアントに発行した後に、古い更新トークンを取り消す場合があります。"
重要
spa として登録されたリダイレクト URI に送信される更新トークンの場合、更新トークンは 24 時間後に期限切れになります。 初期更新トークンを使用して取得された追加の更新トークンは、その有効期限を引き継ぎます。そのため、24 時間ごとに新しい更新トークンを取得するために、対話型認証を使用して認可コード フローを再実行するようにアプリを準備する必要があります。 ユーザーは自分の資格情報を入力する必要はなく、通常はユーザーエクスペリエンスも表示されず、アプリケーションを再読み込みするだけです。 ブラウザーは、ログイン セッションを表示するために、最上位フレームのログイン ページにアクセスする必要があります。 これは、サード パーティの Cookie をブロックするブラウザーのプライバシー機能のためです。
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded
| パラメーター | 型 | 内容 |
|---|---|---|
tenant |
required | 要求パスの {tenant} の値を使用して、アプリケーションにサインインできるユーザーを制御します。 有効な値は、common、organizations、consumers、およびテナント識別子です。 詳しくは、「エンドポイント」をご覧ください。 |
client_id |
必須 | [Microsoft Entra 管理センター - アプリの登録] エクスペリエンスからアプリに割り当てられたアプリケーション (クライアント) ID。 |
grant_type |
必須 | この段階の承認コード フローでは refresh_token を指定する必要があります。 |
scope |
オプション | スペースで区切られたスコープのリスト。 この段階で要求するスコープは、当初の authorization_code 要求の段階で要求したスコープと同じか、またはそのサブセットである必要があります。 この要求で指定したスコープが複数のリソース サーバーにまたがる場合、Microsoft ID プラットフォームからは、最初のスコープで指定したリソースのトークンが返されます。 詳細については、「Microsoft ID プラットフォーム エンドポイントでのアクセス許可と同意」を参照してください。 |
refresh_token |
必須 | フローの第 2 段階で取得した refresh_token。 |
client_secret |
Web アプリの場合は必須 | アプリ登録ポータルで作成した、アプリケーションのシークレット。 ネイティブ アプリでは使用しないでください。デバイスに client_secret を確実に保存できないためです。 サーバー側で client_secret を安全に保存できる Web アプリや Web API では、これは必須です。 このシークレットは URL エンコードする必要があります。 詳細については、URI の一般構文の仕様に関する記事を参照してください。 |
成功応答
次の例は、正常なトークンの応答を示しています。
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| パラメーター | 説明 |
|---|---|
access_token |
要求されたアクセス トークン。 アプリはこのトークンを使用して、Web API など、保護されたリソースに対して認証できます。 |
token_type |
トークン タイプ値を指定します。 Microsoft Entra ID でサポートされる種類はベアラーのみです。 |
expires_in |
アクセス トークンの有効期間 (秒)。 |
scope |
access_token が有効である範囲。 |
refresh_token |
新しい OAuth 2.0 更新トークン。 できるだけ長い時間、更新トークンを有効な状態に維持するために、この新しく取得した更新トークンで古い更新トークンを置き換えます。 注: offline_access スコープが要求された場合のみ提供されます。 |
id_token |
無署名の JSON Web トークン。 アプリは、このトークンのセグメントをデコードして、サインインしたユーザーに関する情報を要求することができます。 アプリはこの値をキャッシュして表示できますが、承認やセキュリティ境界のためにこの値を使用することはできません。 id_token の詳細については、「id_token」を参照してください。 注: openid スコープが要求された場合のみ提供されます。 |
警告
この例のトークンを含めて、自分が所有していないすべての API について、トークンの検証や読み取りを行わないでください。 Microsoft サービスのトークンには、JWT として検証されない特殊な形式を使用できます。また、コンシューマー (Microsoft アカウント) ユーザーに対して暗号化される場合もあります。 トークンの読み取りは便利なデバッグおよび学習ツールですが、コード内でこれに対する依存関係を取得したり、自分で制御する API 用ではないトークンについての詳細を想定したりしないでください。
エラー応答
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read 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": "2016-01-09 02:02:12Z",
"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 |
コンポーネント間での診断に役立つ、要求の一意の識別子。 |
エラー コードとクライアントに推奨される対処法については、「トークン エンドポイント エラーのエラー コード」を参照してください。
次のステップ
- MSAL JS のサンプルを見直して、コーディング作業を開始します。
- トークン交換のシナリオについて理解します。