Skip to content

usage-guide.adoc

Latest commit

 

History

History
118 lines (98 loc) · 3.58 KB

usage-guide.adoc

File metadata and controls

118 lines (98 loc) · 3.58 KB
Raw

Token-Sheriff Core Usage Guide

Table of Contents

1. Basic Token Validation

TokenValidator tokenValidator = TokenValidator.builder()
    .issuerConfig(IssuerConfig.builder()
        .issuerIdentifier("https://example.com")
        .jwksContent(jwksJsonString)
        .build())
    .build();

try {
    AccessTokenContent token = tokenValidator.createAccessToken(AccessTokenRequest.of(jwtString));
    Optional<String> subject = token.getSubject();
    List<String> roles = token.getRoles();
} catch (TokenValidationException e) {
    LOGGER.error(e, "Token validation failed: %s", e.getMessage());
}

2. Access Token Caching

AccessTokenCacheConfig cacheConfig = AccessTokenCacheConfig.builder()
    .maxSize(1000)
    .evictionIntervalSeconds(300L)
    .build();

TokenValidator tokenValidator = TokenValidator.builder()
    .cacheConfig(cacheConfig)
    .issuerConfig(issuerConfig)
    .build();

// Subsequent validations of the same token are served from cache
AccessTokenContent token1 = tokenValidator.createAccessToken(AccessTokenRequest.of(jwtString));
AccessTokenContent token2 = tokenValidator.createAccessToken(AccessTokenRequest.of(jwtString)); // From cache

3. Multi-Issuer Configuration

TokenValidator tokenValidator = TokenValidator.builder()
    .issuerConfig(IssuerConfig.builder()
        .issuerIdentifier("https://keycloak.example.com/auth/realms/main")
        .httpJwksLoaderConfig(HttpJwksLoaderConfig.builder()
            .issuerIdentifier("https://keycloak.example.com/auth/realms/main")
            .jwksUrl("https://keycloak.example.com/auth/realms/main/protocol/openid-connect/certs")
            .build())
        .build())
    .issuerConfig(IssuerConfig.builder()
        .issuerIdentifier("https://auth0.example.com/")
        .httpJwksLoaderConfig(HttpJwksLoaderConfig.builder()
            .issuerIdentifier("https://auth0.example.com/")
            .jwksUrl("https://auth0.example.com/.well-known/jwks.json")
            .build())
        .build())
    .build();

// Validator automatically selects correct issuer based on token
AccessTokenContent token = tokenValidator.createAccessToken(AccessTokenRequest.of(jwtString));

4. OpenID Connect Discovery

IssuerConfig issuerConfig = IssuerConfig.builder()
    .httpJwksLoaderConfig(HttpJwksLoaderConfig.builder()
        .wellKnownUrl("https://accounts.google.com/.well-known/openid-configuration")
        .build())
    .expectedAudience("your-google-client-id")
    .build();

4.1. Configuring TokenValidator

TokenValidator tokenValidator = TokenValidator.builder()
    .issuerConfig(issuerConfig)
    .parserConfig(ParserConfig.builder()
        .maxTokenSize(16384)
        .maxPayloadSize(8192)
        .build())
    .build();

5. Custom Claim Mapping

IssuerConfig issuerConfig = IssuerConfig.builder()
    .issuerIdentifier("https://example.com")
    .jwksContent(jwksJsonString)
    .claimMapper("roles", customRolesMapper)   // Custom mapper for nested roles
    .claimMapper("groups", customGroupsMapper) // Custom mapper for groups
    .build();

TokenValidator validator = TokenValidator.builder()
    .issuerConfig(issuerConfig)
    .build();

AccessTokenContent token = validator.createAccessToken(AccessTokenRequest.of(jwtString));
List<String> roles = token.getRoles();   // From custom roles mapper
List<String> groups = token.getGroups(); // From custom groups mapper

For more examples, see the API Reference.