AD FS OpenID Connect/OAuth flows and application scenarios

Applies to Active Directory Federation Services (AD FS) 2019 and later

Implicit grant flow

For single-page applications (AngularJS, Ember.js, React.js, and so on), AD FS supports the OAuth 2.0 implicit grant flow. The implicit flow is described in the OAuth 2.0 specification. Its primary benefit is that it allows the app to get tokens from AD FS without performing a backend server credential exchange. This flow allows the app to sign in the user, maintain session, and get tokens to other web APIs within the client JavaScript code. There are a few important security considerations to take into account when using the implicit flow, specifically around client.

If you want to use the implicit flow and AD FS to add authentication to your JavaScript app, follow the general steps in the following section.

Protocol diagram

The following diagram shows what the entire implicit sign-in flow looks like. The sections that follow describe each step in more detail.

Request an ID token and access token

To initially sign the user in to your app, you can send an OpenID Connect authentication request and get an id_token and access token from the AD FS endpoint.

// Line breaks for legibility only

https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token+token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345

At this point, the user is asked to enter their credentials and complete the authentication. After the user authenticates, the AD FS authorization endpoint returns a response to your app at the indicated redirect_uri, using the method specified in the response_mode parameter.

Successful response

A successful response, when response_mode=fragment and response_type=id_token+token is used, looks like this:

// Line breaks for legibility only

GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZEstZnl0aEV...
&token_type=Bearer
&expires_in=3599
&scope=openid
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZstZnl0aEV1Q...
&state=12345

Refresh tokens

The implicit grant doesn't provide refresh tokens. Both id_tokens and access_tokens expire after a short period of time, so your app must be prepared to refresh these tokens periodically. To refresh either type of token, you can perform the same hidden iframe request as in the previous section, using the prompt=none parameter to control the identity platform's behavior. If you want to receive a new id_token, be sure to use response_type=id_token.

Authorization code grant flow

You can use the OAuth 2.0 authorization code grant in web apps to gain access to protected resources like web APIs. The OAuth 2.0 authorization code flow is described in section 4.1 of the OAuth 2.0 specification. It's used to perform authentication and authorization in most app types, including web apps and natively installed apps. The flow enables apps to securely acquire access_tokens that can be used to access resources that trust AD FS.

Protocol diagram

At a high level, the authentication flow for a native application looks a bit like this:

Request an authorization code

The authorization code flow begins with the client directing the user to the /authorize endpoint. In this request, the client indicates the permissions it needs to acquire from the user:

// Line breaks for legibility only

https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&resource=https://webapi.com/
&scope=openid
&state=12345

At this point, the user is asked to enter their credentials and complete the authentication. After the user authenticates, AD FS returns a response to your app at the indicated redirect_uri, using the method specified in the response_mode parameter.

Successful response

A successful response, when response_mode=query is used, looks like this:

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

Request an access token

Now that you've acquired an authorization_code and have been granted permission by the user, you can redeem the code for an access_token to the desired resource. Redeem the code by sending a POST request to the /token endpoint:

// Line breaks for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com/
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for confidential clients (web apps)

Successful response

A successful token response looks like this:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "refresh_token_expires_in": 28800,
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}

Use the access token

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

Refresh the token grant flow

Access_tokens are short lived, and you must refresh them after they expire to continue accessing resources. You can do so by submitting another POST request to the /token endpoint, this time providing the refresh_token instead of the code. Refresh tokens are valid for all permissions that your client has already received access tokens for.

Refresh tokens don't have specified lifetimes. Typically, the lifetimes of refresh tokens are relatively long. However, in some cases, refresh tokens expire, are revoked, or lack sufficient privileges for the desired action. Your application needs to expect and handle errors returned by the token issuance endpoint correctly.

Although refresh tokens aren't revoked when used to acquire new access tokens, you're expected to discard the old refresh token. The OAuth 2.0 specification says: "The authorization server MAY issue a new refresh token, in which case the client MUST discard the old refresh token and replace it with the new refresh token. The authorization server MAY revoke the old refresh token after issuing a new refresh token to the client." AD FS issues refresh tokens when the new refresh token lifetime is longer than previous refresh token lifetime. To view additional information on AD FS refresh token lifetimes, see AD FS single sign-on settings.

// Line breaks for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh      // NOTE: Only required for confidential clients (web apps)

Successful response

A successful token response looks like this:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "refresh_token_expires_in": 28800,
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}

Proof Key for Code Exchange (PKCE) support for OAuth

OAuth public clients that use the authorization code grant are vulnerable to authorization code interception attacks, as described in RFC 7636. To mitigate these attacks, as of Windows Server 2019, AD FS supports Proof Key for Code Exchange (PKCE) for the OAuth authorization code grant flow.

The PKCE support specification adds more parameters to the OAuth 2.0 authorization and access token requests. The following diagram shows an outline of the PKCE process when a client contacts AD FS in Windows Server 2019.

In the section labeled A, the client creates and records a secret named code_verifier and derives a transformed version of the secret called t(code_verifier), also known as code_challenge. The client then sends the secret in the OAuth 2.0 authorization request along with the t_m transformation method.

In the section labeled B, the authorization endpoint responds as usual, but records the t(code_verifier) secret and the transformation method.

In the section labeled C, the client sends the authorization code in the access token request as usual, but includes the code_verifier secret generated in section A.

In the section labeled D, AD FS transforms the code_verifiersecret and compares it to the t(code_verifier) secret from section B. If their values aren't equal, AD FS denies access.

How to choose multiple authentication providers for the same rule policy in Windows Server 2019

AD FS already supports triggering extra authentication based on a claim rule policy (RP). You can set these policies for a particular RP or at a global level. You can set an extra authentication policy for a particular RP by opening PowerShell as an administrator and running the Set-AdfsRelyingPartyTrust cmdlet, passing either the AdditionalAuthenticationRules or AdditionalAuthenticationRulesFile parameter. To set it globally, an admin can use the Set-AdfsAdditionalAuthenticationRule cmdlet. Setting extra policies lets you use more than one authentication provider for the same application.

Claim rules provide the option to select the authentication provider for additional authentication, which proves beneficial in situations where customers are switching between providers or require a distinct provider for certain applications. As of Windows Server 2019, you can use claims rules to decide which other authentication provider to invoke for extra authentication. This feature is useful in two scenarios:

• Users are transitioning from one authentication provider to another. As you onboard users to a newer authentication provider, they can use groups to control which extra authentication provider the service uses.

• Users need a specific extra authentication provider for certain applications but also need to use a different method for other applications.

You can configure these settings by running the following command from other authentication policies:

Set-AdfsAdditionalAuthenticationRule -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", value = "http://schemas.microsoft.com/claims/multipleauthn" );' 

To set up this rule, you must issue the claim http://schemas.microsoft.com/claims/authnmethodsproviders from other authentication policies. The value of this claim should be the Name variable of the authentication provider.

You can also modify this rule configuration to help users transition from one authentication provider to another. For example, let's say that you want to modify one group that you manage to use Microsoft Entra multifactor authentication (MFA) and one group to use certificates as an extra authentication provider.

If you want to track how many people register for MFA and certificate authentication, you can run a command like this, with the values replaced with values that are relevant to your organization:

'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" ); 

 c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "S-1-5-21-608905689-872870963-3921916988-12345"] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "AzureMfaAuthentication"); 

not exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value=="S-1-5-21-608905689-872870963-3921916988-12345"]) => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "CertificateAuthentication");’ 

Next, you can set the first application, called AppA, to use MFA as an extra authentication provider by running this command:

Set-AdfsRelyingPartyTrust -TargetName AppA -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" ); 

c:[] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "AzureMfaAuthentication");' 

Finally, you can set the second app, called AppB, to use certificates as an extra authentication provider by running this command:

Set-AdfsRelyingPartyTrust -TargetName AppB -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" ); 

c:[] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "CertificateAuthentication");' 

Admins can also make rules to allow more than one extra authentication provider. In this case, AD FS shows the issued authentication method providers, and a user can choose any of them. To allow multiple extra authentication providers, they should issue multiple claims by using the value http://schemas.microsoft.com/claims/authnmethodsproviders.

If the claim evaluation returns none of the authentication providers, AD FS rolls back and displays a list showing all the extra authentication providers configured by the admin on AD FS. The user must then manually select the appropriate authentication provider.

If your preferred authentication provider isn't on the list, you can run the following cmdlet to view all supported providers:

(Get-AdfsGlobalAuthenticationPolicy).AdditionalAuthenticationProvider

The value you use for the http://schemas.microsoft.com/claims/authnmethodsproviders claim should be one of the provider names returned by the list of providers that AD FS returned.

AD FS doesn't support triggering a particular extra authentication provider while the RP is using Access Control Policies in AD FS Windows Server 2016. When you move an application out of an access control policy, AD FS copies the corresponding policy from Access Control Policy to AdditionalAuthenticationRules and IssuanceAuthorizationRules. If an admin wants to use a specific authentication provider, they should stop using the access control policy and instead modify AdditionalAuthenticationRules.

On-Behalf-Of flow

The OAuth 2.0 On-Behalf-Of flow (OBO) serves the use case where an application invokes a service/web API, which in turn needs to call another service/web API. The idea is to propagate the delegated user identity and permissions through the request chain. For the middle-tier service to make authenticated requests to the downstream service, it needs to secure an access token from AD FS, on behalf of the user.

Protocol diagram

Assume that a user is authenticated on an application using the OAuth 2.0 authorization code grant flow described in the previous section. At this point, the application has an access token for API A (token A) with the user's claims and consent to access the middle-tier web API (API A). Make sure the client requests user_impersonation scope in the token. Now, API A needs to make an authenticated request to the downstream web API (API B).

The steps that follow constitute the OBO flow and are explained with the help of the following diagram.

1. The client application makes a request to API A with token A. (When you configure OBO flow in AD FS, make sure scope user_impersonation is selected and that clients request user_impersonation scope in the request.)
2. API A authenticates to the AD FS token issuance endpoint and requests a token to access API B. (When you configure this flow in AD FS, make sure API A is also registered as a server application with a client ID that has the same value as the resource ID in API A.)
3. The AD FS token issuance endpoint validates API A's credentials with token A and issues the access token for API B (token B).
4. Token B is set in the authorization header of the request to API B.
5. Data from the secured resource is returned by API B.

Service-to-service access token request

To request an access token, make an HTTP POST to the AD FS token endpoint with the parameters described in the following sections.

First case: Access token request with a shared secret

For a shared secret, a service-to-service access token request contains the following parameters:

Example

The following HTTP POST requests an access token and a refresh token.

// Line breaks for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=https://webapi.com/
&client_secret=BYyVnAt56JpLwUcyo47XODd
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope=openid

Second case: Access token request with a certificate

A service-to-service access token request with a certificate contains the following parameters:

Notice that the parameters are almost the same. This example is similar to the request by shared secret except that the client_secret parameter is replaced by two parameters: client_assertion_type and client_assertion.

Example

The following HTTP POST requests an access token for the web API with a certificate.

// Line breaks for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id= https://webapi.com/
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNS…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope= openid

Service-to-service access token response

A success response is a JSON OAuth 2.0 response that has the following parameters.

Success response example

The following example shows a success response to a request for an access token for the web API.

{
  "token_type": "Bearer",
  "scope": openid,
  "expires_in": 3269,
  "access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1t"
  "id_token": "aWRfdG9rZW49ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKU1V6STFOa"
  "refresh_token": "OAQABAAAAAABnfiG…"
  "refresh_token_expires_in": 28800,
}

Use the access token to access the secured resource

Now the middle-tier service can use the token acquired in the previous response example to make authenticated requests to the downstream web API. Set the token in the Authorization header.

Example

GET /v1.0/me HTTP/1.1
Host: https://secondwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQ…

Client credentials grant flow

You can use the OAuth 2.0 client credentials grant specified in RFC 6749 to access web-hosted resources by using the identity of an application. This type of grant is commonly used for server-to-server interactions that must run in the background, without immediate interaction with a user. These types of applications are often referred to as daemons or service accounts.

The OAuth 2.0 client credentials grant flow permits a web service (confidential client) to use its own credentials, instead of impersonating a user, to authenticate when calling another web service. In this scenario, the client is typically a middle-tier web service, a daemon service, or a web site. For a higher level of assurance, AD FS also allows the calling service to use a certificate (instead of a shared secret) as a credential.

Protocol diagram

The following diagram shows the client credentials grant flow.

Request a token

To get a token by using the client credentials grant, send a POST request to the /token AD FS endpoint, as shown in the following sections.

First case: Access token request with a shared secret

POST /adfs/oauth2/token HTTP/1.1
// Line breaks for legibility only

Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials

Second case: Access token request with a certificate

POST /adfs/oauth2/token HTTP/1.1

// Line breaks for legibility only

Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

Use a token

Now that you've acquired a token, use the token to make requests to the resource. When the token expires, repeat the request to the /token endpoint to acquire a fresh access token.

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

Resource owner password credentials grant flow (not recommended)

Resource owner password credential (ROPC) grant allows an application to sign in the user by directly handling their password. The ROPC flow requires a high degree of trust and user exposure. You should use this flow only when you can't use other flows that are more secure.

Protocol diagram

The following diagram shows the ROPC flow.

Authorization request

The ROPC flow is a single request—it sends the client identification and user's credentials to the IDP, and then receives tokens in return. The client must request the user's email address (UPN) and password before doing so. Immediately after a successful request, the client should securely release the user's credentials from memory. It must never save them.

// Line breaks and spaces are for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope= openid
&username=myusername@contoso.com
&password=SuperS3cret
&grant_type=password

Successful authentication response

The following example shows a successful token response:

{
    "token_type": "Bearer",
    "scope": "openid",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "refresh_token_expires_in": 28800,
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDR..."
}

You can use the refresh token to acquire new access tokens and refresh tokens by using the same flow described in the authentication code grant flow section of this article.

Device code flow

Device code grant allows users to sign in to input-constrained devices such as a smart TV, IoT device, or printer. To enable this flow, the device has the user visit a webpage in their browser on another device to sign in. After the user signs in, the device is able to get access tokens and refresh tokens as needed.

Protocol diagram

The entire device code flow is similar the flow shown in the next diagram. Each of the steps is described later in this article.

Device authorization request

The client must first check with the authentication server for a device and user code that's used to initiate authentication. The client collects this request from the /devicecode endpoint. In this request, the client should also include the permissions it needs to acquire from the user. From the time this request is sent, the user has only 15 minutes to sign in (the usual value for expires_in), so only make this request when the user has indicated they're ready to sign in.

// Line breaks are for legibility only

POST https://adfs.contoso.com/adfs/oauth2/devicecode
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
scope=openid

Device authorization response

A successful response is a JSON object containing the required information to allow the user to sign in.

Authenticating the user

After the client receives the user_code and verification_uri, it displays these details to the user, instructing them to sign in by using their mobile phone or PC browser. Additionally, the client can use a QR code or similar mechanism to display the verfication_uri_complete, which takes the step of entering the user_code for the user. While the user is authenticating at the verification_uri, the client should be polling the /token endpoint for the requested token using the device_code.

POST https://adfs.contoso.com /adfs/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type: urn:ietf:params:oauth:grant-type:device_code
client_id: 00001111-aaaa-2222-bbbb-3333cccc4444
device_code: GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8

Successful authentication response

A successful token response can include these parameters:

Related content

See AD FS Development for the complete list of walk-through articles, which provide step-by-step instructions on using the related flows.