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 トークンを取得します。

• 単一ページの Web アプリケーション (SPA)
• 標準 (サーバー ベース) Web アプリケーション
• デスクトップ アプリとモバイル アプリ

プロトコルの詳細

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

この時点で、ユーザーに資格情報の入力と認証が求められます。 また、Microsoft ID プラットフォームでは、ユーザーが scope クエリ パラメーターに示されたアクセス許可に同意していることも確認されます。 いずれのアクセス許可にもユーザーが同意しなかった場合、必要なアクセス許可に同意するようユーザーは求められます。 詳細については、「Microsoft ID プラットフォーム エンドポイントでのアクセス許可と同意」を参照してください。

ユーザーが認証され、同意すると、Microsoft ID プラットフォームは response_mode パラメーターで指定されたメソッドを使用して、指定された redirect_uri でアプリに応答を返します。

成功応答

この例では、response_mode=query を使用した正常な応答を示します。

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345

また、ID トークンを要求し、アプリケーションの登録で暗黙的な許可が有効になっている場合には、その ID トークンを受け取ることができます。 この動作は、"ハイブリッド フロー" と呼ばれる場合があります。 これは、ASP.NET のようなフレームワークによって使用されます。

エラー応答

アプリ側でエラーを適切に処理できるよう、 redirect_uri にはエラー応答も送信されます。

GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication

承認エンドポイント エラーのエラー コード

次の表で、エラー応答の error パラメーターで返される可能性のあるさまざまなエラー コードを説明します。

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

fragment を応答モードとして使用すると、リダイレクトからコードを読み取る Web アプリに問題が発生します。 このフラグメントはブラウザーから Web サーバーに渡されません。 このような状況では、すべてのデータがサーバーに送信されるようにするために、アプリで form_post 応答モードを使用してください。

成功応答

この例では、response_mode=fragment を使用した正常な応答を示します。

GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345

アクセス トークンのコードを引き換える

すべての機密クライアントでは、クライアント シークレットまたは証明書資格情報の使用を選択できます。 対称共有シークレットは、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.

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

// 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

パラメーターは共有シークレットによる要求の場合と同じです。ただし、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..."
}

エラー応答

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

{
  "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"
}

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

アクセス トークンを使用する

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 仕様には次のようにあります。"承認サーバーで新しい更新トークンが発行される場合があります。この場合、クライアントは古い更新トークンを破棄し、新しい更新トークンに置き換える必要があります。 承認サーバーは新しい更新トークンをクライアントに発行した後に、古い更新トークンを取り消す場合があります。"

// 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

成功応答

次の例は、正常なトークンの応答を示しています。

{
    "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..."
}

エラー応答

{
  "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"
}

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

次のステップ

• MSAL JS のサンプルを見直して、コーディング作業を開始します。
• トークン交換のシナリオについて理解します。