oidc-spring-support-demo

Demo project for Spring Boot

License	License MIT License
Categories	Categories Security
GroupId	GroupId no.nav.security
ArtifactId	ArtifactId oidc-spring-support-demo
Last Version	Last Version 0.2.18
Release Date	Release Date May 15, 2019
Type	Type jar
Description	Description oidc-spring-support-demo Demo project for Spring Boot

Download oidc-spring-support-demo

Filename	Size
oidc-spring-support-demo-0.2.18.pom
oidc-spring-support-demo-0.2.18.jar	5 KB
oidc-spring-support-demo-0.2.18-sources.jar	3 KB
oidc-spring-support-demo-0.2.18-javadoc.jar	48 KB
Browse

How to add to project

Apache Maven

<!-- https://jarcasting.com/artifacts/no.nav.security/oidc-spring-support-demo/ -->
<dependency>
    <groupId>no.nav.security</groupId>
    <artifactId>oidc-spring-support-demo</artifactId>
    <version>0.2.18</version>
</dependency>

Gradle Groovy

// https://jarcasting.com/artifacts/no.nav.security/oidc-spring-support-demo/
implementation 'no.nav.security:oidc-spring-support-demo:0.2.18'

Gradle Kotlin

// https://jarcasting.com/artifacts/no.nav.security/oidc-spring-support-demo/
implementation ("no.nav.security:oidc-spring-support-demo:0.2.18")

Apache Buildr

'no.nav.security:oidc-spring-support-demo:jar:0.2.18'

Apache Ivy

<dependency org="no.nav.security" name="oidc-spring-support-demo" rev="0.2.18">
  <artifact name="oidc-spring-support-demo" type="jar" />
</dependency>

Groovy Grape

@Grapes(
@Grab(group='no.nav.security', module='oidc-spring-support-demo', version='0.2.18')
)

Scala SBT

libraryDependencies += "no.nav.security" % "oidc-spring-support-demo" % "0.2.18"

Leiningen

[no.nav.security/oidc-spring-support-demo "0.2.18"]

Dependencies

compile (4)

Group / Artifact	Type	Version
org.springframework.boot : spring-boot-starter-web	jar
org.springframework.boot : spring-boot-starter-jetty	jar
no.nav.security : oidc-spring-support	jar	0.2.18
no.nav.security : oidc-test-support	jar	0.2.18

test (5)

Group / Artifact	Type	Version
org.springframework.boot : spring-boot-starter-test	jar	2.1.3.RELEASE
org.mockito : mockito-junit-jupiter	jar
org.junit.jupiter : junit-jupiter-params	jar
org.junit.jupiter : junit-jupiter-engine	jar
org.junit.platform : junit-platform-launcher	jar

Project Modules

There are no modules declared in this project.

token-support

This project provides several standalone modules supporting common security token handling in Java and Kotlin applications, e.g. either as an OAuth 2.0 client or a OAuth 2.0 Resource Server with JWT validation.

The main motivation behind the project is to support multiple token issuers/identity providers with as much ease as possible.

The modules are roughly split in two:

token-client-* (support for multiple OAuth 2.0 grants/flows as a client)
token-validation-* (support for JWT token validation following best practice and OAuth 2.0 specifications)

The client and validation modules provide a core module and specific "wrapper" implementations for some well known libraries such as Spring Boot, JAX-RS and KTOR.

Main components

This project is mainly composed of modules wrapping other well known libraries. Currently there is support for:

Spring Boot and Spring Web MVC
JAX-RS
Plain Java
Kotlin with ktor

token-validation-core

Provides the core token validation support, using the Nimbus OAuth 2.0 SDK with OpenID Connect extensions. Token signing keys are retrieved from the external issuer and cached in the JwtTokenValidator, using the com.nimbusds.openid.connect.sdk.validators.IDTokenValidator (this validator also works well for validating access_tokens). Token signing keys will be fetched from the jwt_keys endpoint configured in the provider configuration metadata endpoint (e.g. /.well-known/openid-configuration) when required (e.g. new signing keys are detected).

This module can be used standalone (e.g. if you do not use Spring or JAX-RS). You will however need to code the part to "hook in" enforcement and trigger the token validation (e.g. as done in the token-validation-filter module). If you use Spring, JAX-RS or Ktor you should use the specific module for your framework.

token-validation-filter

Simple servlet filter using the token-validation-core components for validating tokens on inbound HTTP requests. Can be used standalone but is more commonly used together with Spring or JAX-RS.

token-validation-spring

Spring Boot (Spring Web) specific wrapper around token-validation-core and token-validation-filter providing auto configuration of the relevant components. To enable token validation for a spring boot application, simply annotate your SpringApplication class or any Spring Configuration class with @EnableJwtTokenValidation. Optionally list the packages or classses you dont want token validations for (e.g. error controllers). The package org.springframework - e.g. @EnableJwtTokenValidation(ignore="org.springframework") is listed as ignored by default if you dont specify a ignore list. Use the @Unprotected or @Protected/@ProtectedWithClaims annotations at rest controller method/class level to indicate if token validation is required or not.

There is a short sample below, however more detailed samples are available in the token-validation-spring-demo module.

SpringApplication sample

This annotation will enable token validation and token transportation/propagation through the service

@SpringBootApplication
@EnableJwtTokenValidation
public class ProductServiceApplication {

	public static void main(String[] args) {
		SpringApplication.run(ProductServiceApplication.class, args);
	}
}

Rest controller sample

This example shows

First method - An unprotected endpoint. No token is required to use this endpoint.
Second method - A protected endpoint. This endpoint will require a valid token from the "employee" issuer.
Third method - A protected endpoint. This endpoint will require a valid token from one of the configured issuers.
Fourth method - A non-annotated endpoint. This endpoint will not be accessible from outside the server (will return a 501 NOT_IMPLEMENTED).

@RestController
class ProductController {
	
	private final ProductService productService;
  
  ProductController(ProductService productService){
    this.productService = productService;
  }
	
	@Unprotected
	@RequestMapping(value = "/product/{id}", method = RequestMethod.GET)
	public Product read(@PathVariable("id") String id) {
		return productService.read(id);
	}
	
	@Protected(issuer="employee")
	@RequestMapping(value = "/product", method = RequestMethod.POST)
	public Product create(@RequestBody Product product) {		
		return productService.create(product);
	}

	@Protected
	@RequestMapping(value = "/product/sample", method = RequestMethod.GET)
	public Product sample() {
		Product product = Product.sample();
		product.setId(UUID.randomUUID().toString());
		return product;
	}

	@RequestMapping(value = "/product/{id}/variant", method = RequestMethod.GET)
	public Variant readVariant(@PathVariable("id") String id) {
		return productService.readVariant(id);
	}

}

token-validation-jaxrs

JAX-RS wrapper around token-validation-core and token-validation-filter. Two steps are necessary to enable token validation:

Register the servlet filter JaxrsJwtTokenValidationFilter with your servlet container to pick up the token of incoming requests
Register the JwtTokenContainerRequestFilter with your Application (plain JAX-RS) or ResourceConfig (Jersey)

Use the @Unprotected, @Protected or @ProtectedWithClaims annotations on resource methods and/or classes indicate if token validation is required or not. Method annotations have precedence One additional step is required to pass the token do other services

Example

Register the servlet filter with your container, as done in spring boots @SpringBootConfiguration in the snippet below. How you get hold of the configuration map of issuers is up to the implementor.

    @Bean
    public FilterRegistrationBean<JwtTokenValidationFilter> jwtTokenValidationFilterBean(MultiIssuerConfiguraton config) {
        return new FilterRegistrationBean<>(new JaxrsJwtTokenValidationFilter(config));
    }

    @Bean
    public MultiIssuerConfiguraton multiIssuerConfiguration(Map<String, IssuerProperties> issuerConfiguration, ProxyAwareResourceRetriever resourceRetriever) {
        return new MultiIssuerConfiguraton(issuerConfiguration, resourceRetriever);
    }

    @Bean
    public ProxyAwareResourceRetriever proxyAwareResourceRetriever() {
        return new ProxyAwareResourceRetriever();
    }

How you configure the servlet filter depends on how you launch your app, e.g. if you use spring or not, and whether you use tomcat or jetty

Configure jersey

There are two options, explicit registering of resources

new ResourceConfig()
  .register(JwtTokenContainerRequestFilter.class)
  // ...
  .register(Resource.class);

or let jersey scan for Resources and/or @Provider-annotated classes

new ResourceConfig()
  .packages("no.nav.security.token.support.jaxrs", "x.y.z.resourcepackage");

Rest controller sample with method annotations

This example shows

First method - An unprotected endpoint. No token is required to use this endpoint.
Second method - A protected endpoint. This endpoint will require a valid token from the "employee" issuer.
Third method - A protected endpoint. This endpoint will require a valid token from one of the configured issuers.
Fourth method - A non-annotated endpoint. This endpoint will not be accessible from outside the server (will return a 501 NOT_IMPLEMENTED).

@Path("/rest")
public class ProductResource {
	
    // ...
	
  @GET
  @PATH("/product/")
  @Unprotected
  public List<Product> list() {
    return service.list();
  }
	
  @POST
  @PATH("/product")
  @Protected
  public Product add(Product product) {		
    return service.create(product);
  }
	
  @DELETE
  @PATH("/product/{id}")
  @ProtectedWithClaims(issuer = "manager", claimMap = { "acr=Level4" })
  public void add(String id) {		
    return service.delete(id);   
  }

}

token-validation-ktor

See demo application in token-validation-ktor-demo.

token-validation-* configuration

Add the modules that you need as Maven dependencies.

token-validation-spring:

   <dependency>     
        <groupId>no.nav.security</groupId>
        <artifactId>token-validation-spring</artifactId>
        <version>${token-support.version}</version>
    </dependency>

token-validation-jaxrs:

   <dependency>     
        <groupId>no.nav.security</groupId>
        <artifactId>token-validation-jaxrs</artifactId>
        <version>${token-support.version}</version>
    </dependency>

token-validation-ktor:

   <dependency>     
        <groupId>no.nav.security</groupId>
        <artifactId>token-validation-ktor</artifactId>
        <version>${token-support.version}</version>
    </dependency>

token-validation-core (included as dependency in all of the above):

   <dependency>     
        <groupId>no.nav.security</groupId>
        <artifactId>token-validation-core</artifactId>
        <version>${token-support.version}</version>
    </dependency>

Required properties (yaml or properties)

no.nav.security.jwt.issuer.[issuer shortname] - all properties relevant for a particular issuer must be listed under a short name for that issuer (not the actual issuer value from the token, but a chosen name to represent config for the actual issuer) you trust, e.g. citizen or employee
no.nav.security.jwt.issuer.[issuer shortname].discoveryurl - The identity provider configuration/discovery endpoint (metadata)
no.nav.security.jwt.issuer.[issuer shortname].accepted_audience - The value of the audience (aud) claim in the JWT token. For OIDC it is the client ID of the client responsible for acquiring the token, in OAuth 2.0 it should be the identifier for you api.
no.nav.security.jwt.issuer.[issuer shortname].cookiename - The value of the cookie containing a ID token (not required, only necessary if your api receives calls directly from a browser)
no.nav.security.jwt.issuer.[issuer shortname].validation.optional-claims - A comma separated list of optional claims that will be excluded from default claims.
no.nav.security.jwt.issuer.[issuer shortname].jwks-cache.lifespan - Cache the retrieved JWK keys to speed up subsequent look-ups. A non-negative lifespan expressed in minutes. (Default 15 min)
no.nav.security.jwt.issuer.[issuer shortname].jwks-cache.refreshtime - A non-negative refresh time expressed in minutes. (Default 5 min)

"Corporate" proxy support per issuer

Each issuer can be configured to use or not use a proxy by specifying the following properties:

no.nav.security.jwt.issuer.[issuer shortname].proxyurl - The full url of the proxy, e.g. http://proxyhost:8088

token-client-core

Provides core OAuth 2.0 client support, supporting the following OAuth 2.0 grants:

jwt_bearer
client_credentials
token_exchange

This module can be used standalone (e.g. if you do not use Spring or Ktor). You will however need to code the part to "hook in" the client and trigger the token retrieval. If you use Spring you should use the specific wrapper module.

When requesting a token from an OAuth 2.0 Authorization Server the client must authenticate itself with one of the following client authentication methods:

private_key_jwt
client_secret_post
client_secret_basic

The module will choose the client authentication method based on provided configuration in the class ClientProperties.

Use the interface JwtBearerTokenResolver to supply a JWT that should be exchanged for another, i.e. in jwt_bearer or token_exchange grants. The OAuth2HttpClient interface lets you provide a HTTP client of your choosing to perform the actual POST request to the OAuth 2.0 server.

token-client-spring

Spring Boot wrapper for the module token-client-core, providing auto configuration for Spring.
Simply annotate your SpringApplication class or any Spring Configuration class with EnableOAuth2Client. Enable caching for the OAuth 2.0 access_token response with cacheEnabled = true and configurable cacheEvictSkew and cacheMaximumSize properties.

@EnableOAuth2Client(cacheEnabled = true)
@Configuration
public class Configuration {
    // ...
}

Detailed samples are available in the token-client-spring-demo module.

token-client-ktor

Not implemented as of now. See demo application in token-client-ktor-demo.

token-client-* configuration

Add the module that you need as dependencies.

token-client-spring:

   <dependency>     
        <groupId>no.nav.security</groupId>
        <artifactId>token-client-spring</artifactId>
        <version>${token-support.version}</version>
    </dependency>

token-client-core (included as dependency of the above):

   <dependency>     
        <groupId>no.nav.security</groupId>
        <artifactId>token-client-core</artifactId>
        <version>${token-support.version}</version>
    </dependency>

Required properties (yaml or properties)

no.nav.security.jwt.client.registration[client shortname] - All properties relevant for a particular client must be listed under a short name for that client
no.nav.security.jwt.client.registration[client shortname].token-endpoint-url - The identity provider /token endpoint, to retrieve a token
no.nav.security.jwt.client.registration[client shortname].grant-type - The OAuth 2.0 grant_type to use. Accepted grant types:
- urn:ietf:params:oauth:grant-type:jwt-bearer
- client_credentials
- urn:ietf:params:oauth:grant-type:token-exchange

Not required

no.nav.security.jwt.client.registration[client shortname].scope - OAuth 2.0 scopes provide a way to limit the amount of access for access tokens

Required Authentication properties (yaml or properties)

no.nav.security.jwt.client.registration[client shortname].authentication - All properties relevant for client authentication must be listed under authentication.
no.nav.security.jwt.client.registration[client shortname].authentication.client-id - The client ID for your application (usually preregistered at your OAuth 2.0 authorization server.
no.nav.security.jwt.client.registration[client shortname].authentication.client-auth-method - Standard methods for client authentication. Supported methods are:
- client_secret_basic
- client_secret_post
- private_key_jwt

Any of

no.nav.security.jwt.client.registration[client shortname].authentication.client-secret - The client secret must be kept confidential.
no.nav.security.jwt.client.registration[client shortname].authentication.client-jwk - client-jwk - Used to sign the client JWT, instead of client-secret for authentication against a provider.

Token-exchange

no.nav.security.jwt.client.registration[client shortname].token-exchange - All properties relevant for the grant token-exchange must be listed under token-exchange.
no.nav.security.jwt.client.registration[client shortname].token-exchange.audience - The logical name of the target service where the client intends to use the requested security token.

Running JUnit tests or running your app locally while using these modules

There is a separate module in token-validation-spring-test for Spring apps, see separate README for more information.

For apps not using Spring we recommend you use the mock-oauth2-server and setup your tests/properties accordingly.

Build & Release

Sonatype OSS & Maven Central

Releases

In order to release a new version go to https://github.com/navikt/token-support/releases and click edit on the draft release. Edit or approve the changelog and click publish. Github Action will trigger a new release.

First, it will appear in Sonatype OSS releases, before eventually (a couple of minutes later) it is synced to Maven Central.

Contact

If you have any questions, please open an issue on the Github issue tracker.

For NAV employees, you can ask questions at the Slack channel #token-support

NAV IT

Arbeids- og velferdsdirektoratet - The Norwegian Labour and Welfare Directorate

Versions

Version
0.2.18 May 15, 2019

oidc-spring-support-demo

License

Categories

GroupId

ArtifactId

Last Version

Release Date

Type

Description

Download oidc-spring-support-demo

How to add to project

Dependencies

compile (4)

test (5)

Project Modules

token-support

Main components

token-validation-core

token-validation-filter

token-validation-spring

SpringApplication sample

Rest controller sample

token-validation-jaxrs

Example

Configure jersey

Rest controller sample with method annotations

token-validation-ktor

token-validation-* configuration

Required properties (yaml or properties)

"Corporate" proxy support per issuer

token-client-core

token-client-spring

token-client-ktor

token-client-* configuration

Required properties (yaml or properties)

Not required

Required Authentication properties (yaml or properties)

Any of

Token-exchange

Running JUnit tests or running your app locally while using these modules

Build & Release

Sonatype OSS & Maven Central

Releases

Contact

NAV IT

Versions