|
It is recommended to be cautious with this feature since all HTTP requests will receive the access token.
Alternatively, if setDefaultClientRegistrationId("okta") is configured with a valid ClientRegistration, the OAuth2AccessToken associated with the OAuth2AuthorizedClient is used.
The following code shows the specific configuration:
@Bean
WebClient webClient(OAuth2AuthorizedClientManager authorizedClientManager) {
ServletOAuth2AuthorizedClientExchangeFilterFunction oauth2Client =
new ServletOAuth2AuthorizedClientExchangeFilterFunction(authorizedClientManager);
oauth2Client.setDefaultClientRegistrationId("okta");
return WebClient.builder()
.apply(oauth2Client.oauth2Configuration())
.build();
![[Warning]](images/warning.png) | Warning |
|---|
|
It is recommended to be cautious with this feature since all HTTP requests will receive the access token.
Spring Security supports protecting endpoints using two forms of OAuth 2.0 Bearer Tokens:
Opaque Tokens
This is handy in circumstances where an application has delegated its authority management to an authorization server (for example, Okta or Ping Identity).
This authorization server can be consulted by resource servers to authorize requests.
Working samples for both JWTs and Opaque Tokens are available in the Spring Security repository.
Most Resource Server support is collected into spring-security-oauth2-resource-server.
However, the support for decoding and verifying JWTs is in spring-security-oauth2-jose, meaning that both are necessary in order to have a working resource server that supports JWT-encoded Bearer Tokens.
When using Spring Boot, configuring an application as a resource server consists of two basic steps.
First, include the needed dependencies and second, indicate the location of the authorization server.
In a Spring Boot application, to specify which authorization server to use, simply do:
spring:
security:
oauth2:
resourceserver:
issuer-uri: https://idp.example.com/issuer
Where https://idp.example.com/issuer is the value contained in the iss claim for JWT tokens that the authorization server will issue.
Resource Server will use this property to further self-configure, discover the authorization server’s public keys, and subsequently validate incoming JWTs.
To use the issuer-uri property, it must also be true that one of https://idp.example.com/issuer/.well-known/openid-configuration, https://idp.example.com/.well-known/openid-configuration/issuer, or https://idp.example.com/.well-known/oauth-authorization-server/issuer is a supported endpoint for the authorization server.
This endpoint is referred to as a Provider Configuration endpoint or a Authorization Server Metadata endpoint.
And that’s it!
When this property and these dependencies are used, Resource Server will automatically configure itself to validate JWT-encoded Bearer Tokens.
It achieves this through a deterministic startup process:
Hit the Provider Configuration or Authorization Server Metadata endpoint, processing the response for the jwks_url property
Configure the validation strategy to query jwks_url for valid public keys
Configure the validation strategy to validate each JWTs iss claim against https://idp.example.com.
A consequence of this process is that the authorization server must be up and receiving requests in order for Resource Server to successfully start up.
If the authorization server is down when Resource Server queries it (given appropriate timeouts), then startup will fail.
Once the application is started up, Resource Server will attempt to process any request containing an Authorization: Bearer header:
GET / HTTP/1.1
Authorization: Bearer some-token-value # Resource Server will process this
So long as this scheme is indicated, Resource Server will attempt to process the request according to the Bearer Token specification.
Given a well-formed JWT, Resource Server will:
Validate its signature against a public key obtained from the jwks_url endpoint during startup and matched against the JWT
Validate the JWT’s exp and nbf timestamps and the JWT’s iss claim, and
Map each scope to an authority with the prefix SCOPE_.
As the authorization server makes available new keys, Spring Security will automatically rotate the keys used to validate JWTs.
The resulting Authentication#getPrincipal, by default, is a Spring Security Jwt object, and Authentication#getName maps to the JWT’s sub property, if one is present.
From here, consider jumping to:
How to Configure without Tying Resource Server startup to an authorization server’s availability
How to Configure without Spring Boot
If the authorization server doesn’t support any configuration endpoints, or if Resource Server must be able to start up independently from the authorization server, then the jwk-set-uri can be supplied as well:
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: https://idp.example.com
jwk-set-uri: https://idp.example.com/.well-known/jwks.json
The JWK Set uri is not standardized, but can typically be found in the authorization server’s documentation
Consequently, Resource Server will not ping the authorization server at startup.
We still specify the issuer-uri so that Resource Server still validates the iss claim on incoming JWTs.
This property can also be supplied directly on the DSL.
There are two @Bean s that Spring Boot generates on Resource Server’s behalf.
The first is a WebSecurityConfigurerAdapter that configures the app as a resource server. When including spring-security-oauth2-jose, this WebSecurityConfigurerAdapter looks like:
protected void configure(HttpSecurity http) {
.authorizeRequests()
.anyRequest().authenticated()
.and()
.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt)
If the application doesn’t expose a WebSecurityConfigurerAdapter bean, then Spring Boot will expose the above default one.
Replacing this is as simple as exposing the bean within the application:
@EnableWebSecurity
public class MyCustomSecurityConfiguration extends WebSecurityConfigurerAdapter {
protected void configure(HttpSecurity http) {
.authorizeRequests()
.mvcMatchers("/messages/**").hasAuthority("SCOPE_message:read")
.anyRequest().authenticated()
.and()
.oauth2ResourceServer()
.jwt()
.jwtAuthenticationConverter(myConverter());
The above requires the scope of message:read for any URL that starts with /messages/.
Methods on the oauth2ResourceServer DSL will also override or replace auto configuration.
For example, the second @Bean Spring Boot creates is a JwtDecoder, which decodes String tokens into validated instances of Jwt:
@Bean
public JwtDecoder jwtDecoder() {
return JwtDecoders.fromIssuerLocation(issuerUri);
Calling JwtDecoders#fromIssuerLocation is what invokes the Provider Configuration or Authorization Server Metadata endpoint in order to derive the JWK Set Uri.
If the application doesn’t expose a JwtDecoder bean, then Spring Boot will expose the above default one.
And its configuration can be overridden using jwkSetUri() or replaced using decoder().
An authorization server’s JWK Set Uri can be configured as a configuration property or it can be supplied in the DSL:
@EnableWebSecurity
public class DirectlyConfiguredJwkSetUri extends WebSecurityConfigurerAdapter {
protected void configure(HttpSecurity http) {
.authorizeRequests()
.anyRequest().authenticated()
.and()
.oauth2ResourceServer()
.jwt()
.jwkSetUri("https://idp.example.com/.well-known/jwks.json");
Using jwkSetUri() takes precedence over any configuration property.
More powerful than jwkSetUri() is decoder(), which will completely replace any Boot auto configuration of JwtDecoder:
@EnableWebSecurity
public class DirectlyConfiguredJwtDecoder extends WebSecurityConfigurerAdapter {
protected void configure(HttpSecurity http) {
.authorizeRequests()
.anyRequest().authenticated()
.and()
.oauth2ResourceServer()
.jwt()
.decoder(myCustomDecoder());
This is handy when deeper configuration, like validation, mapping, or request timeouts, is necessary.
Or, exposing a JwtDecoder @Bean has the same effect as decoder():
@Bean
public JwtDecoder jwtDecoder() {
return NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build();
By default, NimbusJwtDecoder, and hence Resource Server, will only trust and verify tokens using RS256.
You can customize this via Spring Boot, the NimbusJwtDecoder builder, or from the JWK Set response.
The simplest way to set the algorithm is as a property:
spring:
security:
oauth2:
resourceserver:
jwt:
jws-algorithm: RS512
jwk-set-uri: https://idp.example.org/.well-known/jwks.json
For greater power, though, we can use a builder that ships with NimbusJwtDecoder:
@Bean
JwtDecoder jwtDecoder() {
return NimbusJwtDecoder.fromJwkSetUri(this.jwkSetUri)
.jwsAlgorithm(RS512).build();
Calling jwsAlgorithm more than once will configure NimbusJwtDecoder to trust more than one algorithm, like so:
@Bean
JwtDecoder jwtDecoder() {
return NimbusJwtDecoder.fromJwkSetUri(this.jwkSetUri)
.jwsAlgorithm(RS512).jwsAlgorithm(EC512).build();
Or, you can call jwsAlgorithms:
@Bean
JwtDecoder jwtDecoder() {
return NimbusJwtDecoder.fromJwkSetUri(this.jwkSetUri)
.jwsAlgorithms(algorithms -> {
algorithms.add(RS512);
algorithms.add(EC512);
}).build();
Since Spring Security’s JWT support is based off of Nimbus, you can use all it’s great features as well.
For example, Nimbus has a JWSKeySelector implementation that will select the set of algorithms based on the JWK Set URI response.
You can use it to generate a NimbusJwtDecoder like so:
@Bean
public JwtDecoder jwtDecoder() {
JWSKeySelector<SecurityContext> jwsKeySelector =
JWSAlgorithmFamilyJWSKeySelector.fromJWKSetURL(this.jwkSetUrl);
DefaultJWTProcessor<SecurityContext> jwtProcessor =
new DefaultJWTProcessor<>();
jwtProcessor.setJWSKeySelector(jwsKeySelector);
return new NimbusJwtDecoder(jwtProcessor);
Simpler than backing a Resource Server with a JWK Set endpoint is to hard-code an RSA public key.
The public key can be provided via Spring Boot or by Using a Builder.
Specifying a key via Spring Boot is quite simple.
The key’s location can be specified like so:
spring:
security:
oauth2:
resourceserver:
jwt:
public-key-location: classpath:my-key.pub
Or, to allow for a more sophisticated lookup, you can post-process the RsaKeyConversionServicePostProcessor:
@Bean
BeanFactoryPostProcessor conversionServiceCustomizer() {
return beanFactory ->
beanFactory.getBean(RsaKeyConversionServicePostProcessor.class)
.setResourceLoader(new CustomResourceLoader());
Specify your key’s location:
key.location: hfds://my-key.pub
And then autowire the value:
@Value("${key.location}")
RSAPublicKey key;
To wire an RSAPublicKey directly, you can simply use the appropriate NimbusJwtDecoder builder, like so:
@Bean
public JwtDecoder jwtDecoder() {
return NimbusJwtDecoder.withPublicKey(this.key).build();
Using a single symmetric key is also simple.
You can simply load in your SecretKey and use the appropriate NimbusJwtDecoder builder, like so:
@Bean
public JwtDecoder jwtDecoder() {
return NimbusJwtDecoder.withSecretKey(this.key).build();
A JWT that is issued from an OAuth 2.0 Authorization Server will typically either have a scope or scp attribute, indicating the scopes (or authorities) it’s been granted, for example:
{ …, "scope" : "messages contacts"}
When this is the case, Resource Server will attempt to coerce these scopes into a list of granted authorities, prefixing each scope with the string "SCOPE_".
This means that to protect an endpoint or method with a scope derived from a JWT, the corresponding expressions should include this prefix:
@EnableWebSecurity
public class DirectlyConfiguredJwkSetUri extends WebSecurityConfigurerAdapter {
protected void configure(HttpSecurity http) {
.authorizeRequests(authorizeRequests -> authorizeRequests
.mvcMatchers("/contacts/**").hasAuthority("SCOPE_contacts")
.mvcMatchers("/messages/**").hasAuthority("SCOPE_messages")
.anyRequest().authenticated()
.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt);
Or similarly with method security:
@PreAuthorize("hasAuthority('SCOPE_messages')")
public List<Message> getMessages(...) {}
However, there are a number of circumstances where this default is insufficient.
For example, some authorization servers don’t use the scope attribute, but instead have their own custom attribute.
Or, at other times, the resource server may need to adapt the attribute or a composition of attributes into internalized authorities.
To this end, the DSL exposes jwtAuthenticationConverter():
@EnableWebSecurity
public class DirectlyConfiguredJwkSetUri extends WebSecurityConfigurerAdapter {
protected void configure(HttpSecurity http) {
.authorizeRequests()
.anyRequest().authenticated()
.and()
.oauth2ResourceServer()
.jwt()
.jwtAuthenticationConverter(grantedAuthoritiesExtractor());
Converter<Jwt, AbstractAuthenticationToken> grantedAuthoritiesExtractor() {
JwtAuthenticationConverter jwtAuthenticationConverter =
new JwtAuthenticationConverter();
jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter
(new GrantedAuthoritiesExtractor());
return jwtAuthenticationConverter;
which is responsible for converting a Jwt into an Authentication.
As part of its configuration, we can supply a subsidiary converter to go from Jwt to a Collection of granted authorities.
That final converter might be something like GrantedAuthoritiesExtractor below:
static class GrantedAuthoritiesExtractor
implements Converter<Jwt, Collection<GrantedAuthority>> {
public Collection<GrantedAuthority> convert(Jwt jwt) {
Collection<String> authorities = (Collection<String>)
jwt.getClaims().get("mycustomclaim");
return authorities.stream()
.map(SimpleGrantedAuthority::new)
.collect(Collectors.toList());
For more flexibility, the DSL supports entirely replacing the converter with any class that implements Converter<Jwt, AbstractAuthenticationToken>:
static class CustomAuthenticationConverter implements Converter<Jwt, AbstractAuthenticationToken> {
public AbstractAuthenticationToken convert(Jwt jwt) {
return new CustomAuthenticationToken(jwt);
Using minimal Spring Boot configuration, indicating the authorization server’s issuer uri, Resource Server will default to verifying the iss claim as well as the exp and nbf timestamp claims.
In circumstances where validation needs to be customized, Resource Server ships with two standard validators and also accepts custom OAuth2TokenValidator instances.
JWT’s typically have a window of validity, with the start of the window indicated in the nbf claim and the end indicated in the exp claim.
However, every server can experience clock drift, which can cause tokens to appear expired to one server, but not to another.
This can cause some implementation heartburn as the number of collaborating servers increases in a distributed system.
Resource Server uses JwtTimestampValidator to verify a token’s validity window, and it can be configured with a clockSkew to alleviate the above problem:
@Bean
JwtDecoder jwtDecoder() {
NimbusJwtDecoder jwtDecoder = (NimbusJwtDecoder)
JwtDecoders.fromIssuerLocation(issuerUri);
OAuth2TokenValidator<Jwt> withClockSkew = new DelegatingOAuth2TokenValidator<>(
new JwtTimestampValidator(Duration.ofSeconds(60)),
new IssuerValidator(issuerUri));
jwtDecoder.setJwtValidator(withClockSkew);
return jwtDecoder;
By default, Resource Server configures a clock skew of 60 seconds.
Adding a check for the aud claim is simple with the OAuth2TokenValidator API:
public class AudienceValidator implements OAuth2TokenValidator<Jwt> {
OAuth2Error error = new OAuth2Error("invalid_token", "The required audience is missing", null);
public OAuth2TokenValidatorResult validate(Jwt jwt) {
if (jwt.getAudience().contains("messaging")) {
return OAuth2TokenValidatorResult.success();
} else {
return OAuth2TokenValidatorResult.failure(error);
Then, to add into a resource server, it’s a matter of specifying the JwtDecoder instance:
@Bean
JwtDecoder jwtDecoder() {
NimbusJwtDecoder jwtDecoder = (NimbusJwtDecoder)
JwtDecoders.fromIssuerLocation(issuerUri);
OAuth2TokenValidator<Jwt> audienceValidator = new AudienceValidator();
OAuth2TokenValidator<Jwt> withIssuer = JwtValidators.createDefaultWithIssuer(issuerUri);
OAuth2TokenValidator<Jwt> withAudience = new DelegatingOAuth2TokenValidator<>(withIssuer, audienceValidator);
jwtDecoder.setJwtValidator(withAudience);
return jwtDecoder;
Spring Security uses the Nimbus library for parsing JWTs and validating their signatures.
Consequently, Spring Security is subject to Nimbus’s interpretation of each field value and how to coerce each into a Java type.
For example, because Nimbus remains Java 7 compatible, it doesn’t use Instant to represent timestamp fields.
And it’s entirely possible to use a different library or for JWT processing, which may make its own coercion decisions that need adjustment.
Or, quite simply, a resource server may want to add or remove claims from a JWT for domain-specific reasons.
For these purposes, Resource Server supports mapping the JWT claim set with MappedJwtClaimSetConverter.
By default, MappedJwtClaimSetConverter will attempt to coerce claims into the following types:
Claim | Java Type | aud
| Collection<String>
| exp
| Instant
| iat
| Instant
| iss
| String
| jti
| String
| nbf
| Instant
| sub
| String
|
An individual claim’s conversion strategy can be configured using MappedJwtClaimSetConverter.withDefaults:
@Bean
JwtDecoder jwtDecoder() {
NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build();
MappedJwtClaimSetConverter converter = MappedJwtClaimSetConverter
.withDefaults(Collections.singletonMap("sub", this::lookupUserIdBySub));
jwtDecoder.setClaimSetConverter(converter);
return jwtDecoder;
This will keep all the defaults, except it will override the default claim converter for sub.
MappedJwtClaimSetConverter can also be used to add a custom claim, for example, to adapt to an existing system:
MappedJwtClaimSetConverter.withDefaults(Collections.singletonMap("custom", custom -> "value"));
And removing a claim is also simple, using the same API:
MappedJwtClaimSetConverter.withDefaults(Collections.singletonMap("legacyclaim", legacy -> null));
In more sophisticated scenarios, like consulting multiple claims at once or renaming a claim, Resource Server accepts any class that implements Converter<Map<String, Object>, Map<String,Object>>:
public class UsernameSubClaimAdapter implements Converter<Map<String, Object>, Map<String, Object>> {
private final MappedJwtClaimSetConverter delegate =
MappedJwtClaimSetConverter.withDefaults(Collections.emptyMap());
public Map<String, Object> convert(Map<String, Object> claims) {
Map<String, Object> convertedClaims = this.delegate.convert(claims);
String username = (String) convertedClaims.get("user_name");
convertedClaims.put("sub", username);
return convertedClaims;
And then, the instance can be supplied like normal:
@Bean
JwtDecoder jwtDecoder() {
NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build();
jwtDecoder.setClaimSetConverter(new UsernameSubClaimAdapter());
return jwtDecoder;
By default, Resource Server uses connection and socket timeouts of 30 seconds each for coordinating with the authorization server.
This may be too short in some scenarios.
Further, it doesn’t take into account more sophisticated patterns like back-off and discovery.
To adjust the way in which Resource Server connects to the authorization server, NimbusJwtDecoder accepts an instance of RestOperations:
@Bean
public JwtDecoder jwtDecoder(RestTemplateBuilder builder) {
RestOperations rest = builder
.setConnectionTimeout(60000)
.setReadTimeout(60000)
.build();
NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withJwkSetUri(jwkSetUri).restOperations(rest).build();
return jwtDecoder;
Typically, an opaque token can be verified via an OAuth 2.0 Introspection Endpoint, hosted by the authorization server.
This can be handy when revocation is a requirement.
When using Spring Boot, configuring an application as a resource server that uses introspection consists of two basic steps.
First, include the needed dependencies and second, indicate the introspection endpoint details.
To specify where the introspection endpoint is, simply do:
security:
oauth2:
resourceserver:
opaque-token:
introspection-uri: https://idp.example.com/introspect
client-id: client
client-secret: secret
Where https://idp.example.com/introspect is the introspection endpoint hosted by your authorization server and client-id and client-secret are the credentials needed to hit that endpoint.
Resource Server will use these properties to further self-configure and subsequently validate incoming JWTs.
When using introspection, the authorization server’s word is the law.
If the authorization server responses that the token is valid, then it is.
And that’s it!
When this property and these dependencies are used, Resource Server will automatically configure itself to validate Opaque Bearer Tokens.
This startup process is quite a bit simpler than for JWTs since no endpoints need to be discovered and no additional validation rules get added.
Once the application is started up, Resource Server will attempt to process any request containing an Authorization: Bearer header:
GET / HTTP/1.1
Authorization: Bearer some-token-value # Resource Server will process this
So long as this scheme is indicated, Resource Server will attempt to process the request according to the Bearer Token specification.
Given an Opaque Token, Resource Server will
Query the provided introspection endpoint using the provided credentials and the token
Inspect the response for an { 'active' : true } attribute
Map each scope to an authority with the prefix SCOPE_
The resulting Authentication#getPrincipal, by default, is a Spring Security OAuth2AuthenticatedPrincipal object, and Authentication#getName maps to the token’s sub property, if one is present.
From here, you may want to jump to:
Looking Up Attributes Post-Authentication
Extracting Authorities Manually
Using Introspection with JWTs
Once a token is authenticated, an instance of BearerTokenAuthentication is set in the SecurityContext.
This means that it’s available in @Controller methods when using @EnableWebMvc in your configuration:
@GetMapping("/foo")
public String foo(BearerTokenAuthentication authentication) {
return authentication.getTokenAttributes().get("sub") + " is the subject";
Since BearerTokenAuthentication holds an OAuth2AuthenticatedPrincipal, that also means that it’s available to controller methods, too:
@GetMapping("/foo")
public String foo(@AuthenticationPrincipal OAuth2AuthenticatedPrincipal principal) {
return principal.getAttribute("sub") + " is the subject";
Of course, this also means that attributes can be accessed via SpEL.
For example, if using @EnableGlobalMethodSecurity so that you can use @PreAuthorize annotations, you can do:
@PreAuthorize("principal?.attributes['sub'] == 'foo'")
public String forFoosEyesOnly() {
return "foo";
There are two @Bean s that Spring Boot generates on Resource Server’s behalf.
The first is a WebSecurityConfigurerAdapter that configures the app as a resource server.
When use Opaque Token, this WebSecurityConfigurerAdapter looks like:
protected void configure(HttpSecurity http) {
.authorizeRequests()
.anyRequest().authenticated()
.and()
.oauth2ResourceServer(OAuth2ResourceServerConfigurer::opaqueToken)
If the application doesn’t expose a WebSecurityConfigurerAdapter bean, then Spring Boot will expose the above default one.
Replacing this is as simple as exposing the bean within the application:
@EnableWebSecurity
public class MyCustomSecurityConfiguration extends WebSecurityConfigurerAdapter {
protected void configure(HttpSecurity http) {
.authorizeRequests()
.mvcMatchers("/messages/**").hasAuthority("SCOPE_message:read")
.anyRequest().authenticated()
.and()
.oauth2ResourceServer()
.opaqueToken()
.introspector(myIntrospector());
The above requires the scope of message:read for any URL that starts with /messages/.
Methods on the oauth2ResourceServer DSL will also override or replace auto configuration.
For example, the second @Bean Spring Boot creates is an OpaqueTokenIntrospector, which decodes String tokens into validated instances of OAuth2AuthenticatedPrincipal:
@Bean
public OpaqueTokenIntrospector introspector() {
return new NimbusOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
If the application doesn’t expose a OpaqueTokenIntrospector bean, then Spring Boot will expose the above default one.
And its configuration can be overridden using introspectionUri() and introspectionClientCredentials() or replaced using introspector().
An authorization server’s Introspection Uri can be configured as a configuration property or it can be supplied in the DSL:
@EnableWebSecurity
public class DirectlyConfiguredIntrospectionUri extends WebSecurityConfigurerAdapter {
protected void configure(HttpSecurity http) {
.authorizeRequests()
.anyRequest().authenticated()
.and()
.oauth2ResourceServer()
.opaqueToken()
.introspectionUri("https://idp.example.com/introspect")
.introspectionClientCredentials("client", "secret");
Using introspectionUri() takes precedence over any configuration property.
More powerful than introspectionUri() is introspector(), which will completely replace any Boot auto configuration of OpaqueTokenIntrospector:
@EnableWebSecurity
public class DirectlyConfiguredIntrospector extends WebSecurityConfigurerAdapter {
protected void configure(HttpSecurity http) {
.authorizeRequests()
.anyRequest().authenticated()
.and()
.oauth2ResourceServer()
.opaqueToken()
.introspector(myCustomIntrospector());
This is handy when deeper configuration, like authority mapping, JWT revocation, or request timeouts, is necessary.
Or, exposing a OpaqueTokenIntrospector @Bean has the same effect as introspector():
@Bean
public OpaqueTokenIntrospector introspector() {
return new NimbusOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
An OAuth 2.0 Introspection endpoint will typically return a scope attribute, indicating the scopes (or authorities) it’s been granted, for example:
{ …, "scope" : "messages contacts"}
When this is the case, Resource Server will attempt to coerce these scopes into a list of granted authorities, prefixing each scope with the string "SCOPE_".
This means that to protect an endpoint or method with a scope derived from an Opaque Token, the corresponding expressions should include this prefix:
@EnableWebSecurity
public class MappedAuthorities extends WebSecurityConfigurerAdapter {
protected void configure(HttpSecurity http) {
.authorizeRequests(authorizeRequests -> authorizeRequests
.mvcMatchers("/contacts/**").hasAuthority("SCOPE_contacts")
.mvcMatchers("/messages/**").hasAuthority("SCOPE_messages")
.anyRequest().authenticated()
.oauth2ResourceServer(OAuth2ResourceServerConfigurer::opaqueToken);
Or similarly with method security:
@PreAuthorize("hasAuthority('SCOPE_messages')")
public List<Message> getMessages(...) {}
By default, Opaque Token support will extract the scope claim from an introspection response and parse it into individual GrantedAuthority instances.
For example, if the introspection response were:
"active" : true,
"scope" : "message:read message:write"
Then Resource Server would generate an Authentication with two authorities, one for message:read and the other for message:write.
This can, of course, be customized using a custom OpaqueTokenIntrospector that takes a look at the attribute set and converts in its own way:
public class CustomAuthoritiesOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
private OpaqueTokenIntrospector delegate =
new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
public OAuth2AuthenticatedPrincipal introspect(String token) {
OAuth2AuthenticatedPrincipal principal = this.delegate.introspect(token);
return new DefaultOAuth2AuthenticatedPrincipal(
principal.getName(), principal.getAttributes(), extractAuthorities(principal));
private Collection<GrantedAuthority> extractAuthorities(OAuth2AuthenticatedPrincipal principal) {
List<String> scopes = principal.getAttribute(OAuth2IntrospectionClaimNames.SCOPE);
return scopes.stream()
.map(SimpleGrantedAuthority::new)
.collect(Collectors.toList());
Thereafter, this custom introspector can be configured simply by exposing it as a @Bean:
@Bean
public OpaqueTokenIntrospector introspector() {
return new CustomAuthoritiesOpaqueTokenIntrospector();
By default, Resource Server uses connection and socket timeouts of 30 seconds each for coordinating with the authorization server.
This may be too short in some scenarios.
Further, it doesn’t take into account more sophisticated patterns like back-off and discovery.
To adjust the way in which Resource Server connects to the authorization server, NimbusOpaqueTokenIntrospector accepts an instance of RestOperations:
@Bean
public OpaqueTokenIntrospector introspector(RestTemplateBuilder builder) {
RestOperations rest = builder
.basicAuthentication(clientId, clientSecret)
.setConnectionTimeout(60000)
.setReadTimeout(60000)
.build();
return new NimbusOpaqueTokenIntrospector(introspectionUri, rest);
A common question is whether or not introspection is compatible with JWTs.
Spring Security’s Opaque Token support has been designed to not care about the format of the token — it will gladly pass any token to the introspection endpoint provided.
So, let’s say that you’ve got a requirement that requires you to check with the authorization server on each request, in case the JWT has been revoked.
Even though you are using the JWT format for the token, your validation method is introspection, meaning you’d want to do:
spring:
security:
oauth2:
resourceserver:
opaque-token:
introspection-uri: https://idp.example.org/introspection
client-id: client
client-secret: secret
In this case, the resulting Authentication would be BearerTokenAuthentication.
Any attributes in the corresponding OAuth2AuthenticatedPrincipal would be whatever was returned by the introspection endpoint.
But, let’s say that, oddly enough, the introspection endpoint only returns whether or not the token is active.
Now what?
In this case, you can create a custom OpaqueTokenIntrospector that still hits the endpoint, but then updates the returned principal to have the JWTs claims as the attributes:
public class JwtOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
private OpaqueTokenIntrospector delegate =
new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
private JwtDecoder jwtDecoder = new NimbusJwtDecoder(new ParseOnlyJWTProcessor());
public OAuth2AuthenticatedPrincipal introspect(String token) {
OAuth2AuthenticatedPrincipal principal = this.delegate.introspect(token);
try {
Jwt jwt = this.jwtDecoder.decode(token);
return new DefaultOAuth2AuthenticatedPrincipal(jwt.getClaims(), NO_AUTHORITIES);
} catch (JwtException e) {
throw new OAuth2IntrospectionException(e);
private static class ParseOnlyJWTProcessor extends DefaultJWTProcessor<SecurityContext> {
JWTClaimsSet process(SignedJWT jwt, SecurityContext context)
throws JOSEException {
return jwt.getJWTClaimSet();
Thereafter, this custom introspector can be configured simply by exposing it as a @Bean:
@Bean
public OpaqueTokenIntrospector introspector() {
return new JwtOpaqueTokenIntropsector();
Generally speaking, a Resource Server doesn’t care about the underlying user, but instead about the authorities that have been granted.
That said, at times it can be valuable to tie the authorization statement back to a user.
If an application is also using spring-security-oauth2-client, having set up the appropriate ClientRegistrationRepository, then this is quite simple with a custom OpaqueTokenIntrospector.
This implementation below does three things:
Delegates to the introspection endpoint, to affirm the token’s validity
Looks up the appropriate client registration associated with the /userinfo endpoint
Invokes and returns the response from the /userinfo endpoint
public class UserInfoOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
private final OpaqueTokenIntrospector delegate =
new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
private final OAuth2UserService oauth2UserService = new DefaultOAuth2UserService();
private final ClientRegistrationRepository repository;
@Override
public OAuth2AuthenticatedPrincipal introspect(String token) {
OAuth2AuthenticatedPrincipal authorized = this.delegate.introspect(token);
Instant issuedAt = authorized.getAttribute(ISSUED_AT);
Instant expiresAt = authorized.getAttribute(EXPIRES_AT);
ClientRegistration clientRegistration = this.repository.findByRegistrationId("registration-id");
OAuth2AccessToken token = new OAuth2AccessToken(BEARER, token, issuedAt, expiresAt);
OAuth2UserRequest oauth2UserRequest = new OAuth2UserRequest(clientRegistration, token);
return this.oauth2UserService.loadUser(oauth2UserRequest);
If you aren’t using spring-security-oauth2-client, it’s still quite simple.
You will simply need to invoke the /userinfo with your own instance of WebClient:
public class UserInfoOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
private final OpaqueTokenIntrospector delegate =
new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
private final WebClient rest = WebClient.create();
@Override
public OAuth2AuthenticatedPrincipal introspect(String token) {
OAuth2AuthenticatedPrincipal authorized = this.delegate.introspect(token);
return makeUserInfoRequest(authorized);
Either way, having created your OpaqueTokenIntrospector, you should publish it as a @Bean to override the defaults:
@Bean
OpaqueTokenIntrospector introspector() {
return new UserInfoOpaqueTokenIntrospector(...);
|
|
![[Important]](images/important.png)
