Microsoft ID プラットフォーム アクセス トークンMicrosoft identity platform access tokens

• 2020/05/18
• • 
  • 
  • 

アクセス トークンにより、クライアントは保護された API を安全に呼び出すことができます。Access tokens enable clients to securely call protected APIs. Microsoft ID プラットフォーム アクセス トークンは JWT、つまり Microsoft ID プラットフォームによって署名された Base64 でエンコードされた JSON オブジェクトです。Microsoft identity platform access tokens are , Base64 encoded JSON objects signed by Microsoft identity platform. アクセス トークンの内容は特定のリソースのみを対象としているため、クライアントはトークンを不透明型の文字列として扱う必要があります。Clients should treat access tokens as opaque strings, as the contents of the token are intended for the resource only. 検証とデバッグを目的として、開発者は jwt.ms などのサイトを使用して、JWT (JSON Web トークン) をデコードすることができます。For validation and debugging purposes, developers can decode JWTs (JSON Web Tokens) using a site like . クライアントは、さまざまなプロトコルを使用して、v1.0 エンドポイントまたは v2.0 エンドポイントのどちらからでもアクセス トークンを取得できます。Your client can get an access token from either the v1.0 endpoint or the v2.0 endpoint using a variety of protocols.

クライアントがアクセス トークンを要求すると、Microsoft ID プラットフォームからは、アプリで消費されるそのアクセス トークンに関する何らかのメタデータも返されます。When your client requests an access token, Microsoft identity platform also returns some metadata about the access token for your app's consumption. この情報には、アクセス トークンの有効期限や、それが有効なスコープが含まれます。This information includes the expiry time of the access token and the scopes for which it's valid. このデータを使用すると、アプリはアクセス トークン自体を解析しなくても、そのアクセス トークンのインテリジェントなキャッシュを実行できます。This data allows your app to do intelligent caching of access tokens without having to parse the access token itself.

ご自分のアプリケーションが、クライアントからアクセス要求が可能なリソース (Web API) である場合、アクセス トークンを使って、認証と承認に使用する有用な情報 (ユーザー、クライアント、発行元、アクセス許可など) を提供できます。If your application is a resource (web API) that clients can request access to, access tokens provide helpful information for use in authentication and authorization, such as the user, client, issuer, permissions, and more.

リソースでアクセス トークン内のクレームを検証して使用する方法については、以下のセクションをご覧ください。See the following sections to learn how a resource can validate and use the claims inside an access token.

サンプル トークンSample tokens

v1.0 トークンと v2.0 トークンは似ており、同じクレームが多く含まれています。v1.0 and v2.0 tokens look similar and contain many of the same claims. 各トークンの例を次に示します。An example of each is provided here.

v1.0v1.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

この v1.0 トークンは JWT.ms で表示できます。View this v1.0 token in .

v2.0v2.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

この v2.0 トークンは JWT.ms で表示できます。View this v2.0 token in .

アクセス トークン内のクレームClaims in access tokens

JWT (JSON Web トークン) は 3 つの部分に分かれています。JWTs (JSON Web Tokens) are split into three pieces:

• ヘッダー - トークンの種類や署名方法に関する情報など、トークンの検証方法に関する情報が提供されます。 - Provides information about how to including information about the type of token and how it was signed.
• ペイロード - サービスを呼び出そうとしているユーザーまたはアプリに関する重要なデータがすべて含まれています。 - Contains all of the important data about the user or app that is attempting to call your service.
• 署名 - トークンの検証に使用される原材料です。 - Is the raw material used to validate the token.

各部分はピリオド (.) で区切られ、Base64 で個別にエンコードされます。Each piece is separated by a period () and separately Base64 encoded.

クレームは、そこに入力される値が存在する場合にのみ存在します。Claims are present only if a value exists to fill it. そのため、アプリはクレームの存在に依存することはできません。So, your app shouldn't take a dependency on a claim being present. 例として、pwd_exp (すべてのテナントでパスワードを期限切れにする必要があるわけではありません) や、family_name (名前のないアプリケーションに代わって、クライアント資格情報 (v1.0、v2.0) フローが使用されます) などがあります。Examples include (not every tenant requires passwords to expire) or (client credential (, ) flows are on behalf of applications, which don't have names). アクセス トークンの検証に使用されるクレームは常に存在します。Claims used for access token validation will always be present.

ヘッダーのクレームHeader claims

ペイロードのクレームPayload claims

グループ超過要求

トークンのサイズが HTTP ヘッダー サイズの上限を超えないよう、Azure AD では、グループ要求に含まれるオブジェクト ID の数が制限されます。To ensure that the token size doesn't exceed HTTP header size limits, Azure AD limits the number of object IDs that it includes in the groups claim. 超過制限 (SAML トークンの場合は 150、JWT トークンの場合は 200) を超えるグループのメンバーにユーザーがなっている場合、Azure AD は、グループ要求をトークンに出力しません。If a user is member of more groups than the overage limit (150 for SAML tokens, 200 for JWT tokens), then Azure AD does not emit the groups claim in the token. 代わりに、Microsoft Graph API に照会してユーザーのグループ メンバーシップを取得するようアプリケーションに指示する超過要求がトークンに追加されます。Instead, it includes an overage claim in the token that indicates to the application to query the Microsoft Graph API to retrieve the user's group membership.

{
  ...
  "_claim_names": {
   "groups": "src1"
    },
    {
  "_claim_sources": {
    "src1": {
        "endpoint":"[Url to get this user's group membership from]"
        }
       }
     }
  ...
 }

超過のシナリオは、App Creation Scripts フォルダーにある BulkCreateGroups.ps1 を使用してテストできます。You can use the provided in the folder to help test overage scenarios.

v1.0 の基本要求v1.0 basic claims

次の要求は、該当する場合は v1.0 トークンに含まれますが、既定では v2.0 トークンには含まれません。The following claims will be included in v1.0 tokens if applicable, but aren't included in v2.0 tokens by default. v2.0 を使用しており、これらの要求のいずれかが必要な場合は、省略可能な要求を使用してそれらを要求してください。If you're using v2.0 and need one of these claims, request them using .

amr 要求The claim

Microsoft ID は、アプリケーションに関連している可能性のあるさまざまな方法で認証できます。Microsoft identities can authenticate in different ways, which may be relevant to your application. amr 要求は、パスワードと Authenticator アプリの両方を使用した認証用に、複数の項目を格納できる配列 (["mfa", "rsa", "pwd"] など) です。The claim is an array that can contain multiple items, such as , for an authentication that used both a password and the Authenticator app.

トークンの検証Validating tokens

id_token または access_token を検証するには、アプリはトークンの署名と要求の両方を検証する必要があります。To validate an id_token or an access_token, your app should validate both the token's signature and the claims. アクセス トークンを検証するには、アプリは発行者、対象ユーザー、および署名トークンも検証する必要があります。To validate access tokens, your app should also validate the issuer, the audience, and the signing tokens. これらの検証は、OpenID 探索ドキュメント内の値に対して行ってください。These need to be validated against the values in the OpenID discovery document. たとえば、テナントに依存しないバージョンのドキュメントは https://login.microsoftonline.com/common/.well-known/openid-configuration にあります。For example, the tenant-independent version of the document is located at .

Azure AD ミドルウェアにはアクセス トークンを検証するための機能が組み込まれており、選択した言語のサンプルを参照できます。The Azure AD middleware has built-in capabilities for validating access tokens, and you can browse through our to find one in the language of your choice.

トークンの検証を処理する方法を示すライブラリとコード サンプルが用意されています。We provide libraries and code samples that show how to handle token validation. 以下の情報は、基になるプロセスを理解することを望む開発者を対象としています。The below information is provided for those who wish to understand the underlying process. JWT の検証に使用できるサードパーティのオープン ソース ライブラリもいくつか存在し、ほぼすべてのプラットフォームと言語に対して少なくとも 1 つのオプションがあります。There are also several third-party open-source libraries available for JWT validation - there is at least one option for almost every platform and language out there. Azure AD 認証ライブラリとコード サンプルの詳細については、v1.0 認証ライブラリに関する記事および v2.0 認証ライブラリに関する記事をご覧ください。For more information about Azure AD authentication libraries and code samples, see and .

署名の検証Validating the signature

JWT には 3 つのセグメントがあり、 . 文字で区切られています。A JWT contains three segments, which are separated by the character. 1 番目のセグメントはヘッダー、2 番目は本文、3 番目は署名と呼ばれます。The first segment is known as the , the second as the , and the third as the . 署名セグメントを使用してトークンの信頼性を検証し、アプリで信頼できることを確認できます。The signature segment can be used to validate the authenticity of the token so that it can be trusted by your app.

Azure AD によって発行されるトークンは、RS256 などの業界標準の非対称暗号アルゴリズムを使用して署名されます。Tokens issued by Azure AD are signed using industry standard asymmetric encryption algorithms, such as RS256. JWT のヘッダーには、トークンの署名に使用されたキーと暗号方法に関する情報が含まれます。The header of the JWT contains information about the key and encryption method used to sign the token:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

alg 要求はトークンへの署名に使用されたアルゴリズムを示し、kid 要求はトークンへの検証に使用された特定の公開キーを示します。The claim indicates the algorithm that was used to sign the token, while the claim indicates the particular public key that was used to validate the token.

いつでも、Azure AD は公開/秘密キー ペアの特定セットのいずれかを使用して、id_token に署名できます。At any given point in time, Azure AD may sign an id_token using any one of a certain set of public-private key pairs. Azure AD は定期的に使用可能なキー セットをローテーションするので、このキー変更を自動的に処理するようにアプリを作成する必要があります。Azure AD rotates the possible set of keys on a periodic basis, so your app should be written to handle those key changes automatically. Azure AD によって使用される公開キーの更新を確認する適切な頻度は、24 時間間隔です。A reasonable frequency to check for updates to the public keys used by Azure AD is every 24 hours.

署名の検証に必要な署名キー データは、次の場所にある OpenID Connect メタデータのドキュメントを使用して入手できます。You can acquire the signing key data necessary to validate the signature by using the located at:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

このメタデータ ドキュメントの詳細は次のとおりです。This metadata document:

• OpenID Connect 認証を実行するために必要なさまざまなエンドポイントの場所などの、いくつかの有効な情報を含む JSON オブジェクトです。Is a JSON object containing several useful pieces of information, such as the location of the various endpoints required for doing OpenID Connect authentication.
• トークンの署名に使用される公開キーのセットの場所を示す jwks_uri が含まれます。Includes a , which gives the location of the set of public keys used to sign tokens. jwks_uri にある JSON Web キー (JWK) には、特定の時点で使用されているすべての公開キー情報が含まれます。The JSON Web Key (JWK) located at the contains all of the public key information in use at that particular moment in time. JWK 形式については RFC 7517 を参照してください。The JWK format is described in . アプリでは、 kid 要求を JWT ヘッダーで使用して、特定のトークンの署名に使用されたこのドキュメント内の公開キーを選択できます。Your app can use the claim in the JWT header to select which public key in this document has been used to sign a particular token. その後、正しい公開キーと指定されたアルゴリズムを使用して、署名の検証を実行できます。It can then do signature validation using the correct public key and the indicated algorithm.

署名の検証の実行は、このドキュメントの範囲外です。必要に応じて、それを実行するために役立つオープン ソース ライブラリが多数存在します。Doing signature validation is outside the scope of this document - there are many open-source libraries available for helping you do so if necessary. ただし、Microsoft Identity プラットフォームには、標準に対する 1 つのトークン署名拡張であるカスタム署名トークンがあります。However, the Microsoft Identity platform has one token signing extension to the standards - custom signing keys.

claims-mapping 機能を使用した結果としてアプリにカスタム署名キーがある場合は、アプリの署名キー情報 (検証に使用する必要があります) を指す jwks_uri を取得するために、アプリ ID を含む appid クエリ パラメーターを追加する必要があります。If your app has custom signing keys as a result of using the feature, you must append an query parameter containing the app ID to get a pointing to your app's signing key information, which should be used for validation. 例: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e には、https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e の jwks_uri が含まれます。For example: contains a of .

クレーム ベースの承認Claims based authorization

アプリケーションのビジネス ロジックでこの手順を示します。一般的な承認方法を次に示します。Your application's business logic will dictate this step, some common authorization methods are laid out below.

• scp または roles 要求をチェックして、存在するすべてのスコープが API によって公開されているものに一致することを確認し、クライアントが要求されたアクションを実行することを許可します。Check the or claim to verify that all present scopes match those exposed by your API, and allow the client to do the requested action.
• ご自分の API に対して、呼び出し元のクライアントが appid クレームを使った 呼び出しを許可されていることを確認します。Ensure the calling client is allowed to call your API using the claim.
• appidacr を使用して、呼び出し元のクライアントの認証の状態を検証します。これは、パブリック クライアントが API の呼び出しを許可されていない場合は 0 になります。Validate the authentication status of the calling client using - it shouldn't be 0 if public clients aren't allowed to call your API.
• 過去の nonce 要求のリストと照合して、トークンが再生されていないことを確認します。Check against a list of past claims to verify the token isn't being replayed.
• tid が、API の呼び出しを許可されているテナントと一致することを確認します。Check that the matches a tenant that is allowed to call your API.
• acr 要求を使用して、ユーザーが MFA を実行したことを確認します。Use the claim to verify the user has performed MFA. これは、条件付きアクセスを使用して適用する必要があります。This should be enforced using .
• アクセス トークンで roles または groups 要求を要求した場合は、ユーザーが、このアクションの実行を許可されているグループに属していることを確認します。If you've requested the or claims in the access token, verify that the user is in the group allowed to do this action.
  • 暗黙的フローを使用してトークンを取得した場合、このデータは大きすぎてトークンに収まらないことが多いため、データを Microsoft Graph に照会することが必要になる可能性があります。For tokens retrieved using the implicit flow, you'll likely need to query the for this data, as it's often too large to fit in the token.

ユーザー トークンとアプリケーション トークンUser and application tokens

アプリケーションでは、ユーザーに代わってトークンを受け取る (通常のフロー) か、(クライアント資格情報フロー (v1.0、v2.0) を通じて) アプリケーションから直接受け取る場合があります。Your application may receive tokens on behalf of a user (the usual flow) or directly from an application (through the client credential flow (, ). これらのアプリ専用トークンは、この呼び出しがアプリケーションからのものであり、その背後にユーザーがいないことを示します。These app-only tokens indicate that this call is coming from an application and does not have a user backing it. これらのトークンはほぼ同様に処理されますが、違いがいくつかあります。These tokens are handled largely the same, with some differences:

• アプリ専用トークンには scp 要求は含まれず、代わりに roles 要求が含まれることがあります。App-only tokens will not have a claim, and may instead have a claim. これに、(委任されたアクセス許可ではなく) アプリケーションのアクセス許可が記録されます。This is where application permission (as opposed to delegated permissions) will be recorded. 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、アクセス許可と同意 (v1.0、v2.0) に関するページを参照してください。For more information about delegated and application permissions, see permission and consent (, ).
• 多くの人間固有の要求 (name や upn など) はありません。Many human-specific claims will be missing, such as or .
• sub および oid 要求は同じになります。The and claims will be the same.

トークンの失効Token revocation

更新トークンは、さまざまな理由でいつでも無効にしたり、取り消したりできます。Refresh tokens can be invalidated or revoked at any time, for different reasons. これらはタイムアウトと失効の 2 つに大きく分けることができます。These fall into two main categories: timeouts and revocations.

トークンのタイムアウトToken timeouts

トークンの有効期間の構成を使用すると、更新トークンの有効期間を変更できます。Using , the lifetime of refresh tokens can be altered. 一部のトークンが使用されない場合 (たとえば、ユーザーがアプリを 3 か月間開いていない場合)、有効期限が切れますが、これは正常です。It is normal and expected for some tokens to go without use (e.g. the user does not open the app for 3 months) and therefore expire. アプリでは、ログイン サーバーが期限切れのために更新トークンを拒否するシナリオが発生します。Apps will encounter scenarios where the login server rejects a refresh token due to its age.

• MaxInactiveTime:更新トークンが MaxInactiveTime で指示された時間内に使用されなかった場合、更新トークンは無効になります。MaxInactiveTime: If the refresh token hasn't been used within the time dictated by the MaxInactiveTime, the Refresh Token will no longer be valid.
• MaxSessionAge:MaxAgeSessionMultiFactor または MaxAgeSessionSingleFactor が既定値 (Until-revoked) 以外に設定されている場合、MaxAgeSession* に設定された時間が経過すると、再認証が必要になります。MaxSessionAge: If MaxAgeSessionMultiFactor or MaxAgeSessionSingleFactor have been set to something other than their default (Until-revoked), then reauthentication will be required after the time set in the MaxAgeSession* elapses.
• 例 :Examples:
  • テナントの MaxInactiveTime が 5 日で、ユーザーが 1 週間の休暇を取った場合、7 日間にわたり Azure AD はユーザーからの新しいトークン要求を認識しません。The tenant has a MaxInactiveTime of five days, and the user went on vacation for a week, and so Azure AD hasn't seen a new token request from the user in 7 days. ユーザーが次に新しいトークンを要求するとき、更新トークンが失効していることがわかります。資格情報を再び入力する必要があります。The next time the user requests a new token, they'll find their Refresh Token has been revoked, and they must enter their credentials again.
  • 機密性の高いアプリケーションの MaxAgeSessionSingleFactor は 1 日に設定されています。A sensitive application has a MaxAgeSessionSingleFactor of one day. ユーザーが月曜日にログインし、次に火曜日 (25 時間が経過した後) にログインした場合は、再認証が必要になります。If a user logs in on Monday, and on Tuesday (after 25 hours have elapsed), they'll be required to reauthenticate.

無効化Revocation

更新トークンは、資格情報の変更、または管理者の操作により、サーバーによって取り消される場合があります。Refresh tokens can be revoked by the server due to a change in credentials, or due to use or admin action. 更新トークンは、機密クライアント (右端の列) に対して発行されたクラスと、パブリック クライアント (その他すべての列) に対して発行されたクラスの 2 つのクラスに分類されます。Refresh tokens fall into two classes - those issued to confidential clients (the rightmost column) and those issued to public clients (all other columns).

次のステップNext steps

• Azure AD の id_tokens の詳細を確認します。Learn about .
• アクセス許可と同意 (v1.0、v2.0) の詳細を確認します。Learn about permission and consent ( , ).