apache/dolphinscheduler · error · ServiceException

OIDC_TOKEN_EXCHANGE_FAILED

OIDC_TOKEN_EXCHANGE_FAILED

Error message

OIDC_TOKEN_EXCHANGE_FAILED

What it means

exchangeCodeForTokens sends the OIDC authorization-code token request via Nimbus OAuth2 SDK. If the HTTP request itself throws (network error, malformed response, parse failure), OIDCTokenResponseParser.parse or send() raises and the code wraps it in ServiceException(Status.OIDC_TOKEN_EXCHANGE_FAILED). Called from the tokens() endpoint during OIDC login callback.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/security/impl/oidc/OidcAuthenticator.java:254

            ClientAuthentication clientAuth;
            if ("client_secret_post".equalsIgnoreCase(providerConfig.getClientAuthenticationMethod())) {
                clientAuth = new ClientSecretPost(clientID, clientSecret);
            } else {
                clientAuth = new ClientSecretBasic(clientID, clientSecret);
            }

            TokenRequest tokenRequest = new TokenRequest(
                    providerMetadata.getTokenEndpointURI(),
                    clientAuth,
                    codeGrant);

            TokenResponse tokenResponse;
            try {
                tokenResponse = OIDCTokenResponseParser.parse(tokenRequest.toHTTPRequest().send());
            } catch (Exception e) {
                log.error("Failed to send token request", e);
                throw new ServiceException(Status.OIDC_TOKEN_EXCHANGE_FAILED);
            }

            if (!tokenResponse.indicatesSuccess()) {
                log.error("Token request failed: {}", tokenResponse.toErrorResponse().getErrorObject());
                throw new ServiceException(Status.OIDC_TOKEN_EXCHANGE_FAILED);
            }

            return ((OIDCTokenResponse) tokenResponse).getOIDCTokens();
        } catch (java.net.URISyntaxException e) {
            log.error("Invalid redirect URI configured for OIDC provider: {}", providerId, e);
            throw new ServiceException("Failed to construct OIDC redirect URI", e);
        }
    }

    /**
     * Validate ID token and extract claims
     */
    private IDTokenClaimsSet validateIdToken(OIDCProviderMetadata providerMetadata,

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Check api-server logs for the underlying 'Failed to send token request' exception to find the root cause (connectivity/TLS/parse)
  2. Verify the OIDC provider token endpoint URL and network reachability from the api-server (curl the token endpoint)
  3. Import the provider's TLS certificate into the JVM truststore if it's a certificate error
  4. Confirm the OIDC provider is up and the configured issuer/discovery URL is correct

Example fix

null
Defensive patterns

Strategy: try-catch

Validate before calling

// verify token endpoint reachability before login flow
HttpURLConnection c = (HttpURLConnection) new URL(tokenEndpoint).openConnection();
c.setConnectTimeout(5000);
if (c.getResponseCode() < 200 || c.getResponseCode() >= 500) {
    throw new IllegalStateException("OIDC provider unreachable: " + tokenEndpoint);
}

Try / catch

try {
    loginViaOidc(authorizationCode);
} catch (ServiceException e) {
    if (Status.OIDC_TOKEN_EXCHANGE_FAILED.equals(e.getCode())) {
        log.error("OIDC token exchange failed; check provider reachability and TLS trust");
    }
}

Prevention

When it happens

Trigger: User completing OIDC login: the callback's code is exchanged at the token endpoint but the HTTP send fails (connection refused/TLS error/timeout) or the provider returns an unparseable body, so parse() throws.

Common situations: OIDC provider unreachable from the api-server (firewall, wrong issuer/token-endpoint URL); token endpoint misconfigured; provider down; TLS certificate not trusted by the JVM; provider returning HTML error page instead of JSON.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/457971dec6d90870. Report an issue: GitHub.