OIDC/OAuth error - Authorization Code does not match or has already been used

Version Affected:  SecureAuth Identity Platform: All
 

Description:  
When attempting to exchange an Authorization Code for an access token, Identity Platform does not issue one.  When looking at the logs, it states "Authorization Code does not match or has already been used"

Message="[TokenEndpointHandler].[ValidateAuthorizationCodeFlow]: Authorization Code does not match or has already been used."

 

Cause(s):  
This error can have more than a single root cause:
(In the below examples, it is assumed the Datastore is Active Directory, this also applies to other types of Datastore storage where a replication flow is in place)

Cause 1 — Consent Storage attribute is not writeable
The attribute mapped to Consent Storage in the realm's Data tab has not been marked as writeable by the Service Account. IdP cannot write the authorisation code to AD, so the code is never stored and cannot be validated during the token exchange


How to identify Cause 1:

• The error occurs on every authentication attempt, consistently
• The error is not affected by timing - slowing down the Auth Code exchange makes no difference

Cause 2 — AD replication lag in multi-site deployments (intermittent failures only)
In environments with multiple IdP nodes spread across more than one AD site, a race condition can occur between the authorisation code being written to AD and the token exchange reading it back

When a user authenticates, IdP writes the authorisation code to the Consent Storage attribute on the Domain Controller it is connected to at that moment (for example, DC1 in Site A). The service provider then immediately sends the Auth Code exchange request. If that request is routed to a different DC (for example, DC2 in Site B), and AD replication has not yet propagated the entry from DC1 to DC2, IdP finds no matching code and returns this error


How to identify Cause 2:

• The error is intermittent — it does not occur on every attempt
• Consent Storage is enabled on the realm
• The Consent Storage attribute is confirmed to be writeable (Cause 1 has been ruled out)
• The error is more likely when the service provider processes quickly, slowing the flow down on the SP side can allow the Auth Code exchange to succeed
• The IdP environment reaches out across more than one AD site or geographically distributed Domain Controllers

Resolution(s):  

Cause 1

• Open the Admin Console and navigate to the Post Authentication and Data tab (Classic) or the Datastore - Properties (New Experience) of the affected OIDC realm
• Locate the attribute configured for Consent Storage (for example, Aux ID 10 / houseidentifier)
• Ensure the Writable checkbox is ticked for that attribute
• Confirm the Service Account used by the realm has write permission to that attribute in Active Directory
• Save the changes and re-test

Classic Realms
(Post Authentication Tab - newer versions of Identity Platform do not have a 'Consent Storage Attribute' field on the Post Authentication Tab - configuration is limited to the Data tab)


(Data Tab - if the Post Authentication Tab has a setting for the Consent Storage Attribute)


(Data Tab - if the Post Authentication Tab DOES NOT have a setting for the Consent Storage Attribute)



New Experience Realms
(Datastore - Properties)

Cause 2
Option 1 — Pin the datastore to a single AD Site (recommended)
Modify the datastore connection string for the OIDC realm so that all IdP nodes query Domain Controllers within the same AD site. Intra-site replication is near-instantaneous, which eliminates the race condition while retaining DC failover within that site

See: How to connect to a specific AD Site

Option 2 — Pin the datastore to a single Domain Controller (not recommended for production)
Point the Realm's datastore connection string directly at one DC. This eliminates replication lag entirely but removes all DC-level failover for that realm. This is suitable for confirming the root cause during troubleshooting but is not appropriate as a permanent solution

Option 3 — Disable Consent Storage (only where not required)
If the realm does not use the Introspection endpoint or Token Refresh, Consent Storage can be disabled on the Post-Auth tab of the realm. Note: disabling Consent Storage will break the Introspect and token Refresh  endpoints if those are in use by any application connected to this realm

Internal/DMZ deployments: If your environment uses separate Internal and DMZ SecureAuth servers, the Authorisation Code exchange can also fail, but due to a slightly different issue
See: OIDC with Internal and DMZ combination fails for internal users

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.