mirror of
https://github.com/spring-projects/spring-security.git
synced 2025-10-31 06:38:42 +00:00
991 lines
33 KiB
Plaintext
991 lines
33 KiB
Plaintext
= OAuth 2.0 Resource Server Opaque Token
|
|
:figures: servlet/oauth2
|
|
|
|
[[oauth2resourceserver-opaque-minimaldependencies]]
|
|
== Minimal Dependencies for Introspection
|
|
As described in xref:servlet/oauth2/resource-server/jwt.adoc#oauth2resourceserver-jwt-minimaldependencies[Minimal Dependencies for JWT] most of Resource Server support is collected in `spring-security-oauth2-resource-server`.
|
|
However unless a custom <<oauth2resourceserver-opaque-introspector,`OpaqueTokenIntrospector`>> is provided, the Resource Server will fallback to NimbusOpaqueTokenIntrospector.
|
|
Meaning that both `spring-security-oauth2-resource-server` and `oauth2-oidc-sdk` are necessary in order to have a working minimal Resource Server that supports opaque Bearer Tokens.
|
|
Please refer to `spring-security-oauth2-resource-server` in order to determine the correct version for `oauth2-oidc-sdk`.
|
|
|
|
[[oauth2resourceserver-opaque-minimalconfiguration]]
|
|
== Minimal Configuration for Introspection
|
|
|
|
Typically, an opaque token can be verified via an https://tools.ietf.org/html/rfc7662[OAuth 2.0 Introspection Endpoint], hosted by the authorization server.
|
|
This can be handy when revocation is a requirement.
|
|
|
|
When using https://spring.io/projects/spring-boot[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.
|
|
|
|
[[oauth2resourceserver-opaque-introspectionuri]]
|
|
=== Specifying the Authorization Server
|
|
|
|
To specify where the introspection endpoint is, simply do:
|
|
|
|
[source,yaml]
|
|
----
|
|
spring:
|
|
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.
|
|
|
|
[NOTE]
|
|
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!
|
|
|
|
=== Startup Expectations
|
|
|
|
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.
|
|
|
|
=== Runtime Expectations
|
|
|
|
Once the application is started up, Resource Server will attempt to process any request containing an `Authorization: Bearer` header:
|
|
|
|
[source,http]
|
|
----
|
|
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
|
|
|
|
1. Query the provided introspection endpoint using the provided credentials and the token
|
|
2. Inspect the response for an `{ 'active' : true }` attribute
|
|
3. Map each scope to an authority with the prefix `SCOPE_`
|
|
|
|
The resulting `Authentication#getPrincipal`, by default, is a Spring Security `{security-api-url}org/springframework/security/oauth2/core/OAuth2AuthenticatedPrincipal.html[OAuth2AuthenticatedPrincipal]` object, and `Authentication#getName` maps to the token's `sub` property, if one is present.
|
|
|
|
From here, you may want to jump to:
|
|
|
|
* <<oauth2resourceserver-opaque-architecture>>
|
|
* <<oauth2resourceserver-opaque-attributes,Looking Up Attributes Post-Authentication>>
|
|
* <<oauth2resourceserver-opaque-authorization-extraction,Extracting Authorities Manually>>
|
|
* <<oauth2resourceserver-opaque-jwt-introspector,Using Introspection with JWTs>>
|
|
|
|
[[oauth2resourceserver-opaque-architecture]]
|
|
== How Opaque Token Authentication Works
|
|
|
|
Next, let's see the architectural components that Spring Security uses to support https://tools.ietf.org/html/rfc7662[opaque token] Authentication in servlet-based applications, like the one we just saw.
|
|
|
|
{security-api-url}org/springframework/security/oauth2/server/resource/authentication/OpaqueTokenAuthenticationProvider.html[`OpaqueTokenAuthenticationProvider`] is an xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationprovider[`AuthenticationProvider`] implementation that leverages a <<oauth2resourceserver-opaque-introspector,`OpaqueTokenIntrospector`>> to authenticate an opaque token.
|
|
|
|
Let's take a look at how `OpaqueTokenAuthenticationProvider` works within Spring Security.
|
|
The figure explains details of how the xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationmanager[`AuthenticationManager`] in figures from <<oauth2resourceserver-authentication-bearertokenauthenticationfilter,Reading the Bearer Token>> works.
|
|
|
|
.`OpaqueTokenAuthenticationProvider` Usage
|
|
image::{figures}/opaquetokenauthenticationprovider.png[]
|
|
|
|
image:{icondir}/number_1.png[] The authentication `Filter` from <<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 `OpaqueTokenAuthenticationProvider`.
|
|
|
|
[[oauth2resourceserver-opaque-architecture-introspector]]
|
|
image:{icondir}/number_3.png[] `OpaqueTokenAuthenticationProvider` introspects the opaque token and adds granted authorities using an <<oauth2resourceserver-opaque-introspector,`OpaqueTokenIntrospector`>>.
|
|
When authentication is successful, the xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[`Authentication`] that is returned is of type `BearerTokenAuthentication` and has a principal that is the `OAuth2AuthenticatedPrincipal` returned by the configured <<oauth2resourceserver-opaque-introspector,`OpaqueTokenIntrospector`>>.
|
|
Ultimately, the returned `BearerTokenAuthentication` will be set on the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`] by the authentication `Filter`.
|
|
|
|
[[oauth2resourceserver-opaque-attributes]]
|
|
== Looking Up Attributes Post-Authentication
|
|
|
|
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:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@GetMapping("/foo")
|
|
public String foo(BearerTokenAuthentication authentication) {
|
|
return authentication.getTokenAttributes().get("sub") + " is the subject";
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@GetMapping("/foo")
|
|
fun foo(authentication: BearerTokenAuthentication): String {
|
|
return authentication.tokenAttributes["sub"].toString() + " is the subject"
|
|
}
|
|
----
|
|
======
|
|
|
|
Since `BearerTokenAuthentication` holds an `OAuth2AuthenticatedPrincipal`, that also means that it's available to controller methods, too:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@GetMapping("/foo")
|
|
public String foo(@AuthenticationPrincipal OAuth2AuthenticatedPrincipal principal) {
|
|
return principal.getAttribute("sub") + " is the subject";
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@GetMapping("/foo")
|
|
fun foo(@AuthenticationPrincipal principal: OAuth2AuthenticatedPrincipal): String {
|
|
return principal.getAttribute<Any>("sub").toString() + " is the subject"
|
|
}
|
|
----
|
|
======
|
|
|
|
=== Looking Up Attributes Via SpEL
|
|
|
|
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:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@PreAuthorize("principal?.attributes['sub'] == 'foo'")
|
|
public String forFoosEyesOnly() {
|
|
return "foo";
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@PreAuthorize("principal?.attributes['sub'] == 'foo'")
|
|
fun forFoosEyesOnly(): String {
|
|
return "foo"
|
|
}
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-opaque-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 use Opaque Token, this `SecurityFilterChain` looks like:
|
|
|
|
.Default Opaque Token Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
|
|
http
|
|
.authorizeHttpRequests(authorize -> authorize
|
|
.anyRequest().authenticated()
|
|
)
|
|
.oauth2ResourceServer(OAuth2ResourceServerConfigurer::opaqueToken);
|
|
return http.build();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
|
|
http {
|
|
authorizeRequests {
|
|
authorize(anyRequest, authenticated)
|
|
}
|
|
oauth2ResourceServer {
|
|
opaqueToken { }
|
|
}
|
|
}
|
|
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 Opaque Token Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@EnableWebSecurity
|
|
public class MyCustomSecurityConfiguration {
|
|
@Bean
|
|
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
|
|
http
|
|
.authorizeHttpRequests(authorize -> authorize
|
|
.requestMatchers("/messages/**").hasAuthority("SCOPE_message:read")
|
|
.anyRequest().authenticated()
|
|
)
|
|
.oauth2ResourceServer(oauth2 -> oauth2
|
|
.opaqueToken(opaqueToken -> opaqueToken
|
|
.introspector(myIntrospector())
|
|
)
|
|
);
|
|
return http.build();
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@EnableWebSecurity
|
|
class MyCustomSecurityConfiguration {
|
|
@Bean
|
|
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
|
|
http {
|
|
authorizeRequests {
|
|
authorize("/messages/**", hasAuthority("SCOPE_message:read"))
|
|
authorize(anyRequest, authenticated)
|
|
}
|
|
oauth2ResourceServer {
|
|
opaqueToken {
|
|
introspector = myIntrospector()
|
|
}
|
|
}
|
|
}
|
|
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-opaque-introspector]]
|
|
For example, the second `@Bean` Spring Boot creates is an `OpaqueTokenIntrospector`, <<oauth2resourceserver-opaque-architecture-introspector,which decodes `String` tokens into validated instances of `OAuth2AuthenticatedPrincipal`>>:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public OpaqueTokenIntrospector introspector() {
|
|
return new NimbusOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun introspector(): OpaqueTokenIntrospector {
|
|
return NimbusOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret)
|
|
}
|
|
----
|
|
======
|
|
|
|
If the application doesn't expose an <<oauth2resourceserver-opaque-architecture-introspector,`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()`.
|
|
|
|
If the application doesn't expose an `OpaqueTokenAuthenticationConverter` bean, then spring-security will build `BearerTokenAuthentication`.
|
|
|
|
Or, if you're not using Spring Boot at all, then all of these components - the filter chain, an <<oauth2resourceserver-opaque-architecture-introspector,`OpaqueTokenIntrospector`>> and an `OpaqueTokenAuthenticationConverter` can be specified in XML.
|
|
|
|
The filter chain is specified like so:
|
|
|
|
.Default Opaque Token Configuration
|
|
[tabs]
|
|
======
|
|
Xml::
|
|
+
|
|
[source,xml,role="primary"]
|
|
----
|
|
<http>
|
|
<intercept-uri pattern="/**" access="authenticated"/>
|
|
<oauth2-resource-server>
|
|
<opaque-token introspector-ref="opaqueTokenIntrospector"
|
|
authentication-converter-ref="opaqueTokenAuthenticationConverter"/>
|
|
</oauth2-resource-server>
|
|
</http>
|
|
----
|
|
======
|
|
|
|
And the <<oauth2resourceserver-opaque-architecture-introspector,`OpaqueTokenIntrospector`>> like so:
|
|
|
|
.Opaque Token Introspector
|
|
[tabs]
|
|
======
|
|
Xml::
|
|
+
|
|
[source,xml,role="primary"]
|
|
----
|
|
<bean id="opaqueTokenIntrospector"
|
|
class="org.springframework.security.oauth2.server.resource.introspection.NimbusOpaqueTokenIntrospector">
|
|
<constructor-arg value="${spring.security.oauth2.resourceserver.opaquetoken.introspection_uri}"/>
|
|
<constructor-arg value="${spring.security.oauth2.resourceserver.opaquetoken.client_id}"/>
|
|
<constructor-arg value="${spring.security.oauth2.resourceserver.opaquetoken.client_secret}"/>
|
|
</bean>
|
|
----
|
|
======
|
|
|
|
And the `OpaqueTokenAuthenticationConverter` like so:
|
|
|
|
.Opaque Token Authentication Converter
|
|
[tabs]
|
|
======
|
|
Xml::
|
|
+
|
|
[source,xml,role="primary"]
|
|
----
|
|
<bean id="opaqueTokenAuthenticationConverter"
|
|
class="com.example.CustomOpaqueTokenAuthenticationConverter"/>
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-opaque-introspectionuri-dsl]]
|
|
=== Using `introspectionUri()`
|
|
|
|
An authorization server's Introspection Uri can be configured <<oauth2resourceserver-opaque-introspectionuri,as a configuration property>> or it can be supplied in the DSL:
|
|
|
|
.Introspection URI Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@EnableWebSecurity
|
|
public class DirectlyConfiguredIntrospectionUri {
|
|
@Bean
|
|
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
|
|
http
|
|
.authorizeHttpRequests(authorize -> authorize
|
|
.anyRequest().authenticated()
|
|
)
|
|
.oauth2ResourceServer(oauth2 -> oauth2
|
|
.opaqueToken(opaqueToken -> opaqueToken
|
|
.introspectionUri("https://idp.example.com/introspect")
|
|
.introspectionClientCredentials("client", "secret")
|
|
)
|
|
);
|
|
return http.build();
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@EnableWebSecurity
|
|
class DirectlyConfiguredIntrospectionUri {
|
|
@Bean
|
|
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
|
|
http {
|
|
authorizeRequests {
|
|
authorize(anyRequest, authenticated)
|
|
}
|
|
oauth2ResourceServer {
|
|
opaqueToken {
|
|
introspectionUri = "https://idp.example.com/introspect"
|
|
introspectionClientCredentials("client", "secret")
|
|
}
|
|
}
|
|
}
|
|
return http.build()
|
|
}
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
<bean id="opaqueTokenIntrospector"
|
|
class="org.springframework.security.oauth2.server.resource.introspection.NimbusOpaqueTokenIntrospector">
|
|
<constructor-arg value="https://idp.example.com/introspect"/>
|
|
<constructor-arg value="client"/>
|
|
<constructor-arg value="secret"/>
|
|
</bean>
|
|
----
|
|
======
|
|
|
|
Using `introspectionUri()` takes precedence over any configuration property.
|
|
|
|
[[oauth2resourceserver-opaque-introspector-dsl]]
|
|
=== Using `introspector()`
|
|
|
|
More powerful than `introspectionUri()` is `introspector()`, which will completely replace any Boot auto configuration of <<oauth2resourceserver-opaque-architecture-introspector,`OpaqueTokenIntrospector`>>:
|
|
|
|
.Introspector Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@EnableWebSecurity
|
|
public class DirectlyConfiguredIntrospector {
|
|
@Bean
|
|
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
|
|
http
|
|
.authorizeHttpRequests(authorize -> authorize
|
|
.anyRequest().authenticated()
|
|
)
|
|
.oauth2ResourceServer(oauth2 -> oauth2
|
|
.opaqueToken(opaqueToken -> opaqueToken
|
|
.introspector(myCustomIntrospector())
|
|
)
|
|
);
|
|
return http.build();
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@EnableWebSecurity
|
|
class DirectlyConfiguredIntrospector {
|
|
@Bean
|
|
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
|
|
http {
|
|
authorizeRequests {
|
|
authorize(anyRequest, authenticated)
|
|
}
|
|
oauth2ResourceServer {
|
|
opaqueToken {
|
|
introspector = myCustomIntrospector()
|
|
}
|
|
}
|
|
}
|
|
return http.build()
|
|
}
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
<http>
|
|
<intercept-uri pattern="/**" access="authenticated"/>
|
|
<oauth2-resource-server>
|
|
<opaque-token introspector-ref="myCustomIntrospector"/>
|
|
</oauth2-resource-server>
|
|
</http>
|
|
----
|
|
======
|
|
|
|
This is handy when deeper configuration, like <<oauth2resourceserver-opaque-authorization-extraction,authority mapping>>, <<oauth2resourceserver-opaque-jwt-introspector,JWT revocation>>, or <<oauth2resourceserver-opaque-timeouts,request timeouts>>, is necessary.
|
|
|
|
[[oauth2resourceserver-opaque-introspector-bean]]
|
|
=== Exposing a `OpaqueTokenIntrospector` `@Bean`
|
|
|
|
Or, exposing a <<oauth2resourceserver-opaque-architecture-introspector,`OpaqueTokenIntrospector`>> `@Bean` has the same effect as `introspector()`:
|
|
|
|
[source,java]
|
|
----
|
|
@Bean
|
|
public OpaqueTokenIntrospector introspector() {
|
|
return new NimbusOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
|
|
}
|
|
----
|
|
|
|
[[oauth2resourceserver-opaque-authorization]]
|
|
== Configuring Authorization
|
|
|
|
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:
|
|
|
|
.Authorization Opaque Token Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@EnableWebSecurity
|
|
public class MappedAuthorities {
|
|
@Bean
|
|
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
|
|
http
|
|
.authorizeHttpRequests(authorizeRequests -> authorizeRequests
|
|
.requestMatchers("/contacts/**").hasAuthority("SCOPE_contacts")
|
|
.requestMatchers("/messages/**").hasAuthority("SCOPE_messages")
|
|
.anyRequest().authenticated()
|
|
)
|
|
.oauth2ResourceServer(OAuth2ResourceServerConfigurer::opaqueToken);
|
|
return http.build();
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@EnableWebSecurity
|
|
class MappedAuthorities {
|
|
@Bean
|
|
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
|
|
http {
|
|
authorizeRequests {
|
|
authorize("/contacts/**", hasAuthority("SCOPE_contacts"))
|
|
authorize("/messages/**", hasAuthority("SCOPE_messages"))
|
|
authorize(anyRequest, authenticated)
|
|
}
|
|
oauth2ResourceServer {
|
|
opaqueToken { }
|
|
}
|
|
}
|
|
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>
|
|
<opaque-token introspector-ref="opaqueTokenIntrospector"/>
|
|
</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-opaque-authorization-extraction]]
|
|
=== Extracting Authorities Manually
|
|
|
|
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:
|
|
|
|
[source,json]
|
|
----
|
|
{
|
|
"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 <<oauth2resourceserver-opaque-architecture-introspector,`OpaqueTokenIntrospector`>> that takes a look at the attribute set and converts in its own way:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
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());
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
class CustomAuthoritiesOpaqueTokenIntrospector : OpaqueTokenIntrospector {
|
|
private val delegate: OpaqueTokenIntrospector = NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
|
|
override fun introspect(token: String): OAuth2AuthenticatedPrincipal {
|
|
val principal: OAuth2AuthenticatedPrincipal = delegate.introspect(token)
|
|
return DefaultOAuth2AuthenticatedPrincipal(
|
|
principal.name, principal.attributes, extractAuthorities(principal))
|
|
}
|
|
|
|
private fun extractAuthorities(principal: OAuth2AuthenticatedPrincipal): Collection<GrantedAuthority> {
|
|
val scopes: List<String> = principal.getAttribute(OAuth2IntrospectionClaimNames.SCOPE)
|
|
return scopes
|
|
.map { SimpleGrantedAuthority(it) }
|
|
}
|
|
}
|
|
----
|
|
======
|
|
|
|
Thereafter, this custom introspector can be configured simply by exposing it as a `@Bean`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public OpaqueTokenIntrospector introspector() {
|
|
return new CustomAuthoritiesOpaqueTokenIntrospector();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun introspector(): OpaqueTokenIntrospector {
|
|
return CustomAuthoritiesOpaqueTokenIntrospector()
|
|
}
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-opaque-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, `NimbusOpaqueTokenIntrospector` accepts an instance of `RestOperations`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public OpaqueTokenIntrospector introspector(RestTemplateBuilder builder, OAuth2ResourceServerProperties properties) {
|
|
RestOperations rest = builder
|
|
.basicAuthentication(properties.getOpaquetoken().getClientId(), properties.getOpaquetoken().getClientSecret())
|
|
.setConnectTimeout(Duration.ofSeconds(60))
|
|
.setReadTimeout(Duration.ofSeconds(60))
|
|
.build();
|
|
|
|
return new NimbusOpaqueTokenIntrospector(introspectionUri, rest);
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun introspector(builder: RestTemplateBuilder, properties: OAuth2ResourceServerProperties): OpaqueTokenIntrospector? {
|
|
val rest: RestOperations = builder
|
|
.basicAuthentication(properties.opaquetoken.clientId, properties.opaquetoken.clientSecret)
|
|
.setConnectTimeout(Duration.ofSeconds(60))
|
|
.setReadTimeout(Duration.ofSeconds(60))
|
|
.build()
|
|
return NimbusOpaqueTokenIntrospector(introspectionUri, rest)
|
|
}
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-opaque-jwt-introspector]]
|
|
== Using Introspection with JWTs
|
|
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
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 <<oauth2resourceserver-opaque-architecture-introspector,`OpaqueTokenIntrospector`>> that still hits the endpoint, but then updates the returned principal to have the JWTs claims as the attributes:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
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 ex) {
|
|
throw new OAuth2IntrospectionException(ex);
|
|
}
|
|
}
|
|
|
|
private static class ParseOnlyJWTProcessor extends DefaultJWTProcessor<SecurityContext> {
|
|
JWTClaimsSet process(SignedJWT jwt, SecurityContext context)
|
|
throws JOSEException {
|
|
return jwt.getJWTClaimsSet();
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
class JwtOpaqueTokenIntrospector : OpaqueTokenIntrospector {
|
|
private val delegate: OpaqueTokenIntrospector = NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
|
|
private val jwtDecoder: JwtDecoder = NimbusJwtDecoder(ParseOnlyJWTProcessor())
|
|
override fun introspect(token: String): OAuth2AuthenticatedPrincipal {
|
|
val principal = delegate.introspect(token)
|
|
return try {
|
|
val jwt: Jwt = jwtDecoder.decode(token)
|
|
DefaultOAuth2AuthenticatedPrincipal(jwt.claims, NO_AUTHORITIES)
|
|
} catch (ex: JwtException) {
|
|
throw OAuth2IntrospectionException(ex.message)
|
|
}
|
|
}
|
|
|
|
private class ParseOnlyJWTProcessor : DefaultJWTProcessor<SecurityContext>() {
|
|
override fun process(jwt: SignedJWT, context: SecurityContext): JWTClaimsSet {
|
|
return jwt.jwtClaimsSet
|
|
}
|
|
}
|
|
}
|
|
----
|
|
======
|
|
|
|
Thereafter, this custom introspector can be configured simply by exposing it as a `@Bean`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public OpaqueTokenIntrospector introspector() {
|
|
return new JwtOpaqueTokenIntrospector();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun introspector(): OpaqueTokenIntrospector {
|
|
return JwtOpaqueTokenIntrospector()
|
|
}
|
|
----
|
|
======
|
|
|
|
[[oauth2resourceserver-opaque-userinfo]]
|
|
== Calling a `/userinfo` Endpoint
|
|
|
|
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 <<oauth2resourceserver-opaque-architecture-introspector,`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
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
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;
|
|
|
|
// ... constructor
|
|
|
|
@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);
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
class UserInfoOpaqueTokenIntrospector : OpaqueTokenIntrospector {
|
|
private val delegate: OpaqueTokenIntrospector = NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
|
|
private val oauth2UserService = DefaultOAuth2UserService()
|
|
private val repository: ClientRegistrationRepository? = null
|
|
|
|
// ... constructor
|
|
|
|
override fun introspect(token: String): OAuth2AuthenticatedPrincipal {
|
|
val authorized = delegate.introspect(token)
|
|
val issuedAt: Instant? = authorized.getAttribute(ISSUED_AT)
|
|
val expiresAt: Instant? = authorized.getAttribute(EXPIRES_AT)
|
|
val clientRegistration: ClientRegistration = repository!!.findByRegistrationId("registration-id")
|
|
val accessToken = OAuth2AccessToken(BEARER, token, issuedAt, expiresAt)
|
|
val oauth2UserRequest = OAuth2UserRequest(clientRegistration, accessToken)
|
|
return 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`:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
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);
|
|
}
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
class UserInfoOpaqueTokenIntrospector : OpaqueTokenIntrospector {
|
|
private val delegate: OpaqueTokenIntrospector = NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
|
|
private val rest: WebClient = WebClient.create()
|
|
|
|
override fun introspect(token: String): OAuth2AuthenticatedPrincipal {
|
|
val authorized = delegate.introspect(token)
|
|
return makeUserInfoRequest(authorized)
|
|
}
|
|
}
|
|
----
|
|
======
|
|
|
|
Either way, having created your <<oauth2resourceserver-opaque-architecture-introspector,`OpaqueTokenIntrospector`>>, you should publish it as a `@Bean` to override the defaults:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
OpaqueTokenIntrospector introspector() {
|
|
return new UserInfoOpaqueTokenIntrospector(...);
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun introspector(): OpaqueTokenIntrospector {
|
|
return UserInfoOpaqueTokenIntrospector(...)
|
|
}
|
|
----
|
|
======
|