Okta Token Exchange Grant Support for Subject Tokens Issued by Third-Party Identity Providers
Last Updated:
Overview
The OAuth 2.0 Token Exchange grant in Okta does not accept subject tokens that external, third-party identity providers issue. Okta enforces this boundary to maintain a secure trust domain, requiring the same Okta organization to issue the subject token included in the exchange request. Developers attempting to pass an identity or access token from a third-party identity provider directly to the Okta /oauth2/v1/token endpoint using the grant_type=urn:ietf:params:oauth:grant-type:token-exchange grant type receive the following error:
"error": "invalid_grant",
"error_description": "subject token is invalid"
Applies To
- Okta Identity Engine (OIE)
- Okta Classic Engine
- API Access Management
- OAuth 2.0 Token Exchange (RFC 8693)
Cause
In the OAuth 2.0 Token Exchange flow, a subject token represents the identity of the party on behalf of whom the client makes the request. Developers encounter an invalid grant error when they attempt to exchange an access token or identity token that a third-party identity provider (such as Azure AD, Auth0, Google, Ping Identity, or another Okta org) issues directly with Okta to obtain an Okta-issued access token. Okta rejects these requests because it restricts token exchange operations to a single trust domain. Okta requires the authorization server minting the new token to cryptographically verify the original subject token, which only succeeds when the same Okta organization issues both tokens.
Solution
Why does Okta reject third-party subject tokens during a token exchange?
Okta strictly enforces trust boundaries for the Token Exchange grant. An Okta Authorization Server belonging to the exact same Okta organization that processes the exchange request and mints the new token must issue the subject token included in the exchange request. Okta does not support federated trust for subject tokens originating from external identity providers.
The Subject Token Must Originate From the Same Okta Organization
Establish a valid token exchange pattern by authenticating the user directly against the Okta organization and utilizing the resulting Okta-issued token as the subject token for subsequent exchange requests.
- Authenticate the client or user against the Okta Authorization Server to obtain the initial access token.
- Provide this Okta-issued access token as the
subject_tokenin the OAuth 2.0 Token Exchange request. - Ensure the request targets the same Okta organization that issued the initial token.
How does Okta handle third-party identity federation before a token exchange?
Integrate external identity providers by configuring an inbound federation trust in Okta and routing the initial authentication request through the Okta authorization server.
- Configure the external identity provider as an Identity Provider within the Okta organization.
- Route the initial user authentication through Okta using an OAuth 2.0 flow linked to the external Identity Provider.
- Capture the resulting Okta-issued access token.
- Submit the Okta-issued access token as the
subject_tokenin the Token Exchange request.
