mirror of
https://github.com/spring-projects/spring-security.git
synced 2025-10-27 12:48:44 +00:00
1643 lines
48 KiB
Plaintext
1643 lines
48 KiB
Plaintext
= OAuth 2.0 Resource Server JWT
|
|
:figures: servlet/oauth2
|
|
|
|
[[oauth2resourceserver-jwt-minimaldependencies]]
|
|
== Minimal Dependencies for JWT
|
|
|
|
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.
|
|
|
|
[[oauth2resourceserver-jwt-minimalconfiguration]]
|
|
== Minimal Configuration for JWTs
|
|
|
|
When using https://spring.io/projects/spring-boot[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.
|
|
|
|
=== Specifying the Authorization Server
|
|
|
|
In a Spring Boot application, to specify which authorization server to use, simply do:
|
|
|
|
[source,yml]
|
|
----
|
|
spring:
|
|
security:
|
|
oauth2:
|
|
resourceserver:
|
|
jwt:
|
|
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.
|
|
|
|
[NOTE]
|
|
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 https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[Provider Configuration] endpoint or a https://tools.ietf.org/html/rfc8414#section-3[Authorization Server Metadata] endpoint.
|
|
|
|
And that's it!
|
|
|
|
=== Startup Expectations
|
|
|
|
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:
|
|
|
|
1. Query the Provider Configuration or Authorization Server Metadata endpoint for the `jwks_url` property
|
|
2. Query the `jwks_url` endpoint for supported algorithms
|
|
3. Configure the validation strategy to query `jwks_url` for valid public keys of the algorithms found
|
|
4. 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.
|
|
|
|
[NOTE]
|
|
If the authorization server is down when Resource Server queries it (given appropriate timeouts), then startup will fail.
|
|
|
|
=== Runtime Expectations
|
|
|
|
Once the application is started up, Resource Server will attempt to process any request containing an `Authorization: Bearer` header:
|
|
|
|
[source,html]
|
|
----
|
|
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:
|
|
|
|
1. Validate its signature against a public key obtained from the `jwks_url` endpoint during startup and matched against the JWT
|
|
2. Validate the JWT's `exp` and `nbf` timestamps and the JWT's `iss` claim, and
|
|
3. Map each scope to an authority with the prefix `SCOPE_`.
|
|
|
|
[NOTE]
|
|
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:
|
|
|
|
* <<oauth2resourceserver-jwt-architecture,How JWT Authentication Works>>
|
|
* <<oauth2resourceserver-jwt-jwkseturi,How to Configure without tying Resource Server startup to an authorization server's availability>>
|
|
* <<oauth2resourceserver-jwt-sansboot,How to Configure without Spring Boot>>
|
|
|
|
[[oauth2resourceserver-jwt-architecture]]
|
|
== How JWT Authentication Works
|
|
|
|
Next, let's see the architectural components that Spring Security uses to support https://tools.ietf.org/html/rfc7519[JWT] Authentication in servlet-based applications, like the one we just saw.
|
|
|
|
javadoc:org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationProvider[] is an xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationprovider[`AuthenticationProvider`] implementation that leverages a <<oauth2resourceserver-jwt-decoder,`JwtDecoder`>> and <<oauth2resourceserver-jwt-authorization-extraction,`JwtAuthenticationConverter`>> to authenticate a JWT.
|
|
|
|
Let's take a look at how `JwtAuthenticationProvider` works within Spring Security.
|
|
The figure explains details of how the xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationmanager[`AuthenticationManager`] in figures from xref:servlet/oauth2/resource-server/index.adoc#oauth2resourceserver-authentication-bearertokenauthenticationfilter[Reading the Bearer Token] works.
|
|
|
|
.`JwtAuthenticationProvider` Usage
|
|
[.invert-dark]
|
|
image::{figures}/jwtauthenticationprovider.png[]
|
|
|
|
image:{icondir}/number_1.png[] The authentication `Filter` from xref:servlet/oauth2/resource-server/index.adoc#oauth2resourceserver-authentication-bearertokenauthenticationfilter[Reading the Bearer Token] passes a `BearerTokenAuthenticationToken` to the `AuthenticationManager` which is implemented by xref:servlet/authentication/architecture.adoc#servlet-authentication-providermanager[`ProviderManager`].
|
|
|
|
image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationprovider[AuthenticationProvider] of type `JwtAuthenticationProvider`.
|
|
|
|
[[oauth2resourceserver-jwt-architecture-jwtdecoder]]
|
|
image:{icondir}/number_3.png[] `JwtAuthenticationProvider` decodes, verifies, and validates the `Jwt` using a <<oauth2resourceserver-jwt-decoder,`JwtDecoder`>>.
|
|
|
|
[[oauth2resourceserver-jwt-architecture-jwtauthenticationconverter]]
|
|
image:{icondir}/number_4.png[] `JwtAuthenticationProvider` then uses the <<oauth2resourceserver-jwt-authorization-extraction,`JwtAuthenticationConverter`>> to convert the `Jwt` into a `Collection` of granted authorities.
|
|
|
|
image:{icondir}/number_5.png[] When authentication is successful, the xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[`Authentication`] that is returned is of type `JwtAuthenticationToken` and has a principal that is the `Jwt` returned by the configured `JwtDecoder`.
|
|
Ultimately, the returned `JwtAuthenticationToken` will be set on the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`] by the authentication `Filter`.
|
|
|
|
[[oauth2resourceserver-jwt-jwkseturi]]
|
|
== Specifying the Authorization Server JWK Set Uri Directly
|
|
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
spring:
|
|
security:
|
|
oauth2:
|
|
resourceserver:
|
|
jwt:
|
|
issuer-uri: https://idp.example.com
|
|
jwk-set-uri: https://idp.example.com/.well-known/jwks.json
|
|
----
|
|
|
|
[NOTE]
|
|
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.
|
|
|
|
[NOTE]
|
|
This property can also be supplied directly on the <<oauth2resourceserver-jwt-jwkseturi-dsl,DSL>>.
|
|
|
|
== Supplying Audiences
|
|
|
|
As already seen, the <<_specifying_the_authorization_server, `issuer-uri` property validates the `iss` claim>>; this is who sent the JWT.
|
|
|
|
Boot also has the `audiences` property for validating the `aud` claim; this is who the JWT was sent to.
|
|
|
|
A resource server's audience can be indicated like so:
|
|
|
|
[source,yaml]
|
|
----
|
|
spring:
|
|
security:
|
|
oauth2:
|
|
resourceserver:
|
|
jwt:
|
|
issuer-uri: https://idp.example.com
|
|
audiences: https://my-resource-server.example.com
|
|
----
|
|
|
|
[NOTE]
|
|
You can also add <<oauth2resourceserver-jwt-validation-custom, the `aud` validation programmatically>>, if needed.
|
|
|
|
The result will be that if the JWT's `iss` claim is not `https://idp.example.com`, and its `aud` claim does not contain `https://my-resource-server.example.com` in its list, then validation will fail.
|
|
|
|
[[oauth2resourceserver-jwt-sansboot]]
|
|
== Overriding or Replacing Boot Auto Configuration
|
|
|
|
There are two ``@Bean``s that Spring Boot generates on Resource Server's behalf.
|
|
|
|
The first is a `SecurityFilterChain` that configures the app as a resource server. When including `spring-security-oauth2-jose`, this `SecurityFilterChain` looks like:
|
|
|
|
.Default JWT Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
|
|
http
|
|
.authorizeHttpRequests(authorize -> authorize
|
|
.anyRequest().authenticated()
|
|
)
|
|
.oauth2ResourceServer((oauth2) -> oauth2.jwt(Customizer.withDefaults()));
|
|
return http.build();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
|
|
http {
|
|
authorizeRequests {
|
|
authorize(anyRequest, authenticated)
|
|
}
|
|
oauth2ResourceServer {
|
|
jwt { }
|
|
}
|
|
}
|
|
return http.build()
|
|
}
|
|
----
|
|
======
|
|
|
|
If the application doesn't expose a `SecurityFilterChain` bean, then Spring Boot will expose the above default one.
|
|
|
|
Replacing this is as simple as exposing the bean within the application:
|
|
|
|
.Custom JWT Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
import static org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope;
|
|
|
|
@Configuration
|
|
@EnableWebSecurity
|
|
public class MyCustomSecurityConfiguration {
|
|
@Bean
|
|
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
|
|
http
|
|
.authorizeHttpRequests(authorize -> authorize
|
|
.requestMatchers("/messages/**").access(hasScope("message:read"))
|
|
.anyRequest().authenticated()
|
|
)
|
|
.oauth2ResourceServer(oauth2 -> oauth2
|
|
.jwt(jwt -> jwt
|
|
.jwtAuthenticationConverter(myConverter())
|
|
)
|
|
);
|
|
return http.build();
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
import org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope
|
|
|
|
@Configuration
|
|
@EnableWebSecurity
|
|
class MyCustomSecurityConfiguration {
|
|
@Bean
|
|
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
|
|
http {
|
|
authorizeRequests {
|
|
authorize("/messages/**", hasScope("message:read"))
|
|
authorize(anyRequest, authenticated)
|
|
}
|
|
oauth2ResourceServer {
|
|
jwt {
|
|
jwtAuthenticationConverter = myConverter()
|
|
}
|
|
}
|
|
}
|
|
return http.build()
|
|
}
|
|
}
|
|
----
|
|
======
|
|
|
|
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.
|
|
|
|
[[oauth2resourceserver-jwt-decoder]]
|
|
For example, the second `@Bean` Spring Boot creates is a `JwtDecoder`, which <<oauth2resourceserver-jwt-architecture-jwtdecoder,decodes `String` tokens into validated instances of `Jwt`>>:
|
|
|
|
.JWT Decoder
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public JwtDecoder jwtDecoder() {
|
|
return JwtDecoders.fromIssuerLocation(issuerUri);
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
return JwtDecoders.fromIssuerLocation(issuerUri)
|
|
}
|
|
----
|
|
======
|
|
|
|
[NOTE]
|
|
Calling javadoc:org.springframework.security.oauth2.jwt.JwtDecoders#fromIssuerLocation-java.lang.String-[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()`.
|
|
|
|
Or, if you're not using Spring Boot at all, then both of these components - the filter chain and a `JwtDecoder` can be specified in XML.
|
|
|
|
The filter chain is specified like so:
|
|
|
|
.Default JWT Configuration
|
|
[tabs]
|
|
======
|
|
Xml::
|
|
+
|
|
[source,xml,role="primary"]
|
|
----
|
|
<http>
|
|
<intercept-uri pattern="/**" access="authenticated"/>
|
|
<oauth2-resource-server>
|
|
<jwt decoder-ref="jwtDecoder"/>
|
|
</oauth2-resource-server>
|
|
</http>
|
|
----
|
|
======
|
|
|
|
And the `JwtDecoder` like so:
|
|
|
|
.JWT Decoder
|
|
[tabs]
|
|
======
|
|
Xml::
|
|
+
|
|
[source,xml,role="primary"]
|
|
----
|
|
<bean id="jwtDecoder"
|
|
class="org.springframework.security.oauth2.jwt.JwtDecoders"
|
|
factory-method="fromIssuerLocation">
|
|
<constructor-arg value="${spring.security.oauth2.resourceserver.jwt.jwk-set-uri}"/>
|
|
</bean>
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-jwkseturi-dsl]]
|
|
=== Using `jwkSetUri()`
|
|
|
|
An authorization server's JWK Set Uri can be configured <<oauth2resourceserver-jwt-jwkseturi,as a configuration property>> or it can be supplied in the DSL:
|
|
|
|
.JWK Set Uri Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Configuration
|
|
@EnableWebSecurity
|
|
public class DirectlyConfiguredJwkSetUri {
|
|
@Bean
|
|
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
|
|
http
|
|
.authorizeHttpRequests(authorize -> authorize
|
|
.anyRequest().authenticated()
|
|
)
|
|
.oauth2ResourceServer(oauth2 -> oauth2
|
|
.jwt(jwt -> jwt
|
|
.jwkSetUri("https://idp.example.com/.well-known/jwks.json")
|
|
)
|
|
);
|
|
return http.build();
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Configuration
|
|
@EnableWebSecurity
|
|
class DirectlyConfiguredJwkSetUri {
|
|
@Bean
|
|
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
|
|
http {
|
|
authorizeRequests {
|
|
authorize(anyRequest, authenticated)
|
|
}
|
|
oauth2ResourceServer {
|
|
jwt {
|
|
jwkSetUri = "https://idp.example.com/.well-known/jwks.json"
|
|
}
|
|
}
|
|
}
|
|
return http.build()
|
|
}
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
<http>
|
|
<intercept-uri pattern="/**" access="authenticated"/>
|
|
<oauth2-resource-server>
|
|
<jwt jwk-set-uri="https://idp.example.com/.well-known/jwks.json"/>
|
|
</oauth2-resource-server>
|
|
</http>
|
|
----
|
|
======
|
|
|
|
Using `jwkSetUri()` takes precedence over any configuration property.
|
|
|
|
[[oauth2resourceserver-jwt-decoder-dsl]]
|
|
=== Using `decoder()`
|
|
|
|
More powerful than `jwkSetUri()` is `decoder()`, which will completely replace any Boot auto configuration of <<oauth2resourceserver-jwt-architecture-jwtdecoder,`JwtDecoder`>>:
|
|
|
|
.JWT Decoder Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Configuration
|
|
@EnableWebSecurity
|
|
public class DirectlyConfiguredJwtDecoder {
|
|
@Bean
|
|
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
|
|
http
|
|
.authorizeHttpRequests(authorize -> authorize
|
|
.anyRequest().authenticated()
|
|
)
|
|
.oauth2ResourceServer(oauth2 -> oauth2
|
|
.jwt(jwt -> jwt
|
|
.decoder(myCustomDecoder())
|
|
)
|
|
);
|
|
return http.build();
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Configuration
|
|
@EnableWebSecurity
|
|
class DirectlyConfiguredJwtDecoder {
|
|
@Bean
|
|
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
|
|
http {
|
|
authorizeRequests {
|
|
authorize(anyRequest, authenticated)
|
|
}
|
|
oauth2ResourceServer {
|
|
jwt {
|
|
jwtDecoder = myCustomDecoder()
|
|
}
|
|
}
|
|
}
|
|
return http.build()
|
|
}
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
<http>
|
|
<intercept-uri pattern="/**" access="authenticated"/>
|
|
<oauth2-resource-server>
|
|
<jwt decoder-ref="myCustomDecoder"/>
|
|
</oauth2-resource-server>
|
|
</http>
|
|
----
|
|
======
|
|
|
|
This is handy when deeper configuration, like <<oauth2resourceserver-jwt-validation,validation>>, <<oauth2resourceserver-jwt-claimsetmapping,mapping>>, or <<oauth2resourceserver-jwt-timeouts,request timeouts>>, is necessary.
|
|
|
|
[[oauth2resourceserver-jwt-decoder-bean]]
|
|
=== Exposing a `JwtDecoder` `@Bean`
|
|
|
|
Or, exposing a <<oauth2resourceserver-jwt-architecture-jwtdecoder,`JwtDecoder`>> `@Bean` has the same effect as `decoder()`.
|
|
You can construct one with a `jwkSetUri` like so:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public JwtDecoder jwtDecoder() {
|
|
return NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
return NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build()
|
|
}
|
|
----
|
|
======
|
|
|
|
or you can use the issuer and have `NimbusJwtDecoder` look up the `jwkSetUri` when `build()` is invoked, like the following:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public JwtDecoder jwtDecoder() {
|
|
return NimbusJwtDecoder.withIssuerLocation(issuer).build();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
return NimbusJwtDecoder.withIssuerLocation(issuer).build()
|
|
}
|
|
----
|
|
======
|
|
|
|
Or, if the defaults work for you, you can also use `JwtDecoders`, which does the above in addition to configuring the decoder's validator:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public JwtDecoders jwtDecoder() {
|
|
return JwtDecoders.fromIssuerLocation(issuer);
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoders {
|
|
return JwtDecoders.fromIssuerLocation(issuer)
|
|
}
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-decoder-algorithm]]
|
|
== Configuring Trusted Algorithms
|
|
|
|
By default, `NimbusJwtDecoder`, and hence Resource Server, will only trust and verify tokens using `RS256`.
|
|
|
|
You can customize this via <<oauth2resourceserver-jwt-boot-algorithm,Spring Boot>>, <<oauth2resourceserver-jwt-decoder-builder,the NimbusJwtDecoder builder>>, or from the <<oauth2resourceserver-jwt-decoder-jwk-response,JWK Set response>>.
|
|
|
|
[[oauth2resourceserver-jwt-boot-algorithm]]
|
|
=== Via Spring Boot
|
|
|
|
The simplest way to set the algorithm is as a property:
|
|
|
|
[source,yaml]
|
|
----
|
|
spring:
|
|
security:
|
|
oauth2:
|
|
resourceserver:
|
|
jwt:
|
|
jws-algorithms: RS512
|
|
jwk-set-uri: https://idp.example.org/.well-known/jwks.json
|
|
----
|
|
|
|
[[oauth2resourceserver-jwt-decoder-builder]]
|
|
=== Using a Builder
|
|
|
|
For greater power, though, we can use a builder that ships with `NimbusJwtDecoder`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
JwtDecoder jwtDecoder() {
|
|
return NimbusJwtDecoder.withIssuerLocation(this.issuer)
|
|
.jwsAlgorithm(RS512).build();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
return NimbusJwtDecoder.withIssuerLocation(this.issuer)
|
|
.jwsAlgorithm(RS512).build()
|
|
}
|
|
----
|
|
======
|
|
|
|
Calling `jwsAlgorithm` more than once will configure `NimbusJwtDecoder` to trust more than one algorithm, like so:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
JwtDecoder jwtDecoder() {
|
|
return NimbusJwtDecoder.withIssuerLocation(this.issuer)
|
|
.jwsAlgorithm(RS512).jwsAlgorithm(ES512).build();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
return NimbusJwtDecoder.withIssuerLocation(this.issuer)
|
|
.jwsAlgorithm(RS512).jwsAlgorithm(ES512).build()
|
|
}
|
|
----
|
|
======
|
|
|
|
Or, you can call `jwsAlgorithms`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
JwtDecoder jwtDecoder() {
|
|
return NimbusJwtDecoder.withIssuerLocation(this.issuer)
|
|
.jwsAlgorithms(algorithms -> {
|
|
algorithms.add(RS512);
|
|
algorithms.add(ES512);
|
|
}).build();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
return NimbusJwtDecoder.withIssuerLocation(this.issuer)
|
|
.jwsAlgorithms {
|
|
it.add(RS512)
|
|
it.add(ES512)
|
|
}.build()
|
|
}
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-decoder-jwk-response]]
|
|
=== From JWK Set response
|
|
|
|
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:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public JwtDecoder jwtDecoder() {
|
|
// makes a request to the JWK Set endpoint
|
|
JWSKeySelector<SecurityContext> jwsKeySelector =
|
|
JWSAlgorithmFamilyJWSKeySelector.fromJWKSetURL(this.jwkSetUrl);
|
|
|
|
DefaultJWTProcessor<SecurityContext> jwtProcessor =
|
|
new DefaultJWTProcessor<>();
|
|
jwtProcessor.setJWSKeySelector(jwsKeySelector);
|
|
|
|
return new NimbusJwtDecoder(jwtProcessor);
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
// makes a request to the JWK Set endpoint
|
|
val jwsKeySelector: JWSKeySelector<SecurityContext> = JWSAlgorithmFamilyJWSKeySelector.fromJWKSetURL<SecurityContext>(this.jwkSetUrl)
|
|
val jwtProcessor: DefaultJWTProcessor<SecurityContext> = DefaultJWTProcessor()
|
|
jwtProcessor.jwsKeySelector = jwsKeySelector
|
|
return NimbusJwtDecoder(jwtProcessor)
|
|
}
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-decoder-public-key]]
|
|
== Trusting a Single Asymmetric Key
|
|
|
|
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 <<oauth2resourceserver-jwt-decoder-public-key-boot,Spring Boot>> or by <<oauth2resourceserver-jwt-decoder-public-key-builder,Using a Builder>>.
|
|
|
|
[[oauth2resourceserver-jwt-decoder-public-key-boot]]
|
|
=== Via Spring Boot
|
|
|
|
Specifying a key via Spring Boot is quite simple.
|
|
The key's location can be specified like so:
|
|
|
|
[source,yaml]
|
|
----
|
|
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`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
BeanFactoryPostProcessor conversionServiceCustomizer() {
|
|
return beanFactory ->
|
|
beanFactory.getBean(RsaKeyConversionServicePostProcessor.class)
|
|
.setResourceLoader(new CustomResourceLoader());
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun conversionServiceCustomizer(): BeanFactoryPostProcessor {
|
|
return BeanFactoryPostProcessor { beanFactory ->
|
|
beanFactory.getBean<RsaKeyConversionServicePostProcessor>()
|
|
.setResourceLoader(CustomResourceLoader())
|
|
}
|
|
}
|
|
----
|
|
======
|
|
|
|
Specify your key's location:
|
|
|
|
[source,yaml]
|
|
----
|
|
key.location: hfds://my-key.pub
|
|
----
|
|
|
|
And then autowire the value:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Value("${key.location}")
|
|
RSAPublicKey key;
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Value("\${key.location}")
|
|
val key: RSAPublicKey? = null
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-decoder-public-key-builder]]
|
|
=== Using a Builder
|
|
|
|
To wire an `RSAPublicKey` directly, you can simply use the appropriate `NimbusJwtDecoder` builder, like so:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public JwtDecoder jwtDecoder() {
|
|
return NimbusJwtDecoder.withPublicKey(this.key).build();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
return NimbusJwtDecoder.withPublicKey(this.key).build()
|
|
}
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-decoder-secret-key]]
|
|
== Trusting a Single Symmetric Key
|
|
|
|
Using a single symmetric key is also simple.
|
|
You can simply load in your `SecretKey` and use the appropriate `NimbusJwtDecoder` builder, like so:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public JwtDecoder jwtDecoder() {
|
|
return NimbusJwtDecoder.withSecretKey(this.key).build();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
return NimbusJwtDecoder.withSecretKey(key).build()
|
|
}
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-authorization]]
|
|
== Configuring Authorization
|
|
|
|
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:
|
|
|
|
.Authorization Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
import static org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope;
|
|
|
|
@Configuration
|
|
@EnableWebSecurity
|
|
public class DirectlyConfiguredJwkSetUri {
|
|
@Bean
|
|
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
|
|
http
|
|
.authorizeHttpRequests(authorize -> authorize
|
|
.requestMatchers("/contacts/**").access(hasScope("contacts"))
|
|
.requestMatchers("/messages/**").access(hasScope("messages"))
|
|
.anyRequest().authenticated()
|
|
)
|
|
.oauth2ResourceServer(oauth2 -> oauth2
|
|
.jwt(Customizer.withDefaults())
|
|
);
|
|
return http.build();
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
import org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope;
|
|
|
|
@Configuration
|
|
@EnableWebSecurity
|
|
class DirectlyConfiguredJwkSetUri {
|
|
@Bean
|
|
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
|
|
http {
|
|
authorizeRequests {
|
|
authorize("/contacts/**", hasScope("contacts"))
|
|
authorize("/messages/**", hasScope("messages"))
|
|
authorize(anyRequest, authenticated)
|
|
}
|
|
oauth2ResourceServer {
|
|
jwt { }
|
|
}
|
|
}
|
|
return http.build()
|
|
}
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
<http>
|
|
<intercept-uri pattern="/contacts/**" access="hasAuthority('SCOPE_contacts')"/>
|
|
<intercept-uri pattern="/messages/**" access="hasAuthority('SCOPE_messages')"/>
|
|
<oauth2-resource-server>
|
|
<jwt jwk-set-uri="https://idp.example.org/.well-known/jwks.json"/>
|
|
</oauth2-resource-server>
|
|
</http>
|
|
----
|
|
======
|
|
|
|
Or similarly with method security:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@PreAuthorize("hasAuthority('SCOPE_messages')")
|
|
public List<Message> getMessages(...) {}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@PreAuthorize("hasAuthority('SCOPE_messages')")
|
|
fun getMessages(): List<Message> { }
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-authorization-extraction]]
|
|
=== Extracting Authorities Manually
|
|
|
|
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, Spring Security ships with `JwtAuthenticationConverter`, which is responsible for <<oauth2resourceserver-jwt-architecture-jwtauthenticationconverter,converting a `Jwt` into an `Authentication`>>.
|
|
By default, Spring Security will wire the `JwtAuthenticationProvider` with a default instance of `JwtAuthenticationConverter`.
|
|
|
|
As part of configuring a `JwtAuthenticationConverter`, you can supply a subsidiary converter to go from `Jwt` to a `Collection` of granted authorities.
|
|
|
|
Let's say that that your authorization server communicates authorities in a custom claim called `authorities`.
|
|
In that case, you can configure the claim that <<oauth2resourceserver-jwt-architecture-jwtauthenticationconverter,`JwtAuthenticationConverter`>> should inspect, like so:
|
|
|
|
.Authorities Claim Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public JwtAuthenticationConverter jwtAuthenticationConverter() {
|
|
JwtGrantedAuthoritiesConverter grantedAuthoritiesConverter = new JwtGrantedAuthoritiesConverter();
|
|
grantedAuthoritiesConverter.setAuthoritiesClaimName("authorities");
|
|
|
|
JwtAuthenticationConverter jwtAuthenticationConverter = new JwtAuthenticationConverter();
|
|
jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter);
|
|
return jwtAuthenticationConverter;
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtAuthenticationConverter(): JwtAuthenticationConverter {
|
|
val grantedAuthoritiesConverter = JwtGrantedAuthoritiesConverter()
|
|
grantedAuthoritiesConverter.setAuthoritiesClaimName("authorities")
|
|
|
|
val jwtAuthenticationConverter = JwtAuthenticationConverter()
|
|
jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter)
|
|
return jwtAuthenticationConverter
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
<http>
|
|
<intercept-uri pattern="/contacts/**" access="hasAuthority('SCOPE_contacts')"/>
|
|
<intercept-uri pattern="/messages/**" access="hasAuthority('SCOPE_messages')"/>
|
|
<oauth2-resource-server>
|
|
<jwt jwk-set-uri="https://idp.example.org/.well-known/jwks.json"
|
|
jwt-authentication-converter-ref="jwtAuthenticationConverter"/>
|
|
</oauth2-resource-server>
|
|
</http>
|
|
|
|
<bean id="jwtAuthenticationConverter"
|
|
class="org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter">
|
|
<property name="jwtGrantedAuthoritiesConverter" ref="jwtGrantedAuthoritiesConverter"/>
|
|
</bean>
|
|
|
|
<bean id="jwtGrantedAuthoritiesConverter"
|
|
class="org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter">
|
|
<property name="authoritiesClaimName" value="authorities"/>
|
|
</bean>
|
|
----
|
|
======
|
|
|
|
You can also configure the authority prefix to be different as well.
|
|
Instead of prefixing each authority with `SCOPE_`, you can change it to `ROLE_` like so:
|
|
|
|
.Authorities Prefix Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public JwtAuthenticationConverter jwtAuthenticationConverter() {
|
|
JwtGrantedAuthoritiesConverter grantedAuthoritiesConverter = new JwtGrantedAuthoritiesConverter();
|
|
grantedAuthoritiesConverter.setAuthorityPrefix("ROLE_");
|
|
|
|
JwtAuthenticationConverter jwtAuthenticationConverter = new JwtAuthenticationConverter();
|
|
jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter);
|
|
return jwtAuthenticationConverter;
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtAuthenticationConverter(): JwtAuthenticationConverter {
|
|
val grantedAuthoritiesConverter = JwtGrantedAuthoritiesConverter()
|
|
grantedAuthoritiesConverter.setAuthorityPrefix("ROLE_")
|
|
|
|
val jwtAuthenticationConverter = JwtAuthenticationConverter()
|
|
jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter)
|
|
return jwtAuthenticationConverter
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
<http>
|
|
<intercept-uri pattern="/contacts/**" access="hasAuthority('SCOPE_contacts')"/>
|
|
<intercept-uri pattern="/messages/**" access="hasAuthority('SCOPE_messages')"/>
|
|
<oauth2-resource-server>
|
|
<jwt jwk-set-uri="https://idp.example.org/.well-known/jwks.json"
|
|
jwt-authentication-converter-ref="jwtAuthenticationConverter"/>
|
|
</oauth2-resource-server>
|
|
</http>
|
|
|
|
<bean id="jwtAuthenticationConverter"
|
|
class="org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter">
|
|
<property name="jwtGrantedAuthoritiesConverter" ref="jwtGrantedAuthoritiesConverter"/>
|
|
</bean>
|
|
|
|
<bean id="jwtGrantedAuthoritiesConverter"
|
|
class="org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter">
|
|
<property name="authorityPrefix" value="ROLE_"/>
|
|
</bean>
|
|
----
|
|
======
|
|
|
|
Or, you can remove the prefix altogether by calling `JwtGrantedAuthoritiesConverter#setAuthorityPrefix("")`.
|
|
|
|
For more flexibility, the DSL supports entirely replacing the converter with any class that implements `Converter<Jwt, AbstractAuthenticationToken>`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
static class CustomAuthenticationConverter implements Converter<Jwt, AbstractAuthenticationToken> {
|
|
public AbstractAuthenticationToken convert(Jwt jwt) {
|
|
return new CustomAuthenticationToken(jwt);
|
|
}
|
|
}
|
|
|
|
// ...
|
|
|
|
@Configuration
|
|
@EnableWebSecurity
|
|
public class CustomAuthenticationConverterConfig {
|
|
@Bean
|
|
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
|
|
http
|
|
.authorizeHttpRequests(authorize -> authorize
|
|
.anyRequest().authenticated()
|
|
)
|
|
.oauth2ResourceServer(oauth2 -> oauth2
|
|
.jwt(jwt -> jwt
|
|
.jwtAuthenticationConverter(new CustomAuthenticationConverter())
|
|
)
|
|
);
|
|
return http.build();
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
internal class CustomAuthenticationConverter : Converter<Jwt, AbstractAuthenticationToken> {
|
|
override fun convert(jwt: Jwt): AbstractAuthenticationToken {
|
|
return CustomAuthenticationToken(jwt)
|
|
}
|
|
}
|
|
|
|
// ...
|
|
|
|
@Configuration
|
|
@EnableWebSecurity
|
|
class CustomAuthenticationConverterConfig {
|
|
@Bean
|
|
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
|
|
http {
|
|
authorizeRequests {
|
|
authorize(anyRequest, authenticated)
|
|
}
|
|
oauth2ResourceServer {
|
|
jwt {
|
|
jwtAuthenticationConverter = CustomAuthenticationConverter()
|
|
}
|
|
}
|
|
}
|
|
return http.build()
|
|
}
|
|
}
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-validation]]
|
|
== Configuring Validation
|
|
|
|
Using <<oauth2resourceserver-jwt-minimalconfiguration,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.
|
|
|
|
[[oauth2resourceserver-jwt-validation-clockskew]]
|
|
=== Customizing Timestamp Validation
|
|
|
|
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:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
JwtDecoder jwtDecoder() {
|
|
NimbusJwtDecoder jwtDecoder = (NimbusJwtDecoder)
|
|
JwtDecoders.fromIssuerLocation(issuerUri);
|
|
|
|
OAuth2TokenValidator<Jwt> withClockSkew = new DelegatingOAuth2TokenValidator<>(
|
|
new JwtTimestampValidator(Duration.ofSeconds(60)),
|
|
new JwtIssuerValidator(issuerUri));
|
|
|
|
jwtDecoder.setJwtValidator(withClockSkew);
|
|
|
|
return jwtDecoder;
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
val jwtDecoder: NimbusJwtDecoder = JwtDecoders.fromIssuerLocation(issuerUri) as NimbusJwtDecoder
|
|
|
|
val withClockSkew: OAuth2TokenValidator<Jwt> = DelegatingOAuth2TokenValidator(
|
|
JwtTimestampValidator(Duration.ofSeconds(60)),
|
|
JwtIssuerValidator(issuerUri))
|
|
|
|
jwtDecoder.setJwtValidator(withClockSkew)
|
|
|
|
return jwtDecoder
|
|
}
|
|
----
|
|
======
|
|
|
|
[NOTE]
|
|
By default, Resource Server configures a clock skew of 60 seconds.
|
|
|
|
[[oauth2resourceserver-jwt-validation-rfc9068]]
|
|
=== Configuring RFC 9068 Validation
|
|
|
|
If you need to require tokens that meet https://datatracker.ietf.org/doc/rfc9068/[RFC 9068], you can configure validation in the following way:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
JwtDecoder jwtDecoder() {
|
|
NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withIssuerLocation(issuerUri)
|
|
.validateTypes(false).build();
|
|
jwtDecoder.setJwtValidator(JwtValidators.createAtJwtValidator()
|
|
.audience("https://audience.example.org")
|
|
.clientId("client-identifier")
|
|
.issuer("https://issuer.example.org").build());
|
|
return jwtDecoder;
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
val jwtDecoder = NimbusJwtDecoder.withIssuerLocation(issuerUri)
|
|
.validateTypes(false).build()
|
|
jwtDecoder.setJwtValidator(JwtValidators.createAtJwtValidator()
|
|
.audience("https://audience.example.org")
|
|
.clientId("client-identifier")
|
|
.issuer("https://issuer.example.org").build())
|
|
return jwtDecoder
|
|
}
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-validation-custom]]
|
|
=== Configuring a Custom Validator
|
|
|
|
Adding a check for <<_supplying_audiences, the `aud` claim>> is simple with the `OAuth2TokenValidator` API:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
OAuth2TokenValidator<Jwt> audienceValidator() {
|
|
return new JwtClaimValidator<List<String>>(AUD, aud -> aud.contains("messaging"));
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
fun audienceValidator(): OAuth2TokenValidator<Jwt?> {
|
|
return JwtClaimValidator<List<String>>(AUD) { aud -> aud.contains("messaging") }
|
|
}
|
|
----
|
|
======
|
|
|
|
Or, for more control you can implement your own `OAuth2TokenValidator`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
static class AudienceValidator implements OAuth2TokenValidator<Jwt> {
|
|
OAuth2Error error = new OAuth2Error("custom_code", "Custom error message", null);
|
|
|
|
@Override
|
|
public OAuth2TokenValidatorResult validate(Jwt jwt) {
|
|
if (jwt.getAudience().contains("messaging")) {
|
|
return OAuth2TokenValidatorResult.success();
|
|
} else {
|
|
return OAuth2TokenValidatorResult.failure(error);
|
|
}
|
|
}
|
|
}
|
|
|
|
// ...
|
|
|
|
OAuth2TokenValidator<Jwt> audienceValidator() {
|
|
return new AudienceValidator();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
internal class AudienceValidator : OAuth2TokenValidator<Jwt> {
|
|
var error: OAuth2Error = OAuth2Error("custom_code", "Custom error message", null)
|
|
|
|
override fun validate(jwt: Jwt): OAuth2TokenValidatorResult {
|
|
return if (jwt.audience.contains("messaging")) {
|
|
OAuth2TokenValidatorResult.success()
|
|
} else {
|
|
OAuth2TokenValidatorResult.failure(error)
|
|
}
|
|
}
|
|
}
|
|
|
|
// ...
|
|
|
|
fun audienceValidator(): OAuth2TokenValidator<Jwt> {
|
|
return AudienceValidator()
|
|
}
|
|
----
|
|
======
|
|
|
|
Then, to add into a resource server, it's a matter of specifying the <<oauth2resourceserver-jwt-architecture-jwtdecoder,`JwtDecoder`>> instance:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
JwtDecoder jwtDecoder() {
|
|
NimbusJwtDecoder jwtDecoder = (NimbusJwtDecoder)
|
|
JwtDecoders.fromIssuerLocation(issuerUri);
|
|
|
|
OAuth2TokenValidator<Jwt> audienceValidator = audienceValidator();
|
|
OAuth2TokenValidator<Jwt> withIssuer = JwtValidators.createDefaultWithIssuer(issuerUri);
|
|
OAuth2TokenValidator<Jwt> withAudience = new DelegatingOAuth2TokenValidator<>(withIssuer, audienceValidator);
|
|
|
|
jwtDecoder.setJwtValidator(withAudience);
|
|
|
|
return jwtDecoder;
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
val jwtDecoder: NimbusJwtDecoder = JwtDecoders.fromIssuerLocation(issuerUri) as NimbusJwtDecoder
|
|
|
|
val audienceValidator = audienceValidator()
|
|
val withIssuer: OAuth2TokenValidator<Jwt> = JwtValidators.createDefaultWithIssuer(issuerUri)
|
|
val withAudience: OAuth2TokenValidator<Jwt> = DelegatingOAuth2TokenValidator(withIssuer, audienceValidator)
|
|
|
|
jwtDecoder.setJwtValidator(withAudience)
|
|
|
|
return jwtDecoder
|
|
}
|
|
----
|
|
======
|
|
|
|
[TIP]
|
|
As stated earlier, you can instead <<_supplying_audiences, configure `aud` validation in Boot>>.
|
|
|
|
[[oauth2resourceserver-jwt-claimsetmapping]]
|
|
== Configuring Claim Set Mapping
|
|
|
|
Spring Security uses the https://bitbucket.org/connect2id/nimbus-jose-jwt/wiki/Home[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`.
|
|
|
|
[[oauth2resourceserver-jwt-claimsetmapping-singleclaim]]
|
|
=== Customizing the Conversion of a Single Claim
|
|
|
|
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`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
JwtDecoder jwtDecoder() {
|
|
NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withIssuerLocation(issuer).build();
|
|
|
|
MappedJwtClaimSetConverter converter = MappedJwtClaimSetConverter
|
|
.withDefaults(Collections.singletonMap("sub", this::lookupUserIdBySub));
|
|
jwtDecoder.setClaimSetConverter(converter);
|
|
|
|
return jwtDecoder;
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
val jwtDecoder = NimbusJwtDecoder.withIssuerLocation(issuer).build()
|
|
|
|
val converter = MappedJwtClaimSetConverter
|
|
.withDefaults(mapOf("sub" to this::lookupUserIdBySub))
|
|
jwtDecoder.setClaimSetConverter(converter)
|
|
|
|
return jwtDecoder
|
|
}
|
|
----
|
|
======
|
|
This will keep all the defaults, except it will override the default claim converter for `sub`.
|
|
|
|
[[oauth2resourceserver-jwt-claimsetmapping-add]]
|
|
=== Adding a Claim
|
|
|
|
`MappedJwtClaimSetConverter` can also be used to add a custom claim, for example, to adapt to an existing system:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
MappedJwtClaimSetConverter.withDefaults(Collections.singletonMap("custom", custom -> "value"));
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
MappedJwtClaimSetConverter.withDefaults(mapOf("custom" to Converter<Any, String> { "value" }))
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-claimsetmapping-remove]]
|
|
=== Removing a Claim
|
|
|
|
And removing a claim is also simple, using the same API:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
MappedJwtClaimSetConverter.withDefaults(Collections.singletonMap("legacyclaim", legacy -> null));
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
MappedJwtClaimSetConverter.withDefaults(mapOf("legacyclaim" to Converter<Any, Any> { null }))
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-claimsetmapping-rename]]
|
|
=== Renaming a Claim
|
|
|
|
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>>`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
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;
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
class UsernameSubClaimAdapter : Converter<Map<String, Any?>, Map<String, Any?>> {
|
|
private val delegate = MappedJwtClaimSetConverter.withDefaults(Collections.emptyMap())
|
|
override fun convert(claims: Map<String, Any?>): Map<String, Any?> {
|
|
val convertedClaims = delegate.convert(claims)
|
|
val username = convertedClaims["user_name"] as String
|
|
convertedClaims["sub"] = username
|
|
return convertedClaims
|
|
}
|
|
}
|
|
----
|
|
======
|
|
|
|
And then, the instance can be supplied like normal:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
JwtDecoder jwtDecoder() {
|
|
NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withIssuerLocation(issuer).build();
|
|
jwtDecoder.setClaimSetConverter(new UsernameSubClaimAdapter());
|
|
return jwtDecoder;
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(): JwtDecoder {
|
|
val jwtDecoder: NimbusJwtDecoder = NimbusJwtDecoder.withIssuerLocation(issuer).build()
|
|
jwtDecoder.setClaimSetConverter(UsernameSubClaimAdapter())
|
|
return jwtDecoder
|
|
}
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-jwt-timeouts]]
|
|
== Configuring Timeouts
|
|
|
|
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`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public JwtDecoder jwtDecoder(RestTemplateBuilder builder) {
|
|
RestOperations rest = builder
|
|
.setConnectTimeout(Duration.ofSeconds(60))
|
|
.setReadTimeout(Duration.ofSeconds(60))
|
|
.build();
|
|
|
|
NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withIssuerLocation(issuer).restOperations(rest).build();
|
|
return jwtDecoder;
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(builder: RestTemplateBuilder): JwtDecoder {
|
|
val rest: RestOperations = builder
|
|
.setConnectTimeout(Duration.ofSeconds(60))
|
|
.setReadTimeout(Duration.ofSeconds(60))
|
|
.build()
|
|
return NimbusJwtDecoder.withIssuerLocation(issuer).restOperations(rest).build()
|
|
}
|
|
----
|
|
======
|
|
|
|
Also by default, Resource Server caches in-memory the authorization server's JWK set for 5 minutes, which you may want to adjust.
|
|
Further, it doesn't take into account more sophisticated caching patterns like eviction or using a shared cache.
|
|
|
|
To adjust the way in which Resource Server caches the JWK set, `NimbusJwtDecoder` accepts an instance of `Cache`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public JwtDecoder jwtDecoder(CacheManager cacheManager) {
|
|
return NimbusJwtDecoder.withIssuerLocation(issuer)
|
|
.cache(cacheManager.getCache("jwks"))
|
|
.build();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun jwtDecoder(cacheManager: CacheManager): JwtDecoder {
|
|
return NimbusJwtDecoder.withIssuerLocation(issuer)
|
|
.cache(cacheManager.getCache("jwks"))
|
|
.build()
|
|
}
|
|
----
|
|
======
|
|
|
|
When given a `Cache`, Resource Server will use the JWK Set Uri as the key and the JWK Set JSON as the value.
|
|
|
|
NOTE: Spring isn't a cache provider, so you'll need to make sure to include the appropriate dependencies, like `spring-boot-starter-cache` and your favorite caching provider.
|
|
|
|
NOTE: Whether it's socket or cache timeouts, you may instead want to work with Nimbus directly.
|
|
To do so, remember that `NimbusJwtDecoder` ships with a constructor that takes Nimbus's `JWTProcessor`.
|