Keycloak S2S Verification with Postman and the aud Claim 

In our previous post, we detailed why we moved away from legacy AD service users and adopted Keycloak’s Client Credentials Grant for secure Service-to-Service (S2S) authentication. We configured our Chat App Service (chat-app-service) to call the protected CRM API Gateway (crm-api-gateway), locking down access using the critical Audience (aud) claim. 

Now for the final, and most satisfying, step: Verification. 

We needed a standard, accessible tool to prove that Keycloak was correctly issuing tokens with the required audience and that our services could successfully use them. We chose Postman to simulate the chat-app-service requesting a token. 

The Core Goal: Verify the Dedicated aud Claim 

For our solution to be safe, the access token must contain the crm-api-gateway ID in its Audience (aud) claim. Without this claim, the CRM API Gateway would reject the token, preventing token reuse. 

The process breaks down into two main steps: 

1. Acquire the Token: Use Postman to act as the chat-app-service and request the token from Keycloak. 

2. Verify the Token: Inspect the token payload to ensure the aud claim is present and correct. 

Postman Configuration and Token Acquisition 

This flow is essential for Service Accounts (machine-to-machine) authentication. 

Prerequisites 

• A Confidential Keycloak Client ID and Secret (for our chat-app-service). 

• The client must have Service Account Enabled set to ON in the Keycloak Admin Console. 

• Postman desktop application installed. 

Step 1: Configure the Request Details  

1. Open Postman and create a new request. 

2. Set the Method to POST. 

3. Set the URL to your Keycloak Token Endpoint URL: 

https://<KEYCLOAK_HOST>:<PORT>/auth/realms/<YOUR_REALM>/protocol/openid-connect/token

Step 2: Configure OAuth 2.0 and Apply the Crucial Fix 

The configuration below is sensitive, particularly regarding how the client credentials are sent, which is a common developer hurdle. 

1. Go to the Authorization tab. 

2. Set Type to OAuth 2.0. 

3. Scroll down to the Configure New Token section and set: 

• Grant Type: Select Client Credentials. 

• Access Token URL: Enter the Token Endpoint URL from Step 1. 

• Client ID: Enter the ID of your calling service (chat-app-service). 

• Client Secret: Enter the Secret obtained from Keycloak. 

• Scope: Enter the scopes you need (e.g., openid). 

• Client Authentication: Select: Send client credentials in body.  

• This is the critical “fix” that ensures Keycloak receives the required grant_type parameter, resolving the common “Missing form parameter” error. 

4. Click Get New Access Token. 

5. If successful, click Use Token. The new token will now be applied automatically to the request header for subsequent API calls. 

Verification Steps 

Step 3: Inspect the Token Payload (The aud Check) 

Before calling our CRM API Gateway, we needed to be 100% sure the token contained the correct claims, especially the Audience (aud) claim. 

1. Copy the entire Access Token string obtained in Step 2. 

2. Paste the token into an online JWT Decoder (e.g., jwt.io). 

3. Validate: Check the Payload section to confirm: 

• The azp (Authorized Party) is set to your client ID (chat-app-service). 

• The aud (Audience) claim is present and set to the ID of the resource it’s meant to call (crm-api-gateway). 

Step 4: Test the Access Token on a Protected API 

Finally, we test the complete flow against our protected service: 

1. Create a new request targeting your protected resource (e.g., a POST request to the CRM endpoint). 

2. Go to the Authorization tab. 

3. Set Type to Bearer Token. (Postman should have automatically populated the token from Step 2). 

4. Click Send. 

5. A HTTP 200 OK response indicates success: the chat-app-service authenticated with Keycloak, obtained a correctly scoped token, and the crm-api-gateway accepted it. 

Troubleshooting 

Error Message	Reason	Solution
“Missing form parameter: grant_type”	Postman did not send grant_type=client_credentials in the body.	In the OAuth 2.0 config (Step 2), ensure Client Authentication is set to Send client credentials in body.
“Client not enabled to retrieve service account”	The client is not configured for the Client Credentials Grant.	In Keycloak Admin Console, ensure Service accounts enabled is ON for this client.
“401 Unauthorized” on API call	The protected API rejected the token.	Check the token’s expiry and, most importantly, the aud claim (using Step 3) to ensure it’s valid for the target API.

By using this structured approach, we not only solved our S2S authentication problem but also established a reliable, repeatable verification process that any developer could use. This is how we achieved truly secure, microservice-friendly authentication. 🎉 

AVI E.