Microsoft Intune におけるアクセストークンの取得方法について（備忘録） #Azure

認証フローのダイアグラム

（参考）シングルページアプリに必要なリダイレクト URI のセットアップ

シングルページアプリケーションの承認フローの場合は、追加のセットアップが必要。詳細は以下を参照。

シングルページアプリに必要なリダイレクト URI

大まかな流れ

Microsoft Intune のアクセストークンを取得する流れとしては、クライアント側から、Microsoft 承認コードを要求し、その承認コードを使用（交換）してアクセストークンを取得するという流れ。

承認コードを要求する

承認コードのフローは、アプリ側がユーザーを /authorize エンドポイントにリダイレクトさせることから始まる。

// 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=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

パラメータ	必須項目	説明
tenant	必須	アプリケーションにサインインできるユーザーを制御する値。使用可能な値は `common`、`organizations`、`consumers` 及びテナント識別子。詳細はプロトコルの基礎ページ。
client_id	必須	Azure portal のアプリ登録でアプリに割り当てられたアプリケーション ID。
response_type	必須	承認コードのフローでは `code` を指定する。
redirect_uri	必須	アプリのリダイレクト URI。この URI で認証応答を送受信することが可能。ポータルで登録したリダイレクト URI と完全に一致する必要がある。
scope	必須	ユーザーに同意を求めるスコープのリスト。利用するアプリが呼び出す必要のある API に対しての同意を取得することを求める。
resonse_mode	推奨	結果として得られたトークンをアプリに返す際に使用するメソッドを指定。`query`、`fragment`、`from_post` のいずれかを使用して、承認コードを取得可能。細かい差異は OpenID 仕様則るため、詳細はこちら（OpenID Connect プロトコル）で確認。
state	推奨	要求に含まれ、トークンの応答として返される値。クロスサイトリクエストフォージェリ攻撃を防ぐため、通常はランダム値を使用する。
prompt	省略可能	ユーザーとの必要な対話の種類を指定。`logine`、`none`、`consent` が有効。`prompt=login`：その要求でユーザーに資格情報の入力を強制し、シングルサインオンを無効にする。`prompt=none`：ユーザーにどのプロンプトを表示させないようにする。エラー時は `interaction_rerquired` エラーが発生する。`prompt=consent`：ユーザーがサインインした後で、 OAuth 同意ダイアログが表示され、アプリへのアクセス許可の付与をユーザーに求める。
login_hint	省略可能	ユーザー名が事前にわかっている場合、事前にサインインページの電子メールアドレスなどが入力されるようにできる。
domaiin_hint	省略可能	本パラメータあると、ユーザーサインイン時に入力する電子メールの検出プロセスが省略され、効率化される。
code_challenge	推奨/必須	PKCE (Proof Key for Code Excahnge) を使用して承認コード付与をセキュリティ保護するために使用される。`code_challenge_method` が含まれている場合は必須。詳細は PKCE RFC を参照。
code_challenge_method	推奨/必須	`code_challenge` パラメータの `code_verifier` をエンコードするために使用されるメソッド。本来は `S256` が推奨されるが、本パラメータが除外されている場合に `code_challenge` が含まれていると、プレーンテキストとみなされるようになる。詳細は PKCE RFC を参照。

ユーザー本人であることを証明し、同意の許可が得られたら、Microsoft ID プラットフォームエンドポイントは response_mode パラメータで指定された方法を使用して、指定された redirect_uri でアプリ側にレスポンスを返す。

成功時

response_mode=query を使用した場合の正常な応答は以下のようになる。

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

パラメーター	説明
code	アプリが要求した `authorization_code`。アプリはこの承認コードを使用して、対象リソースのアクセストークンを要求する。承認コードは有効期間が短く、通常 10 分後には期限切れとなる。
state	要求に `state` パラメータが含まれていた場合、同じ値が応答にも含まれる。要求と応答に含まれる状態値が同じであることをアプリ側に確認する必要があるため。

エラー時

アプリ側でエラーを処理できるよう、redirect_uri には以下のようなエラーレスポンスが返る。

GET https://login.microsoftonline.com/common/oauth2/nativeclient?
error=access_denied
&error_description=the+user+canceled+the+authentication

パラメータ	説明
error	発生したエラーコード文字列
error_description	認証エラー時のエラーメッセージ

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

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

アクセストークンを要求する

先の手順で authorization_code を取得し、ユーザーからアクセス許可を得たら、access_token を取得できるようになる。これを行うには、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	必須	アプリケーションにサインインできるユーザーを制御する値。使用可能な値は `common`、`organizations`、`consumers` 及びテナント識別子。詳細はプロトコルの基礎ページ。
client_id	必須	Azure portal のアプリ登録でアプリに割り当てられたアプリケーション ID。
grant_type	必須	本承認コードフローでは、`authorization_code` を指定する。
scope	省略可能	スコープリスト。このスコープは、OIDC スコープ（`profile`、`openid`、`email`）に沿って、1 津のリソースからである必要がある。詳細はアクセス許可、同意、スコープを参照。これは Microsoft 拡張機能であり、トークンの引換時にトークンが必要なリソースをアプリによって宣言できるようにするためのものである。
code	必須	フローの最初の段階（承認コードフロー）で取得した authorization_code を指定。
redirect_uri	必須	authorization_code の取得時に使用された同じ redirect_uri を指定。
client_secret	機密 Web アプリには必須	アプリ登録ポータルで作成した、アプリケーションのシークレット。Web アプリや Web API では client_secret をサーバー側で唖然に保存する機能があるため、必ず指定する指定する必要がある。なお、client_secret は送信前に URL エンコードされる必要がある（詳細）。
code_verifier	推奨	authorization_code を取得するために使用されたのと同じ code_verifier を指定する。承認コード付与要求で PKCE が使用された場合は必須。詳細は PKCERFC を参照。

成功時のレスポンス

{
    "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	本記事のゴール。アクセストークン。
token_type	トークンタイプ値。 Azure AD でサポートされるのは Bearer のみ。
expires_in	アクセストークンの有効期間（秒）。
scope	access_token が有効である範囲。
refresh_token	OAuth 2.0 更新トークン。現在のアクセストークンの有効期限が切れた後、アプリはこのトークンを使用して、追加のアクセストークンを取得することが可能。更新トークンは有効期限が長く、リソースへのアックセスを長時間保持するときに利用できる。※ `offline_Access` スコープが要求された場合のみ。
id_token	JSON Web トークン（JWT）。アプリはこのトークンのセグメントをでコードすることでサインインしたユーザーに関する情報を要求することが可能。なお、詳細は 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: 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	アプリによって要求されたスコープが無効です。	認証要求のスコープパラメーターの値を有効な値に更新します。

注意：シングルページアプリケーションで invaid_request エラーが発生することがあり、これは、クロスオリジントークンの使用がシングルページアプリケーションクライアントタイプにしか許可されていないことを示している。つまり、トークンを使用するためのリダイレクト URI がシングルページアプリケーションのリダイレクト URI としてマークされていないことを示している。子のフローを有効にするには、アプリケーションの登録手順に関する記事を参照。

（参考）アクセストークンを使用する

access_token を取得後は、その悪 k セストークンを Authorization ヘッダーに追加することによって、Web API への要求に使用することができる。

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

（参考）アクセストークンを更新する

アクセストークンは有効期間が短いため、アクセストークンを更新するためには、もう一度 POST 要求を /token エンドポイントに送信する。この際、code の代わりに refresh_token を指定する。

※ Web アプリとネイティブアプリにの更新トークンには指定の有効期限はないが、クライアントアプリケーションの場合はトークン発行エンドポイントから返されるエラーを予期して対処するしなければならない場合がある。

※ 新しいアクセストークンを取得した際に使用された更新トークンは、期限内にもかかわらず、古い更新トークンを破棄するよう要請される（OAuth 2.0 の仕様により）。

★ 重要：シングルページアプリケーションとして登録されたリダイレクト URI 　に送信される投信トークンの場合、更新トークンは 24 時間後に期限切れになる。初期更新トークンを使用して取得された追加の投信トークンは、その有効期限を引き継ぐ。そのため、24 時間ごとに新しい更新トークンを取得するために、対話型認証を使用して承認コードフローを再実行するようにアプリを準備する必要がある。

// 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
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh      // NOTE: Only required for web apps. This secret needs to be URL-Encoded

パラメーター	Type	説明
tenant	必須	アプリケーションにサインインできるユーザーを制御する値。使用可能な値は `common`、`organizations`、`consumers` 及びテナント識別子。詳細はプロトコルの基礎ページを参照。
client_id	必須Azure portal のアプリ登録でアプリに割り当てられたアプリケーション ID。
grant_type	必須	本承認コードフローでは、`refresh_token` を指定する。
scope	必須	スコープリスト。この段階で要求するスコープは、最初の承認コード要求段階で要求したスコープと同じか、またはそのサブセットである必要がある。詳細はアクセス許可、同意、スコープを参照。
refresh_token	必須	フローの第 2 段階（アクセストークンを要求する）で取得した refresh_token。
client_secret	Web アプリの場合は必須	アプリ登録ポータルで作成した、アプリケーションのシークレット。ネイティブアプリでは使用しないこと。Web アプリや Web API では client_secret をサーバー側で安全に保存する機能が備わっており、必ず指定する必要がある。なお、このシークレットは URL エンコードする必要があります（詳細）。

成功時のレスポンス内容

{
    "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 更新トークン。できるだけ長い時間、更新トークンを有効な状態に維持するためには、この新しく取得した更新トークンで古い更新トークンを置き換える必要がある。注: offline_access スコープが要求された場合のみ提供される。
id_token	無署名の JSON Web トークン (JWT)。アプリは、このトークンのセグメントをデコードすることによって、サインインしたユーザーに関する情報を要求することができる。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: 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	コンポーネント間での診断に役立つ、要求の一意の識別子。

なお、エラーコードとクライアントに推奨される対処法は、「トークンエンドポイントとエラーコード」を参照。

その他（参考までに）

参考資料

Microsoft ID プラットフォームと OAuth 2.0 認証コードフロー