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 とアクセス トークンを要求することもできます。

ヒント

Postman でこの要求を実行してみる
Postman でこの要求やその他を実行してみてください。その際、トークンと ID を忘れずに置き換えてください。

次の図は、認証フローの概要を示しています。

OAuth 認可コード フローを示す図。ネイティブ アプリと Web API は、この記事で説明するトークンを使用して対話します。

単一ページ アプリ (SPA) のリダイレクト URI

認可コード フローを使用する SPA のリダイレクト URI には、特別な構成が必要です。

spa のリダイレクトの種類は、暗黙的なフローと下位互換性があります。 トークンを取得するために暗黙的なフローを現在使用しているアプリは、問題なく spa のリダイレクト URI の種類に移行し、暗黙的なフローを引き続き使用することができます。

リダイレクト 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 エンドポイントにリダイレクトさせることから始まります。 この要求では、クライアントは、ユーザーからの openidoffline_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=6731de76-14a6-49ae-97bc-6eba6914391e
&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

ヒント

この要求を実行するには、以下のリンクを選択してください。 サインイン後、ブラウザーは http://localhost/myapp/ にリダイレクトされ、アドレス バーに code が含まれた状態になります。 https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

パラメーター 必須/省略可能 説明
tenant required 要求パスの {tenant} の値を使用して、アプリケーションにサインインできるユーザーを制御します。 有効な値は、commonorganizationsconsumers、およびテナント識別子です。 あるテナントから別のテナントにユーザーをサインインさせるゲスト シナリオでは、ユーザーをリソース テナントにサインインさせるためにテナント識別子を指定する "必要があります"。 詳しくは、「エンドポイント」をご覧ください。
client_id required Azure portal の [アプリの登録] エクスペリエンスでアプリに割り当てられたアプリケーション (クライアント) ID
response_type required 承認コード フローでは code を指定する必要があります。 id_tokenを使用する場合は、id_token または token を含めることもできます。
redirect_uri 必須 アプリの redirect_uri。ここでは、認証応答をアプリで送受信できます。 ポータルで登録したいずれかのリダイレクト 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 省略可能 ユーザーとの必要な対話の種類を指定します。 有効な値は、loginnoneconsentselect_account です。

- prompt=login を指定すると、ユーザーはその要求に対して自分の資格情報の入力を強制され、シングル サインオンが無効になります。
- prompt=none はその逆です。 これを指定すると、ユーザーに対して対話形式のプロンプトは表示されません。 シングル サインオンを使用して確認なしで要求を完了できない場合は、Microsoft ID プラットフォームから interaction_required エラーが返されます。
- prompt=consent を指定すると、ユーザーがサインインした後で OAuth 同意ダイアログが表示され、アプリへのアクセス許可の付与をユーザーは求められます。
- prompt=select_account を指定すると、シングル サインオンは中断され、まったく別のアカウントの使用を選択するためのオプションとして、セッション内または記憶されているアカウント内のいずれかにある全アカウントを一覧表示するアカウント選択エクスペリエンスが提供されます。
login_hint 省略可能 このパラメーターを使用すると、ユーザーに代わって、サインイン ページのユーザー名およびメール アドレス フィールドに事前入力できます。 アプリでは、以前のサインインから login_hintlogin_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 をエンコードするために使用されるメソッド。 これは である "べき" ですが、クライアントで SHA256 がサポートできない場合、仕様では plain の使用が許可されています。

除外されていると、code_challenge が含まれている場合、code_challenge はプレーンテキストであると見なされます。 Microsoft ID プラットフォームは plainS256 の両方をサポートします。 詳細については、「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 クライアント アプリケーションは、承認コードの要求を許可されていません。 通常、このエラーは、クライアント アプリケーションが Azure AD に登録されていない、またはユーザーの Azure AD テナントに追加されていないときに発生します。 アプリケーションでは、アプリケーションのインストールと Azure AD への追加を求める指示をユーザーに表示できます。
access_denied リソースの所有者が同意を拒否しました。 クライアント アプリケーションは、ユーザーが同意しないと続行できないことを、ユーザーに通知できます。
unsupported_response_type 承認サーバーでは、要求に含まれる応答の種類がサポートされていません。 要求を修正し再送信します。 このエラーは、開発エラーであり、通常は初期テスト中に発生します。 ハイブリッド フローでは、このエラーは、クライアント アプリの登録で ID トークンの暗黙的な許可設定を有効にする必要があることを示します。
server_error サーバーで予期しないエラーが発生しました。 要求をやり直してください。 これらのエラーは一時的な状況によって発生します。 クライアント アプリケーションは、一時的なエラーのため応答が遅れることをユーザーに説明する場合があります。
temporarily_unavailable サーバーが一時的にビジー状態であるため、要求を処理できません。 要求をやり直してください。 クライアント アプリケーションは、一時的な状況が原因で応答が遅れることをユーザーに説明する場合があります。
invalid_resource 対象のリソースは、存在しない、Azure AD が見つけられない、または正しく構成されていないために無効です。 このエラーは、リソース (存在する場合) がテナントで構成されていないことを示します。 アプリケーションでは、アプリケーションのインストールと Azure AD への追加を求める指示をユーザーに表示できます。
login_required ユーザーが多すぎるか、見つかりません。 クライアントからサイレント認証が要求されましたが (prompt=none)、ユーザーは 1 人も見つかりませんでした。 このエラーは、セッションで複数のユーザーがアクティブになっているか、ユーザーがいないことを意味する可能性があります。 このエラーでは、選択したテナントが考慮されます。 たとえば、2 つのアクティブな Azure AD アカウントと 1 つの Microsoft アカウントがあり、consumers が選択されている場合、サイレント認証は機能します。
interaction_required 要求にユーザーの介入が必要です。 別の認証手順または同意が必要になります。 prompt=none なしで要求を再試行してください。

ID トークンも要求する (ハイブリッド フロー)

認可コードの引き換え前にユーザーが誰であるかを確認するには、一般的に、アプリケーションで認可コードを要求するときに ID トークンも要求します。 この手法は、暗黙的な許可と認可コード フローが混在するため、"ハイブリッド フロー" と呼ばれます。

ハイブリッド フローは、コードの引き換え時にブロックなしでユーザーにページをレンダリングする ために 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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単なる承認コードに対してですが、fragmentid_tokenresponse_typeOpenID 仕様で指定された要求が含まれている場合form_post、 特に http://localhostリダイレクト URI として使用する場合は、アプリの使用をお勧めします。

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_tokencode を引き換えることができます。 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
パラメーター 必須/省略可能 説明
tenant required 要求パスの {tenant} の値を使用して、アプリケーションにサインインできるユーザーを制御します。 有効な値は、commonorganizationsconsumers、およびテナント識別子です。 詳しくは、「エンドポイント」をご覧ください。
client_id 必須 Azure portal の [アプリの登録] ページでアプリに割り当てられたアプリケーション (クライアント) ID
scope オプション スペースで区切られたスコープのリスト。 このスコープはすべて、OIDC スコープ (profileopenidemail) に沿って、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 ヘッダーで資格情報を提供する基本認証パターンもサポートされています。

証明書資格情報を使用してアクセス トークンを要求する

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

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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} の値を使用して、アプリケーションにサインインできるユーザーを制御します。 有効な値は、commonorganizationsconsumers、およびテナント識別子です。 詳細については、「エンドポイント」を参照してください。
client_id 必須 Azure portal の [アプリの登録] ページでアプリに割り当てられたアプリケーション (クライアント) ID
scope オプション スペースで区切られたスコープのリスト。 このスコープはすべて、OIDC スコープ (profileopenidemail) に沿って、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_typeclient_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 トークン タイプ値を指定します。 Azure AD でサポートされるのは Bearer のみです。
expires_in アクセス トークンの有効期間 (秒)。
scope access_token が有効である範囲。 省略可能。 これは非標準です。省略した場合、トークンはフローの最初の段階で要求されたスコープ用になります。
refresh_token OAuth 2.0 更新トークン。 現在のアクセス トークンの有効期限が切れた後に他のアクセス トークンを取得するために、アプリでこのトークンを使用できます。 更新トークンの有効期間は長期です。 これは、リソースへのアクセスを長期間維持できます。 アクセス トークンの更新の詳細については、この記事で後述する「アクセス トークンを更新する」を参照してください。
注: スコープが要求された場合のみ提供されます。
id_token JSON Web トークン。 アプリは、このトークンのセグメントをデコードして、サインインしたユーザーに関する情報を要求することができます。 アプリではこの値をキャッシュして表示できます。また、機密クライアントでは認可にこのトークンを使用できます。 id_token の詳細については、id_token referenceを参照してください。
注: スコープが要求された場合のみ提供されます。

エラー応答

この例は、エラー応答です。

{
  "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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
パラメーター 説明
error エラーの種類を分類し、エラーに対処するために使用できるエラー コード文字列。
error_description 認証エラーの原因を開発者が特定するのに役立つ具体的なエラー メッセージ。
error_codes 診断に役立つ STS 固有のエラー コードの一覧。
timestamp エラーが発生した時刻。
trace_id 診断に役立つ、要求の一意の識別子。
correlation_id コンポーネント間での診断に役立つ、要求の一意の識別子。

トークン エンドポイント エラーのエラー コード

エラー コード 説明 クライアント側の処理
invalid_request 必要なパラメーターが不足しているなどのプロトコル エラーです。 要求またはアプリの登録を修正し、要求を再送信します。
invalid_grant 承認コードまたは PKCE コード検証機能が無効か、有効期限切れです。 /authorize エンドポイントに対する新しい要求を試し、code_verifier パラメーターが正しいことを確認します。
unauthorized_client 認証されたクライアントは、この承認付与の種類を使用する権限がありません。 通常、このエラーは、クライアント アプリケーションが Azure AD に登録されていない、またはユーザーの Azure AD テナントに追加されていないときに発生します。 アプリケーションでは、アプリケーションのインストールと Azure AD への追加を求める指示をユーザーに表示できます。
invalid_client クライアント認証に失敗しました。 クライアント資格情報が有効ではありません。 修正するには、アプリケーション管理者が資格情報を更新します。
unsupported_grant_type 認可付与タイプが承認サーバーでサポートされていません。 要求の付与の種類を変更します。 この種のエラーは、開発時にのみ発生し、初期テスト中に検出する必要があります。
invalid_resource 対象のリソースは、存在しない、Azure AD で見つけられない、または正しく構成されていないために無効です。 このコードは、リソース (存在する場合) がテナントで構成されていないことを示します。 アプリケーションでは、アプリケーションのインストールと Azure AD への追加を求める指示をユーザーに表示できます。
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=535fb089-9ff3-47b6-9bfb-4f1264799865
&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
パラメーター Type 説明
tenant required 要求パスの {tenant} の値を使用して、アプリケーションにサインインできるユーザーを制御します。 有効な値は、commonorganizationsconsumers、およびテナント識別子です。 詳しくは、「エンドポイント」をご覧ください。
client_id required Azure portal の [アプリの登録] エクスペリエンスでアプリに割り当てられたアプリケーション (クライアント) ID
grant_type required この段階の承認コード フローでは 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 トークン タイプ値を指定します。 Azure AD でサポートされるのは Bearer タイプのみです。
expires_in アクセス トークンの有効期間 (秒)。
scope access_token が有効である範囲。
refresh_token 新しい OAuth 2.0 更新トークン。 できるだけ長い時間、更新トークンを有効な状態に維持するために、この新しく取得した更新トークンで古い更新トークンを置き換えます。
注: スコープが要求された場合のみ提供されます。
id_token 無署名の JSON Web トークン。 アプリは、このトークンのセグメントをデコードして、サインインしたユーザーに関する情報を要求することができます。 アプリはこの値をキャッシュして表示できますが、承認やセキュリティ境界のためにこの値を使用することはできません。 id_token の詳細については、「id_token」を参照してください。
注: スコープが要求された場合のみ提供されます。

警告

この例のトークンを含めて、自分が所有していないすべての 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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
パラメーター 説明
error エラーの種類を分類し、エラーに対処するために使用できるエラー コード文字列。
error_description 認証エラーの根本的な原因を開発者が特定しやすいように記述した具体的なエラー メッセージ。
error_codes 診断に役立つ STS 固有のエラー コードの一覧。
timestamp エラーが発生した時刻。
trace_id 診断に役立つ、要求の一意の識別子。
correlation_id コンポーネント間での診断に役立つ、要求の一意の識別子。

エラー コードとクライアントに推奨される対処法については、「トークン エンドポイント エラーのエラー コード」を参照してください。

次のステップ