Align OAuth Reactive/Servlet Resource Server Docs

Fixes gh-7430
Fixes gh-7425
Fixes gh-7460

docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/resource-server.adoc

@@ -1,14 +1,17 @@
 [[webflux-oauth2-resource-server]]
 = OAuth2 Resource Server
 
-Spring Security supports protecting endpoints using https://tools.ietf.org/html/rfc7519[JWT]-encoded OAuth 2.0 https://tools.ietf.org/html/rfc6750.html[Bearer Tokens].
+Spring Security supports protecting endpoints using two forms of OAuth 2.0 https://tools.ietf.org/html/rfc6750.html[Bearer Tokens]:
 
-This is handy in circumstances where an application has federated its authority management out to an https://tools.ietf.org/html/rfc6749[authorization server] (for example, Okta or Ping Identity).
-This authorization server can be consulted by Resource Servers to validate authority when serving requests.
+* https://tools.ietf.org/html/rfc7519[JWT]
+* Opaque Tokens
+
+This is handy in circumstances where an application has delegated its authority management to an https://tools.ietf.org/html/rfc6749[authorization server] (for example, Okta or Ping Identity).
+This authorization server can be consulted by resource servers to authorize requests.
 
 [NOTE]
 ====
-A complete working example can be found in {gh-samples-url}/boot/oauth2resourceserver-webflux[*OAuth 2.0 Resource Server WebFlux sample*].
+A complete working example for {gh-samples-url}/boot/oauth2resourceserver-webflux[*JWTs*]  is available in the {gh-samples-url}[Spring Security repository].
 ====
 
 == Dependencies
@@ -16,13 +19,13 @@ A complete working example can be found in {gh-samples-url}/boot/oauth2resources
 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.
 
-[[webflux-oauth2-resource-server-minimal-configuration]]
-== Minimal Configuration
+[[webflux-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.
 
-=== Specify the Authorization Server
+=== Specifying the Authorization Server
 
 In a Spring Boot application, to specify which authorization server to use, simply do:
 
@@ -51,7 +54,7 @@ When this property and these dependencies are used, Resource Server will automat
 
 It achieves this through a deterministic startup process:
 
-1. Hit the Provider Configuration endpoint, `https://the.issuer.location/.well-known/openid-configuration`, processing the response for the `jwks_url` property
+1. Hit the Provider Configuration endpoint, `https://idp.example.com/.well-known/openid-configuration`, processing the response for the `jwks_url` property
 2. Configure the validation strategy to query `jwks_url` for valid public keys
 3. Configure the validation strategy to validate each JWTs `iss` claim against `https://idp.example.com`.
 
@@ -72,7 +75,7 @@ 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 token, Resource Server will:
+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 JWTs header
 2. Validate the JWTs `exp` and `nbf` timestamps and the JWTs `iss` claim, and
@@ -83,11 +86,13 @@ As the authorization server makes available new keys, Spring Security will autom
 
 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.
 
-<<webflux-oauth2-resource-server-jwkseturi,How to Configure without Tying Resource Server startup to an authorization server's availability>>
+From here, consider jumping to:
+
+<<webflux-oauth2resourceserver-jwt-jwkseturi,How to Configure without Tying Resource Server startup to an authorization server's availability>>
 
-<<webflux-oauth2-resource-server-sans-boot,How to Configure without Spring Boot>>
+<<webflux-oauth2resourceserver-jwt-sansboot,How to Configure without Spring Boot>>
 
-[[webflux-oauth2-resource-server-jwkseturi]]
+[[webflux-oauth2resourceserver-jwt-jwkseturi]]
 === Specifying the Authorization Server JWK Set Uri Directly
 
 If the authorization server doesn't support the Provider Configuration endpoint, or if Resource Server must be able to start up independently from the authorization server, then `issuer-uri` can be exchanged for `jwk-set-uri`:
@@ -109,14 +114,14 @@ Consequently, Resource Server will not ping the authorization server at startup.
 However, it will also no longer validate the `iss` claim in the JWT (since Resource Server no longer knows what the issuer value should be).
 
 [NOTE]
-This property can also be supplied directly on the <<webflux-oauth2-resource-server-jwkseturi-dsl,DSL>>.
+This property can also be supplied directly on the <<webflux-oauth2resourceserver-jwt-jwkseturi-dsl,DSL>>.
 
-[[webflux-oauth2-resource-server-sans-boot]]
+[[webflux-oauth2resourceserver-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 `SecurityWebFilterChain` that configures the app as a resource server:
+The first is a `SecurityWebFilterChain` that configures the app as a resource server. When including `spring-security-oauth2-jose`, this `WebSecurityConfigurerAdapter` looks like:
 
 [source,java]
 ----
@@ -127,10 +132,7 @@ SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
 			exchanges
 				.anyExchange().authenticated()
 		)
-		.oauth2ResourceServer(oauth2ResourceServer ->
-			oauth2ResourceServer
-				.jwt(withDefaults())
-		);
+		.oauth2ResourceServer(OAuth2ResourceServerSpec::jwt)
 	return http.build();
 }
 ----
@@ -175,10 +177,10 @@ If the application doesn't expose a `ReactiveJwtDecoder` bean, then Spring Boot
 
 And its configuration can be overridden using `jwkSetUri()` or replaced using `decoder()`.
 
-[[webflux-oauth2-resource-server-jwkseturi-dsl]]
+[[webflux-oauth2resourceserver-jwt-jwkseturi-dsl]]
 ==== Using `jwkSetUri()`
 
-An authorization server's JWK Set Uri can be configured <<webflux-oauth2-resource-server-jwkseturi,as a configuration property>> or it can be supplied in the DSL:
+An authorization server's JWK Set Uri can be configured <<webflux-oauth2resourceserver-jwt-jwkseturi,as a configuration property>> or it can be supplied in the DSL:
 
 [source,java]
 ----
@@ -202,7 +204,7 @@ SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
 
 Using `jwkSetUri()` takes precedence over any configuration property.
 
-[[webflux-oauth2-resource-server-decoder-dsl]]
+[[webflux-oauth2resourceserver-jwt-decoder-dsl]]
 ==== Using `decoder()`
 
 More powerful than `jwkSetUri()` is `decoder()`, which will completely replace any Boot auto configuration of `JwtDecoder`:
@@ -212,24 +214,19 @@ More powerful than `jwkSetUri()` is `decoder()`, which will completely replace a
 @Bean
 SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
 	http
-		.authorizeExchange(exchanges ->
-			exchanges
-				.anyExchange().authenticated()
-		)
-		.oauth2ResourceServer(oauth2ResourceServer ->
-			oauth2ResourceServer
-				.jwt(jwt ->
-					jwt
-						.decoder(myCustomDecoder())
-				)
-		);
+		.authorizeExchange()
+			.anyExchange().authenticated()
+			.and()
+		.oauth2ResourceServer()
+			.jwt()
+				.decoder(myCustomDecoder());
     return http.build();
 }
 ----
 
-This is handy when deeper configuration, like <<webflux-oauth2-resource-server-validation,validation>>, is necessary.
+This is handy when deeper configuration, like <<webflux-oauth2resourceserver-jwt-validation,validation>>, is necessary.
 
-[[webflux-oauth2-resource-server-decoder-bean]]
+[[webflux-oauth2resourceserver-decoder-bean]]
 ==== Exposing a `ReactiveJwtDecoder` `@Bean`
 
 Or, exposing a `ReactiveJwtDecoder` `@Bean` has the same effect as `decoder()`:
@@ -237,12 +234,147 @@ Or, exposing a `ReactiveJwtDecoder` `@Bean` has the same effect as `decoder()`:
 [source,java]
 ----
 @Bean
-public JwtDecoder jwtDecoder() {
-    return new NimbusReactiveJwtDecoder(jwkSetUri);
+public ReactiveJwtDecoder jwtDecoder() {
+    return NimbusReactiveJwtDecoder.withJwkSetUri(jwkSetUri).build();
+}
+----
+
+[[webflux-oauth2resourceserver-jwt-decoder-algorithm]]
+== Configuring Trusted Algorithms
+
+By default, `NimbusReactiveJwtDecoder`, and hence Resource Server, will only trust and verify tokens using `RS256`.
+
+You can customize this via <<webflux-oauth2resourceserver-jwt-boot-algorithm,Spring Boot>> or <<webflux-oauth2resourceserver-jwt-decoder-builder,the NimbusJwtDecoder builder>>.
+
+[[webflux-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-algorithm: RS512
+          jwk-set-uri: https://idp.example.org/.well-known/jwks.json
+----
+
+[[webflux-oauth2resourceserver-jwt-decoder-builder]]
+==== Using a Builder
+
+For greater power, though, we can use a builder that ships with `NimbusReactiveJwtDecoder`:
+
+[source,java]
+----
+@Bean
+ReactiveJwtDecoder jwtDecoder() {
+    return NimbusReactiveJwtDecoder.fromJwkSetUri(this.jwkSetUri)
+            .jwsAlgorithm(RS512).build();
+}
+----
+
+Calling `jwsAlgorithm` more than once will configure `NimbusReactiveJwtDecoder` to trust more than one algorithm, like so:
+
+[source,java]
+----
+@Bean
+ReactiveJwtDecoder jwtDecoder() {
+    return NimbusReactiveJwtDecoder.fromJwkSetUri(this.jwkSetUri)
+            .jwsAlgorithm(RS512).jwsAlgorithm(EC512).build();
+}
+----
+
+Or, you can call `jwsAlgorithms`:
+
+[source,java]
+----
+@Bean
+ReactiveJwtDecoder jwtDecoder() {
+    return NimbusReactiveJwtDecoder.fromJwkSetUri(this.jwkSetUri)
+            .jwsAlgorithms(algorithms -> {
+                    algorithms.add(RS512);
+                    algorithms.add(EC512);
+            }).build();
+}
+----
+
+[[webflux-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 <<webflux-oauth2resourceserver-jwt-decoder-public-key-boot,Spring Boot>> or by <<webflux-oauth2resourceserver-jwt-decoder-public-key-builder,Using a Builder>>.
+
+[[webflux-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`:
+
+[source,java]
+----
+@Bean
+BeanFactoryPostProcessor conversionServiceCustomizer() {
+    return beanFactory ->
+        beanFactory.getBean(RsaKeyConversionServicePostProcessor.class)
+                .setResourceLoader(new CustomResourceLoader());
+}
+----
+
+Specify your key's location:
+
+```yaml
+key.location: hfds://my-key.pub
+```
+
+And then autowire the value:
+
+```java
+@Value("${key.location}")
+RSAPublicKey key;
+```
+
+[[webflux-oauth2resourceserver-jwt-decoder-public-key-builder]]
+==== Using a Builder
+
+To wire an `RSAPublicKey` directly, you can simply use the appropriate `NimbusReactiveJwtDecoder` builder, like so:
+
+```java
+@Bean
+public ReactiveJwtDecoder jwtDecoder() {
+    return NimbusReactiveJwtDecoder.withPublicKey(this.key).build();
+}
+```
+
+[[webflux-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 `NimbusReactiveJwtDecoder` builder, like so:
+
+[source,java]
+----
+@Bean
+public ReactiveJwtDecoder jwtDecoder() {
+    return NimbusReactiveJwtDecoder.withSecretKey(this.key).build();
 }
 ----
 
-[[webflux-oauth2-resource-server-authorization]]
+[[webflux-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:
@@ -258,16 +390,12 @@ This means that to protect an endpoint or method with a scope derived from a JWT
 @Bean
 SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
 	http
-		.authorizeExchange(exchanges ->
-			exchanges
-				.mvcMatchers("/contacts/**").hasAuthority("SCOPE_contacts")
-				.mvcMatchers("/messages/**").hasAuthority("SCOPE_messages")
-				.anyExchange().authenticated()
+		.authorizeExchange(exchanges ->exchanges
+			.mvcMatchers("/contacts/**").hasAuthority("SCOPE_contacts")
+			.mvcMatchers("/messages/**").hasAuthority("SCOPE_messages")
+			.anyExchange().authenticated()
 		)
-		.oauth2ResourceServer(oauth2ResourceServer ->
-			oauth2ResourceServer
-				.jwt(withDefaults())
-		);
+		.oauth2ResourceServer(OAuth2ResourceServerSpec::jwt);
     return http.build();
 }
 ----
@@ -277,10 +405,10 @@ Or similarly with method security:
 [source,java]
 ----
 @PreAuthorize("hasAuthority('SCOPE_messages')")
-public List<Message> getMessages(...) {}
+public Flux<Message> getMessages(...) {}
 ----
 
-[[webflux-oauth2-resource-server-authorization-extraction]]
+[[webflux-oauth2resourceserver-jwt-authorization-extraction]]
 ==== Extracting Authorities Manually
 
 However, there are a number of circumstances where this default is insufficient.
@@ -294,34 +422,35 @@ To this end, the DSL exposes `jwtAuthenticationConverter()`:
 @Bean
 SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
 	http
-		.authorizeExchange(exchanges ->
-			exchanges
-				.anyExchange().authenticated()
-		)
-		.oauth2ResourceServer(oauth2ResourceServer ->
-			oauth2ResourceServer
-				.jwt(jwt ->
-					jwt
-						.jwtAuthenticationConverter(grantedAuthoritiesExtractor())
-				)
-		);
+		.authorizeExchange()
+			.anyExchange().authenticated()
+			.and()
+		.oauth2ResourceServer()
+			.jwt()
+				.jwtAuthenticationConverter(grantedAuthoritiesExtractor());
 	return http.build();
 }
 
 Converter<Jwt, Mono<AbstractAuthenticationToken>> grantedAuthoritiesExtractor() {
-    GrantedAuthoritiesExtractor extractor = new GrantedAuthoritiesExtractor();
-    return new ReactiveJwtAuthenticationConverterAdapter(extractor);
+    JwtAuthenticationConverter jwtAuthenticationConverter =
+            new JwtAuthenticationConverter();
+    jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter
+            (new GrantedAuthoritiesExtractor());
+    return new ReactiveJwtAuthenticationConverterAdapter(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.
 
-We can override this quite simply to alter the way granted authorities are derived:
+That final converter might be something like `GrantedAuthoritiesExtractor` below:
 
 [source,java]
 ----
-static class GrantedAuthoritiesExtractor extends JwtAuthenticationConverter {
-    protected Collection<GrantedAuthority> extractAuthorities(Jwt jwt) {
+static class GrantedAuthoritiesExtractor
+        implements Converter<Jwt, Collection<GrantedAuthority>> {
+
+    public Collection<GrantedAuthority> convert(Jwt jwt) {
         Collection<String> authorities = (Collection<String>)
                 jwt.getClaims().get("mycustomclaim");
 
@@ -343,14 +472,14 @@ static class CustomAuthenticationConverter implements Converter<Jwt, Mono<Abstra
 }
 ----
 
-[[webflux-oauth2-resource-server-validation]]
+[[webflux-oauth2resourceserver-jwt-validation]]
 === Configuring Validation
 
-Using <<webflux-oauth2-resource-server-minimal-configuration,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.
+Using <<webflux-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.
 
-[[webflux-oauth2-resource-server-validation-clockskew]]
+[[webflux-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.
@@ -380,7 +509,7 @@ ReactiveJwtDecoder jwtDecoder() {
 [NOTE]
 By default, Resource Server configures a clock skew of 30 seconds.
 
-[[webflux-oauth2-resource-server-validation-custom]]
+[[webflux-oauth2resourceserver-validation-custom]]
 ==== Configuring a Custom Validator
 
 Adding a check for the `aud` claim is simple with the `OAuth2TokenValidator` API:
@@ -419,3 +548,452 @@ ReactiveJwtDecoder jwtDecoder() {
 }
 ----
 
+[[webflux-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.
+
+==== Specifying the Authorization Server
+
+To specify where the introspection endpoint is, simply do:
+
+[source,yaml]
+----
+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:
+
+```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 `OAuth2AuthenticatedPrincipal` object, and `Authentication#getName` maps to the token's `sub` property, if one is present.
+
+From here, you may want to jump to:
+
+* <<webflux-oauth2resourceserver-opaque-attributes,Looking Up Attributes Post-Authentication>>
+* <<webflux-oauth2resourceserver-opaque-authorization-extraction,Extracting Authorities Manually>>
+* <<webflux-oauth2resourceserver-opaque-jwt-introspector,Using Introspection with JWTs>>
+
+[[webflux-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 `@EnableWebFlux` in your configuration:
+
+[source,java]
+----
+@GetMapping("/foo")
+public Mono<String> foo(BearerTokenAuthentication authentication) {
+    return Mono.just(authentication.getTokenAttributes().get("sub") + " is the subject");
+}
+----
+
+Since `BearerTokenAuthentication` holds an `OAuth2AuthenticatedPrincipal`, that also means that it's available to controller methods, too:
+
+[source,java]
+----
+@GetMapping("/foo")
+public Mono<String> foo(@AuthenticationPrincipal OAuth2AuthenticatedPrincipal principal) {
+    return Mono.just(principal.getAttribute("sub") + " is the subject");
+}
+----
+
+==== Looking Up Attributes Via SpEL
+
+Of course, this also means that attributes can be accessed via SpEL.
+
+For example, if using `@EnableReactiveMethodSecurity` so that you can use `@PreAuthorize` annotations, you can do:
+
+```java
+@PreAuthorize("principal?.attributes['sub'] == 'foo'")
+public Mono<String> forFoosEyesOnly() {
+    return Mono.just("foo");
+}
+```
+
+[[webflux-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 `SecurityWebFilterChain` that configures the app as a resource server.
+When use Opaque Token, this `SecurityWebFilterChain` looks like:
+
+[source,java]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		.authorizeExchange()
+			.anyExchange().authenticated()
+			.and()
+		.oauth2ResourceServer(ServerHttpSecurity.OAuth2ResourceServerSpec::opaqueToken)
+	return http.build();
+}
+----
+
+If the application doesn't expose a `SecurityWebFilterChain` bean, then Spring Boot will expose the above default one.
+
+Replacing this is as simple as exposing the bean within the application:
+
+[source,java]
+----
+@EnableWebFluxSecurity
+public class MyCustomSecurityConfiguration {
+    @Bean
+    SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+        http
+            .authorizeExchange()
+                .pathMatchers("/messages/**").hasAuthority("SCOPE_message:read")
+                .anyExchange().authenticated()
+                .and()
+            .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.
+
+For example, the second `@Bean` Spring Boot creates is a `ReactiveOpaqueTokenIntrospector`, which decodes `String` tokens into validated instances of `OAuth2AuthenticatedPrincipal`:
+
+[source,java]
+----
+@Bean
+public ReactiveOpaqueTokenIntrospector introspector() {
+    return new NimbusReactiveOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
+}
+----
+
+If the application doesn't expose a `ReactiveOpaqueTokenIntrospector` bean, then Spring Boot will expose the above default one.
+
+And its configuration can be overridden using `introspectionUri()` and `introspectionClientCredentials()` or replaced using `introspector()`.
+
+[[webflux-oauth2resourceserver-opaque-introspectionuri-dsl]]
+==== Using `introspectionUri()`
+
+An authorization server's Introspection Uri can be configured <<webflux-oauth2resourceserver-opaque-introspectionuri,as a configuration property>> or it can be supplied in the DSL:
+
+[source,java]
+----
+@EnableWebFluxSecurity
+public class DirectlyConfiguredIntrospectionUri {
+    @Bean
+    SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+        http
+            .authorizeExchange()
+                .anyExchange().authenticated()
+                .and()
+            .oauth2ResourceServer()
+                .opaqueToken()
+                    .introspectionUri("https://idp.example.com/introspect")
+                    .introspectionClientCredentials("client", "secret");
+        return http.build();
+    }
+}
+----
+
+Using `introspectionUri()` takes precedence over any configuration property.
+
+[[webflux-oauth2resourceserver-opaque-introspector-dsl]]
+==== Using `introspector()`
+
+More powerful than `introspectionUri()` is `introspector()`, which will completely replace any Boot auto configuration of `ReactiveOpaqueTokenIntrospector`:
+
+[source,java]
+----
+@EnableWebFluxSecurity
+public class DirectlyConfiguredIntrospector {
+    @Bean
+    SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+        http
+            .authorizeExchange()
+                .anyExchange().authenticated()
+                .and()
+            .oauth2ResourceServer()
+                .opaqueToken()
+                    .introspector(myCustomIntrospector());
+        return http.build();
+    }
+}
+----
+
+This is handy when deeper configuration, like <<webflux-oauth2resourceserver-opaque-authorization-extraction,authority mapping>>or <<webflux-oauth2resourceserver-opaque-jwt-introspector,JWT revocation>> is necessary.
+
+[[webflux-oauth2resourceserver-opaque-introspector-bean]]
+==== Exposing a `ReactiveOpaqueTokenIntrospector` `@Bean`
+
+Or, exposing a `ReactiveOpaqueTokenIntrospector` `@Bean` has the same effect as `introspector()`:
+
+[source,java]
+----
+@Bean
+public ReactiveOpaqueTokenIntrospector introspector() {
+    return new NimbusOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
+}
+----
+
+[[webflux-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:
+
+```java
+@EnableWebFluxSecurity
+public class MappedAuthorities {
+    @Bean
+    SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+        http
+            .authorizeExchange(exchange -> exchange
+                .pathMatchers("/contacts/**").hasAuthority("SCOPE_contacts")
+                .pathMatchers("/messages/**").hasAuthority("SCOPE_messages")
+                .anyExchange().authenticated()
+            )
+            .oauth2ResourceServer(ServerHttpSecurity.OAuth2ResourceServerSpec::opaqueToken);
+        return http.build();
+    }
+}
+```
+
+Or similarly with method security:
+
+```java
+@PreAuthorize("hasAuthority('SCOPE_messages')")
+public Flux<Message> getMessages(...) {}
+```
+
+[[webflux-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 `ReactiveOpaqueTokenIntrospector` that takes a look at the attribute set and converts in its own way:
+
+[source,java]
+----
+public class CustomAuthoritiesOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
+    private ReactiveOpaqueTokenIntrospector delegate =
+            new NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
+
+    public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
+        return this.delegate.introspect(token)
+                .map(principal -> 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`:
+
+[source,java]
+----
+@Bean
+public ReactiveOpaqueTokenIntrospector introspector() {
+    return new CustomAuthoritiesOpaqueTokenIntrospector();
+}
+----
+
+[[webflux-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 `ReactiveOpaqueTokenIntrospector` that still hits the endpoint, but then updates the returned principal to have the JWTs claims as the attributes:
+
+[source,java]
+----
+public class JwtOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
+	private ReactiveOpaqueTokenIntrospector delegate =
+			new NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
+	private ReactiveJwtDecoder jwtDecoder = new NimbusReactiveJwtDecoder(new ParseOnlyJWTProcessor());
+
+	public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
+		return this.delegate.introspect(token)
+				.flatMap(principal -> this.jwtDecoder.decode(token))
+				.map(jwt -> new DefaultOAuth2AuthenticatedPrincipal(jwt.getClaims(), NO_AUTHORITIES));
+	}
+
+	private static class ParseOnlyJWTProcessor implements Converter<JWT, Mono<JWTClaimsSet>> {
+		public Mono<JWTClaimsSet> convert(JWT jwt) {
+			try {
+				return Mono.just(jwt.getJWTClaimsSet());
+			} catch (Exception e) {
+				return Mono.error(e);
+			}
+		}
+	}
+}
+----
+
+Thereafter, this custom introspector can be configured simply by exposing it as a `@Bean`:
+
+[source,java]
+----
+@Bean
+public ReactiveOpaqueTokenIntrospector introspector() {
+    return new JwtOpaqueTokenIntropsector();
+}
+----
+
+[[webflux-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 `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
+
+[source,java]
+----
+public class UserInfoOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
+	private final ReactiveOpaqueTokenIntrospector delegate =
+			new NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
+	private final ReactiveOAuth2UserService<OAuth2UserRequest, OAuth2User> oauth2UserService =
+			new DefaultReactiveOAuth2UserService();
+
+	private final ReactiveClientRegistrationRepository repository;
+
+	// ... constructor
+
+	@Override
+	public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
+		return Mono.zip(this.delegate.introspect(token), this.repository.findByRegistrationId("registration-id"))
+				.map(t -> {
+					OAuth2AuthenticatedPrincipal authorized = t.getT1();
+					ClientRegistration clientRegistration = t.getT2();
+					Instant issuedAt = authorized.getAttribute(ISSUED_AT);
+					Instant expiresAt = authorized.getAttribute(OAuth2IntrospectionClaimNames.EXPIRES_AT);
+					OAuth2AccessToken accessToken = new OAuth2AccessToken(BEARER, token, issuedAt, expiresAt);
+					return new OAuth2UserRequest(clientRegistration, accessToken);
+				})
+				.flatMap(this.oauth2UserService::loadUser);
+	}
+}
+----
+
+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`:
+
+[source,java]
+----
+public class UserInfoOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
+    private final ReactiveOpaqueTokenIntrospector delegate =
+            new NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
+    private final WebClient rest = WebClient.create();
+
+    @Override
+    public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
+        return this.delegate.introspect(token)
+		        .map(this::makeUserInfoRequest);
+    }
+}
+----
+
+Either way, having created your `ReactiveOpaqueTokenIntrospector`, you should publish it as a `@Bean` to override the defaults:
+
+[source,java]
+----
+@Bean
+ReactiveOpaqueTokenIntrospector introspector() {
+    return new UserInfoOpaqueTokenIntrospector(...);
+}
+----
+

docs/manual/src/docs/asciidoc/_includes/reactive/test.adoc

@@ -148,3 +148,123 @@ this.rest
 	.uri("/login")
 	...
 ----
+
+
+=== Testing Bearer Authentication
+
+In order to make an authorized request on a resource server, you need a bearer token.
+If your resource server is configured for JWTs, then this would mean that the bearer token needs to be signed and then encoded according to the JWT specification.
+All of this can be quite daunting, especially when this isn't the focus of your test.
+
+Fortunately, there are a number of simple ways that you can overcome this difficulty and allow your tests to focus on authorization and not on representing bearer tokens.
+We'll look at two of them now:
+
+===== `mockJwt() WebTestClientConfigurer`
+
+The first way is via a `WebTestClientConfigurer`.
+The simplest of these would look something like this:
+
+[source,java]
+----
+client
+    .mutateWith(mockJwt()).get().uri("/endpoint").exchange();
+----
+
+What this will do is create a mock `Jwt`, passing it correctly through any authentication APIs so that it's available for your authorization mechanisms to verify.
+
+By default, the `JWT` that it creates has the following characteristics:
+
+[source,json]
+----
+{
+  "headers" : { "alg" : "none" },
+  "claims" : {
+    "sub" : "user",
+    "scope" : "read"
+  }
+}
+----
+
+And the resulting `Jwt`, were it tested, would pass in the following way:
+
+[source,java]
+----
+assertThat(jwt.getTokenValue()).isEqualTo("token");
+assertThat(jwt.getHeaders().get("alg")).isEqualTo("none");
+assertThat(jwt.getSubject()).isEqualTo("sub");
+GrantedAuthority authority = jwt.getAuthorities().iterator().next();
+assertThat(authority.getAuthority()).isEqualTo("read");
+----
+
+These values can, of course be configured.
+
+Any headers or claims can be configured with their corresponding methods:
+
+[source,java]
+----
+client
+	.mutateWith(jwt(jwt -> jwt.header("kid", "one")
+		.claim("iss", "https://idp.example.org")))
+	.get().uri("/endpoint").exchange();
+----
+
+[source,java]
+----
+client
+	.mutateWith(jwt(jwt -> jwt.claims(claims -> claims.remove("scope"))))
+	.get().uri("/endpoint").exchange();
+----
+
+The `scope` and `scp` claims are processed the same way here as they are in a normal bearer token request.
+However, this can be overridden simply by providing the list of `GrantedAuthority` instances that you need for your test:
+
+[source,java]
+----
+client
+	.mutateWith(jwt().authorities(new SimpleGrantedAuthority("SCOPE_messages")))
+	.get().uri("/endpoint").exchange();
+----
+
+Or, if you have a custom `Jwt` to `Collection<GrantedAuthority>` converter, you can also use that to derive the authorities:
+
+[source,java]
+----
+client
+	.mutateWith(jwt().authorities(new MyConverter()))
+	.get().uri("/endpoint").exchange();
+----
+
+You can also specify a complete `Jwt`, for which `Jwt.Builder` comes quite handy:
+
+[source,java]
+----
+Jwt jwt = Jwt.withTokenValue("token")
+    .header("alg", "none")
+    .claim("sub", "user")
+    .claim("scope", "read");
+
+client
+	.mutateWith(jwt(jwt))
+	.get().uri("/endpoint").exchange();
+----
+
+===== `authentication()` `WebTestClientConfigurer`
+
+The second way is by using the `authentication()` `Mutator`.
+Essentially, you can instantiate your own `JwtAuthenticationToken` and provide it in your test, like so:
+
+[source,java]
+----
+Jwt jwt = Jwt.withTokenValue("token")
+    .header("alg", "none")
+    .claim("sub", "user")
+    .build();
+Collection<GrantedAuthority> authorities = AuthorityUtils.createAuthorityList("SCOPE_read");
+JwtAuthenticationToken token = new JwtAuthenticationToken(jwt, authorities);
+
+client
+	.mutateWith(authentication(token))
+	.get().uri("/endpoint").exchange();
+----
+
+Note that as an alternative to these, you can also mock the `ReactiveJwtDecoder` bean itself with a `@MockBean` annotation.

docs/manual/src/docs/asciidoc/_includes/servlet/preface/java-configuration.adoc

@@ -430,15 +430,17 @@ First, include the needed dependencies and second, indicate the location of the
 
 ==== Specifying the Authorization Server
 
-To specify which authorization server to use, simply do:
+In a Spring Boot application, to specify which authorization server to use, simply do:
 
-```yaml
-security:
-  oauth2:
-    resourceserver:
-      jwt:
-        issuer-uri: https://idp.example.com
-```
+[source,yml]
+----
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: https://idp.example.com
+----
 
 Where `https://idp.example.com` 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.
@@ -468,14 +470,15 @@ If the authorization server is down when Resource Server queries it (given appro
 
 Once the application is started up, Resource Server will attempt to process any request containing an `Authorization: Bearer` header:
 
-```http
+[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
+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 JWTs header
 2. Validate the JWTs `exp` and `nbf` timestamps and the JWTs `iss` claim, and
@@ -497,13 +500,15 @@ From here, consider jumping to:
 
 If the authorization server doesn't support the Provider Configuration endpoint, or if Resource Server must be able to start up independently from the authorization server, then `issuer-uri` can be exchanged for `jwk-set-uri`:
 
-```yaml
-security:
-  oauth2:
-    resourceserver:
-      jwt:
-        jwk-set-uri: https://idp.example.com/.well-known/jwks.json
-```
+[source,yaml]
+----
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          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
@@ -521,7 +526,8 @@ 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:
 
-```java
+[source,java]
+----
 protected void configure(HttpSecurity http) {
     http
         .authorizeRequests()
@@ -529,13 +535,14 @@ protected void configure(HttpSecurity http) {
             .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:
 
-```java
+[source,java]
+----
 @EnableWebSecurity
 public class MyCustomSecurityConfiguration extends WebSecurityConfigurerAdapter {
     protected void configure(HttpSecurity http) {
@@ -549,7 +556,7 @@ public class MyCustomSecurityConfiguration extends WebSecurityConfigurerAdapter
                     .jwtAuthenticationConverter(myConverter());
     }
 }
-```
+----
 
 The above requires the scope of `message:read` for any URL that starts with `/messages/`.
 
@@ -557,12 +564,13 @@ Methods on the `oauth2ResourceServer` DSL will also override or replace auto con
 
 For example, the second `@Bean` Spring Boot creates is a `JwtDecoder`, which decodes `String` tokens into validated instances of `Jwt`:
 
-```java
+[source,java]
+----
 @Bean
 public JwtDecoder jwtDecoder() {
     return JwtDecoders.fromOidcIssuerLocation(issuerUri);
 }
-```
+----
 
 If the application doesn't expose a `JwtDecoder` bean, then Spring Boot will expose the above default one.
 
@@ -573,7 +581,8 @@ And its configuration can be overridden using `jwkSetUri()` or replaced using `d
 
 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:
 
-```java
+[source,java]
+----
 @EnableWebSecurity
 public class DirectlyConfiguredJwkSetUri extends WebSecurityConfigurerAdapter {
     protected void configure(HttpSecurity http) {
@@ -586,7 +595,7 @@ public class DirectlyConfiguredJwkSetUri extends WebSecurityConfigurerAdapter {
                     .jwkSetUri("https://idp.example.com/.well-known/jwks.json");
     }
 }
-```
+----
 
 Using `jwkSetUri()` takes precedence over any configuration property.
 
@@ -595,7 +604,8 @@ Using `jwkSetUri()` takes precedence over any configuration property.
 
 More powerful than `jwkSetUri()` is `decoder()`, which will completely replace any Boot auto configuration of `JwtDecoder`:
 
-```java
+[source,java]
+----
 @EnableWebSecurity
 public class DirectlyConfiguredJwtDecoder extends WebSecurityConfigurerAdapter {
     protected void configure(HttpSecurity http) {
@@ -608,7 +618,7 @@ public class DirectlyConfiguredJwtDecoder extends WebSecurityConfigurerAdapter {
                     .decoder(myCustomDecoder());
     }
 }
-```
+----
 
 This is handy when deeper configuration, like <<oauth2resourceserver-jwt-validation,validation>>, <<oauth2resourceserver-jwt-claimsetmapping,mapping>>, or <<oauth2resourceserver-jwt-timeouts,request timeouts>>, is necessary.
 
@@ -617,26 +627,28 @@ This is handy when deeper configuration, like <<oauth2resourceserver-jwt-validat
 
 Or, exposing a `JwtDecoder` `@Bean` has the same effect as `decoder()`:
 
-```java
+[source,java]
+----
 @Bean
 public JwtDecoder jwtDecoder() {
     return NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build();
 }
-```
+----
 
 [[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 <<oauth2-resourceserver-jwt-boot-algorithm,Spring Boot>>, <<oauth2-resourceserver-jwt-decoder-builder,the NimbusJwtDecoder builder>>, or from the <<oauth2-resourceserver-jwt-decoder-jwk-response,JWK Set response>>.
+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>>.
 
-[[oauth2-resourceserver-jwt-boot-algorithm]]
+[[oauth2resourceserver-jwt-boot-algorithm]]
 ==== Via Spring Boot
 
 The simplest way to set the algorithm is as a property:
 
-```yaml
+[source,yaml]
+----
 spring:
   security:
     oauth2:
@@ -644,34 +656,37 @@ spring:
         jwt:
           jws-algorithm: RS512
           jwk-set-uri: https://idp.example.org/.well-known/jwks.json
-```
+----
 
-[[oauth2-resourceserver-jwt-decoder-builder]]
+[[oauth2resourceserver-jwt-decoder-builder]]
 ==== Using a Builder
 
 For greater power, though, we can use a builder that ships with `NimbusJwtDecoder`:
 
-```java
+[source,java]
+----
 @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:
 
-```java
+[source,java]
+----
 @Bean
 JwtDecoder jwtDecoder() {
     return NimbusJwtDecoder.fromJwkSetUri(this.jwkSetUri)
             .jwsAlgorithm(RS512).jwsAlgorithm(EC512).build();
 }
-```
+----
 
 Or, you can call `jwsAlgorithms`:
 
-```java
+[source,java]
+----
 @Bean
 JwtDecoder jwtDecoder() {
     return NimbusJwtDecoder.fromJwkSetUri(this.jwkSetUri)
@@ -680,9 +695,9 @@ JwtDecoder jwtDecoder() {
                     algorithms.add(EC512);
             }).build();
 }
-```
+----
 
-[[oauth2-resourceserver-jwt-decoder-jwk-response]]
+[[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.
@@ -717,25 +732,27 @@ The public key can be provided via <<oauth2resourceserver-jwt-decoder-public-key
 Specifying a key via Spring Boot is quite simple.
 The key's location can be specified like so:
 
-```yaml
+[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`:
 
-```java
+[source,java]
+----
 @Bean
 BeanFactoryPostProcessor conversionServiceCustomizer() {
     return beanFactory ->
         beanFactory.getBean(RsaKeyConversionServicePostProcessor.class)
                 .setResourceLoader(new CustomResourceLoader());
 }
-```
+----
 
 Specify your key's location:
 
@@ -768,12 +785,13 @@ public JwtDecoder jwtDecoder() {
 Using a single symmetric key is also simple.
 You can simply load in your `SecretKey` and use the appropriate `NimbusJwtDecoder` builder, like so:
 
-```java
+[source,java]
+----
 @Bean
 public JwtDecoder jwtDecoder() {
     return NimbusJwtDecoder.withSecretKey(this.key).build();
 }
-```
+----
 
 [[oauth2resourceserver-jwt-authorization]]
 === Configuring Authorization
@@ -786,7 +804,8 @@ When this is the case, Resource Server will attempt to coerce these scopes into
 
 This means that to protect an endpoint or method with a scope derived from a JWT, the corresponding expressions should include this prefix:
 
-```java
+[source,java]
+----
 @EnableWebSecurity
 public class DirectlyConfiguredJwkSetUri extends WebSecurityConfigurerAdapter {
     protected void configure(HttpSecurity http) {
@@ -799,14 +818,15 @@ public class DirectlyConfiguredJwkSetUri extends WebSecurityConfigurerAdapter {
             .oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt);
     }
 }
-```
+----
 
 Or similarly with method security:
 
-```java
+[source,java]
+----
 @PreAuthorize("hasAuthority('SCOPE_messages')")
 public List<Message> getMessages(...) {}
-```
+----
 
 [[oauth2resourceserver-jwt-authorization-extraction]]
 ==== Extracting Authorities Manually
@@ -817,7 +837,8 @@ Or, at other times, the resource server may need to adapt the attribute or a com
 
 To this end, the DSL exposes `jwtAuthenticationConverter()`:
 
-```java
+[source,java]
+----
 @EnableWebSecurity
 public class DirectlyConfiguredJwkSetUri extends WebSecurityConfigurerAdapter {
     protected void configure(HttpSecurity http) {
@@ -838,14 +859,15 @@ Converter<Jwt, AbstractAuthenticationToken> grantedAuthoritiesExtractor() {
             (new GrantedAuthoritiesExtractor());
     return jwtAuthenticationConveter;
 }
-```
+----
 
 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:
 
-```java
+[source,java]
+----
 static class GrantedAuthoritiesExtractor
         implements Converter<Jwt, Collection<GrantedAuthority>> {
 
@@ -858,17 +880,18 @@ static class GrantedAuthoritiesExtractor
                 .collect(Collectors.toList());
     }
 }
-```
+----
 
 For more flexibility, the DSL supports entirely replacing the converter with any class that implements `Converter<Jwt, AbstractAuthenticationToken>`:
 
-```java
+[source,java]
+----
 static class CustomAuthenticationConverter implements Converter<Jwt, AbstractAuthenticationToken> {
     public AbstractAuthenticationToken convert(Jwt jwt) {
         return new CustomAuthenticationToken(jwt);
     }
 }
-```
+----
 
 [[oauth2resourceserver-jwt-validation]]
 === Configuring Validation
@@ -887,7 +910,8 @@ This can cause some implementation heartburn as the number of collaborating serv
 
 Resource Server uses `JwtTimestampValidator` to verify a token's validity window, and it can be configured with a `clockSkew` to alleviate the above problem:
 
-```java
+[source,java]
+----
 @Bean
 JwtDecoder jwtDecoder() {
      NimbusJwtDecoder jwtDecoder = (NimbusJwtDecoder)
@@ -901,7 +925,7 @@ JwtDecoder jwtDecoder() {
 
      return jwtDecoder;
 }
-```
+----
 
 [NOTE]
 By default, Resource Server configures a clock skew of 30 seconds.
@@ -911,7 +935,8 @@ By default, Resource Server configures a clock skew of 30 seconds.
 
 Adding a check for the `aud` claim is simple with the `OAuth2TokenValidator` API:
 
-```java
+[source,java]
+----
 public class AudienceValidator implements OAuth2TokenValidator<Jwt> {
     OAuth2Error error = new OAuth2Error("invalid_token", "The required audience is missing", null);
 
@@ -923,11 +948,12 @@ public class AudienceValidator implements OAuth2TokenValidator<Jwt> {
         }
     }
 }
-```
+----
 
 Then, to add into a resource server, it's a matter of specifying the `JwtDecoder` instance:
 
-```java
+[source,java]
+----
 @Bean
 JwtDecoder jwtDecoder() {
     NimbusJwtDecoder jwtDecoder = (NimbusJwtDecoder)
@@ -941,7 +967,7 @@ JwtDecoder jwtDecoder() {
 
     return jwtDecoder;
 }
-```
+----
 
 [[oauth2resourceserver-jwt-claimsetmapping]]
 === Configuring Claim Set Mapping
@@ -1075,7 +1101,8 @@ First, include the needed dependencies and second, indicate the introspection en
 
 To specify where the introspection endpoint is, simply do:
 
-```yaml
+[source,yaml]
+----
 security:
   oauth2:
     resourceserver:
@@ -1083,7 +1110,7 @@ security:
         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.
 
@@ -1133,21 +1160,23 @@ Once a token is authenticated, an instance of `BearerTokenAuthentication` is set
 
 This means that it's available in `@Controller` methods when using `@EnableWebMvc` in your configuration:
 
-```java
+[source,java]
+----
 @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:
 
-```java
+[source,java]
+----
 @GetMapping("/foo")
 public String foo(@AuthenticationPrincipal OAuth2AuthenticatedPrincipal principal) {
     return principal.getAttribute("sub") + " is the subject";
 }
-```
+----
 
 ==== Looking Up Attributes Via SpEL
 
@@ -1170,7 +1199,8 @@ 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:
 
-```java
+[source,java]
+----
 protected void configure(HttpSecurity http) {
     http
         .authorizeRequests()
@@ -1178,13 +1208,14 @@ protected void configure(HttpSecurity http) {
             .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:
 
-```java
+[source,java]
+----
 @EnableWebSecurity
 public class MyCustomSecurityConfiguration extends WebSecurityConfigurerAdapter {
     protected void configure(HttpSecurity http) {
@@ -1198,7 +1229,7 @@ public class MyCustomSecurityConfiguration extends WebSecurityConfigurerAdapter
                     .introspector(myIntrospector());
     }
 }
-```
+----
 
 The above requires the scope of `message:read` for any URL that starts with `/messages/`.
 
@@ -1206,12 +1237,13 @@ Methods on the `oauth2ResourceServer` DSL will also override or replace auto con
 
 For example, the second `@Bean` Spring Boot creates is an `OpaqueTokenIntrospector`, which decodes `String` tokens into validated instances of `OAuth2AuthenticatedPrincipal`:
 
-```java
+[source,java]
+----
 @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.
 
@@ -1222,7 +1254,8 @@ And its configuration can be overridden using `introspectionUri()` and `introspe
 
 An authorization server's Introspection Uri can be configured <<oauth2resourceserver-opaque-introspectionuri,as a configuration property>> or it can be supplied in the DSL:
 
-```java
+[source,java]
+----
 @EnableWebSecurity
 public class DirectlyConfiguredIntrospectionUri extends WebSecurityConfigurerAdapter {
     protected void configure(HttpSecurity http) {
@@ -1236,7 +1269,7 @@ public class DirectlyConfiguredIntrospectionUri extends WebSecurityConfigurerAda
                     .introspectionClientCredentials("client", "secret");
     }
 }
-```
+----
 
 Using `introspectionUri()` takes precedence over any configuration property.
 
@@ -1245,7 +1278,8 @@ Using `introspectionUri()` takes precedence over any configuration property.
 
 More powerful than `introspectionUri()` is `introspector()`, which will completely replace any Boot auto configuration of `OpaqueTokenIntrospector`:
 
-```java
+[source,java]
+----
 @EnableWebSecurity
 public class DirectlyConfiguredIntrospector extends WebSecurityConfigurerAdapter {
     protected void configure(HttpSecurity http) {
@@ -1258,7 +1292,7 @@ public class DirectlyConfiguredIntrospector extends WebSecurityConfigurerAdapter
                     .introspector(myCustomIntrospector());
     }
 }
-```
+----
 
 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.
 
@@ -1267,12 +1301,13 @@ This is handy when deeper configuration, like <<oauth2resourceserver-opaque-auth
 
 Or, exposing a `OpaqueTokenIntrospector` `@Bean` has the same effect as `introspector()`:
 
-```java
+[source,java]
+----
 @Bean
 public OpaqueTokenIntrospector introspector() {
     return new NimbusOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
 }
-```
+----
 
 [[oauth2resourceserver-opaque-authorization]]
 === Configuring Authorization
@@ -1314,18 +1349,20 @@ By default, Opaque Token support will extract the scope claim from an introspect
 
 For example, if the introspection response were:
 
-```json
+[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 `OpaqueTokenIntrospector` that takes a look at the attribute set and converts in its own way:
 
-```java
+[source,java]
+----
 public class CustomAuthoritiesOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
     private OpaqueTokenIntrospector delegate =
             new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
@@ -1343,16 +1380,17 @@ public class CustomAuthoritiesOpaqueTokenIntrospector implements OpaqueTokenIntr
                 .collect(Collectors.toList());
     }
 }
-```
+----
 
 Thereafter, this custom introspector can be configured simply by exposing it as a `@Bean`:
 
-```java
+[source,java]
+----
 @Bean
 public OpaqueTokenIntrospector introspector() {
     return new CustomAuthoritiesOpaqueTokenIntrospector();
 }
-```
+----
 
 [[oauth2resourceserver-opaque-timeouts]]
 === Configuring Timeouts
@@ -1387,7 +1425,8 @@ So, let's say that you've got a requirement that requires you to check with the
 
 Even though you are using the JWT format for the token, your validation method is introspection, meaning you'd want to do:
 
-```yaml
+[source,yaml]
+----
 spring:
   security:
     oauth2:
@@ -1396,7 +1435,7 @@ spring:
           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.
@@ -1406,7 +1445,8 @@ 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:
 
-```java
+[source,java]
+----
 public class JwtOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
     private OpaqueTokenIntrospector delegate =
             new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
@@ -1429,16 +1469,17 @@ public class JwtOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
         }
     }
 }
-```
+----
 
 Thereafter, this custom introspector can be configured simply by exposing it as a `@Bean`:
 
-```java
+[source,java]
+----
 @Bean
 public OpaqueTokenIntrospector introspector() {
     return new JwtOpaqueTokenIntropsector();
 }
-```
+----
 
 [[oauth2resourceserver-opaque-userinfo]]
 === Calling a `/userinfo` Endpoint
@@ -1454,7 +1495,8 @@ This implementation below does three things:
 * Looks up the appropriate client registration associated with the `/userinfo` endpoint
 * Invokes and returns the response from the `/userinfo` endpoint
 
-```java
+[source,java]
+----
 public class UserInfoOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
     private final OpaqueTokenIntrospector delegate =
             new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
@@ -1475,12 +1517,13 @@ public class UserInfoOpaqueTokenIntrospector implements OpaqueTokenIntrospector
         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`:
 
-```java
+[source,java]
+----
 public class UserInfoOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
     private final OpaqueTokenIntrospector delegate =
             new NimbusOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
@@ -1492,19 +1535,17 @@ public class UserInfoOpaqueTokenIntrospector implements OpaqueTokenIntrospector
         return makeUserInfoRequest(authorized);
     }
 }
-```
+----
 
 Either way, having created your `OpaqueTokenIntrospector`, you should publish it as a `@Bean` to override the defaults:
 
-```java
+[source,java]
+----
 @Bean
 OpaqueTokenIntrospector introspector() {
     return new UserInfoOpaqueTokenIntrospector(...);
 }
-```
-
-[[jc-authentication]]
-== Authentication
+----
 
 Thus far we have only taken a look at the most basic authentication configuration.
 Let's take a look at a few slightly more advanced options for configuring authentication.