{
	"id": "68036f05-6dcf-4fb4-9d4d-74a79cc8d0a2",
	"created_at": "2026-04-06T00:21:22.222479Z",
	"updated_at": "2026-04-10T03:21:04.254837Z",
	"deleted_at": null,
	"sha1_hash": "2bd5450fb9fc9e5ad531a2fe8c28a5cff4e67f6a",
	"title": "Microsoft identity platform and OAuth 2.0 authorization code flow - Microsoft identity platform",
	"llm_title": "",
	"authors": "",
	"file_creation_date": "0001-01-01T00:00:00Z",
	"file_modification_date": "0001-01-01T00:00:00Z",
	"file_size": 369008,
	"plain_text": "Microsoft identity platform and OAuth 2.0 authorization code flow -\r\nMicrosoft identity platform\r\nBy Dickson-Mwendia\r\nArchived: 2026-04-05 20:30:17 UTC\r\nThe OAuth 2.0 authorization code grant type, or auth code flow, enables a client application to obtain authorized access to\r\nprotected resources like web APIs. The auth code flow requires a user-agent that supports redirection from the\r\nauthorization server (the Microsoft identity platform) back to your application. For example, a web browser, desktop, or\r\nmobile application operated by a user to sign in to your app and access their data.\r\nThis article describes low-level protocol details required only when manually crafting and issuing raw HTTP requests to\r\nexecute the flow, which we do not recommend. Instead, use a Microsoft-built and supported authentication library to get\r\nsecurity tokens and call protected web APIs in your apps.\r\nUse the auth code flow paired with Proof Key for Code Exchange (PKCE) and OpenID Connect (OIDC) to get access\r\ntokens and ID tokens in these types of apps:\r\nSingle-page web application (SPA)\r\nStandard (server-based) web application\r\nDesktop and mobile apps\r\nThe OAuth 2.0 authorization code flow is described in section 4.1 of the OAuth 2.0 specification. Apps using the OAuth\r\n2.0 authorization code flow acquire an access_token to include in requests to resources protected by the Microsoft\r\nidentity platform (typically APIs). Apps can also request new ID and access tokens for previously authenticated entities by\r\nusing a refresh mechanism.\r\nThis diagram shows a high-level view of the authentication flow:\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 1 of 17\n\nRedirect URIs for SPAs that use the auth code flow require special configuration.\r\nAdd a redirect URI that supports auth code flow with PKCE and cross-origin resource sharing (CORS): Follow\r\nthe steps in How to add a redirect URI to your application.\r\nUpdate a redirect URI: Set the redirect URI's type to spa by using the application manifest editor in the\r\nMicrosoft Entra admin center.\r\nThe spa redirect type is backward-compatible with the implicit flow. Apps currently using the implicit flow to get\r\ntokens can move to the spa redirect URI type without issues and continue using the implicit flow. Despite this backward\r\ncompatibility, we recommend that you use the auth code flow with PKCE for SPAs.\r\nIf you attempt to use the authorization code flow without setting up CORS for your redirect URI, you'll see this error in\r\nthe console:\r\naccess to XMLHttpRequest at 'https://login.microsoftonline.com/common/oauth2/v2.0/token' from origin 'yourApp.com' has\r\nIf so, visit your app registration and update the redirect URI for your app to use the spa type.\r\nApplications can't use a spa redirect URI with non-SPA flows, for example, native applications or client credential\r\nflows. To ensure security and best practices, the Microsoft identity platform returns an error if you attempt to use a spa\r\nredirect URI without an Origin header. Similarly, the Microsoft identity platform also prevents the use of client\r\ncredentials in all flows in the presence of an Origin header, to ensure that secrets aren't used from within the browser.\r\nThe authorization code flow begins with the client directing the user to the /authorize endpoint. In this example\r\nrequest, the client requests the openid , offline_access , and https://graph.microsoft.com/mail.read permissions\r\nfrom the user.\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 2 of 17\n\nSome permissions are admin-restricted, for example, writing data to an organization's directory by using\r\nDirectory.ReadWrite.All . If your application requests access to one of these permissions from an organizational user,\r\nthe user receives an error message that says they're not authorized to consent to your app's permissions. To request access\r\nto admin-restricted scopes, you should request them directly from a Global Administrator. For more information, see\r\nAdmin-restricted permissions.\r\nUnless specified otherwise, there are no default values for optional parameters. There is, however, default behavior for a\r\nrequest omitting optional parameters. The default behavior is to either sign in the sole current user, show the account\r\npicker if there are multiple users, or show the login page if there are no users signed in.\r\n// Line breaks for legibility only\r\nhttps://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?\r\nclient_id=00001111-aaaa-2222-bbbb-3333cccc4444\r\n\u0026response_type=code\r\n\u0026redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F\r\n\u0026response_mode=query\r\n\u0026scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read\r\n\u0026state=12345\r\n\u0026code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl\r\n\u0026code_challenge_method=S256\r\nParameter Required/optional Description\r\ntenant required\r\nThe {tenant} value in the path of the request can be used to\r\ncontrol who can sign into the application. Valid values are common ,\r\norganizations , consumers , and tenant identifiers. For guest\r\nscenarios where you sign a user from one tenant into another tenant,\r\nyou must provide the tenant identifier to sign them into the resource\r\ntenant. For more information, see Endpoints.\r\nclient_id required\r\nThe Application (client) ID that the Microsoft Entra admin center –\r\nApp registrations experience assigned to your app.\r\nresponse_type required\r\nMust include code for the authorization code flow. Can also\r\ninclude id_token or token if using the hybrid flow.\r\nredirect_uri required\r\nThe redirect_uri of your app, where authentication responses can\r\nbe sent and received by your app. It must exactly match one of the\r\nredirect URIs you registered in the Microsoft Entra admin center,\r\nexcept it must be URL-encoded. For native and mobile apps, use one\r\nof the recommended values:\r\nhttps://login.microsoftonline.com/common/oauth2/nativeclient\r\nfor apps using embedded browsers or http://localhost for apps\r\nthat use system browsers.\r\nscope required A space-separated list of scopes that you want the user to consent to.\r\nFor the /authorize leg of the request, this parameter can cover\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 3 of 17\n\nParameter Required/optional Description\r\nmultiple resources. This value allows your app to get consent for\r\nmultiple web APIs you want to call.\r\nresponse_mode recommended\r\nSpecifies how the identity platform should return the requested token\r\nto your app.\r\nSupported values:\r\n- query : Default when requesting an access token. Provides the\r\ncode as a query string parameter on your redirect URI. The query\r\nparameter isn't supported when requesting an ID token by using the\r\nimplicit flow.\r\n- fragment : Default when requesting an ID token by using the\r\nimplicit flow. Also supported if requesting only a code.\r\n- form_post : Executes a POST containing the code to your redirect\r\nURI. Supported when requesting a code.\r\nprompt optional\r\nIndicates the type of user interaction that is required. Valid values are\r\nlogin , none , consent , and select_account .\r\n- prompt=login forces the user to enter their credentials on that\r\nrequest, negating single-sign on.\r\n- prompt=none is the opposite. It ensures that the user isn't\r\npresented with any interactive prompt. If the request can't be\r\ncompleted silently by using single-sign on, the Microsoft identity\r\nplatform returns an interaction_required error.\r\n- prompt=consent triggers the OAuth consent dialog after the user\r\nsigns in, asking the user to grant permissions to the app.\r\n- prompt=select_account interrupts single sign-on providing\r\naccount selection experience listing all the accounts either in session\r\nor any remembered account or an option to choose to use a different\r\naccount altogether.\r\nlogin_hint optional\r\nYou can use this parameter to pre-fill the username and email address\r\nfield of the sign-in page for the user. Apps can use this parameter\r\nduring reauthentication, after already extracting the login_hint\r\noptional claim from an earlier sign-in.\r\ndomain_hint optional\r\nIf included, the app skips the email-based discovery process that user\r\ngoes through on the sign-in page, leading to a slightly more\r\nstreamlined user experience. For example, sending them to their\r\nfederated identity provider. Apps can use this parameter during\r\nreauthentication, by extracting the tid from a previous sign-in.\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 4 of 17\n\nParameter Required/optional Description\r\ncode_challenge\r\nrecommended /\r\nrequired\r\nUsed to secure authorization code grants by using Proof Key for\r\nCode Exchange (PKCE). Required if code_challenge_method is\r\nincluded. For more information, see the PKCE RFC. This parameter\r\nis now recommended for all application types, both public and\r\nconfidential clients, and required by the Microsoft identity platform\r\nfor single page apps using the authorization code flow.\r\ncode_challenge_method\r\nrecommended /\r\nrequired\r\nThe method used to encode the code_verifier for the\r\ncode_challenge parameter. This SHOULD be S256 , but the spec\r\nallows the use of plain if the client can't support SHA256.\r\nIf excluded, code_challenge is assumed to be plaintext if\r\ncode_challenge is included. The Microsoft identity platform\r\nsupports both plain and S256 . For more information, see the\r\nPKCE RFC. This parameter is required for single page apps using\r\nthe authorization code flow.\r\nstate recommended\r\nA value included in the request that is also returned in the token\r\nresponse. It can be a string of any content that you wish. A randomly\r\ngenerated unique value is typically used for preventing cross-site\r\nrequest forgery attacks. The value can also encode information about\r\nthe user's state in the app before the authentication request occurred.\r\nFor instance, it could encode the page or view they were on.\r\nFor security and privacy, do not put URLs or other sensitive data directly in the state parameter. Instead, use a key or\r\nidentifier that corresponds to data stored in browser storage, such as localStorage or sessionStorage. This approach lets\r\nyour app securely reference the necessary data after authentication.\r\nAt this point, the user is asked to enter their credentials and complete the authentication. The Microsoft identity platform\r\nalso ensures that the user has consented to the permissions indicated in the scope query parameter. If the user hasn't\r\nconsented to any of those permissions, it asks the user to consent to the required permissions. For more information, see\r\nPermissions and consent in the Microsoft identity platform.\r\nOnce the user authenticates and grants consent, the Microsoft identity platform returns a response to your app at the\r\nindicated redirect_uri , using the method specified in the response_mode parameter.\r\nThis example shows a successful response using response_mode=query :\r\nGET http://localhost?\r\ncode=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...\r\n\u0026state=12345\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 5 of 17\n\nParameter Description\r\ncode\r\nThe authorization_code that the app requested. The app can use the authorization code to request an\r\naccess token for the target resource. Authorization codes are short lived. Typically, they expire after\r\nabout 1 minute.\r\nstate\r\nIf a state parameter is included in the request, the same value should appear in the response. The\r\napp should verify that the state values in the request and response are identical.\r\nYou can also receive an ID token if you request one and have the implicit grant enabled in your application registration.\r\nThis behavior is sometimes referred to as the hybrid flow. It's used by frameworks like ASP.NET.\r\nError responses may also be sent to the redirect_uri so the app can handle them appropriately:\r\nGET http://localhost?\r\nerror=access_denied\r\n\u0026error_description=the+user+canceled+the+authentication\r\nParameter Description\r\nerror\r\nAn error code string that can be used to classify types of errors, and to react to errors. This\r\npart of the error is provided so that the app can react appropriately to the error, but doesn't\r\nexplain in depth why an error occurred.\r\nerror_description\r\nA specific error message that can help a developer identify the cause of an authentication\r\nerror. This part of the error contains most of the useful information about why the error\r\noccurred.\r\nThe following table describes the various error codes that can be returned in the error parameter of the error response.\r\nError Code Description Client Action\r\ninvalid_request\r\nProtocol error, such as a\r\nmissing required\r\nparameter.\r\nFix and resubmit the request. This error is a\r\ndevelopment error typically caught during initial\r\ntesting.\r\nunauthorized_client\r\nThe client application\r\nisn't permitted to request\r\nan authorization code.\r\nThis error usually occurs when the client application\r\nisn't registered in Microsoft Entra ID or isn't added to\r\nthe user's Microsoft Entra tenant. The application can\r\nprompt the user with instruction for installing the\r\napplication and adding it to Microsoft Entra ID.\r\naccess_denied\r\nResource owner denied\r\nconsent\r\nThe client application can notify the user that it can't\r\ncontinue unless the user consents.\r\nunsupported_response_type The authorization server\r\ndoesn't support the\r\nFix and resubmit the request. This error is a\r\ndevelopment error typically caught during initial\r\ntesting. In the hybrid flow, this error signals that you\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 6 of 17\n\nError Code Description Client Action\r\nresponse type in the\r\nrequest.\r\nmust enable the ID token implicit grant setting on the\r\nclient app registration.\r\nserver_error\r\nThe server encountered\r\nan unexpected error.\r\nRetry the request. These errors can result from\r\ntemporary conditions. The client application might\r\nexplain to the user that its response is delayed to a\r\ntemporary error.\r\ntemporarily_unavailable\r\nThe server is\r\ntemporarily too busy to\r\nhandle the request.\r\nRetry the request. The client application might explain\r\nto the user that its response is delayed because of a\r\ntemporary condition.\r\ninvalid_resource\r\nThe target resource is\r\ninvalid because it\r\ndoesn't exist, Microsoft\r\nEntra ID can't find it, or\r\nit's not correctly\r\nconfigured.\r\nThis error indicates the resource, if it exists, hasn't been\r\nconfigured in the tenant. The application can prompt\r\nthe user with instruction for installing the application\r\nand adding it to Microsoft Entra ID.\r\nlogin_required\r\nToo many or no users\r\nfound.\r\nThe client requested silent authentication\r\n( prompt=none ), but a single user couldn't be found.\r\nThis error may mean there are multiple users active in\r\nthe session, or no users. This error takes into account\r\nthe tenant chosen. For example, if there are two\r\nMicrosoft Entra accounts active and one Microsoft\r\naccount, and consumers is chosen, silent\r\nauthentication works.\r\ninteraction_required\r\nThe request requires\r\nuser interaction.\r\nAnother authentication step or consent is required.\r\nRetry the request without prompt=none .\r\nTo learn who the user is before redeeming an authorization code, it's common for applications to also request an ID token\r\nwhen they request the authorization code. This approach is called the hybrid flow because it mixes OIDC with the OAuth2\r\nauthorization code flow.\r\nThe hybrid flow is commonly used in web apps to render a page for a user without blocking on code redemption, notably\r\nin ASP.NET. Both single-page apps and traditional web apps benefit from reduced latency in this model.\r\nThe hybrid flow is the same as the authorization code flow described earlier but with three additions. All of these\r\nadditions are required to request an ID token: new scopes, a new response_type, and a new nonce query parameter.\r\n// Line breaks for legibility only\r\nhttps://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?\r\nclient_id=00001111-aaaa-2222-bbbb-3333cccc4444\r\n\u0026response_type=code%20id_token\r\n\u0026redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 7 of 17\n\n\u0026response_mode=fragment\r\n\u0026scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read\r\n\u0026state=12345\r\n\u0026nonce=abcde\r\n\u0026code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl\r\n\u0026code_challenge_method=S256\r\nUpdated\r\nParameter\r\nRequired/optional Description\r\nresponse_type required\r\nThe addition of id_token indicates to the server that the application\r\nwould like an ID token in the response from the /authorize endpoint.\r\nscope required\r\nFor ID tokens, this parameter must be updated to include the ID token\r\nscopes: openid and optionally profile and email .\r\nnonce required\r\nA value included in the request, generated by the app, that is included in\r\nthe resulting id_token as a claim. The app can then verify this value to\r\nmitigate token replay attacks. The value is typically a randomized, unique\r\nstring that can be used to identify the origin of the request.\r\nresponse_mode recommended\r\nSpecifies the method that should be used to send the resulting token back\r\nto your app. Default value is query for just an authorization code, but\r\nfragment if the request includes an id_token response_type as\r\nspecified in the OpenID spec. We recommend apps use form_post ,\r\nespecially when using http://localhost as a redirect URI.\r\nThe use of fragment as a response mode causes issues for web apps that read the code from the redirect. Browsers don't\r\npass the fragment to the web server. In these situations, apps should use the form_post response mode to ensure that all\r\ndata is sent to the server.\r\nThis example shows a successful response using response_mode=fragment :\r\nGET https://login.microsoftonline.com/common/oauth2/nativeclient#\r\ncode=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...\r\n\u0026id_token=eYj...\r\n\u0026state=12345\r\nParameter Description\r\ncode\r\nThe authorization code that the app requested. The app can use the authorization code to request an\r\naccess token for the target resource. Authorization codes are short lived, typically expiring after about 1\r\nminute.\r\nid_token\r\nAn ID token for the user, issued by using the implicit grant. Contains a special c_hash claim that is\r\nthe hash of the code in the same request.\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 8 of 17\n\nParameter Description\r\nstate\r\nIf a state parameter is included in the request, the same value should appear in the response. The\r\napp should verify that the state values in the request and response are identical.\r\nAll confidential clients have a choice of using client secrets or certificate credentials. Symmetric shared secrets are\r\ngenerated by the Microsoft identity platform. Certificate credentials are asymmetric keys uploaded by the developer. For\r\nmore information, see Microsoft identity platform application authentication certificate credentials.\r\nFor best security, we recommend using certificate credentials. Public clients, which include native applications and single\r\npage apps, must not use secrets or certificates when redeeming an authorization code. Always ensure that your redirect\r\nURIs include the type of application and are unique.\r\nNow that you've acquired an authorization_code and have been granted permission by the user, you can redeem the\r\ncode for an access_token to the resource. Redeem the code by sending a POST request to the /token endpoint:\r\n// Line breaks for legibility only\r\nPOST /{tenant}/oauth2/v2.0/token HTTP/1.1\r\nHost: https://login.microsoftonline.com\r\nContent-Type: application/x-www-form-urlencoded\r\nclient_id=11112222-bbbb-3333-cccc-4444dddd5555\r\n\u0026scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read\r\n\u0026code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...\r\n\u0026redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F\r\n\u0026grant_type=authorization_code\r\n\u0026code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong\r\n\u0026client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded.\r\nParameter Required/optional Description\r\ntenant required\r\nThe {tenant} value in the path of the request can be used to control\r\nwho can sign into the application. Valid values are common ,\r\norganizations , consumers , and tenant identifiers. For more\r\ninformation, see Endpoints.\r\nclient_id required\r\nThe Application (client) ID that the Microsoft Entra admin center – App\r\nregistrations page assigned to your app.\r\nscope optional\r\nA space-separated list of scopes. The scopes must all be from a single\r\nresource, along with OIDC scopes ( profile , openid , email ). For\r\nmore information, see Permissions and consent in the Microsoft identity\r\nplatform. This parameter is a Microsoft extension to the authorization\r\ncode flow, intended to allow apps to declare the resource they want the\r\ntoken for during token redemption.\r\ncode required The authorization_code that you acquired in the first leg of the flow.\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 9 of 17\n\nParameter Required/optional Description\r\nredirect_uri required\r\nThe same redirect_uri value that was used to acquire the\r\nauthorization_code .\r\ngrant_type required Must be authorization_code for the authorization code flow.\r\ncode_verifier recommended\r\nThe same code_verifier that was used to obtain the\r\nauthorization_code. Required if PKCE was used in the authorization\r\ncode grant request. For more information, see the PKCE RFC.\r\nclient_secret\r\nrequired for\r\nconfidential web\r\napps\r\nThe application secret that you created in the app registration portal for\r\nyour app. Don't use the application secret in a native app or single page\r\napp because a client_secret can't be reliably stored on devices or web\r\npages. It's required for web apps and web APIs, which can store the\r\nclient_secret securely on the server side. Like all parameters here, the\r\nclient secret must be URL-encoded before being sent. This step is done\r\nby the SDK. For more information on URI encoding, see the URI\r\nGeneric Syntax specification. The Basic auth pattern of instead providing\r\ncredentials in the Authorization header, per RFC 6749 is also supported.\r\n// Line breaks for legibility only\r\nPOST /{tenant}/oauth2/v2.0/token HTTP/1.1\r\nHost: login.microsoftonline.com\r\nContent-Type: application/x-www-form-urlencoded\r\nclient_id=00001111-aaaa-2222-bbbb-3333cccc4444\r\n\u0026scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read\r\n\u0026code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...\r\n\u0026redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F\r\n\u0026grant_type=authorization_code\r\n\u0026code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong\r\n\u0026client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer\r\n\u0026client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U\r\nParameter Required/optional Description\r\ntenant required\r\nThe {tenant} value in the path of the request can be used to\r\ncontrol who can sign into the application. Valid values are\r\ncommon , organizations , consumers , and tenant identifiers.\r\nFor more detail, see Endpoints.\r\nclient_id required\r\nThe Application (client) ID that the Microsoft Entra admin\r\ncenter – App registrations page assigned to your app.\r\nscope optional A space-separated list of scopes. The scopes must all be from a\r\nsingle resource, along with OIDC scopes ( profile , openid ,\r\nemail ). For more information, see permissions, consent, and\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 10 of 17\n\nParameter Required/optional Description\r\nscopes. This parameter is a Microsoft extension to the\r\nauthorization code flow. This extension allows apps to declare\r\nthe resource they want the token for during token redemption.\r\ncode required\r\nThe authorization_code that you acquired in the first leg of\r\nthe flow.\r\nredirect_uri required\r\nThe same redirect_uri value that was used to acquire the\r\nauthorization_code .\r\ngrant_type required Must be authorization_code for the authorization code flow.\r\ncode_verifier recommended\r\nThe same code_verifier that was used to obtain the\r\nauthorization_code . Required if PKCE was used in the\r\nauthorization code grant request. For more information, see the\r\nPKCE RFC.\r\nclient_assertion_type\r\nrequired for\r\nconfidential web\r\napps\r\nThe value must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer to use a certificate credential.\r\nclient_assertion\r\nrequired for\r\nconfidential web\r\napps\r\nAn assertion, which is a JSON web token (JWT), that you need\r\nto create and sign with the certificate you registered as\r\ncredentials for your application. Read about certificate\r\ncredentials to learn how to register your certificate and the\r\nformat of the assertion.\r\nThe parameters are same as the request by shared secret except that the client_secret parameter is replaced by two\r\nparameters: a client_assertion_type and client_assertion .\r\nThis example shows a successful token response:\r\n{\r\n \"access_token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...\",\r\n \"token_type\": \"Bearer\",\r\n \"expires_in\": 3599,\r\n \"scope\": \"https%3A%2F%2Fgraph.microsoft.com%2Fmail.read\",\r\n \"refresh_token\": \"AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...\",\r\n \"id_token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...\"\r\n}\r\nParameter Description\r\naccess_token\r\nThe requested access token. The app can use this token to authenticate to the secured resource,\r\nsuch as a web API.\r\ntoken_type Indicates the token type value. The only type that Microsoft Entra ID supports is Bearer .\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 11 of 17\n\nParameter Description\r\nexpires_in How long the access token is valid, in seconds.\r\nscope\r\nThe scopes that the access_token is valid for. Optional. This parameter is non-standard and, if\r\nomitted, the token is for the scopes requested on the initial leg of the flow.\r\nrefresh_token\r\nAn OAuth 2.0 refresh token. The app can use this token to acquire other access tokens after the\r\ncurrent access token expires. Refresh tokens are long-lived. They can maintain access to\r\nresources for extended periods. For more detail on refreshing an access token, refer to Refresh the\r\naccess token later in this article.\r\nNote: Only provided if offline_access scope was requested.\r\nid_token\r\nA JSON Web Token. The app can decode the segments of this token to request information about\r\nthe user who signed in. The app can cache the values and display them, and confidential clients\r\ncan use this token for authorization. For more information about id_tokens, see the id_token\r\nreference .\r\nNote: Only provided if openid scope was requested.\r\nThis example is an Error response:\r\n{\r\n \"error\": \"invalid_scope\",\r\n \"error_description\": \"AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://\r\n \"error_codes\": [\r\n 70011\r\n ],\r\n \"timestamp\": \"2016-01-09 02:02:12Z\",\r\n \"trace_id\": \"0000aaaa-11bb-cccc-dd22-eeeeee333333\",\r\n \"correlation_id\": \"aaaa0000-bb11-2222-33cc-444444dddddd\"\r\n}\r\nParameter Description\r\nerror An error code string that can be used to classify types of errors, and to react to errors.\r\nerror_description\r\nA specific error message that can help a developer identify the cause of an authentication\r\nerror.\r\nerror_codes A list of STS-specific error codes that can help in diagnostics.\r\ntimestamp The time at which the error occurred.\r\ntrace_id A unique identifier for the request that can help in diagnostics.\r\ncorrelation_id A unique identifier for the request that can help in diagnostics across components.\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 12 of 17\n\nError Code Description Client Action\r\ninvalid_request\r\nProtocol error, such as a missing\r\nrequired parameter.\r\nFix the request or app registration and\r\nresubmit the request.\r\ninvalid_grant\r\nThe authorization code or PKCE code\r\nverifier is invalid or has expired.\r\nTry a new request to the /authorize\r\nendpoint and verify that the\r\ncode_verifier parameter was correct.\r\nunauthorized_client\r\nThe authenticated client isn't authorized\r\nto use this authorization grant type.\r\nThis error usually occurs when the client\r\napplication isn't registered in Microsoft\r\nEntra ID or isn't added to the user's\r\nMicrosoft Entra tenant. The application\r\ncan prompt the user with instruction for\r\ninstalling the application and adding it to\r\nMicrosoft Entra ID.\r\ninvalid_client Client authentication failed.\r\nThe client credentials aren't valid. To fix,\r\nthe Application Administrator updates the\r\ncredentials.\r\nunsupported_grant_type\r\nThe authorization server doesn't support\r\nthe authorization grant type.\r\nChange the grant type in the request. This\r\ntype of error should occur only during\r\ndevelopment and be detected during\r\ninitial testing.\r\ninvalid_resource\r\nThe target resource is invalid because it\r\ndoesn't exist, Microsoft Entra ID can't\r\nfind it, or it's not correctly configured.\r\nThis code indicates the resource, if it\r\nexists, hasn't been configured in the\r\ntenant. The application can prompt the\r\nuser with instruction for installing the\r\napplication and adding it to Microsoft\r\nEntra ID.\r\ninteraction_required\r\nNon-standard, as the OIDC specification\r\ncalls for this code only on the\r\n/authorize endpoint. The request\r\nrequires user interaction. For example,\r\nanother authentication step is required.\r\nRetry the /authorize request with the\r\nsame scopes.\r\ntemporarily_unavailable\r\nThe server is temporarily too busy to\r\nhandle the request.\r\nRetry the request after a small delay. The\r\nclient application might explain to the\r\nuser that its response is delayed because\r\nof a temporary condition.\r\nconsent_required The request requires user consent. This\r\nerror is non-standard. It's usually only\r\nreturned on the /authorize endpoint\r\nper OIDC specifications. Returned when\r\nThe client should send the user back to\r\nthe /authorize endpoint with the\r\ncorrect scope to trigger consent.\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 13 of 17\n\nError Code Description Client Action\r\na scope parameter was used on the\r\ncode redemption flow that the client app\r\ndoesn't have permission to request.\r\ninvalid_scope\r\nThe scope requested by the app is\r\ninvalid.\r\nUpdate the value of the scope\r\nparameter in the authentication request to\r\na valid value.\r\nNote\r\nSingle page apps may receive an invalid_request error indicating that cross-origin token redemption is permitted only\r\nfor the 'Single-Page Application' client-type. This indicates that the redirect URI used to request the token has not been\r\nmarked as a spa redirect URI. Review the application registration steps on how to enable this flow.\r\nNow that you have successfully acquired an access_token , you can use the token in requests to web APIs by including it\r\nin the Authorization header:\r\nGET /v1.0/me/messages\r\nHost: https://graph.microsoft.com\r\nAuthorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...\r\nAccess tokens are short lived. Refresh them after they expire to continue accessing resources. You can do so by submitting\r\nanother POST request to the /token endpoint. Provide the refresh_token instead of the code . Refresh tokens are\r\nvalid for all permissions that your client has already received consent for. For example, a refresh token issued on a request\r\nfor scope=mail.read can be used to request a new access token for scope=api://contoso.com/api/UseResource .\r\nRefresh tokens for web apps and native apps don't have specified lifetimes. Typically, the lifetimes of refresh tokens are\r\nrelatively long. However, in some cases, refresh tokens expire, are revoked, or lack sufficient privileges for the action.\r\nYour application needs to expect and handle errors returned by the token issuance endpoint. Single page apps get a token\r\nwith a 24-hour lifetime, requiring a new authentication every day. This action can be done silently in an iframe when\r\nthird-party cookies are enabled. It must be done in a top-level frame, either full page navigation or a pop-up window, in\r\nbrowsers without third-party cookies, such as Safari.\r\nRefresh tokens aren't revoked when used to acquire new access tokens. You're expected to discard the old refresh token.\r\nThe OAuth 2.0 spec says: \"The authorization server MAY issue a new refresh token, in which case the client MUST\r\ndiscard the old refresh token and replace it with the new refresh token. The authorization server MAY revoke the old\r\nrefresh token after issuing a new refresh token to the client.\"\r\nImportant\r\nFor refresh tokens sent to a redirect URI registered as spa , the refresh token expires after 24 hours. Additional refresh\r\ntokens acquired using the initial refresh token carries over that expiration time, so apps must be prepared to re-run the\r\nauthorization code flow using an interactive authentication to get a new refresh token every 24 hours. Users do not have to\r\nenter their credentials, and usually don't even see any user experience, just a reload of your application. The browser must\r\nvisit the login page in a top level frame in order to see the login session. This is due to privacy features in browsers that\r\nblock third party cookies.\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 14 of 17\n\n// Line breaks for legibility only\r\nPOST /{tenant}/oauth2/v2.0/token HTTP/1.1\r\nHost: https://login.microsoftonline.com\r\nContent-Type: application/x-www-form-urlencoded\r\nclient_id=00001111-aaaa-2222-bbbb-3333cccc4444\r\n\u0026scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read\r\n\u0026refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...\r\n\u0026grant_type=refresh_token\r\n\u0026client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded\r\nParameter Type Description\r\ntenant required\r\nThe {tenant} value in the path of the request can be used to control who can sign\r\ninto the application. Valid values are common , organizations , consumers , and\r\ntenant identifiers. For more information, see Endpoints.\r\nclient_id required\r\nThe Application (client) ID that the Microsoft Entra admin center – App\r\nregistrations experience assigned to your app.\r\ngrant_type required Must be refresh_token for this leg of the authorization code flow.\r\nscope optional\r\nA space-separated list of scopes. The scopes requested in this leg must be\r\nequivalent to or a subset of the scopes requested in the original\r\nauthorization_code request leg. If the scopes specified in this request span\r\nmultiple resource server, then the Microsoft identity platform returns a token for the\r\nresource specified in the first scope. For more information, see Permissions and\r\nconsent in the Microsoft identity platform.\r\nrefresh_token required The refresh_token that you acquired in the second leg of the flow.\r\nclient_secret\r\nrequired\r\nfor web\r\napps\r\nThe application secret that you created in the app registration portal for your app. It\r\nshouldn't be used in a native app, because a client_secret can't be reliably stored\r\non devices. It's required for web apps and web APIs, which can store the\r\nclient_secret securely on the server side. This secret needs to be URL-Encoded.\r\nFor more information, see the URI Generic Syntax specification.\r\nThis example shows a successful token response:\r\n{\r\n \"access_token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...\",\r\n \"token_type\": \"Bearer\",\r\n \"expires_in\": 3599,\r\n \"scope\": \"https%3A%2F%2Fgraph.microsoft.com%2Fmail.read\",\r\n \"refresh_token\": \"AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...\",\r\n \"id_token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...\"\r\n}\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 15 of 17\n\nParameter Description\r\naccess_token\r\nThe requested access token. The app can use this token to authenticate to the secured resource,\r\nsuch as a web API.\r\ntoken_type Indicates the token type value. The only type that Microsoft Entra ID supports is Bearer.\r\nexpires_in How long the access token is valid, in seconds.\r\nscope The scopes that the access_token is valid for.\r\nrefresh_token\r\nA new OAuth 2.0 refresh token. Replace the old refresh token with this newly acquired refresh\r\ntoken to ensure your refresh tokens remain valid for as long as possible.\r\nNote: Only provided if offline_access scope was requested.\r\nid_token\r\nAn unsigned JSON Web Token. The app can decode the segments of this token to request\r\ninformation about the user who signed in. The app can cache the values and display them, but it\r\nshouldn't rely on them for any authorization or security boundaries. For more information about\r\nid_token , see the Microsoft identity platform ID tokens.\r\nNote: Only provided if openid scope was requested.\r\nWarning\r\nDon't attempt to validate or read tokens for any API you don't own, including the tokens in this example, in your code.\r\nTokens for Microsoft services can use a special format that will not validate as a JWT, and may also be encrypted for\r\nconsumer (Microsoft account) users. While reading tokens is a useful debugging and learning tool, do not take\r\ndependencies on this in your code or assume specifics about tokens that aren't for an API you control.\r\n{\r\n \"error\": \"invalid_scope\",\r\n \"error_description\": \"AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://\r\n \"error_codes\": [\r\n 70011\r\n ],\r\n \"timestamp\": \"2016-01-09 02:02:12Z\",\r\n \"trace_id\": \"0000aaaa-11bb-cccc-dd22-eeeeee333333\",\r\n \"correlation_id\": \"aaaa0000-bb11-2222-33cc-444444dddddd\"\r\n}\r\nParameter Description\r\nerror An error code string that can be used to classify types of errors, and to react to errors.\r\nerror_description\r\nA specific error message that can help a developer identify the root cause of an authentication\r\nerror.\r\nerror_codes A list of STS-specific error codes that can help in diagnostics.\r\ntimestamp The time at which the error occurred.\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 16 of 17\n\nParameter Description\r\ntrace_id A unique identifier for the request that can help in diagnostics.\r\ncorrelation_id A unique identifier for the request that can help in diagnostics across components.\r\nFor a description of the error codes and the recommended client action, see Error codes for token endpoint errors.\r\nGo over the MSAL JS samples to get started coding.\r\nLearn about token exchange scenarios.\r\nSource: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nhttps://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow\r\nPage 17 of 17",
	"extraction_quality": 1,
	"language": "EN",
	"sources": [
		"MITRE"
	],
	"references": [
		"https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow"
	],
	"report_names": [
		"v2-oauth2-auth-code-flow"
	],
	"threat_actors": [],
	"ts_created_at": 1775434882,
	"ts_updated_at": 1775791264,
	"ts_creation_date": 0,
	"ts_modification_date": 0,
	"files": {
		"pdf": "https://archive.orkl.eu/2bd5450fb9fc9e5ad531a2fe8c28a5cff4e67f6a.pdf",
		"text": "https://archive.orkl.eu/2bd5450fb9fc9e5ad531a2fe8c28a5cff4e67f6a.txt",
		"img": "https://archive.orkl.eu/2bd5450fb9fc9e5ad531a2fe8c28a5cff4e67f6a.jpg"
	}
}