Introduction

OpenID Connect (OIDC) requires the ID token's aud (audience) claim to match the client ID of the application requesting authentication. When using a custom or self-hosted OIDC provider, misconfiguration can cause the audience claim to contain an incorrect value, causing the application's OIDC library to reject the token and block user authentication.

Symptoms

  • User authentication fails after successful login at the identity provider
  • Application logs show OIDC ID token audience validation failed
  • ID token decoded shows aud claim different from the application's client ID
  • Error occurs immediately after identity provider redirects back to the application
  • Error message: Error: id_token audience (aud) claim does not match client_id

Common Causes

  • Custom OIDC provider configured with the wrong audience for the client
  • Application client ID changed but the OIDC provider was not updated
  • Multiple applications sharing the same OIDC client registration with different audiences
  • Provider including additional audiences in the aud array that the application does not recognize
  • OIDC provider using a different audience format (e.g., full URL vs. client ID string)

Step-by-Step Fix

  1. 1.Decode the ID token to inspect the audience claim: Check what the provider is sending.
  2. 2.```bash
  3. 3.# Decode the ID token (second part of the JWT)
  4. 4.echo "eyJhbGci..." | cut -d. -f2 | base64 -d 2>/dev/null | jq '.aud'
  5. 5.# Compare with the expected client_id
  6. 6.`
  7. 7.Verify the application's configured client ID: Check what the application expects.
  8. 8.```bash
  9. 9.# Check application OIDC configuration
  10. 10.grep -r "client_id|audience" /etc/app/oidc-config.yaml
  11. 11.# Or check environment variables
  12. 12.echo $OIDC_CLIENT_ID
  13. 13.`
  14. 14.Update the OIDC provider client configuration: Fix the audience setting.
  15. 15.`
  16. 16.# In the custom OIDC provider (e.g., Keycloak, Dex, custom):
  17. 17.# Navigate to the client configuration
  18. 18.# Update the Audience or Client ID to match the application's expected value
  19. 19.# For Keycloak: Client Settings > Client ID > save
  20. 20.`
  21. 21.Update the application to accept the provider's audience: Alternatively, fix the application.
  22. 22.```javascript
  23. 23.// If the provider sends a different audience format, configure the app to accept it
  24. 24.const oidcConfig = {
  25. 25.issuer: 'https://auth.example.com',
  26. 26.client_id: 'my-app',
  27. 27.expected_audience: ['my-app', 'https://api.example.com'], // Accept multiple audiences
  28. 28.};
  29. 29.`
  30. 30.Test the authentication flow end-to-end: Verify the fix works.
  31. 31.```bash
  32. 32.# Trigger authentication and check the ID token
  33. 33.curl -v https://app.example.com/login
  34. 34.# Follow the redirect chain and inspect the final ID token
  35. 35.`

Prevention

  • Document the expected audience format for each OIDC client registration
  • Test OIDC integration after any client ID or provider configuration changes
  • Use standardized OIDC client configuration (client ID = audience) for consistency
  • Monitor OIDC authentication failure rates and alert on audience validation errors
  • Include audience validation in the OIDC integration test suite
  • Use OIDC discovery to automatically configure audience expectations from the provider's metadata