README.adoc

Geronimo Microprofile JWT Auth Implementation

Artifacts

API

Important

you can also use the eclipse bundle.

<parent>
  <groupId>org.apache.geronimo</groupId>
  <artifactId>geronimo-microprofile-jwt-auth-spec</artifactId>
  <version>${jwtauth.version}</version>
</parent>

Implementation

<parent>
  <groupId>org.apache.geronimo</groupId>
  <artifactId>geronimo-jwt-auth-impl</artifactId>
  <version>${jwtauth.version}</version>
</parent>

Configuration

Important

configuration uses Microprofile Configuration if available and if not system properties and META-INF/geronimo/microprofile/jwt-auth.properties.

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
geronimo.jwt-auth.filter.active	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	-
geronimo.jwt-auth.kids.key.mapping	The mapping between the kid and the public key to use	-
geronimo.jwt-auth.kids.issuer.mapping	The mapping of the issuer expected per kid	-
geronimo.jwt-auth.issuer.default	The default issuer to use when no mapping is found	-
geronimo.jwt-auth.cookie.name	The cookie name to read the JWT, note that header is read before in any case.	Bearer
geronimo.jwt-auth.header.name	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
geronimo.jwt-auth.date.tolerance	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	-
geronimo.jwt-auth.public-key.cache.active	Should public keys be cached	true
geronimo.jwt-auth.jwks.invalidation.interval	Invalidation interval in seconds (less than 1 means no invalidation)	0
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/jwt-auth.properties (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 = https://server.example.com

# mapping kid1 to the embedded resource /publicKey.pem
# can be an absolute path too
geronimo.jwt-auth.kids.key.mapping = \
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/openwebbeans.properties:

configuration.ordinal=1001

# 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 {
    @Override
    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.