Article

In distributed systems and microservices architectures, tokens often need to be transformed, exchanged, or delegated. A service might need to act on behalf of a user when calling another service, or a client might need to exchange a token from one identity provider for a token from another. OAuth 2.0 Token Exchange (RFC 8693) provides a standardized mechanism for these scenarios, enabling secure token transformation and delegation. For Java developers, implementing token exchange is essential for building sophisticated identity and authorization flows.

What is Token Exchange (RFC 8693)?

Token Exchange is an OAuth 2.0 extension that allows a client to request a new security token based on an existing token. The specification defines:

1. Subject Token: The original token being exchanged
2. Actor Token: A token representing the acting party (for delegation)
3. Requested Token Type: The type of token desired (e.g., JWT, access token)
4. Resource: The target service or resource
5. Scope: The requested scope for the new token

Key Use Cases

┌──────────┐      ┌──────────┐      ┌──────────┐
│  User    │      │ Service A│      │ Service B│
└────┬─────┘      └────┬─────┘      └────┬─────┘
│                  │                  │
│ 1. User Token    │                  │
├─────────────────>│                  │
│                  │ 2. Token Exchange│
│                  │─────────────────>│
│                  │                  │
│                  │ 3. Service Token │
│                  │<─────────────────│
│                  │                  │
│ 4. Act on behalf │                  │
│                  ├─────────────────>│
│                  │                  │
│                  │ 5. Response      │
│                  │<─────────────────│
│                  │                  │

1. Delegation: Service acts on behalf of a user
2. Impersonation: One entity impersonates another
3. Token Translation: Convert between different token formats
4. Downstream Authentication: Propagate identity across service boundaries

Complete Token Exchange Implementation in Java

1. Dependencies and Setup

<dependencies>
<!-- Spring Security OAuth2 -->
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-oauth2-client</artifactId>
<version>6.1.5</version>
</dependency>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-oauth2-jose</artifactId>
<version>6.1.5</version>
</dependency>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-oauth2-resource-server</artifactId>
<version>6.1.5</version>
</dependency>
<!-- Nimbus JOSE + JWT -->
<dependency>
<groupId>com.nimbusds</groupId>
<artifactId>nimbus-jose-jwt</artifactId>
<version>9.37.3</version>
</dependency>
<!-- Web and REST -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<!-- For JSON processing -->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
</dependency>
<!-- For testing -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>

2. Token Exchange Request/Response Models

package com.example.tokenexchange.model;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.Map;
import java.util.Set;
/**
* Token Exchange Request (RFC 8693)
*/
public class TokenExchangeRequest {
@JsonProperty("grant_type")
private String grantType = "urn:ietf:params:oauth:grant-type:token-exchange";
@JsonProperty("subject_token")
private String subjectToken;
@JsonProperty("subject_token_type")
private String subjectTokenType;
@JsonProperty("actor_token")
private String actorToken;
@JsonProperty("actor_token_type")
private String actorTokenType;
@JsonProperty("resource")
private String resource;
@JsonProperty("audience")
private String audience;
@JsonProperty("scope")
private String scope;
@JsonProperty("requested_token_type")
private String requestedTokenType = "urn:ietf:params:oauth:token-type:access_token";
// Additional custom parameters
private Map<String, Object> additionalParameters;
// Constructors
public TokenExchangeRequest() {}
public TokenExchangeRequest(String subjectToken, String subjectTokenType) {
this.subjectToken = subjectToken;
this.subjectTokenType = subjectTokenType;
}
// Builder pattern
public static class Builder {
private TokenExchangeRequest request = new TokenExchangeRequest();
public Builder subjectToken(String subjectToken) {
request.subjectToken = subjectToken;
return this;
}
public Builder subjectTokenType(String subjectTokenType) {
request.subjectTokenType = subjectTokenType;
return this;
}
public Builder actorToken(String actorToken) {
request.actorToken = actorToken;
return this;
}
public Builder actorTokenType(String actorTokenType) {
request.actorTokenType = actorTokenType;
return this;
}
public Builder resource(String resource) {
request.resource = resource;
return this;
}
public Builder audience(String audience) {
request.audience = audience;
return this;
}
public Builder scope(String scope) {
request.scope = scope;
return this;
}
public Builder requestedTokenType(String requestedTokenType) {
request.requestedTokenType = requestedTokenType;
return this;
}
public Builder additionalParameters(Map<String, Object> params) {
request.additionalParameters = params;
return this;
}
public TokenExchangeRequest build() {
return request;
}
}
// Getters and setters
public String getGrantType() { return grantType; }
public void setGrantType(String grantType) { this.grantType = grantType; }
public String getSubjectToken() { return subjectToken; }
public void setSubjectToken(String subjectToken) { this.subjectToken = subjectToken; }
public String getSubjectTokenType() { return subjectTokenType; }
public void setSubjectTokenType(String subjectTokenType) { this.subjectTokenType = subjectTokenType; }
public String getActorToken() { return actorToken; }
public void setActorToken(String actorToken) { this.actorToken = actorToken; }
public String getActorTokenType() { return actorTokenType; }
public void setActorTokenType(String actorTokenType) { this.actorTokenType = actorTokenType; }
public String getResource() { return resource; }
public void setResource(String resource) { this.resource = resource; }
public String getAudience() { return audience; }
public void setAudience(String audience) { this.audience = audience; }
public String getScope() { return scope; }
public void setScope(String scope) { this.scope = scope; }
public String getRequestedTokenType() { return requestedTokenType; }
public void setRequestedTokenType(String requestedTokenType) { this.requestedTokenType = requestedTokenType; }
public Map<String, Object> getAdditionalParameters() { return additionalParameters; }
public void setAdditionalParameters(Map<String, Object> additionalParameters) {
this.additionalParameters = additionalParameters;
}
}
/**
* Token Exchange Response
*/
public class TokenExchangeResponse {
@JsonProperty("access_token")
private String accessToken;
@JsonProperty("issued_token_type")
private String issuedTokenType;
@JsonProperty("token_type")
private String tokenType = "Bearer";
@JsonProperty("expires_in")
private Long expiresIn;
@JsonProperty("scope")
private String scope;
@JsonProperty("refresh_token")
private String refreshToken;
private Map<String, Object> additionalParameters;
// Constructors
public TokenExchangeResponse() {}
public TokenExchangeResponse(String accessToken, String issuedTokenType, Long expiresIn) {
this.accessToken = accessToken;
this.issuedTokenType = issuedTokenType;
this.expiresIn = expiresIn;
}
// Builder pattern
public static class Builder {
private TokenExchangeResponse response = new TokenExchangeResponse();
public Builder accessToken(String accessToken) {
response.accessToken = accessToken;
return this;
}
public Builder issuedTokenType(String issuedTokenType) {
response.issuedTokenType = issuedTokenType;
return this;
}
public Builder tokenType(String tokenType) {
response.tokenType = tokenType;
return this;
}
public Builder expiresIn(Long expiresIn) {
response.expiresIn = expiresIn;
return this;
}
public Builder scope(String scope) {
response.scope = scope;
return this;
}
public Builder refreshToken(String refreshToken) {
response.refreshToken = refreshToken;
return this;
}
public Builder additionalParameters(Map<String, Object> params) {
response.additionalParameters = params;
return this;
}
public TokenExchangeResponse build() {
return response;
}
}
// Getters and setters
public String getAccessToken() { return accessToken; }
public void setAccessToken(String accessToken) { this.accessToken = accessToken; }
public String getIssuedTokenType() { return issuedTokenType; }
public void setIssuedTokenType(String issuedTokenType) { this.issuedTokenType = issuedTokenType; }
public String getTokenType() { return tokenType; }
public void setTokenType(String tokenType) { this.tokenType = tokenType; }
public Long getExpiresIn() { return expiresIn; }
public void setExpiresIn(Long expiresIn) { this.expiresIn = expiresIn; }
public String getScope() { return scope; }
public void setScope(String scope) { this.scope = scope; }
public String getRefreshToken() { return refreshToken; }
public void setRefreshToken(String refreshToken) { this.refreshToken = refreshToken; }
public Map<String, Object> getAdditionalParameters() { return additionalParameters; }
public void setAdditionalParameters(Map<String, Object> additionalParameters) {
this.additionalParameters = additionalParameters;
}
}

3. Token Exchange Service

package com.example.tokenexchange.service;
import com.example.tokenexchange.model.TokenExchangeRequest;
import com.example.tokenexchange.model.TokenExchangeResponse;
import com.nimbusds.jose.JWSVerifier;
import com.nimbusds.jose.crypto.RSASSAVerifier;
import com.nimbusds.jwt.SignedJWT;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import java.security.interfaces.RSAPublicKey;
import java.time.Instant;
import java.util.*;
/**
* Token Exchange Service implementing RFC 8693
*/
@Service
public class TokenExchangeService {
private static final Logger logger = LoggerFactory.getLogger(TokenExchangeService.class);
// Token type URNs
public static final String TOKEN_TYPE_ACCESS_TOKEN = 
"urn:ietf:params:oauth:token-type:access_token";
public static final String TOKEN_TYPE_REFRESH_TOKEN = 
"urn:ietf:params:oauth:token-type:refresh_token";
public static final String TOKEN_TYPE_ID_TOKEN = 
"urn:ietf:params:oauth:token-type:id_token";
public static final String TOKEN_TYPE_SAML1 = 
"urn:ietf:params:oauth:token-type:saml1";
public static final String TOKEN_TYPE_SAML2 = 
"urn:ietf:params:oauth:token-type:saml2";
public static final String TOKEN_TYPE_JWT = 
"urn:ietf:params:oauth:token-type:jwt";
@Value("${token-exchange.default-ttl:3600}")
private long defaultTtl;
@Value("${token-exchange.issuer:https://token-exchange.example.com}")
private String issuer;
private final TokenValidator tokenValidator;
private final TokenGenerator tokenGenerator;
private final TokenPolicyEnforcer policyEnforcer;
public TokenExchangeService(TokenValidator tokenValidator,
TokenGenerator tokenGenerator,
TokenPolicyEnforcer policyEnforcer) {
this.tokenValidator = tokenValidator;
this.tokenGenerator = tokenGenerator;
this.policyEnforcer = policyEnforcer;
}
/**
* Exchange a token according to RFC 8693
*/
public TokenExchangeResponse exchangeToken(TokenExchangeRequest request) {
logger.info("Processing token exchange request");
// 1. Validate grant type
validateGrantType(request);
// 2. Validate subject token
TokenValidationResult subjectValidation = validateSubjectToken(request);
// 3. Validate actor token if present (delegation)
TokenValidationResult actorValidation = validateActorToken(request);
// 4. Apply policy enforcement
TokenExchangeContext context = new TokenExchangeContext(
request, subjectValidation, actorValidation);
policyEnforcer.enforcePolicies(context);
// 5. Generate new token
String newToken = generateExchangedToken(context);
// 6. Build response
return buildResponse(newToken, request);
}
private void validateGrantType(TokenExchangeRequest request) {
String expectedGrantType = "urn:ietf:params:oauth:grant-type:token-exchange";
if (!expectedGrantType.equals(request.getGrantType())) {
throw new TokenExchangeException(
"Invalid grant_type. Expected: " + expectedGrantType);
}
}
private TokenValidationResult validateSubjectToken(TokenExchangeRequest request) {
if (request.getSubjectToken() == null || request.getSubjectToken().isEmpty()) {
throw new TokenExchangeException("subject_token is required");
}
if (request.getSubjectTokenType() == null) {
throw new TokenExchangeException("subject_token_type is required");
}
return tokenValidator.validateToken(
request.getSubjectToken(),
request.getSubjectTokenType()
);
}
private TokenValidationResult validateActorToken(TokenExchangeRequest request) {
if (request.getActorToken() != null) {
if (request.getActorTokenType() == null) {
throw new TokenExchangeException(
"actor_token_type is required when actor_token is present");
}
return tokenValidator.validateToken(
request.getActorToken(),
request.getActorTokenType()
);
}
return null;
}
private String generateExchangedToken(TokenExchangeContext context) {
// Determine token type based on requested_token_type or default
String requestedType = context.getRequest().getRequestedTokenType();
if (requestedType == null) {
requestedType = TOKEN_TYPE_ACCESS_TOKEN;
}
// Build claims for new token
Map<String, Object> claims = new HashMap<>();
// Subject from original token
claims.put("sub", context.getSubjectValidation().getSubject());
// Actor if present (delegation)
if (context.getActorValidation() != null) {
claims.put("act", Map.of(
"sub", context.getActorValidation().getSubject(),
"token_type", context.getRequest().getActorTokenType()
));
}
// Issuer
claims.put("iss", issuer);
// Issued at
claims.put("iat", Instant.now().getEpochSecond());
// Expiration
long expiry = Instant.now().getEpochSecond() + defaultTtl;
claims.put("exp", expiry);
// Audience
if (context.getRequest().getAudience() != null) {
claims.put("aud", context.getRequest().getAudience());
}
// Scope
if (context.getRequest().getScope() != null) {
claims.put("scope", context.getRequest().getScope());
}
// Resource
if (context.getRequest().getResource() != null) {
claims.put("resource", context.getRequest().getResource());
}
// Add original token context
claims.put("original_token_type", context.getRequest().getSubjectTokenType());
claims.put("exchange_time", Instant.now().toString());
// Generate token based on requested type
return tokenGenerator.generateToken(claims, requestedType);
}
private TokenExchangeResponse buildResponse(String newToken, TokenExchangeRequest request) {
TokenExchangeResponse response = new TokenExchangeResponse();
response.setAccessToken(newToken);
response.setIssuedTokenType(
request.getRequestedTokenType() != null ? 
request.getRequestedTokenType() : 
TOKEN_TYPE_ACCESS_TOKEN
);
response.setTokenType("Bearer");
response.setExpiresIn(defaultTtl);
if (request.getScope() != null) {
response.setScope(request.getScope());
}
return response;
}
// Exception class
public static class TokenExchangeException extends RuntimeException {
public TokenExchangeException(String message) {
super(message);
}
public TokenExchangeException(String message, Throwable cause) {
super(message, cause);
}
}
// Context class for exchange processing
public static class TokenExchangeContext {
private final TokenExchangeRequest request;
private final TokenValidationResult subjectValidation;
private final TokenValidationResult actorValidation;
public TokenExchangeContext(TokenExchangeRequest request,
TokenValidationResult subjectValidation,
TokenValidationResult actorValidation) {
this.request = request;
this.subjectValidation = subjectValidation;
this.actorValidation = actorValidation;
}
public TokenExchangeRequest getRequest() { return request; }
public TokenValidationResult getSubjectValidation() { return subjectValidation; }
public TokenValidationResult getActorValidation() { return actorValidation; }
}
}

4. Token Validator Implementation

package com.example.tokenexchange.service;
import com.nimbusds.jose.JWSVerifier;
import com.nimbusds.jose.crypto.RSASSAVerifier;
import com.nimbusds.jwt.SignedJWT;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
import java.security.KeyFactory;
import java.security.interfaces.RSAPublicKey;
import java.security.spec.X509EncodedKeySpec;
import java.time.Instant;
import java.util.Base64;
import java.util.Date;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
/**
* Token validation service
*/
@Component
public class TokenValidator {
@Value("${token-exchange.jwks-url:https://auth.example.com/.well-known/jwks.json}")
private String jwksUrl;
private final Map<String, RSAPublicKey> publicKeyCache = new ConcurrentHashMap<>();
/**
* Validate a token and return validation result
*/
public TokenValidationResult validateToken(String token, String tokenType) {
try {
// Parse token based on type
if (tokenType.startsWith("urn:ietf:params:oauth:token-type:jwt") ||
tokenType.equals(TokenExchangeService.TOKEN_TYPE_ACCESS_TOKEN)) {
return validateJWT(token);
} else {
throw new TokenExchangeService.TokenExchangeException(
"Unsupported token type: " + tokenType);
}
} catch (Exception e) {
throw new TokenExchangeService.TokenExchangeException(
"Token validation failed: " + e.getMessage(), e);
}
}
private TokenValidationResult validateJWT(String jwtString) throws Exception {
SignedJWT signedJWT = SignedJWT.parse(jwtString);
// Get key ID from header
String keyId = signedJWT.getHeader().getKeyID();
if (keyId == null) {
throw new TokenExchangeService.TokenExchangeException("No key ID in token header");
}
// Get public key
RSAPublicKey publicKey = getPublicKey(keyId);
// Verify signature
JWSVerifier verifier = new RSASSAVerifier(publicKey);
if (!signedJWT.verify(verifier)) {
throw new TokenExchangeService.TokenExchangeException("Invalid signature");
}
// Get claims
var claims = signedJWT.getJWTClaimsSet();
// Check expiration
Date expiration = claims.getExpirationTime();
if (expiration != null && expiration.before(Date.from(Instant.now()))) {
throw new TokenExchangeService.TokenExchangeException("Token expired");
}
// Check not before
Date notBefore = claims.getNotBeforeTime();
if (notBefore != null && notBefore.after(Date.from(Instant.now()))) {
throw new TokenExchangeService.TokenExchangeException("Token not yet valid");
}
// Build validation result
TokenValidationResult result = new TokenValidationResult();
result.setSubject(claims.getSubject());
result.setIssuer(claims.getIssuer());
result.setAudience(claims.getAudience() != null ? 
String.join(",", claims.getAudience()) : null);
result.setExpirationTime(expiration);
result.setNotBeforeTime(notBefore);
result.setIssueTime(claims.getIssueTime());
result.setClaims(claims.getClaims());
result.setValid(true);
return result;
}
private RSAPublicKey getPublicKey(String keyId) {
// In production, fetch from JWKS endpoint
// This is a simplified example
return publicKeyCache.computeIfAbsent(keyId, k -> {
try {
// In real implementation, fetch from JWKS
// For demo, return a placeholder
return loadPublicKeyFromString(keyId);
} catch (Exception e) {
throw new TokenExchangeService.TokenExchangeException(
"Failed to load public key: " + keyId, e);
}
});
}
private RSAPublicKey loadPublicKeyFromString(String keyId) throws Exception {
// This would load from keystore or JWKS
// Simplified for example
byte[] keyBytes = Base64.getDecoder().decode(
"MIIBCgKCAQEA..." // Your public key here
);
X509EncodedKeySpec spec = new X509EncodedKeySpec(keyBytes);
KeyFactory kf = KeyFactory.getInstance("RSA");
return (RSAPublicKey) kf.generatePublic(spec);
}
}
/**
* Token validation result
*/
class TokenValidationResult {
private String subject;
private String issuer;
private String audience;
private Date expirationTime;
private Date notBeforeTime;
private Date issueTime;
private Map<String, Object> claims;
private boolean valid;
// Getters and setters
public String getSubject() { return subject; }
public void setSubject(String subject) { this.subject = subject; }
public String getIssuer() { return issuer; }
public void setIssuer(String issuer) { this.issuer = issuer; }
public String getAudience() { return audience; }
public void setAudience(String audience) { this.audience = audience; }
public Date getExpirationTime() { return expirationTime; }
public void setExpirationTime(Date expirationTime) { this.expirationTime = expirationTime; }
public Date getNotBeforeTime() { return notBeforeTime; }
public void setNotBeforeTime(Date notBeforeTime) { this.notBeforeTime = notBeforeTime; }
public Date getIssueTime() { return issueTime; }
public void setIssueTime(Date issueTime) { this.issueTime = issueTime; }
public Map<String, Object> getClaims() { return claims; }
public void setClaims(Map<String, Object> claims) { this.claims = claims; }
public boolean isValid() { return valid; }
public void setValid(boolean valid) { this.valid = valid; }
}

5. Token Generator Implementation

package com.example.tokenexchange.service;
import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.RSASSASigner;
import com.nimbusds.jose.jwk.RSAKey;
import com.nimbusds.jose.jwk.gen.RSAKeyGenerator;
import com.nimbusds.jwt.JWTClaimsSet;
import com.nimbusds.jwt.SignedJWT;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
import java.time.Instant;
import java.util.Date;
import java.util.Map;
import java.util.UUID;
/**
* Token generator for exchange responses
*/
@Component
public class TokenGenerator {
private final RSAKey signingKey;
private final JWSSigner signer;
@Value("${token-exchange.issuer}")
private String issuer;
public TokenGenerator() throws JOSEException {
// Generate signing key (in production, load from keystore)
this.signingKey = new RSAKeyGenerator(2048)
.keyID(UUID.randomUUID().toString())
.generate();
this.signer = new RSASSASigner(signingKey);
}
/**
* Generate a token based on requested type
*/
public String generateToken(Map<String, Object> claims, String tokenType) {
if (tokenType.equals(TokenExchangeService.TOKEN_TYPE_ACCESS_TOKEN) ||
tokenType.equals(TokenExchangeService.TOKEN_TYPE_JWT)) {
return generateJWT(claims);
} else {
throw new TokenExchangeService.TokenExchangeException(
"Cannot generate token type: " + tokenType);
}
}
private String generateJWT(Map<String, Object> claims) {
try {
// Build JWT claims set
JWTClaimsSet.Builder claimsBuilder = new JWTClaimsSet.Builder();
claims.forEach((key, value) -> {
if (value instanceof String) {
claimsBuilder.claim(key, (String) value);
} else if (value instanceof Long) {
claimsBuilder.claim(key, (Long) value);
} else if (value instanceof Date) {
claimsBuilder.claim(key, (Date) value);
} else {
claimsBuilder.claim(key, value);
}
});
// Add standard claims if missing
if (!claims.containsKey("jti")) {
claimsBuilder.jwtID(UUID.randomUUID().toString());
}
if (!claims.containsKey("iat")) {
claimsBuilder.issueTime(Date.from(Instant.now()));
}
if (!claims.containsKey("exp")) {
claimsBuilder.expirationTime(
Date.from(Instant.now().plusSeconds(3600)));
}
if (!claims.containsKey("iss") && issuer != null) {
claimsBuilder.issuer(issuer);
}
JWTClaimsSet claimsSet = claimsBuilder.build();
// Create JWS header
JWSHeader header = new JWSHeader.Builder(JWSAlgorithm.RS256)
.keyID(signingKey.getKeyID())
.type(JOSEObjectType.JWT)
.build();
// Sign JWT
SignedJWT signedJWT = new SignedJWT(header, claimsSet);
signedJWT.sign(signer);
return signedJWT.serialize();
} catch (JOSEException e) {
throw new TokenExchangeService.TokenExchangeException(
"Failed to generate token", e);
}
}
/**
* Get the public JWK for token verification
*/
public RSAKey getPublicKey() {
return signingKey.toPublicJWK();
}
}

6. Policy Enforcer Implementation

package com.example.tokenexchange.service;
import org.springframework.stereotype.Component;
import java.util.ArrayList;
import java.util.List;
import java.util.function.Consumer;
/**
* Policy enforcement for token exchange
*/
@Component
public class TokenPolicyEnforcer {
private final List<TokenExchangePolicy> policies = new ArrayList<>();
public TokenPolicyEnforcer() {
// Register default policies
registerDefaultPolicies();
}
private void registerDefaultPolicies() {
// Policy 1: Subject token must be valid
addPolicy(context -> {
if (!context.getSubjectValidation().isValid()) {
throw new TokenExchangeService.TokenExchangeException(
"Subject token is invalid");
}
});
// Policy 2: Check expiration
addPolicy(context -> {
var exp = context.getSubjectValidation().getExpirationTime();
if (exp != null && exp.before(new java.util.Date())) {
throw new TokenExchangeService.TokenExchangeException(
"Subject token has expired");
}
});
// Policy 3: Delegation constraints
addPolicy(context -> {
if (context.getActorValidation() != null) {
// Check if delegation is allowed
var claims = context.getSubjectValidation().getClaims();
if (claims.containsKey("delegation") && 
!Boolean.TRUE.equals(claims.get("delegation"))) {
throw new TokenExchangeService.TokenExchangeException(
"Delegation not allowed for this token");
}
}
});
// Policy 4: Audience constraints
addPolicy(context -> {
String requestedAudience = context.getRequest().getAudience();
if (requestedAudience != null) {
var claims = context.getSubjectValidation().getClaims();
if (claims.containsKey("aud")) {
// Check if requested audience is allowed
// This is simplified - actual implementation would check
// against allowed audiences for the token
}
}
});
// Policy 5: Scope constraints
addPolicy(context -> {
String requestedScope = context.getRequest().getScope();
if (requestedScope != null) {
var claims = context.getSubjectValidation().getClaims();
if (claims.containsKey("scope")) {
String tokenScope = (String) claims.get("scope");
// Check if requested scope is subset of token scope
// This is simplified - actual implementation would do proper scope validation
}
}
});
}
/**
* Add a custom policy
*/
public void addPolicy(TokenExchangePolicy policy) {
policies.add(policy);
}
/**
* Enforce all policies for a token exchange context
*/
public void enforcePolicies(TokenExchangeService.TokenExchangeContext context) {
policies.forEach(policy -> policy.enforce(context));
}
/**
* Policy interface
*/
@FunctionalInterface
public interface TokenExchangePolicy {
void enforce(TokenExchangeService.TokenExchangeContext context);
}
}

7. REST Controller for Token Exchange

package com.example.tokenexchange.controller;
import com.example.tokenexchange.model.TokenExchangeRequest;
import com.example.tokenexchange.model.TokenExchangeResponse;
import com.example.tokenexchange.service.TokenExchangeService;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.*;
import java.util.Map;
/**
* REST controller for token exchange endpoint
*/
@RestController
@RequestMapping("/oauth2")
public class TokenExchangeController {
private static final Logger logger = LoggerFactory.getLogger(TokenExchangeController.class);
private final TokenExchangeService tokenExchangeService;
public TokenExchangeController(TokenExchangeService tokenExchangeService) {
this.tokenExchangeService = tokenExchangeService;
}
/**
* Token Exchange endpoint (RFC 8693)
*/
@PostMapping("/token")
public ResponseEntity<?> exchangeToken(@RequestBody TokenExchangeRequest request) {
logger.info("Received token exchange request");
try {
TokenExchangeResponse response = tokenExchangeService.exchangeToken(request);
return ResponseEntity.ok(response);
} catch (TokenExchangeService.TokenExchangeException e) {
logger.error("Token exchange failed: {}", e.getMessage());
return ResponseEntity
.status(HttpStatus.BAD_REQUEST)
.body(Map.of(
"error", "invalid_request",
"error_description", e.getMessage()
));
} catch (Exception e) {
logger.error("Unexpected error during token exchange", e);
return ResponseEntity
.status(HttpStatus.INTERNAL_SERVER_ERROR)
.body(Map.of(
"error", "server_error",
"error_description", "An unexpected error occurred"
));
}
}
/**
* Health check endpoint
*/
@GetMapping("/token/health")
public ResponseEntity<Map<String, String>> health() {
return ResponseEntity.ok(Map.of(
"status", "up",
"service", "token-exchange",
"rfc", "8693"
));
}
/**
* Error handler for unsupported grant types
*/
@ExceptionHandler(UnsupportedOperationException.class)
public ResponseEntity<Map<String, String>> handleUnsupportedGrantType(
UnsupportedOperationException e) {
return ResponseEntity
.status(HttpStatus.BAD_REQUEST)
.body(Map.of(
"error", "unsupported_grant_type",
"error_description", e.getMessage()
));
}
}

8. Client Implementation for Token Exchange

package com.example.tokenexchange.client;
import com.example.tokenexchange.model.TokenExchangeRequest;
import com.example.tokenexchange.model.TokenExchangeResponse;
import org.springframework.http.*;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
/**
* Client for performing token exchange
*/
@Component
public class TokenExchangeClient {
private final RestTemplate restTemplate;
private final String tokenExchangeUrl;
public TokenExchangeClient(
RestTemplate restTemplate,
@Value("${token-exchange.url:http://localhost:8080/oauth2/token}") 
String tokenExchangeUrl) {
this.restTemplate = restTemplate;
this.tokenExchangeUrl = tokenExchangeUrl;
}
/**
* Exchange a token for a new token
*/
public TokenExchangeResponse exchangeToken(
String subjectToken,
String subjectTokenType,
String requestedTokenType,
String audience,
String scope) {
TokenExchangeRequest request = new TokenExchangeRequest.Builder()
.subjectToken(subjectToken)
.subjectTokenType(subjectTokenType)
.requestedTokenType(requestedTokenType)
.audience(audience)
.scope(scope)
.build();
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
HttpEntity<TokenExchangeRequest> entity = new HttpEntity<>(request, headers);
ResponseEntity<TokenExchangeResponse> response = restTemplate.exchange(
tokenExchangeUrl,
HttpMethod.POST,
entity,
TokenExchangeResponse.class
);
if (!response.getStatusCode().is2xxSuccessful()) {
throw new RuntimeException("Token exchange failed: " + response.getStatusCode());
}
return response.getBody();
}
/**
* Exchange a JWT for a new access token with specific audience
*/
public String exchangeForAudience(String jwt, String audience) {
TokenExchangeResponse response = exchangeToken(
jwt,
TokenExchangeService.TOKEN_TYPE_JWT,
TokenExchangeService.TOKEN_TYPE_ACCESS_TOKEN,
audience,
null
);
return response.getAccessToken();
}
/**
* Delegate token (act on behalf)
*/
public String delegateToken(String userToken, String actorToken) {
TokenExchangeRequest request = new TokenExchangeRequest.Builder()
.subjectToken(userToken)
.subjectTokenType(TokenExchangeService.TOKEN_TYPE_JWT)
.actorToken(actorToken)
.actorTokenType(TokenExchangeService.TOKEN_TYPE_JWT)
.build();
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
HttpEntity<TokenExchangeRequest> entity = new HttpEntity<>(request, headers);
ResponseEntity<TokenExchangeResponse> response = restTemplate.exchange(
tokenExchangeUrl,
HttpMethod.POST,
entity,
TokenExchangeResponse.class
);
return response.getBody().getAccessToken();
}
}

9. Security Configuration

package com.example.tokenexchange.config;
import com.example.tokenexchange.service.TokenGenerator;
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jose.jwk.RSAKey;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.web.SecurityFilterChain;
/**
* Security configuration for token exchange service
*/
@Configuration
@EnableWebSecurity
public class SecurityConfig {
private final TokenGenerator tokenGenerator;
public SecurityConfig(TokenGenerator tokenGenerator) {
this.tokenGenerator = tokenGenerator;
}
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(authz -> authz
.requestMatchers("/oauth2/token").permitAll()
.requestMatchers("/oauth2/token/health").permitAll()
.requestMatchers("/.well-known/jwks.json").permitAll()
.anyRequest().authenticated()
)
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(Customizer.withDefaults())
)
.sessionManagement(session -> session
.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
)
.csrf(csrf -> csrf.disable());
return http.build();
}
@Bean
public JwtDecoder jwtDecoder() {
RSAKey publicKey = tokenGenerator.getPublicKey();
return NimbusJwtDecoder.withPublicKey(publicKey.toRSAPublicKey()).build();
}
@Bean
public JWKSet jwkSet() {
return new JWKSet(tokenGenerator.getPublicKey());
}
}

10. Application Configuration

# application.yml
server:
port: 8080
spring:
application:
name: token-exchange-service
token-exchange:
issuer: https://token-exchange.example.com
default-ttl: 3600
jwks-url: https://auth.example.com/.well-known/jwks.json
allowed-token-types:
- urn:ietf:params:oauth:token-type:access_token
- urn:ietf:params:oauth:token-type:jwt
- urn:ietf:params:oauth:token-type:id_token
logging:
level:
com.example.tokenexchange: DEBUG
org.springframework.security: INFO

11. Testing the Token Exchange

package com.example.tokenexchange;
import com.example.tokenexchange.model.TokenExchangeRequest;
import com.example.tokenexchange.model.TokenExchangeResponse;
import com.example.tokenexchange.service.TokenExchangeService;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.http.*;
import static org.assertj.core.api.Assertions.assertThat;
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class TokenExchangeIntegrationTest {
@Autowired
private TestRestTemplate restTemplate;
@Test
public void testTokenExchange() {
// Create token exchange request
TokenExchangeRequest request = new TokenExchangeRequest.Builder()
.subjectToken("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...") // Valid JWT
.subjectTokenType(TokenExchangeService.TOKEN_TYPE_JWT)
.requestedTokenType(TokenExchangeService.TOKEN_TYPE_ACCESS_TOKEN)
.audience("https://api.example.com")
.scope("read write")
.build();
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
HttpEntity<TokenExchangeRequest> entity = new HttpEntity<>(request, headers);
// Perform exchange
ResponseEntity<TokenExchangeResponse> response = restTemplate.postForEntity(
"/oauth2/token",
entity,
TokenExchangeResponse.class
);
assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
assertThat(response.getBody()).isNotNull();
assertThat(response.getBody().getAccessToken()).isNotBlank();
assertThat(response.getBody().getExpiresIn()).isGreaterThan(0);
assertThat(response.getBody().getIssuedTokenType())
.isEqualTo(TokenExchangeService.TOKEN_TYPE_ACCESS_TOKEN);
}
@Test
public void testInvalidTokenShouldFail() {
TokenExchangeRequest request = new TokenExchangeRequest.Builder()
.subjectToken("invalid.token.format")
.subjectTokenType(TokenExchangeService.TOKEN_TYPE_JWT)
.build();
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
HttpEntity<TokenExchangeRequest> entity = new HttpEntity<>(request, headers);
ResponseEntity<Object> response = restTemplate.postForEntity(
"/oauth2/token",
entity,
Object.class
);
assertThat(response.getStatusCode()).isEqualTo(HttpStatus.BAD_REQUEST);
}
}

Token Exchange Flow Examples

1. Basic Token Exchange

POST /oauth2/token HTTP/1.1
Host: token-exchange.example.com
Content-Type: application/json
{
"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
"subject_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
"audience": "https://api.example.com",
"scope": "read write"
}

2. Delegation (Act on Behalf)

POST /oauth2/token HTTP/1.1
Host: token-exchange.example.com
Content-Type: application/json
{
"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
"subject_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
"actor_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"actor_token_type": "urn:ietf:params:oauth:token-type:access_token",
"audience": "https://downstream.example.com"
}

3. Successful Response

HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read write"
}

Security Considerations

Conclusion

Token Exchange (RFC 8693) provides a powerful, standardized mechanism for token transformation and delegation in OAuth 2.0 ecosystems. The Java implementation presented here demonstrates:

1. Complete RFC compliance with proper request/response handling
2. Flexible token validation supporting multiple token types
3. Delegation support for acting on behalf of users or services
4. Policy enforcement for security and business rules
5. Spring integration for production-ready services

For Java developers building microservices, API gateways, or identity platforms, token exchange is an essential capability. It enables sophisticated identity flows while maintaining security and standards compliance. The implementation provided serves as a solid foundation that can be extended with additional features like:

• Integration with external identity providers
• Caching of exchanged tokens
• Advanced policy engines
• Monitoring and metrics
• Support for additional token formats (SAML, etc.)

As distributed systems become more complex, the ability to securely transform and delegate identity becomes increasingly critical. Token exchange provides the standardized foundation for these patterns, and Java's rich ecosystem makes implementation straightforward and robust.

Java Programming Intermediate Topics – Modifiers, Loops, Math, Methods & Projects (Related to Java Programming)

Access Modifiers in Java:
Access modifiers control how classes, variables, and methods are accessed from different parts of a program. Java provides four main access levels—public, private, protected, and default—which help protect data and control visibility in object-oriented programming.
Read more: https://macronepal.com/blog/access-modifiers-in-java-a-complete-guide/

Static Variables in Java:
Static variables belong to the class rather than individual objects. They are shared among all instances of the class and are useful for storing values that remain common across multiple objects.
Read more: https://macronepal.com/blog/static-variables-in-java-a-complete-guide/

Method Parameters in Java:
Method parameters allow values to be passed into methods so that operations can be performed using supplied data. They help make methods flexible and reusable in different parts of a program.
Read more: https://macronepal.com/blog/method-parameters-in-java-a-complete-guide/

Random Numbers in Java:
This topic explains how to generate random numbers in Java for tasks such as simulations, games, and random selections. Random numbers help create unpredictable results in programs.
Read more: https://macronepal.com/blog/random-numbers-in-java-a-complete-guide/

Math Class in Java:
The Math class provides built-in methods for performing mathematical calculations such as powers, square roots, rounding, and other advanced calculations used in Java programs.
Read more: https://macronepal.com/blog/math-class-in-java-a-complete-guide/

Boolean Operations in Java:
Boolean operations use true and false values to perform logical comparisons. They are commonly used in conditions and decision-making statements to control program flow.
Read more: https://macronepal.com/blog/boolean-operations-in-java-a-complete-guide/

Nested Loops in Java:
Nested loops are loops placed inside other loops to perform repeated operations within repeated tasks. They are useful for pattern printing, tables, and working with multi-level data.
Read more: https://macronepal.com/blog/nested-loops-in-java-a-complete-guide/

Do-While Loop in Java:
The do-while loop allows a block of code to run at least once before checking the condition. It is useful when the program must execute a task before verifying whether it should continue.
Read more: https://macronepal.com/blog/do-while-loop-in-java-a-complete-guide/

Simple Calculator Project in Java:
This project demonstrates how to create a basic calculator program using Java. It combines input handling, arithmetic operations, and conditional logic to perform simple mathematical calculations.
Read more: https://macronepal.com/blog/simple-calculator-project-in-java/