Interface IdTokenExtension

public interface IdTokenExtension

Extension interface for resolving and caching ID tokens from access tokens.

This interface defines the contract for automatic ID token resolution in SecurityContext. Implementations are responsible for:

• Token Exchange: Converting access tokens to ID tokens (e.g., via OAuth2 token exchange)
• Caching Logic: Determining when to return cached tokens vs. re-resolving
• Expiration Handling: Validating token expiration and triggering re-resolution when needed

Caching Strategy:

The extension receives the currently cached ID token (if any) and decides whether to:

1. Return cached token: If it exists and is still valid
2. Re-resolve token: If cached token is expired, missing, or otherwise invalid

This design decouples caching policy from SecurityContext, allowing implementations to customize expiration checks, implement token refresh logic, or add custom validation rules.

Thread Safety:

Implementations must be thread-safe as the extension is registered globally via SecurityContext.registerIdTokenExtension(IdTokenExtension) but operates on thread-local tokens. Multiple threads may call resolveIdToken(Token) concurrently.

Lifecycle:

1. Registration: Extension is registered once at application startup via SecurityContext.registerIdTokenExtension(IdTokenExtension)
2. Resolution: Called by SecurityContext.getIdToken() when ID token is requested
3. Caching: Returned token is cached in thread-local SecurityContext
4. Re-resolution: Called again on next SecurityContext.getIdToken() if cached token expired

Usage Example (Spring Boot):

@Configuration
public class SecurityConfig {
    @PostConstruct
    public void registerExtensions() {
        SecurityContext.registerIdTokenExtension(
            new DefaultIdTokenExtension(tokenService, iasConfig)
        );
    }
}

Error Handling:

Implementations should handle errors gracefully and return null if resolution fails (network errors, invalid tokens, missing configuration, etc.). SecurityContext will propagate the null to callers, allowing them to handle missing ID tokens appropriately.

See Also:

• SecurityContext.getIdToken()
• SecurityContext.registerIdTokenExtension(IdTokenExtension)
• SecurityContext.clearIdToken()

Method Summary

Modifier and Type	Method	Description
Token	resolveIdToken(Token cachedIdToken)	Resolves an ID token from the current security context.

Method Details

resolveIdToken

Token resolveIdToken(@Nullable
 Token cachedIdToken)

Resolves an ID token from the current security context.

This method is called by SecurityContext.getIdToken() to lazily resolve ID tokens when needed. The implementation receives the currently cached ID token (if any) and decides whether to return it or resolve a new one.

Caching Responsibility:

The implementation is responsible for:

1. Checking cached token validity: Inspect cachedIdToken expiration
2. Deciding whether to re-resolve: Return cached token if valid, otherwise resolve new token
3. Token exchange: If re-resolution needed, exchange access token for ID token

Access Token Availability:

The access token is available via SecurityContext.getToken(). If no access token exists, the implementation should return null since token exchange is impossible.

Return Value Handling:

• Non-null token: Cached in SecurityContext for subsequent SecurityContext.getIdToken() calls
• null: No caching occurs; subsequent calls will re-invoke this method

Thread Safety:

This method may be called concurrently from multiple threads. Implementations must be stateless or use proper synchronization.

Parameters:

cachedIdToken - the currently cached ID token from thread-local SecurityContext, or null if:

• No ID token has been resolved yet for this thread
• The cached token was cleared via SecurityContext.clearIdToken()
• The security context was reset via SecurityContext.setToken(Token)

Returns:

the resolved ID token (may be the cached token if still valid), or null if:

• No access token is available in the security context
• Token exchange fails (network error, invalid configuration, etc.)
• The access token does not support ID token exchange