- Article
- 25 minutes to read
Access tokens allow clients to call securely protected web APIs. Access tokens are used by web APIs to perform authentication and authorization.
According to the OAuth specification, access tokens are opaque strings with no defined format. Some identity providers (IDPs) use GUIDs and others use encrypted blobs. The format of the access token can depend on how the API that accepts the token is configured.
Custom APIs that developers register on the Microsoft identity platform can choose between two different formats of JSON called Web Tokens (JWTs).v1.0ev2.0. APIs developed by Microsoft such as Microsoft Graph or APIs in Azure have other proprietary token formats. These proprietary formats can be encrypted tokens, JWTs, or special JWT-like tokens that are not validated.
Clients must treat access tokens as opaque strings because the content of the token is intended only for the API. For validation and debugging purposesjust, developers can decode JWTs using a website likejwt.ms. Tokens received for a Microsoft API may not always be a JWT and may not always be decoded.
To get details about the content of the access token, clients should use the token response data returned with the client access token. When the client requests an access token, the Microsoft identity platform also returns some metadata about the access token for the app to consume. This information includes the access token's expiration time and the scopes for which it is valid. This data allows the application to intelligently cache access tokens without having to parse the access token itself.
The following sections show how an API can validate and use the claims in an access token.
monitoring
All documentation on this page applies only to tokens issued to registered APIs unless otherwise noted. It does not apply to tokens issued to Microsoft-owned APIs, nor can those tokens be used to validate how Microsoft's identity platform issues tokens to a registered API.
Token-Formate
There are two versions of access tokens available in the Microsoft identity platform: v1.0 and v2.0. These versions determine the claims that are in the token and ensure that a web API can process the contents of the token.
For web APIs, one of the following versions is selected by default during registration:
v1.0 for Azure AD only applications. The following example shows a v1.0 token (this token example is not validated as the keys were rotated and personal information was removed before release):
(Video) The basics of modern authentication - Microsoft identity platformeyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJ iYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHdv2.0 for applications supporting consumer accounts. The following example shows a v1.0 token (this token example is not validated as the keys were rotated and personal information was removed before release):
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI 6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt
The version can be set for applications by providing the appropriate value foraccessTokenAcceptedVersionconfiguration onapplication manifest. the values ofNulle1Result in v1.0 token and the value of2yields tokens v2.0.
token property
There are two parties involved in an access token request: the client requesting the token and the resource (Web API) accepting the token. theheardEntitlement to a token indicates the resource for which the token is intended (itspublicly). Clients use the token, but should not understand it or try to parse it. Resources accept the token.
Microsoft identity platform supports issuing any token version from any version endpoint - they are not related. WhenaccessTokenAcceptedVersionis set to2, a client calling the v1.0 endpoint to get a token for that resource will get a v2.0 access token.
Resources always own their tokens with theheardclaim and are the only apps that can change your token details.
Claims in access tokens
JWTs are divided into three parts:
- Header- Provides information about the validation of the token, including information about the type of token and how it was signed.
- Useful charge- Contains all important data about the user or application trying to invoke the service.
- signature- It is the raw material used to validate the token.
Each piece is separated by a period (.) and separately encoded in Base64.
Claims only exist when there is value to fill them. An application must not be made dependent on the existence of a claim. include examplespwd_exp(not every tenant requires passwords to expire) andsurname, surname(customer IDStreams are in the names of apps that don't have names). Claims used for access token validation are always present.
Some claims are used to help the Microsoft identity platform secure tokens for reuse. These claims are marked in the description as not for public useOpaque. These claims may or may not appear on a token, and new ones may be added without notice.
Header Claims
| affirmation | Format | description |
|---|---|---|
Art | rope - alwaysJWT | Indicates that the token is a JWT. |
alg | Corda | Specifies the algorithm used to sign the token, e.g. B.RS256. |
frequently | Corda | Specifies the public key fingerprint that can be used to validate this token signature. Issued in v1.0 and v2.0 access tokens. |
x5t | Corda | It works the same (in use and value) asfrequently.x5tand is a legacy claim issued only to v1.0 access tokens for compatibility reasons. |
claim for payload
| affirmation | Format | description |
|---|---|---|
heard | String, a URI or GUID of an application ID | Identifies the audience for the token. The API must validate this value and reject the token if the value doesn't match. In v2.0 tokens, this value is always the API client ID. In v1.0 tokens, this can be either the client ID or the resource URI used in the request. The value may depend on how the client requested the token. |
iss | String, ein Security Token Service (STS)-URI | Identifies the STS that creates and returns the token and the Azure AD tenant in which the user was authenticated. If the issued token is a v2.0 token (see theverclaim), the URI ends in/v2.0. The GUID indicating that the user is a home user of a Microsoft account9188040d-6c67-4c5b-b112-36a304b66pai. The application can use the GUID part of the claim to limit the set of tenants that can log in to the application, if necessary. |
IDP | String, typically an STS URI | Registers the identity provider that authenticated the token's subject. This value is the same as the issuer's claim value, unless the user's account is not in the same tenant as the issuer, e.g. B. Guests. If the claim does not exist, the value ofisscan be used instead. For person accounts used in an organizational context (e.g. a person account invited to an Azure AD tenant), theIDPthe claim can be "live.com" or an STS URI containing the tenant of the Microsoft account9188040d-6c67-4c5b-b112-36a304b66pai. |
and | int, a Unix timestamp | Indicates when authentication for this token took place. |
nbf | int, a Unix timestamp | Specifies the time before which the JWT should not be accepted for processing. |
exp | int, a Unix timestamp | Specifies the expiration time after which the JWT should not be accepted for processing. A resource can also reject the token before this time. A rejection can occur when an authentication change is required or a token revocation was detected. |
aio | opaque rope | An internal claim used by Azure AD to register data for token reuse. Resources must not use this declaration. |
Acre | Sail, same0or1, only present in Token v1.0 | A value of0for the "Authentication context class" claim indicates that the end-user authentication did not meet the requirements of ISO/IEC 29115. |
amr | JSON array of strings only present in v1.0 tokens | Indicates how the subject of the token was authenticated. |
appid | String, a GUID present only in v1.0 tokens | The application ID of the client using the token. The application can act as itself or on behalf of a user. The application ID typically represents an application object, but can also represent a service principal object in Azure AD. |
Asp | String, a GUID present only in v2.0 tokens | a replacement forappid. The application ID of the client using the token. The application can act as itself or on behalf of a user. The application ID typically represents an application object, but can also represent a service principal object in Azure AD. |
Appidakr | Sail, same0,1, or2, only present in Token v1.0 | Indicates how the client was authenticated. For a contracting authority, the value0. If client id and client secret are used, the value is1. If a client certificate was used for authentication, the value is2. |
Azpacr | Sail, same0,1, or2, only present in Token v2.0 | a replacement forAppidakr. Indicates how the client was authenticated. For a contracting authority, the value0. If client id and client secret are used, the value is1. If a client certificate was used for authentication, the value is2. |
preferred username | String present only in v2.0 tokens. | The primary username that represents the user. The value can be an email address, phone number, or a generic username with no specified format. The value is volatile and may change over time. Because the value is changeable, it should not be used to make authorization decisions. However, the value can be used for username hints and in the human-readable UI as a username. theProfileMargin is required to maintain this claim. |
Name | Corda | Provides a human-readable value that identifies the subject of the token. The value is not guaranteed to be unique, it is editable and is used for display purposes only. theProfileMargin is required to maintain this claim. |
scp | String, a space-separated list of ranges | The set of scopes exposed by the application for which the client application has requested (and received) consent. The application must verify that these scopes are valid as provided by the application and make authorization decisions based on the value of these scopes. Included only for user tokens. |
functions | Array of strings, a whitelist | The set of permissions exposed by the application and that the requesting application or user has been granted permission to invoke. App tokens use this set of permissions duringClient credentials flowinstead of user areas. For user tokens, this value set is populated with the roles that the user has been assigned in the target application. |
latitudes | arrangement ofRoleTemplateIDGUIDs | Identifies the tenant-wide roles assigned to this user, present in the roles sectionBuilt-in Azure AD roles. This claim is configured per application viaGroup Membership ClaimsOwnership ofapplication manifest. configure foratordirectory roleit is necessary. May not be present in tokens retrieved through the implicit stream due to token size concerns. |
The group | JSON-Array von GUIDs | Provides object IDs that represent subject group memberships. These values are unique and can safely be used to manage access, e.g. B. to enforce authorization for access to a resource. The groups contained in the group claim are configured application-specifically viaGroup Membership ClaimsOwnership ofapplication manifest. A value ofNullexcludes all groups, a value ofsecurity groupcontains only Active Directory security group members and a value ofatcontains Microsoft 365 security groups and distribution lists.see the |
hate groups | Boleano | If available, alwaysreal, indicates whether the user is in at least one group. Used instead ofThe groupClaim for JWTs in flows with implicit grant if claiming full groups would extend the URI fragment beyond the URL length limit (currently six or more groups). Specifies that the client should use the Microsoft Graph API to determine groups (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects) of the user. |
Group: src1 | JSON-Object | For token requests whose length is not limited (cfhate groups), but still too big for the token, includes a link to the full list of groups for the user. For JWTs as a distributed statement, for SAML as a new statement instead of theThe groupclaim.Example of a JWT value: |
sub | Corda | The principal about which the token asserts information, e.g. B. the user of an application. This value is immutable and cannot be reassigned or reused. It can be used to securely perform authorization checks, e.g. B. when the token is used to access a resource, and it can be used as a key in database tables. Because the subject is always present in tokens issued by Azure AD, use this value in a general authorization system. However, the subject is a paired identifier that is unique to a given application ID. If a single user logs in to two different applications with two different client IDs, those applications will receive two different values for the subject claim. Two different values may or may not be desired depending on the architecture and privacy requirements. See also theoidDeclaration (which remains the same across all applications within a tenant). |
oid | String, uh GUID | The immutable identifier of the requestor, which is the user or service principal whose identity was verified. It can also be used to securely perform authorization checks and as a key for database tables. This ID uniquely identifies the requester in applications. Two different applications connecting to the same user will get the same value inoidclaim. theoidcan be used when querying Microsoft online services such as Microsoft Graph. Microsoft Graph returns this ID asI would goProperty for a specific user account. Because theoidallows multiple applications to correlate principals thatProfileScope is required to get this entitlement for users. If a single user exists in multiple tenants, the user will contain a different object ID in each tenant. The accounts are considered different even if the user logs into each account with the same credentials. |
Tempo | String, uh GUID | Represents the tenant that the user is logging into. For work and school accounts, the GUID is the immutable tenant ID of the organization the user is logging into. For signing in to a Microsoft tenant with a personal account (services like Xbox, Teams for Life, or Outlook), the amount is9188040d-6c67-4c5b-b112-36a304b66pai. To receive this entitlement, the application must apply for theProfileRange. |
unique name | String, present only in v1.0 tokens | Provides a human-readable value that identifies the subject of the token. This value is not guaranteed to be unique within a tenant and should only be used for display purposes. |
UTI | Corda | Token ID claim, equivalent tojtiin the JWT specification. Case-sensitive unique identifier per token. |
to the right | opaque rope | An internal claim used by Azure to re-validate tokens. Resources must not use this declaration. |
ver | rope, or1,0or2.0 | Specifies the version of the access token. |
group profit entitlement
Azure AD limits the number of object IDs it includes in the group claim to stay within the HTTP header size limit. If a user is a member of more groups than the overflow limit (150 for SAML tokens, 200 for JWT tokens, and only 6 when issued with implicit flow), Azure AD doesn't issue the group claim in the token. Instead, it includes an overflow claim in the token that tells the app to query the Microsoft Graph API to get the user's group membership.
{ ... "_claim_names": { "groups": "src1" }, "_claim_sources": { "src1": { "endpoint": "[URL to get this user's group membership]" } } ... }Use oBulkCreateGroups.ps1provided inApplication creation scriptsFolder for testing overflow scenarios.
Basic Claims v1.0
The following claims are included in v1.0 tokens when applicable, but are not included in v2.0 tokens by default. To use these claims for v2.0, the application requests them usingoptional claims.
| affirmation | Format | description |
|---|---|---|
IP Address | Corda | The IP address from which the user authenticated. |
onprem_sid | Saite, emSID-Format | In cases where the user has local authentication, this claim provides their SID. Use this claim for authorization in legacy apps. |
pwd_exp | int, a Unix timestamp | Indicates when the user's password expires. |
pwd_url | Corda | A URL where users can be sent to reset their password. |
in_corp | Boleano | Signals when the client enters the corporate network. If not, the claim is not included. |
Surname | Corda | Another name for the user, separate from first or last name. |
surname, surname | Corda | Provides the user's last name, last name, or last name as defined in the user object. |
First name | Corda | Provides the user's first name as defined in the user object. |
upn | Corda | The username of the user. This can be a phone number, email address, or an unformatted string. It should only be used for display purposes and to provide username hints in reauthentication scenarios. |
amr complaint
Identities can be authenticated in a variety of ways that may be relevant to the application. theamrClaim is an array that can contain multiple elements, e.g["mfa", "rsa", "pwd"], for authentication that uses a password and the authenticator app.
| bravery | description |
|---|---|
pwd | Password authentication, whether it's a Microsoft user's password or an application's client secret. |
rs | The authentication was based on the proof of an RSA key, for example with theApplication Microsoft Authenticator. This value also indicates whether the authentication was performed by a self-signed JWT with an X509 certificate owned by the service. |
otp | One-time password via email or SMS. |
gefüttert | A federated authentication claim (such as JWT or SAML) was used. |
how | Integrated Windows authentication |
mfa | Multifactor authenticationwas used. If this directive is present, the other authentication methods are included. |
ncmfa | Equivalent tomfa, which is used for providing certain types of extended credentials. |
wiaormfa | The user used Windows or MFA credentials to authenticate. |
none | No authentication was performed. |
Access token lifetime
The default lifetime of an access token is variable. When issued, an access token's default lifetime is assigned a random value between 60 and 90 minutes (75 minutes on average). Variance improves service resiliency by spreading access token requirements over time, preventing hourly traffic spikes to Azure AD.
Tenants not using Conditional Access have a default access token lifetime of two hours for clients such as Microsoft Teams and Microsoft 365.
The lifetime of an access token can be set to control how often the client application times out the application session and how often the user must re-authenticate (silently or interactively). To override the default access token lifetime variation, set a static default access token lifetime usingConfigurable token duration (CTL).
Die standardmäßige Variation der Tokenlebensdauer wird auf Organisationen angewendet, die Continuous Access Assessment (CAE) aktiviert haben. Die standardmäßige Variation der Tokenlebensdauer wird auch dann angewendet, wenn Organisationen CTL-Richtlinien verwenden. Die standardmäßige Tokenlebensdauer für die langlebige Tokenlebensdauer reicht von 20 bis 28 Stunden. Wenn das Zugriffstoken abläuft, muss der Client das Aktualisierungstoken verwenden, um unbemerkt ein neues Aktualisierungstoken und ein neues Zugriffstoken anzufordern.
organizations that useConditional Access (SIF) login frequencyto enforce how often logins occur, cannot override the standard deviation of access token lifetime. When organizations use SIF, the time between logon prompts to a client is the token lifetime, which is between 60 and 90 minutes plus the logon frequency interval.
Here's an example of how varying the default token lifetime with login frequency works. Let's say an organization specifies that the frequency of incoming messages is hourly. The actual input range is from 1 hour to 2.5 hours as the token is issued with a lifetime of 60 to 90 minutes (due to different token lifetimes).
If a user with a one-hour token performs an interactive logon within 59 minutes (just before the logon frequency is exceeded), the logon is not prompted because the logon is below the SIF threshold. If a new token with a lifetime of 90 minutes is issued, the user will not see a login prompt for another hour and a half. When an unattended attempt is made to renew the token lifetime of 90 minutes, Azure AD requires a credential prompt because the total session duration has exceeded the 1 hour logon frequency setting. In this example, the time difference between the credential prompts would be 2.5 hours due to the SIF interval and token lifetime variance.
validate tokens
Not all applications need token validation. Apps should only validate a token in certain scenarios:
- Web APIs must validate access tokens sent to them by a client. They should only accept tokens that contain theirs
heardclaim. - Sensitive web apps like ASP.NET Core must validate the ID tokens sent to them using the user's browser in Hybrid Flow before allowing access to a user's data or establishing a session.
If none of the above scenarios apply, the application will not benefit from token validation and could pose a security and reliability risk when making decisions based on token validity. Public clients like native or single page applications do not benefit from token validation as the application communicates directly with the IDP where SSL protection ensures the tokens are valid.
APIs and web apps should only validate tokens that have oneheardClaim that fits the application. Other resources may have custom token validation rules. For example, tokens for Microsoft Graph are not validated against these rules due to their proprietary format. Validating and accepting tokens destined for another resource is an example of thisconfused deputyProblem.
When the application needs to validate an ID token or an access token, it must first validate the token's signature and issuer against the values in the OpenID discovery document. For example, the cross-client version of the document is located athttps://login.microsoftonline.com/common/.well-known/openid-configuration.
Azure AD middleware has built-in access token validation capabilities, seerehearseto find one in the appropriate language. There are also several third party open source libraries available for JWT validation. For more information about Azure AD authentication libraries and code examples, see theauthentication libraries.
Signature validation
A JWT contains three segments separated by.Character. The first segment is known asHeader, the second as thebody, and the third as thesignature. The signing thread can be used to validate the token's authenticity so that it can be trusted by the application.
Tokens issued by Azure AD are signed using industry-standard asymmetric encryption algorithms such as RS256. The JWT header contains information about the key and encryption method used to sign the token:
{ "typ": "JWT", "alg": "RS256", "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk", "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"}Öalgdeclaration specifies the algorithm used to sign the token, while thefrequentlyClaim indicates the specific public key used to validate the token.
At any time, Azure AD can sign an ID token using any of a specific set of public-private key pairs. Azure AD rotates the possible set of keys on a regular basis, so the application must be written to handle these key changes automatically. A reasonable frequency to check for updates to the public keys used by Azure AD is every 24 hours.
Capture the signing key data required to validate the signature by using theOpenID Connect-Metadatendokumentlocated in:
https://login.microsoftonline.com/common/v2.0/.well-known/openid-configurationTop
Try this in a browser:URL
The following information describes the metadata document:
- It's a JSON object that contains a lot of useful information, e.g. B. The location of the various endpoints required for OpenID Connect authentication.
- contains a
jwks, which provides the location of the set of public keys that correspond to the private keys used to sign tokens. The JSON Web Key (JWK) is located on thejwkscontains all the public key information used at that particular point in time. The JWK format is described inRFC-7517. The application can use thefrequently- Claim in the JWT header to select the public key from this document that corresponds to the private key used to sign a specific token. It can then perform signature validation using the correct public key and the specified algorithm.
monitoring
Use ofrequentlyClaim for validation of the token. Although v1.0 token both thex5tefrequentlyclaims v2.0 tokens contain only thefrequentlyclaim.
Signature validation is outside the scope of this document. There are many open source libraries available to help validate signatures if needed. However, Microsoft's identity platform has a token signing extension for patterns, which are custom signing keys.
If the app has custom signing keys due to the use of itclaim mappingfunction, add oneappidQuery parameter containing the application ID to get onejwkswhich points to the application's signing key information that should be used for validation. For example:https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391econtains ajwksvonhttps://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.
Claims-Based Authorization
The business logic of the application dictates claims-based authorization. Some common authorization methods are listed below.
validate tokens
Use oheardClaim to ensure that the user intended to invoke the application. If the resource identifier is not in theheardassert, deny.
Check user permission
Use ofunctionselatitudes-Instructions to confirm that the user has permission to call the API. For example, an administrator can have permission to write to the API, but not a normal user. check theTempowithin the token corresponds to the tenant ID used to store the data in the API.
If a user saves data in a tenant's API, they must log in to that tenant again to access that data. Never allow data in one tenant to be accessed by another tenant.
Use oamr-Instruction to check if the user has performed MFA. MFA enforcement is done usingConditional Access. SefunctionsorThe groupAccess token requests are requested, ensure the user is in the group with permission for this action.
For tokens obtained using the implicit stream, see theMicrosoft Graphfor this data as it is usually too large to fit in the token.
don't usedie EmailorupnClaim values to determine whether the user should have access to the data in an access token. Fluctuating claim values like these can change over time, making them insecure and unreliable for authorization.
Use immutable claim valuesTempoesuboroidas a mixed key to uniquely identify the API data and determine whether a user should have access to that data.
- Birth:
Tempo+sub - To enhance:
Tempo+oid- aoidis consistent across applications, allowing an ecosystem of applications to audit user access to data.
Do not use mutable human-readable identifiers such asdie Emailorupnto uniquely identify data.
Validate the app login
- Use o
scpAssertion to confirm that the user has granted the calling app permission to call your API. - Make sure the calling client has permission to call your API using
appidclaim (for v1.0 tokens) or theAspClaim (for v2.0 tokens).- You just need to validate these statements (
appid,Asp) if you want to restrict your web API to only be called by predefined apps (e.g. line of business apps or web APIs called by popular front ends). APIs intended to allow access from any calling application do not need to validate these claims.
- You just need to validate these statements (
User and Application Tokens
An app can get tokens for a user or directly from an app through the flow of client credentials. These app-only tokens indicate that this call comes from an app and no user is behind it. These tokens are treated pretty much the same:
- Use
functionsto view the permissions granted to the token's subject. - Use
oidorsubto verify that the calling service principal is the expected one.
If the app needs to distinguish between app-only access tokens and user access tokens, use theidtyp optional claim. To recognize access tokens only for applications, add theidtypcomplain to theaccess tokenfield and check the valueApp. ID tokens and access tokens for users do not have themidtypclaim included.
Token Revocation
Refresh tokens may be invalidated or revoked at any time for a variety of reasons. The reasons fall into the categories of timeouts and revocations.
Token timeout
If an organization usesToken Lifetime Setting, the lifetime of refresh tokens can be changed. It is expected that some tokens may remain unused. For example, the user doesn't open the app for three months and then the token expires. Applications may encounter scenarios where the login server rejects a refresh token based on its age.
- MaxInactiveTime: If the refresh token has not been used within the time specified by MaxInactiveTime, the refresh token is no longer valid.
- MaxSessionAge: If MaxAgeSessionMultiFactor or MaxAgeSessionSingleFactor has been set to a value other than the default value (Until revoked), re-authentication is required after the time set in MaxAgeSession* has elapsed. Examples:
- The tenant has a MaxInactiveTime of five days and the user has been on vacation for a week, so Azure AD hasn't seen a new token request from the user for seven days. The next time the user requests a new token, they will find that their refresh token has been revoked and will have to re-enter their credentials.
- A sensitive application has a MaxAgeSessionSingleFactor of one day. If a user logs in on Monday and Tuesday (after 25 hours), the user must re-authenticate.
Token Revocations
Refresh tokens may be revoked by the server due to a change in credentials, or due to usage or administrative actions. Refresh tokens reside in the confidential client and public client classes.
| To change | password-based cookie | password-based token | Non-password based cookie | Non-password based token | confidential client token |
|---|---|---|---|---|---|
| Password expires | stay alive | stay alive | stay alive | stay alive | stay alive |
| Password changed by user | withdraw | withdraw | stay alive | stay alive | stay alive |
| The user does SSPR | withdraw | withdraw | stay alive | stay alive | stay alive |
| Reset admin password | withdraw | withdraw | stay alive | stay alive | stay alive |
| The user revokes their refresh tokens withPower Shell | withdraw | withdraw | withdraw | withdraw | withdraw |
| The administrator revokes all refresh tokens for a user who is usingPower Shell | withdraw | withdraw | withdraw | withdraw | withdraw |
| only exitthis net | withdraw | stay alive | withdraw | stay alive | stay alive |
not password based
Anot password basedWhen logging in, the user did not enter a password to receive it. Examples of a non-password-based login are:
- Use your face with Windows Hello
- FIDO2 key
- SMS
- Voice
- RIGID
For more information, seePrimary refresh tokens.
Next Steps
- To learnid_tokens no Azure AD.
- To learnpermission and consent.
FAQs
How do I get Microsoft identity platform access token? ›
- Register your app with Azure AD.
- Get authorization.
- Get an access token.
- Call Microsoft Graph with the access token.
- Use a refresh token to get a new access token.
- On this page.
- Get an ID token from the credentials object.
- Verify the integrity of the ID token. Using a Google API Client Library. Calling the tokeninfo endpoint.
- Create an account or session.
- Securing your users' accounts with Cross Account Protection.
Access tokens are what the OAuth client uses to make requests to an API. The access token is meant to be read and validated by the API. An ID token contains information about what happened when a user authenticated, and is intended to be read by the OAuth client.
What should I validate in access token? ›- Retrieve and parse your Okta JSON Web Keys (JWK), which should be checked periodically and cached by your application.
- Decode the access token, which is in JSON Web Token format.
- Verify the signature used to sign the access token.
- Have a user use their browser to request an authorization token (they would be asked to enter their username/password).
- Copy the authorization token from the browser and use it in the request header in a client (e.g. postman) to access my api.
Using a Personal Access Token
Once you've created a token, you can enter it in the password field when prompted for a password within either the GitHub web interface or on the CLI. Note that GitHub may explicitly ask for a "password," but you can still enter a token in most cases.
Under your GitHub user profile (not the repository profile), click the “Settings” link. Scroll down and click the “Developer Settings” link. Click the GitHub “Personal access tokens” link. Click the “Generate new token” link and provide your password again if required.
Is a token the same as a password? ›Token-based authentication is different from traditional password-based or server-based authentication techniques. Tokens offer a second layer of security, and administrators have detailed control over each action and transaction. But using tokens requires a bit of coding know-how.
What is access token example? ›Access tokens are used in token-based authentication to allow an application to access an API. For example, a Calendar application needs access to a Calendar API in the cloud so that it can read the user's scheduled events and create new events.
What is the purpose of ID token? ›What Is an ID Token? An ID token is an artifact that proves that the user has been authenticated. It was introduced by OpenID Connect (OIDC), an open standard for authentication used by many identity providers such as Google, Facebook, and, of course, Auth0.
What three types of information make up an access token? ›
Access tokens contain the following information: The security identifier (SID) for the user's account. SIDs for the groups of which the user is a member. A logon SID that identifies the current logon session.
What is the 6 digit token code? ›The token code is a pseudo-random 6- or 8-digit number (PRN), based on the current time, that is displayed on the RSA SecurID token device. It is presumed that only an authorized user possesses the token device. The token code is a one-time password (OTP).
How do I get an access token without logging in? ›Sometimes you want to authorize servers to access data without interactively logging in each time the servers exchange information. For these cases, you can use the OAuth 2.0 JSON Web Token (JWT) bearer flow. This flow uses a certificate to sign the JWT request and doesn't require explicit user interaction.
How do I get a personal access token ado? ›- From your home page, open user settings and select Personal access tokens.
- Select + New Token.
- Name your token, select the organization where you want to use the token, and then set your token to automatically expire after a set number of days.
- Sign up for a free trial (Enterprise Mobility + Security E5)
- Download the client.
- Quickstart: Deploy the unified labeling client.