JWT, OIDC and Keycloak

mp.jwt.verify.publickey.location points at a PEM-encoded public key (or a JWKS URL, for a provider that publishes one) used to verify the token’s signature; mp.jwt.verify.issuer rejects any token whose iss claim does not match, and smallrye.jwt.path.groups tells SmallRye JWT which claim to read roles from when the token does not use the MicroProfile-standard groups claim name.

org.eclipse.microprofile.jwt.JsonWebToken (itself a java.security.Principal) exposes the whole claim set programmatically (getClaim(String), getGroups(), getExpirationTime()); @Claim injects one named claim directly as a field or constructor parameter, typed as the claim’s natural Java type (String, Long, Set<String>, or JsonValue for anything structured) — the same trade-off as @ConfigProperty vs. @ConfigMapping on the Configuration page: convenient for one value, less structured than reading the whole JsonWebToken for many.

smallrye-jwt-build (pulled in transitively by quarkus-smallrye-jwt) issues tokens instead of only verifying them — useful for a test fixture, an internal token-issuing endpoint, or a service that mints a short-lived token for a downstream call:

.sign() produces a signed JWS (using the private key configured under smallrye.jwt.sign.key.location, the counterpart to mp.jwt.verify.publickey.location); .jwe()…​encrypt() instead produces an encrypted JWE. Both build on the same JOSE mechanics covered on JWT and the JOSE Family.

Web-app mode is for a browser-facing application: quarkus-oidc drives the OAuth 2.0 authorization-code flow itself, storing the resulting tokens in an encrypted session cookie rather than handing them to application code directly.

application-type=web-app is what switches quarkus-oidc into this mode; hitting any endpoint protected by @Authenticated/@RolesAllowed with no valid session redirects the browser into the provider’s login page, and a successful callback establishes the session cookie. quarkus.oidc.logout.path wires an endpoint that clears the local session and redirects to the provider’s own end-session endpoint, landing back at post-logout-path afterward — session/logout mechanics themselves (front-channel vs. back-channel logout, single sign-out) are protocol-level and covered on Logout and Session Management.

Service mode is for a machine-facing API that expects a bearer token on every request and performs no redirect of its own:

By default, quarkus-oidc validates a bearer JWT against the provider’s published JWKS (fetched from the `auth-server-url’s discovery document and cached, refreshed on a configurable interval or on a signing-key-id miss). Switching to token introspection instead — required for an opaque, non-JWT access token, or when the provider’s revocation semantics demand it — is a property away:

A resource method in service mode reads the validated identity the same way as any other Quarkus Security mechanism — SecurityIdentity, JsonWebToken, or @Claim, exactly as under quarkus-smallrye-jwt above — since both extensions converge on the same SecurityIdentity/JsonWebToken types once validation succeeds.

A single Quarkus application can serve more than one OIDC tenant — different realms, different providers, or a mix of web-app and service configuration for different paths — by declaring named tenants under quarkus.oidc."<tenant>".* and resolving which one applies per request:

A custom io.quarkus.oidc.TenantConfigResolver or io.quarkus.oidc.TenantResolver CDI bean picks the active tenant per request (from a path segment, a header, or a subdomain), or the simpler quarkus.oidc.tenant-a.tenant-paths=/tenant-a/* path-based resolution handles the common case of routing by URL prefix without any custom code.

quarkus-oidc-client obtains and refreshes an access token independently of any inbound request — for a scheduled job or a service that needs to call another API using its own client-credentials identity rather than a caller’s token:

When a service should instead forward the caller’s own bearer token to a downstream call — rather than authenticating as itself — quarkus-oidc-token-propagation (paired with a Quarkus REST Client) attaches the current request’s access token to an outbound @RestClient call automatically, via the @AccessToken/reactive filter it registers, with no manual header-copying code needed.

In web-app mode, quarkus-oidc must remember each session’s tokens somewhere between requests. By default that state lives inside the encrypted session cookie itself (quarkus.oidc.token-state-manager.strategy=keep-all-tokens, the default) — simple, but it grows the cookie with every token stored and puts token material in the browser. quarkus-oidc-db-token-state-manager instead persists token state server-side, in a relational database, and keeps only a session reference in the cookie:

Other quarkus.oidc.token-state-manager.strategy values narrow what the cookie holds without moving state server-side: id-refresh-tokens drops the access token from the cookie (it is re-derived from the refresh token as needed), and id-token keeps only the ID token, appropriate when a web app never needs to make an authenticated call of its own and only needs to know who is logged in.