justauth/JustAuth · error · AuthException

object.getString("error_description")

Error message

object.getString("error_description")

What it means

AuthOktaRequest.checkResponse throws AuthException with 'error_description' when an Okta API response contains an 'error' key. Okta returns standard OAuth2 error JSON for token, refresh, and userinfo calls against {domainPrefix}.okta.com/oauth2/{authServerId}.

Source

Thrown at src/main/java/me/zhyd/oauth/request/AuthOktaRequest.java:117

            .build();
    }

    @Override
    public AuthResponse revoke(AuthToken authToken) {
        Map<String, String> params = new HashMap<>(4);
        params.put("token", authToken.getAccessToken());
        params.put("token_type_hint", "access_token");

        HttpHeader header = new HttpHeader()
            .add("Authorization", "Basic " + Base64Utils.encode(config.getClientId().concat(":").concat(config.getClientSecret())));
        new HttpUtils(config.getHttpConfig()).post(revokeUrl(authToken), params, header, false);
        AuthResponseStatus status = AuthResponseStatus.SUCCESS;
        return AuthResponse.builder().code(status.getCode()).msg(status.getMsg()).build();
    }

    private void checkResponse(JSONObject object) {
        if (object.containsKey("error")) {
            throw new AuthException(object.getString("error_description"));
        }
    }

    @Override
    public String authorize(String state) {
        return UrlBuilder.fromBaseUrl(String.format(source.authorize(), config.getDomainPrefix(), config.getAuthServerId()))
            .queryParam("response_type", "code")
            .queryParam("prompt", "consent")
            .queryParam("client_id", config.getClientId())
            .queryParam("redirect_uri", config.getRedirectUri())
            .queryParam("scope", this.getScopes(" ", true, AuthScopeUtils.getDefaultScopes(AuthOktaScope.values())))
            .queryParam("state", getRealState(state))
            .build();
    }

    @Override
    public String accessTokenUrl(String code) {
        return UrlBuilder.fromBaseUrl(String.format(source.accessToken(), config.getDomainPrefix(), config.getAuthServerId()))

View on GitHub (pinned to 694bbf1b01)

Solutions

  1. Verify domainPrefix and authServerId: the authorize URL must be https://{prefix}.okta.com/oauth2/{authServerId}/v1/...
  2. Enable 'Authorization Code' grant and assign the app to the authorization server's policy
  3. Read error_description for the precise OAuth2 error and act accordingly
  4. Ensure the authorization code is redeemed exactly once and promptly

Example fix

null
Defensive patterns

Strategy: try-catch

Validate before calling

null

Type guard

null

Try / catch

try {
    oktaRequest.getAuthResponse(callback);
} catch (AuthException e) {
    log.warn("Okta error: {}", e.getMessage());
    if (e.getMessage() != null && e.getMessage().contains("invalid_client")) {
        // fix client secret
    }
}

Prevention

When it happens

Trigger: Token exchange or userinfo when Okta returns invalid_grant (code expired/consumed), invalid_client (bad client secret), or when the Authorization Server ID is wrong so the request hits a non-existent endpoint returning an error body.

Common situations: Wrong domainPrefix or authServerId in AuthConfig (Okta org vs custom authorization server mix-up), missing 'okta.users.read.self' style scopes, or the app's grant type not enabled for authorization_code.

Related errors

AI-assisted analysis of justauth/JustAuth@694bbf1b01 (2026-08-14). Data as JSON: /api/errors/e55a7559f631ebcb. Report an issue: GitHub.