Interface XsuaaTokenExtension

public interface XsuaaTokenExtension

Extension interface for resolving and caching XSUAA tokens from IAS tokens.

This interface defines the contract for automatic XSUAA token exchange in hybrid authentication scenarios (IAS Level 0 Migration). Implementations are responsible for:

• Token Exchange: Converting IAS tokens to XSUAA format via /token_exchange endpoint
• Caching Logic: Determining when to return cached tokens vs. re-exchanging
• Expiration Handling: Validating token expiration and triggering re-exchange when needed

Hybrid Authentication Context:

In hybrid scenarios, applications migrate from XSUAA-only to IAS-first authentication while maintaining backward compatibility:

1. Incoming Token: IAS token from HTTP Authorization header
2. Authorization Logic: Still uses XSUAA scopes/roles (not yet migrated to IAS)
3. Token Exchange: Extension converts IAS → XSUAA for authorization checks
4. Future Migration: Eventually replace XSUAA authorization with IAS attributes

Caching Strategy:

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

1. Return cached token: If it exists and is still valid
2. Re-exchange 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.registerXsuaaTokenExtension(XsuaaTokenExtension) but operates on thread-local tokens. Multiple threads may call resolveXsuaaToken(Token) concurrently.

Lifecycle:

1. Registration: Extension is registered once at application startup via SecurityContext.registerXsuaaTokenExtension(XsuaaTokenExtension)
2. Exchange: Called by SecurityContext.getXsuaaToken() when XSUAA token is requested
3. Caching: Returned token is cached in thread-local SecurityContext
4. Re-exchange: Called again on next SecurityContext.getXsuaaToken() if cached token expired

Configuration Requirements:

XSUAA token exchange requires proper Cloud Foundry service binding configuration:

# manifest.yml
services:
  - xsuaa-service
env:
  xsuaa-cross-consumption: true  # Enable IAS-to-XSUAA exchange

Usage Example (Spring Boot):

@Configuration
public class SecurityConfig {
    @PostConstruct
    public void registerExtensions() {
        SecurityContext.registerXsuaaTokenExtension(
            new DefaultXsuaaTokenExtension(tokenService, xsuaaConfig)
        );
    }
}

Error Handling:

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

See Also:

• SecurityContext.getXsuaaToken()
• SecurityContext.registerXsuaaTokenExtension(XsuaaTokenExtension)
• SecurityContext.clearXsuaaToken()

Method Summary

Modifier and Type	Method	Description
Token	resolveXsuaaToken(Token cachedXsuaaToken)	Resolves a XSUAA token from the current security context (typically via IAS-to-XSUAA exchange).

Method Details

resolveXsuaaToken

Token resolveXsuaaToken(@Nullable
 Token cachedXsuaaToken)

Resolves a XSUAA token from the current security context (typically via IAS-to-XSUAA exchange).

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

Caching Responsibility:

The implementation is responsible for:

1. Checking cached token validity: Inspect cachedXsuaaToken expiration
2. Deciding whether to re-exchange: Return cached token if valid, otherwise exchange new token
3. Token exchange: If re-exchange needed, convert IAS token to XSUAA format

Source Token Availability:

The source token (typically IAS) is available via SecurityContext.getToken(). If no token exists or it's already a XSUAA token, the implementation should return null or the existing Token since exchange is unnecessary.

Return Value Handling:

• Non-null token: Cached in SecurityContext for subsequent SecurityContext.getXsuaaToken() 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:

cachedXsuaaToken - the currently cached XSUAA token from thread-local SecurityContext, or null if:

• No XSUAA token has been exchanged yet for this thread
• The cached token was cleared via SecurityContext.clearXsuaaToken()
• The security context was reset via SecurityContext.setToken(Token)

Returns:

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

• No IAS token is available in the security context
• Token exchange fails (network error, invalid configuration, missing XSUAA binding, etc.)