Use Both JWT and Opaque Access Tokens With Spring Boot

Brian Demers

Oct. 09, 20 · Tutorial

Like (5)

Save

12.92K Views

How can one validate OAuth 2.0 access tokens? This question frequently comes up — along with the topic of validating JSON Web Tokens (JWT) based access tokens— however, this is NOT part of the OAuth 2.0 specification. JWTs are used so commonly that Spring Security supported them before adding support for remotely validating tokens.

This article will introduce how to build a simple application that utilizes both types of validation.

You can also follow along by watching videos on our YouTube channel.

Prerequisites

Should I Validate Access Tokens Locally or Remote?

Whether you should validate access tokens locally (e.g., a JWT) or remotely (per spec) is a question of how much security you need. Often, people jump to, “I need all of the securities!” This statement simply isn’t true — how much security you need should be balanced with other factors like ease of use, cost, and performance.

There is no such thing as perfect security, only varying levels of insecurity.

Salman Rushdie

The biggest downside to validating a token locally is that your token is, by definition, stale. It is a snapshot of the moment in time when your identity provider (IdP) created the token. The further away you get from that moment, the more likely that token is no longer valid: it could have been revoked, the user could have logged out, or the application that created the token disabled.

Remotely validating tokens are not always ideal, either. Remote validation comes with the cost of adding latency in your application, as you need to add an HTTP request to a remote server every time you need to validate the token.

One way to reduce these concerns is to keep the lifetime of an access token short (say 5 minutes) and validate them locally; this limits the risk of using a revoked token.

There is another option: do both!

Validate Access Tokens Locally and Remotely!

By default, Spring Boot applications can be configured to use JWT validation OR opaque validation, simply by configuring a few properties. Using both types of validation in the same application requires a few extra lines of code.

Obviously, you wouldn’t do both on each request; you could validate more sensitive operations remotely and all other requests locally. For example, when updating a user’s contact information, you may want to validate the token remotely, but when viewing the user’s profile information, validate locally. This pattern keeps your application fast, as updating an address or an email happens less frequently than just viewing contact information.

To get started, you will need an OAuth Web application in Okta.

Login in to your Okta admin console, if you just created a new account, and have not logged in yet, follow the activation link in your inbox.

Make a note of the Org URL on the top right; I’ll refer to this as {yourOktaDomain} in the next section.

Once you are logged in, navigate to the top menu and select Applications -> Add Application. Select Web -> Next.

Give your application a name: “Spring Tokens Example”

Set the Login redirect URIs to https://oidcdebugger.com/debug

Check Implicit (Hybrid)

Click Done

Head over to start.spring.io and click the Generate button.

Note: The above link populates the following settings:

Group: com.okta.example
Artifact: spring-token-example
Package name: com.okta.example
Dependencies:
- Spring Security (security)
- Spring Web (web)

Unzip the project and open it in your favorite IDE.

Add two more dependencies to the Maven pom.xml file:

    XML
   
xxxxxxxxxx

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
    <groupId>com.nimbusds</groupId>
    <artifactId>oauth2-oidc-sdk</artifactId>
    <version>7.3</version>
</dependency>

Add an OAuth2ClientProperties bean to the SpringTokenExampleApplication class to reuse the standard Spring Security OAuth properties.

    Java
   
xxxxxxxxxx

@Bean
OAuth2ClientProperties oAuth2ClientProperties() {
    return new OAuth2ClientProperties();
}

Add a simple REST controller with a GET and a POST handler, in src/main/java/com/okta/example/SimpleController.java

    Java
   
 

     
    
xxxxxxxxxx

            
          
package com.okta.example;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class SimpleController {
    @GetMapping("/")
    String hello() {
        return "Hello!";
    }
    @PostMapping("/")
    String helloPost(@RequestParam("message") String message) {
        return "hello: " + message;
    }
}

Create a new class that will map a RequestMatcher to the AuthenticationManager (more on this below) src/main/java/com/okta/example/RequestMatchingAuthenticationManagerResolver.java

NOTE: This class may be part of a future version of Spring Security.

    Java
   
 

     
    
xxxxxxxxxx

            
          
package com.okta.example;
import java.util.LinkedHashMap;
import java.util.Map;
import javax.servlet.http.HttpServletRequest;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.AuthenticationManagerResolver;
import org.springframework.security.authentication.AuthenticationServiceException;
import org.springframework.security.web.util.matcher.RequestMatcher;
import org.springframework.util.Assert;
/**  An {@link AuthenticationManagerResolver} that returns a {@link AuthenticationManager}
*  instances based upon the type of {@link HttpServletRequest} passed into
*  {@link #resolve(HttpServletRequest)}.
*  @author Josh Cummings
*/  @since 5.2
public class RequestMatchingAuthenticationManagerResolver
        implements AuthenticationManagerResolver<HttpServletRequest> {
    private final LinkedHashMap<RequestMatcher, AuthenticationManager> authenticationManagers;
    private AuthenticationManager defaultAuthenticationManager = authentication -> {
        throw new AuthenticationServiceException("Cannot authenticate " + authentication);
    };
    public RequestMatchingAuthenticationManagerResolver
    (LinkedHashMap<RequestMatcher, AuthenticationManager> authenticationManagers) {
        Assert.notEmpty(authenticationManagers, "authenticationManagers cannot be empty");
        this.authenticationManagers = authenticationManagers;
    }
    @Override
    public AuthenticationManager resolve(HttpServletRequest context) {
        for (Map.Entry<RequestMatcher, AuthenticationManager> entry : this.authenticationManagers.entrySet()) {
            if (entry.getKey().matches(context)) {
                return entry.getValue();
            }
        }
        return this.defaultAuthenticationManager;
    }
    public void setDefaultAuthenticationManager(AuthenticationManager defaultAuthenticationManager) {
        Assert.notNull(defaultAuthenticationManager, "defaultAuthenticationManager cannot be null");
        this.defaultAuthenticationManager = defaultAuthenticationManager;
    }
}

Configure Spring Security to Validate JWTs and Opaque Tokens

Everything up until now has been boilerplate, now we get to the fun part!

Create a new ExampleWebSecurityConfigurer class which uses local JWT validation for GET requests, and remote “opaque” validation for all other requests (be sure to read the inline comments):

    Java
   
 

     
    
xxxxxxxxxx

            
          
package com.okta.example;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.security.oauth2.client.OAuth2ClientProperties;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.AuthenticationManagerResolver;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationProvider;
import org.springframework.security.oauth2.server.resource.authentication.JwtBearerTokenAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.OpaqueTokenAuthenticationProvider;
import org.springframework.security.oauth2.server.resource.introspection.NimbusOpaqueTokenIntrospector;
import org.springframework.security.oauth2.server.resource.introspection.OpaqueTokenIntrospector;
import org.springframework.security.web.util.matcher.RequestMatcher;
import javax.servlet.http.HttpServletRequest;
import java.util.Arrays;
import java.util.LinkedHashMap;
import java.util.List;
@Configuration
public class ExampleWebSecurityConfigurerAdapter extends WebSecurityConfigurerAdapter {
    // Inject the `OAuth2ClientProperties` we configured in the previous step
    @Autowired
    private OAuth2ClientProperties oAuth2ClientProperties;
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        // All routes require authentication
        http.authorizeRequests().anyRequest().authenticated();
        // Configure a custom `AuthenticationManager` to determine 
        // if JWT or opaque token validation should be used
        http.oauth2ResourceServer().authenticationManagerResolver(customAuthenticationManager());
    }
    AuthenticationManagerResolver<HttpServletRequest> customAuthenticationManager() {
        LinkedHashMap<RequestMatcher, AuthenticationManager> authenticationManagers = new LinkedHashMap<>();
        // USE JWT tokens (locally validated) to validate HEAD, GET, and OPTIONS requests
        List<String> readMethod = Arrays.asList("HEAD", "GET", "OPTIONS");
        RequestMatcher readMethodRequestMatcher = request -> readMethod.contains(request.getMethod());
        authenticationManagers.put(readMethodRequestMatcher, jwt());
        // all other requests will use opaque tokens (remotely validated)
        RequestMatchingAuthenticationManagerResolver authenticationManagerResolver 
            = new RequestMatchingAuthenticationManagerResolver(authenticationManagers);
        // Use opaque tokens (remotely validated) for all other requests
        authenticationManagerResolver.setDefaultAuthenticationManager(opaque());
        return authenticationManagerResolver;
    }
    // Mimic the default configuration for JWT validation.
    AuthenticationManager jwt() {
        // this is the keys endpoint for okta
        String issuer = oAuth2ClientProperties.getProvider().get("okta").getIssuerUri();
        String jwkSetUri = issuer + "/v1/keys";
        // This is basically the default jwt logic
        JwtDecoder jwtDecoder = NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build();
        JwtAuthenticationProvider authenticationProvider = new JwtAuthenticationProvider(jwtDecoder);
        authenticationProvider.setJwtAuthenticationConverter(new JwtBearerTokenAuthenticationConverter());
        return authenticationProvider::authenticate;
    }
    // Mimic the default configuration for opaque token validation
    AuthenticationManager opaque() {
        String issuer = oAuth2ClientProperties.getProvider().get("okta").getIssuerUri();
        String introspectionUri = issuer + "/v1/introspect";
        // The default opaque token logic
        OAuth2ClientProperties.Registration oktaRegistration = oAuth2ClientProperties.getRegistration().get("okta");
        OpaqueTokenIntrospector introspectionClient = new NimbusOpaqueTokenIntrospector(
                introspectionUri,
                oktaRegistration.getClientId(),
                oktaRegistration.getClientSecret());
        return new OpaqueTokenAuthenticationProvider(introspectionClient)::authenticate;
    }
}

Better JWT Validation

Out of the box, Spring Security does minimal validation of the JWT because this is a vendor-specific detail. In addition to the standard JWT validation, Okta recommends validating the issuer and audience claims: iss and aud.

Update the above jwt() method to look like the following:

    Java
   
 

     
    
xxxxxxxxxx

            
          
AuthenticationManager jwt() {
    // this is the keys endpoint for okta
    String issuer = oAuth2ClientProperties.getProvider().get("okta").getIssuerUri();
    String jwkSetUri = issuer + "/v1/keys";
    NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build();
    // okta recommends validating the `iss` and `aud` claims
    // see: https://developer.okta.com/docs/guides/validate-access-tokens/java/overview/
    List<OAuth2TokenValidator<Jwt>> validators = new ArrayList<>();
    validators.add(new JwtTimestampValidator());
    // Add validation of the issuer claim
    validators.add(new JwtIssuerValidator(issuer));
    validators.add(token -> {
        Set<String> expectedAudience = new HashSet<>();
        // Add validation of the audience claim
        expectedAudience.add("api://default");
        // For new Okta orgs, the default audience is `api://default`, 
        // if you have changed this from the default update this value
        return !Collections.disjoint(token.getAudience(), expectedAudience)
            ? OAuth2TokenValidatorResult.success()
            : OAuth2TokenValidatorResult.failure(new OAuth2Error(
                OAuth2ErrorCodes.INVALID_REQUEST,
                "This aud claim is not equal to the configured audience",
                "https://tools.ietf.org/html/rfc6750#section-3.1"));
    });
    OAuth2TokenValidator<Jwt> validator = new DelegatingOAuth2TokenValidator<>(validators);
    jwtDecoder.setJwtValidator(validator);
    JwtAuthenticationProvider authenticationProvider = new JwtAuthenticationProvider(jwtDecoder);
    authenticationProvider.setJwtAuthenticationConverter(new JwtBearerTokenAuthenticationConverter());
    return authenticationProvider::authenticate;
}

Configure and Run Your OAuth 2.0 Application

We are in the home stretch; the last thing needed for our application is a little configuration.

Update your src/main/resources/application.properties file to include the properties from the previous steps.

    Properties files
   
xxxxxxxxxx

spring.security.oauth2.client.provider.okta.issuer-uri = {yourOktaDomain}/oauth2/default
spring.security.oauth2.client.registration.okta.client-id = {clientId}
spring.security.oauth2.client.registration.okta.client-secret = {clientSecret}

Run the application on the command line:

    Shell
   
xxxxxxxxxx

./mvnw spring-boot:run

Make a curl request to the server:

    Shell
   
xxxxxxxxxx

curl localhost:8080/ -v

This will return something like:

    Plain Text
   
xxxxxxxxxx

HTTP/1.1 401
WWW-Authenticate: Bearer

A 401 is expected here, as we did not provide an access token to the request. There are a few ways to get an access token — which option is right for you depends on where and how you access your REST application. Usually, another application is calling your REST API and that application already has an access token. For testing purposes, we will set up the OIDC Debugger.

Get a Token With the OIDC Debugger

Head over to https://oidcdebugger.com/ and populate the form with the following values:

Authorize URI - {yourOktaDomain}/oauth2/default/v1/authorize
Client ID - {clientId} from the previous step
State - this is a test (this can be any value)
Response type - select token
Use defaults for all other fields

Press the Send Request button.

If you are using an incognito/private browser, this may prompt you to login again. Once the Success page loads, copy the Access token and create an environment variable:

    Shell
   
xxxxxxxxxx

export TOKEN="<your-access-token-here>"

Now that you have a token, you can make another request to your REST API:

    Shell
   
xxxxxxxxxx

curl localhost:8080/ -H "Authorization: Bearer $TOKEN"
> Hello!

Similarly, we can call the POST endpoint:

    Shell
   
xxxxxxxxxx

curl -X POST -F 'message=there' localhost:8080/ -H "Authorization: Bearer ${TOKEN}"
> hello: there

We can perform a simple (unscientific) performance test using the time utility, by prefixing the above commands with time:

    Shell
   
xxxxxxxxxx

time curl localhost:8080/ -H "Authorization: Bearer ${TOKEN}"
time curl -X POST -F 'message=there' localhost:8080/ -H "Authorization: Bearer ${TOKEN}"

This data isn’t a great benchmark, as both the client and server are running on the same machine, but you can see the first one returned faster.

    Plain Text
   
xxxxxxxxxx

0.00s user 0.01s system 65% cpu 0.013 total
0.00s user 0.01s system 4% cpu 0.210 total

NOTE: The increased CPU usage is caused by the JWT signature validation.

Learn More About Secure Applications

In this post, I’ve discussed the different ways to validate access tokens and provided a simple example that shows how you can use both options. As always, this code is available on GitHub.

Check out these related blog posts to learn more about building secure web applications.

If you like this blog post and want to see more like it, follow @oktadev on Twitter, subscribe to our YouTube channel, or follow us on LinkedIn. As always, please leave a comment below if you have any questions.

Spring Framework Spring Boot JWT (JSON Web Token) Spring Security Web application Requests

Published at DZone with permission of Brian Demers, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Comments

Trending

Trending

Use Both JWT and Opaque Access Tokens With Spring Boot

Should I Validate Access Tokens Locally or Remote?

Validate Access Tokens Locally and Remotely!

Configure Spring Security to Validate JWTs and Opaque Tokens

Better JWT Validation

Configure and Run Your OAuth 2.0 Application

Get a Token With the OIDC Debugger

Learn More About Secure Applications

Trending

Partner Resources