get-Xsuaa-Token

NiklasHerrmann21 · NiklasHerrmann21 · commit b1821cbd6eb0 · 2026-01-12T16:17:18.000+01:00
- MR comments, reworked READMEs
diff --git a/README.md b/README.md
@@ -132,16 +132,25 @@ using XSUAA-based authorization (scopes, role collections).
 
 #### How Token Exchange Works
 
-When a JWT bearer token arrives:
-
-1. The library identifies whether the token was issued by IAS or XSUAA
-2. The token is validated using the appropriate validator
-3. If the token is from IAS and exchange is enabled, an XSUAA token is obtained via OAuth2 JWT bearer flow
-4. The XSUAA token contains the user's roles/scopes as defined in XSUAA
-5. Authorization proceeds using familiar XSUAA token attributes
+```
+1. Request arrives with Authorization: Bearer <token>
+2. Library identifies issuer (IAS vs XSUAA) from token claims
+3. Token validated against appropriate identity service
+4. [IF IAS token + exchange enabled]
+   ├─ Obtain strong IAS ID token (if access token provided)
+   ├─ Call XSUAA /oauth/token endpoint with JWT bearer grant
+   └─ Store exchanged XSUAA token in SecurityContext
+5. [IF exchange disabled OR XSUAA token]
+   └─ Use validated token directly
+6. The XSUAA token contains the user's roles/scopes as defined in XSUAA
+7. Authorization proceeds using familiar XSUAA token attributes
+```
 
 If the incoming token is already an XSUAA token, no exchange occurs—it's validated and used directly.
 
+**Failure Handling**: If token exchange fails (network issues, misconfiguration), authentication fails with 401
+Unauthorized. No silent fallback occurs since IAS access tokens typically lack scopes needed for authorization.
+
 #### Token Exchange Modes
 
 The [`TokenExchangeMode`](java-security/src/main/java/com/sap/cloud/security/token/TokenExchangeMode.java)enum controls
@@ -168,230 +177,38 @@ The Initial token is still available via the [`SecurityContext.getInitialToken()
 2. IAS service binding must include `xsuaa-cross-consumption: true` parameter
 3. Ensure XSUAA trusts the IAS identity provider
 
-#### Token Exchange Flow Summary
-
-```
-1. Request arrives with Authorization: Bearer <token>
-2. Library identifies issuer (IAS vs XSUAA) from token claims
-3. Token validated against appropriate identity service
-4. [IF IAS token + exchange enabled]
-   ├─ Obtain strong IAS ID token (if access token provided)
-   ├─ Call XSUAA /oauth/token endpoint with JWT bearer grant
-   └─ Store exchanged XSUAA token in SecurityContext
-5. [IF exchange disabled OR XSUAA token]
-   └─ Use validated token directly
-6. Request proceeds with authenticated security context
-```
-
-**Failure Handling**: If token exchange fails (network issues, misconfiguration), authentication fails with 401
-Unauthorized. No silent fallback occurs since IAS access tokens typically lack scopes needed for authorization.
-
 #### 2.4.1 Jakarta Example: Using [`HybridTokenAuthenticator`](java-security/src/main/java/com/sap/cloud/security/servlet/HybridTokenAuthenticator.java)
 
 For Jakarta EE applications, use [
 `HybridTokenAuthenticator`](java-security/src/main/java/com/sap/cloud/security/servlet/HybridTokenAuthenticator.java) in
-a servlet filter:
-
-**Setup Requirements**:
-
-- IAS and XSUAA service configurations ([
-  `OAuth2ServiceConfiguration`](java-api/src/main/java/com/sap/cloud/security/config/OAuth2ServiceConfiguration.java))
-- HTTP client for token exchange (`CloseableHttpClient` via [
-  `HttpClientFactory`](token-client/src/main/java/com/sap/cloud/security/client/HttpClientFactory.java))
-- Chosen [`TokenExchangeMode`](java-security/src/main/java/com/sap/cloud/security/token/TokenExchangeMode.java)
-
-**Configuration Example**:
-
-```java
-// 1. Load service configurations from environment
-// OAuth2ServiceConfiguration iasConfig = // obtain from environment bindings
-// OAuth2ServiceConfiguration xsuaaConfig = // obtain from environment bindings
-
-// 2. Create HTTP client for JWKS and token exchange
-CloseableHttpClient httpClient = HttpClientFactory.create(iasConfig.getClientIdentity());
-
-// 3. Choose token exchange mode
-TokenExchangeMode exchangeMode = TokenExchangeMode.FORCE_XSUAA;
-
-// 4. Create authenticator
-HybridTokenAuthenticator authenticator =
-        new HybridTokenAuthenticator(iasConfig, httpClient, xsuaaConfig, exchangeMode);
-
-// 5. Use in servlet filter
-public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
-        throws IOException, ServletException {
-
-    TokenAuthenticationResult result = authenticator.validateRequest(request, response);
+a servlet filter.
 
-    if (result.isAuthenticated()) {
-        // In FORCE_XSUAA mode: SecurityContext.getToken() returns XSUAA token
-        // In PROVIDE_XSUAA mode: SecurityContext.getToken() returns IAS token
-        //                       SecurityContext.getXsuaaToken() returns exchanged XSUAA token
-
-        chain.doFilter(request, response);
-    } else {
-        ((HttpServletResponse) response).sendError(HttpServletResponse.SC_UNAUTHORIZED);
-    }
-}
-```
-
-**Key Classes**:
-
-- [
-  `HybridTokenAuthenticator`](java-security/src/main/java/com/sap/cloud/security/servlet/HybridTokenAuthenticator.java) —
-  Main authenticator
-- [`SecurityContext`](java-api/src/main/java/com/sap/cloud/security/token/SecurityContext.java) — Access tokens and
-  certificates
-- [
-  `TokenAuthenticationResult`](java-security/src/main/java/com/sap/cloud/security/servlet/TokenAuthenticatorResult.java) —
-  Authentication result
+For more information, see the [HybridTokenAuthenticator Javadoc](java-security/README.md#hybridtokenauthenticator-usage).
 
 #### 2.4.2 Spring Boot Example: Using [`HybridJwtDecoder`](spring-security/src/main/java/com/sap/cloud/security/spring/token/authentication/HybridJwtDecoder.java)
 
 For Spring Boot applications, [
 `HybridIdentityServicesAutoConfiguration`](spring-security/src/main/java/com/sap/cloud/security/spring/autoconfig/HybridIdentityServicesAutoConfiguration.java)
 automatically configures hybrid authentication when both IAS and XSUAA bindings are detected.
 
-**Enable Token Exchange via Configuration**:
-
-```yaml
-# application.yml
-sap:
-  spring:
-    security:
-      hybrid:
-        token:
-          exchange:
-            mode: provide_xsuaa  # Options: disabled, provide_xsuaa, force_xsuaa (default: disabled)
-```
-
-**Spring Security Configuration**:
-
-```java
-
-@EnableWebSecurity
-public class SecurityConfig {
-
-    @Override
-    protected void configure(HttpSecurity http) throws Exception {
-        http.oauth2ResourceServer(oauth2 -> oauth2.jwt());
-        // Uses auto-configured HybridJwtDecoder
-    }
-}
-```
-
-**How It Works**:
-
-1. [
-   `HybridIdentityServicesAutoConfiguration`](spring-security/src/main/java/com/sap/cloud/security/spring/autoconfig/HybridIdentityServicesAutoConfiguration.java)
-   detects IAS + XSUAA bindings
-2. Creates [
-   `HybridJwtDecoder`](spring-security/src/main/java/com/sap/cloud/security/spring/token/authentication/HybridJwtDecoder.java)
-   bean with configured mode
-3. Registers [`IdTokenExtension`](java-api/src/main/java/com/sap/cloud/security/token/IdTokenExtension.java) and [
-   `XsuaaTokenExtension`](java-api/src/main/java/com/sap/cloud/security/token/XsuaaTokenExtension.java) in [
-   `SecurityContext`](java-api/src/main/java/com/sap/cloud/security/token/SecurityContext.java)
-4. Spring Security uses decoder for all JWT validation
-
-**Access Tokens in Application Code**:
-
-```java
-
-@RestController
-public class ApiController {
-
-    @GetMapping("/api/resource")
-    public String getResource(@AuthenticationPrincipal Jwt jwt) {
-        // In FORCE_XSUAA mode: jwt is XSUAA token
-        // In PROVIDE_XSUAA mode: jwt is IAS token
-
-        Token xsuaaToken = SecurityContext.getXsuaaToken(); // Always available if exchange enabled
-        List<String> scopes = xsuaaToken.getClaimAsStringList("scope");
-
-        return "Resource accessed";
-    }
-}
-```
-
-**Key Configuration Properties**:
-
-| Property                                         | Default    | Description                                                     |
-|--------------------------------------------------|------------|-----------------------------------------------------------------|
-| `sap.spring.security.hybrid.auto`                | `true`     | Enable/disable hybrid auto-configuration                        |
-| `sap.spring.security.hybrid.token.exchange.mode` | `disabled` | Token exchange mode: `disabled`, `provide_xsuaa`, `force_xsuaa` |
-
-**Key Classes**:
-
-- [
-  `HybridJwtDecoder`](spring-security/src/main/java/com/sap/cloud/security/spring/token/authentication/HybridJwtDecoder.java) —
-  JWT decoder with exchange logic
-- [
-  `HybridIdentityServicesAutoConfiguration`](spring-security/src/main/java/com/sap/cloud/security/spring/autoconfig/HybridIdentityServicesAutoConfiguration.java) —
-  Auto-configuration
-- [
-  `DefaultIdTokenExtension`](java-security/src/main/java/com/sap/cloud/security/token/DefaultIdTokenExtension.java) —
-  ID token resolution
-- [
-  `DefaultXsuaaTokenExtension`](token-client/src/main/java/com/sap/cloud/security/xsuaa/client/DefaultXsuaaTokenExtension.java) —
-  XSUAA token exchange
+For more information, see the [HybridJwtDecoder Javadoc](spring-security/README.md#token-exchange-configuration).
 
 #### Important Constraints
 
 **IAS User Tokens Only**: Token exchange only applies to end-user tokens from IAS. Client credentials tokens are **not**
 exchanged. Attempting exchange on technical tokens will result in errors.
 
-**Service Binding Configuration**:
-
-- Cloud Foundry: IAS binding must include `"xsuaa-cross-consumption": true`
-- Kubernetes/Kyma: Ensure XSUAA trusts IAS as identity provider
-
-**Failure Behavior**: Exchange failures result in 401 Unauthorized responses. There is no silent fallback to avoid
-security issues.
-
 **Performance**: Exchanged tokens are cached per request and reused until expiration. Caching is automatic and requires
 no configuration.
 
-#### Migration Strategy
-
-**Phase 1 - Enable Hybrid Auth**:
-
-```yaml
-mode: provide_xsuaa  # Keep XSUAA for authorization, start accepting IAS tokens
-```
-
-**Phase 2 - Gradual Migration**:
-
-- Migrate roles/authorization to IAS/Attribute Management Service
-- Access both tokens via `SecurityContext`
-- Begin using IAS token attributes for new features
-
-**Phase 3 - Complete Migration**:
-
-```yaml
-mode: disabled  # Remove exchange, operate solely with IAS
-```
-
-- Remove XSUAA binding
-- Use IAS tokens exclusively
-
 #### Troubleshooting
 
 Common issues and solutions:
 
 | Issue                             | Cause                                          | Solution                                         |
 |-----------------------------------|------------------------------------------------|--------------------------------------------------|
 | `Token exchange failed` exception | Missing XSUAA binding or invalid configuration | Verify both IAS and XSUAA service bindings exist |
-| Exchange returns 400              | IAS binding missing `xsuaa-cross-consumption`  | Add parameter to IAS service binding             |
-| Exchanged token has no scopes     | Role mappings not configured in XSUAA          | Configure role collections in XSUAA              |
-| Memory leak warnings              | `SecurityContext` not cleared after request    | Call `SecurityContext.clear()` in finally block  |
-
-**Enable Debug Logging**:
-
-```yaml
-logging:
-  level:
-    com.sap.cloud.security: DEBUG
-```
+| Exchange returns 401              | IAS binding missing `xsuaa-cross-consumption`  | Add parameter to IAS service binding             |
 
 ## Installation
 The SAP Cloud Security Services Integration is published to maven central: https://search.maven.org/search?q=com.sap.cloud.security and is available as a Maven dependency. Add the following BOM to your dependency management in your `pom.xml`:
diff --git a/java-security/README.md b/java-security/README.md
@@ -48,6 +48,7 @@ Since it requires the Tomcat 10 runtime, it needs to be deployed using the [SAP
     - [Maven Dependencies](#maven-dependencies)
 2. [Usage](#usage)
     - [TokenAuthenticator Usage](#tokenauthenticator-usage)
+      - [HybridTokenAuthenticator Usage](#hybridtokenauthenticator-usage)
     - [OAuth2ServiceServiceConfiguration Usage](#oauth2serviceserviceconfiguration-usage)
     - [JwtValidatorBuilder usage](#jwtvalidatorbuilder-usage)
     - [Token keys(JWKs) cache](#token-keys--jwks--cache)
@@ -79,11 +80,12 @@ Since it requires the Tomcat 10 runtime, it needs to be deployed using the [SAP
 ## Usage
 ### `TokenAuthenticator` usage
 The [`TokenAuthenticator`](/java-api/src/main/java/com/sap/cloud/security/servlet/TokenAuthenticator.java)  makes it easy to integrate token based authentication into your java application.
-The library provides 2 default implementations of `TokenAuthenticator` interface:
+The library provides 3 default implementations of `TokenAuthenticator` interface:
 - [XsuaaTokenAuthenticator](src/main/java/com/sap/cloud/security/servlet/XsuaaTokenAuthenticator.java) for Xsuaa Access token validation
 - [IasTokenAuthenticator](src/main/java/com/sap/cloud/security/servlet/IasTokenAuthenticator.java) for Identity OIDC token validation.
+- [HybridTokenAuthenticator](src/main/java/com/sap/cloud/security/servlet/HybridTokenAuthenticator.java) for Identity OIDC token validation with Xsuaa token exchange in hybrid environments.
 
-`XsuaaTokenAuthenticator` and `IasTokenAuthenticator` takes care of
+`XsuaaTokenAuthenticator`, `HybridTokenAuthenticator` and `IasTokenAuthenticator` takes care of
 * `OAuth2ServiceConfiguration` loading
 * `org.apache.http.HttpClient` initialization (it's required for signature validation)
 * Jwt Validator setup with help of [`JwtValidatorBuilder`](src/main/java/com/sap/cloud/security/token/validation/validators/JwtValidatorBuilder.java)
@@ -132,6 +134,50 @@ public class XsuaaSecurityFilter implements Filter {
 }
 ```
 
+#### `HybridTokenAuthenticator` usage
+
+The `HybridTokenAuthenticator` is designed for hybrid scenarios where an application needs to validate tokens issued by the Identity service (IAS) and exchange them for tokens issued by the XSUAA service. This is particularly useful when integrating applications that rely on both services for authentication and authorization.
+
+**Setup Requirements**:
+
+- IAS and XSUAA service configurations ([
+  `OAuth2ServiceConfiguration`](java-api/src/main/java/com/sap/cloud/security/config/OAuth2ServiceConfiguration.java))
+- HTTP client for token exchange (`CloseableHttpClient` via [
+  `HttpClientFactory`](token-client/src/main/java/com/sap/cloud/security/client/HttpClientFactory.java))
+- Chosen [`TokenExchangeMode`](java-security/src/main/java/com/sap/cloud/security/token/TokenExchangeMode.java)
+
+**Configuration Example**:
+
+```java
+// 1. Load service configurations from environment
+ OAuth2ServiceConfiguration iasConfig = Environment.getIasConfiguration();
+ OAuth2ServiceConfiguration xsuaaConfig = Environment.getXsuaaConfiguration();
+
+// 2. Choose token exchange mode
+TokenExchangeMode exchangeMode = TokenExchangeMode.FORCE_XSUAA;
+
+// 3. Create authenticator
+HybridTokenAuthenticator authenticator =
+        new HybridTokenAuthenticator(iasConfig, HttpClientFactory.create(iasConfig.getClientIdentity()), xsuaaConfig, exchangeMode);
+
+// 4. Use in servlet filter
+public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
+        throws IOException, ServletException {
+
+    TokenAuthenticationResult result = authenticator.validateRequest(request, response);
+
+    if (result.isAuthenticated()) {
+        // In FORCE_XSUAA mode: SecurityContext.getToken() returns XSUAA token
+        // In PROVIDE_XSUAA mode: SecurityContext.getToken() returns IAS token
+        //                       SecurityContext.getXsuaaToken() returns exchanged XSUAA token
+
+        chain.doFilter(request, response);
+    } else {
+        ((HttpServletResponse) response).sendError(HttpServletResponse.SC_UNAUTHORIZED);
+    }
+}
+```
+
 ### `OAuth2ServiceServiceConfiguration` usage
 Access the OAuth2 Service configuration bound to the application:
 * For Xsuaa Service
diff --git a/spring-security/README.md b/spring-security/README.md
