Improve feedback on token validation when using Tokens.getAccessToken #39525

nfode · 2025-05-07T12:03:40Z

nfode
May 7, 2025

In our custom endpoint extensions, we use Tokens.getAccessToken(session) to get the token in the request. This has one issue, when the token is invalid, the method always returns null. Since our custom endpoint is used by another service, we want to give a proper response, which is currently not possible.

The problem is not in Tokens.getAccessToken but in the underlying classes it uses. It calls AppAuthManager.BearerTokenAuthenticator.authenticate() which then in turn calls AuthenticationManager.verifyIdentityToken(). The verifyIdentityToken method silently returns null for various error scenarios without providing any context on what went wrong. Most of the time, it only logs debug logs.

Current Implementation

In AuthenticationManager.verifyIdentityToken(), error handling is implemented as returning null in many scenarios:

public static AuthResult verifyIdentityToken(KeycloakSession session, RealmModel realm, UriInfo uriInfo,
        ClientConnection connection, boolean checkActive, boolean checkTokenType,
        String checkAudience, boolean isCookie, String tokenString, HttpHeaders headers,
        Predicate<? super AccessToken>... additionalChecks) {
    try {
        // Token verification logic...
    } catch (VerificationException e) {
        logger.debugf("Failed to verify identity token: %s", e.getMessage());
    }
    return null; // No error information is returned
}

In our custom endpoint implementation, when we call:

val token = Tokens.getAccessToken(session)
if (token == null) {
    // We don't know why the token is invalid
    return Response.status(Status.UNAUTHORIZED).build()
}

Possible Solutions

Option 1: Throw Exceptions Instead of Returning Null

Modify verifyIdentityToken to throw specific exceptions instead of returning null. This would provide more context about what went wrong.

public static AuthResult verifyIdentityToken(KeycloakSession session, RealmModel realm, UriInfo uriInfo,
        ClientConnection connection, boolean checkActive, boolean checkTokenType,
        String checkAudience, boolean isCookie, String tokenString, HttpHeaders headers,
        Predicate<? super AccessToken>... additionalChecks) throws TokenVerificationException {
    try {
        // Token verification logic...
    } catch (VerificationException e) {
        logger.debugf("Failed to verify identity token: %s", e.getMessage());
        throw new TokenVerificationException("Token verification failed", e, TokenVerificationException.Reason.VERIFICATION_FAILED);
    }

    // Other error cases would throw specific exceptions
    if (!token.isActive() || token.getIat() < realm.getNotBefore()) {
        throw new TokenVerificationException("Token is not active", TokenVerificationException.Reason.TOKEN_INACTIVE);
    }

    // Return auth result if all checks pass
    return new AuthResult(user, userSession, token, client);
}

With the introduction of a custom exception class:

public class TokenVerificationException extends RuntimeException {

    public enum Reason {
        TOKEN_EXPIRED,
        TOKEN_INACTIVE,
        TOKEN_MALFORMED,
        SIGNATURE_INVALID,
        VERIFICATION_FAILED,
        CLIENT_DISABLED,
        USER_INVALID,
        // Other specific reasons
    }

    private final Reason reason;

    public TokenVerificationException(String message, Reason reason) {
        super(message);
        this.reason = reason;
    }

    public TokenVerificationException(String message, Throwable cause, Reason reason) {
        super(message, cause);
        this.reason = reason;
    }

    public Reason getReason() {
        return reason;
    }
}

In our custom endpoint implementation, we could then handle specific error cases:

try {
    val token = Tokens.getAccessToken(session)
    // Use token...
} catch (e: TokenVerificationException) {
    when (e.reason) {
        TokenVerificationException.Reason.TOKEN_EXPIRED ->
            return Response.status(Status.UNAUTHORIZED)
                .entity("Token expired")
                .build()
        TokenVerificationException.Reason.SIGNATURE_INVALID ->
            return Response.status(Status.UNAUTHORIZED)
                .entity("Invalid token signature")
                .build()
        // Handle other specific cases
        else ->
            return Response.status(Status.UNAUTHORIZED)
                .entity("Authentication failed: ${e.message}")
                .build()
    }
}

Option 2: Use Result/Either Pattern

Modify verifyIdentityToken to return a result object that contains either the successful result or error details.

public static TokenVerificationResult verifyIdentityToken(KeycloakSession session, RealmModel realm,
        UriInfo uriInfo, ClientConnection connection, boolean checkActive, boolean checkTokenType,
        String checkAudience, boolean isCookie, String tokenString, HttpHeaders headers,
        Predicate<? super AccessToken>... additionalChecks) {
    try {
        // Token verification logic...
        if (!token.isActive() || token.getIat() < realm.getNotBefore()) {
            return TokenVerificationResult.error(TokenError.TOKEN_INACTIVE,
                "Token not active or issued before realm NotBefore");
        }

        // Other checks...

        // Success case
        return TokenVerificationResult.success(new AuthResult(user, userSession, token, client));
    } catch (VerificationException e) {
        logger.debugf("Failed to verify identity token: %s", e.getMessage());
        return TokenVerificationResult.error(TokenError.VERIFICATION_FAILED, e.getMessage());
    }
}

With supporting classes:

public class TokenVerificationResult {
    private final AuthResult authResult;
    private final TokenError error;
    private final String errorMessage;

    private TokenVerificationResult(AuthResult authResult, TokenError error, String errorMessage) {
        this.authResult = authResult;
        this.error = error;
        this.errorMessage = errorMessage;
    }

    public static TokenVerificationResult success(AuthResult authResult) {
        return new TokenVerificationResult(authResult, null, null);
    }

    public static TokenVerificationResult error(TokenError error, String errorMessage) {
        return new TokenVerificationResult(null, error, errorMessage);
    }

    public boolean isSuccess() {
        return authResult != null;
    }

    public AuthResult getAuthResult() {
        return authResult;
    }

    public TokenError getError() {
        return error;
    }

    public String getErrorMessage() {
        return errorMessage;
    }
}

public enum TokenError {
    TOKEN_EXPIRED,
    TOKEN_INACTIVE,
    TOKEN_MALFORMED,
    SIGNATURE_INVALID,
    VERIFICATION_FAILED,
    CLIENT_DISABLED,
    USER_INVALID,
    // Other specific errors
}

In our custom endpoint, we could then use it like:

val verificationResult = Tokens.getAccessTokenWithResult(session)
if (!verificationResult.isSuccess()) {
    val errorResponse = when (verificationResult.error) {
        TokenError.TOKEN_EXPIRED ->
            Response.status(Status.UNAUTHORIZED)
                .entity("Token expired")
                .build()
        TokenError.SIGNATURE_INVALID ->
            Response.status(Status.UNAUTHORIZED)
                .entity("Invalid token signature")
                .build()
        // Handle other specific cases
        else ->
            Response.status(Status.UNAUTHORIZED)
                .entity("Authentication failed: ${verificationResult.errorMessage}")
                .build()
    }
    return errorResponse
}

val token = verificationResult.authResult.token
// Continue with the valid token

Bonus Option

Replace debug logs with events. Debug logs cannot be used in a production environment, therefore events would be very helpful to system admins.

Compatibility Considerations

To be backwards compatible, the old implementation would call the new implementation and then return null for all the newly defined errors.

Navigation Menu

Repository navigation

Improve feedback on token validation when using Tokens.getAccessToken #39525

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Improve feedback on token validation when using Tokens.getAccessToken #39525

Uh oh!

nfode May 7, 2025

Current Implementation

Possible Solutions

Option 1: Throw Exceptions Instead of Returning Null

Option 2: Use Result/Either Pattern

Bonus Option

Compatibility Considerations

Replies: 0 comments

nfode
May 7, 2025