blob: 1741f8240e364b1bd8403e59ca236cfc59bb4f8a [file] [log] [blame]
= Geronimo Microprofile JWT Auth Implementation
== Artifacts
=== API
IMPORTANT: you can also use the eclipse bundle.
=== Implementation
== Configuration
IMPORTANT: configuration uses Microprofile Configuration if available
and if not system properties and `META-INF/geronimo/microprofile/`.
| Name | Description | Default
|geronimo.jwt-auth.jwt.header.kid.default|The default `kid` if specified|-
|geronimo.jwt-auth.jwt.header.alg.default|The default `alg` if specified|RS256
|geronimo.jwt-auth.jwt.header.typ.default|The default `typ` if specified|JWT
|geronimo.jwt-auth.jwt.header.typ.validate|Should the typ value be validated (only `JWT` is supported)|true
||If `true` it forces the filter to be added whatever config (`@LoginConfig` is used or not)|false
|geronimo.jwt-auth.filter.mapping.default|When the JAX-RS `Application` doesn't have an `@ApplicationPath` and no servlet registration are found for the application this defines the path to use to handle JWT|/*
|geronimo.jwt-auth.filter.publicUrls|List of URL to ignore|-
||The mapping between the kid and the public key to use|-
||The mapping of the issuer expected per kid|-
|geronimo.jwt-auth.issuer.default|The default issuer to use when no mapping is found|-
||The cookie name to read the JWT, note that header is read before in any case.|Bearer
||The header name to read the JWT|Authorization
|geronimo.jwt-auth.header.prefix|The header prefix to use|bearer
|geronimo.jwt-auth.header.alg.supported|List of accepted `alg` value|RS256, accepted values: [RS\|HS][256\|384\|512]
|geronimo.jwt-auth.exp.required|Should the validation fail if `exp` is missing|true
|geronimo.jwt-auth.iat.required|Should the validation fail if `iat` is missing|true
||The tolerance in ms for `exp` and `iat`|60000
|geronimo.jwt-auth.jca.provider|The JCA provider (java security)|- (built-in one)
|geronimo.jwt-auth.groups.mapping|The mapping for the groups|-
||Should public keys be cached|true
|geronimo.jwt-auth.public-key.default|Default public key to verify JWT|-
NOTE: `org.eclipse.microprofile.jwt.config.Names` configuration is supported too.
Here is a sample `META-INF/geronimo/microprofile/`
(assuming you don't use Microprofile config) using some of these entries:
# for rolesallowed accept group1 and Group1MappedRole for the requirement Group1MappedRole
geronimo.jwt-auth.groups.mapping = \
Group1MappedRole = group1, Group1MappedRole
# the global expected issuer
geronimo.jwt-auth.issuer.default =
# mapping kid1 to the embedded resource /publicKey.pem
# can be an absolute path too = \
kid1 = /publicKey.pem
== Apache OpenWebBeans
For this specification to work on Apache OpenWebBeans you need to configure a few keys (until 2.0.4).
For that, register a `META-INF/openwebbeans/`:
# OWB default is wrong and we need that
org.apache.webbeans.container.InjectionResolver.fastMatching = false
# only if you use Principal injection instead of JsonWebToken injection
# since 2.0.5
org.apache.webbeans.component.PrincipalBean.proxy = false
org.apache.webbeans.spi.SecurityService = org.superbiz.MySecurityService
And here is a sample security service implementation:
public class MySecurityService extends SimpleSecurityService {
public Principal getCurrentPrincipal() {
return ((Supplier<Principal>) CDI.current().select(HttpServletRequest.class).get()
.getAttribute(Principal.class.getName() + ".supplier")).get();
IMPORTANT: in any case it is not recommended to use CDI `Principal` API, always prefer `JsonWebToken` one.
== Run-as
To enable a "run as" feature - i.e. don't go through the JWT validation etc but still propagate a JWT considered as valid,
you can set the servlet attribute `org.eclipse.microprofile.jwt.JsonWebToken` with an implementation of that API.