api-reference.adoc

Token-Sheriff Core API Reference

Table of Contents

• 1. Core Classes
  • 1.1. TokenValidator
  • 1.2. AccessTokenContent
  • 1.3. IssuerConfig
• 2. Configuration Classes
  • 2.1. ParserConfig
  • 2.2. AccessTokenCacheConfig
  • 2.3. HttpJwksLoaderConfig
• 3. Claim Mappers
  • 3.1. JsonCollectionMapper
  • 3.2. StringSplitterMapper
  • 3.3. Custom ClaimMapper
• 4. Error Handling
  • 4.1. TokenValidationException
• 5. Security Configuration

1. Core Classes

1.1. TokenValidator

The main entry point for token validation.

public class TokenValidator implements Closeable {
    public static TokenValidatorBuilder builder() { ... }

    public AccessTokenContent createAccessToken(AccessTokenRequest request);
    public IdTokenContent createIdToken(IdTokenRequest request);
    public UnvalidatedRefreshToken createRefreshToken(RefreshTokenRequest request);

1.2. AccessTokenContent

Represents a validated access token with its claims.

public class AccessTokenContent extends BaseTokenContent {
    // Standard claims
    public Optional<String> getSubject();
    public String getIssuer();
    public Optional<List<String>> getAudience();
    public OffsetDateTime getExpirationTime();
    public OffsetDateTime getIssuedAtTime();

    // Access token specific
    public List<String> getRoles();
    public List<String> getGroups();
    public List<String> getScopes();
    public Optional<String> getEmail();
    public Optional<String> getPreferredUsername();

    // Authorization checks
    public boolean providesRoles(Collection<String> requiredRoles);
    public boolean providesGroups(Collection<String> requiredGroups);
    public boolean providesScopes(Collection<String> requiredScopes);
    public Set<String> determineMissingRoles(Collection<String> required);
    public Set<String> determineMissingGroups(Collection<String> required);
    public Set<String> determineMissingScopes(Collection<String> required);
}

1.3. IssuerConfig

public class IssuerConfig implements LoadingStatusProvider {
    public static IssuerConfigBuilder builder() { ... }

    public static class IssuerConfigBuilder {
        public IssuerConfigBuilder enabled(boolean enabled);
        public IssuerConfigBuilder issuerIdentifier(String issuer);
        public IssuerConfigBuilder jwksContent(String jwks);
        public IssuerConfigBuilder jwksFilePath(String path);
        public IssuerConfigBuilder httpJwksLoaderConfig(HttpJwksLoaderConfig config);
        public IssuerConfigBuilder jwksLoader(JwksLoader loader);
        public IssuerConfigBuilder expectedAudience(String audience);
        public IssuerConfigBuilder expectedAudience(Set<String> audience);
        public IssuerConfigBuilder expectedClientId(String clientId);
        public IssuerConfigBuilder expectedClientId(Set<String> clientId);
        public IssuerConfigBuilder claimSubOptional(boolean optional);
        public IssuerConfigBuilder expectedTokenType(String type);
        public IssuerConfigBuilder dpopConfig(DpopConfig config);
        public IssuerConfigBuilder algorithmPreferences(SignatureAlgorithmPreferences prefs);
        public IssuerConfigBuilder claimMapper(String claim, ClaimMapper mapper);
        public IssuerConfig build();
    }
}

2. Configuration Classes

2.1. ParserConfig

public class ParserConfig {
    public static class ParserConfigBuilder {
        public ParserConfigBuilder maxTokenSize(int bytes);      // Default: 8192 (8KB)
        public ParserConfigBuilder maxPayloadSize(int bytes);    // Default: 8192 (8KB)
        public ParserConfigBuilder maxStringLength(int bytes);   // Default: 4096 (4KB)
    }
}

2.2. AccessTokenCacheConfig

public class AccessTokenCacheConfig {
    public static class AccessTokenCacheConfigBuilder {
        public AccessTokenCacheConfigBuilder maxSize(int entries);                  // Default: 1000
        public AccessTokenCacheConfigBuilder evictionIntervalSeconds(long seconds); // Default: 10
    }
}

2.3. HttpJwksLoaderConfig

public class HttpJwksLoaderConfig {
    public static class HttpJwksLoaderConfigBuilder {
        public HttpJwksLoaderConfigBuilder jwksUri(URI uri);
        public HttpJwksLoaderConfigBuilder jwksUrl(String url);
        public HttpJwksLoaderConfigBuilder wellKnownUrl(String url);
        public HttpJwksLoaderConfigBuilder wellKnownUri(URI uri);
        public HttpJwksLoaderConfigBuilder connectTimeoutSeconds(int seconds);
        public HttpJwksLoaderConfigBuilder readTimeoutSeconds(int seconds);
        public HttpJwksLoaderConfigBuilder refreshIntervalSeconds(int seconds);
        public HttpJwksLoaderConfigBuilder sslContext(SSLContext context);
        public HttpJwksLoaderConfigBuilder verifyHostname(boolean verify);  // Default: true; mutually exclusive with sslContext
        public HttpJwksLoaderConfigBuilder retryConfig(RetryConfig config);
        public HttpJwksLoaderConfigBuilder issuerIdentifier(String issuer);
        public HttpJwksLoaderConfigBuilder keyRotationGracePeriod(Duration period);
        public HttpJwksLoaderConfigBuilder maxRetiredKeySets(int maxRetiredKeySets);
        public HttpJwksLoaderConfigBuilder parserConfig(ParserConfig config);
    }
}

3. Claim Mappers

3.1. JsonCollectionMapper

Handles JSON arrays (["admin", "user"]), single strings ("admin"), and mixed types.

3.2. StringSplitterMapper

Splits delimited strings: "admin,user" with ',' separator, "admin:user" with ':' separator.

3.3. Custom ClaimMapper

public interface ClaimMapper {
    ClaimValue map(MapRepresentation mapRepresentation, String claimName);
}

4. Error Handling

4.1. TokenValidationException

public class TokenValidationException extends RuntimeException {
    public EventType getEventType();
    public EventCategory getCategory();
}

5. Security Configuration

Setting	Purpose	Default	Applied When
maxTokenSize	Limits entire JWT token string	8KB	Before any processing
maxPayloadSize	Limits each decoded JWT part	8KB	After Base64 decoding
maxStringLength	DSL-JSON enforced limit on string buffer size	4KB	During JSON parsing

Base64 encoding increases size by ~33%, so an 8KB token yields ~6KB decoded content. These limits provide defense-in-depth against denial-of-service attacks, memory exhaustion, and JSON parsing vulnerabilities.

For usage examples, see Usage Guide.