Implementing an OAuth client credentials flow with ADFS–Part 1 - ADFS configuration

It looked like most of the world has made the switch to Microsoft Entra(Azure Active Directory). However one of my clients is still using ADFS. Unfortunately there isn't much information left on how to get an OAuth flow up and running in ADFS. Most of the links I found point to documentation that no longer exists. So therefore this short blog series to show you end-to-end how to get an OAuth Client Credentials flow configured in ADFS.

In todays post, I focus on the ADFS configuration. To make it not unnecessary complex, I’ll show the steps using one of the simplest OAuth flows; the Client Credentials flow.

OAuth Client Credentials flow

The OAuth Client Credentials flow is an authentication method used primarily for machine-to-machine (M2M) communication. In this flow, an application (the "client") requests an access token directly from an OAuth 2.0 authorization server using its own credentials, without involving a user. This access token allows the client to access resources on behalf of itself rather than an end-user.

 

Here's how the flow works:

1. Client Registration: The client (e.g., a backend service or API) is registered with the authorization server(ADFS in our case). During registration, the client is issued a client ID and a client secret.

2. Token Request: The client sends a token request to the authorization server’s token endpoint. This request includes:

   • The grant_type set to "client_credentials"
   • The client ID and client secret
   • Optionally, a scope parameter to define the specific permissions it requires.

3. Token Response: If the credentials are valid and the client is authorized, the authorization server issues an access token. This token is then used by the client to authenticate itself to the resource server (API).

4. Access Resource: The client uses the token to access protected resources by including it in the Authorization header of the API requests as a Bearer token.

Remark: This flow can only be used by a ‘confidential client’. This means that the client should be able to safely store the provided client ID and secret.

Configuring ADFS

Ok, now that we understand the basic concepts, let’s see what needs to be done in ADFS.

In ADFS the client and the resource server are configured together in an Application Group.

• Open the ADFS Management tool.
• Go to the Application Groups section.

• Click on Add Application Group… in the Actions section.

 

• The Add Application Group wizard is loaded. Click on ‘Server application accessing a web API’ from the list of available templates.

 

• Add a name for the application group and an optional description and click on Next.

 

• On the next screen, we need to configure our OAuth client.
• Change the name.
• A client identifier is already generated for us. Feel free to change this if you like.
• We also need to add a redirect URI. For the Client Credentials flow, it isn’t so important what this URI is so add anything that you like and click on Add. Once at least one redirect URI is added, you can click on Next.

• Now we need to specify the form of our client secret. This can be based on a certificate, a Windows account or a shared secret. As a shared secret is the easiest way, let’s continue with that option.
• Check the Generate a shared secret checkbox. A secret is generated.
• Copy it and store it somewhere safe(in a password vault for example). You will not be able to view the secret again.
• Click on Next to continue.

 

• The next step is to configure our OAuth resource server.
• Remark: In ADFS terminology the resource server is called the Relying Party.
• Change the suggested name.
• Add an identifier for your OAuth resource and an optional description.
• Click on Next to continue.

 

• Almost there! Now we can configure an access control policy. By default this is set to Permit everyone. That is OK for us, so just hit Next to continue.

 

• As the last step, we need to specify the permitted scopes the client can use. By default the openid scope is selected.

• Instead of using the openid scope, we’ll create a new one. Therefore click on New scope…
• Enter a name for the new scope and hit OK.

• Unselect the openid scope and click Next to continue.

 

• On the summary page, just click Next.

• The application group is created and you can close the wizard.

 

That's it!

Tomorrow I’ll continue by showing the corresponding application code and configuration.

More information

AD FS OpenID Connect/OAuth flows and Application Scenarios | Microsoft Learn