Resource Server Docs - Servlet

Fixes: gh-5912

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

@@ -920,6 +920,495 @@ The following additional resources describe advanced configuration options:
 ** <<oauth2login-advanced-oauth2-user-service, OAuth 2.0 UserService>>
 ** <<oauth2login-advanced-oidc-user-service, OpenID Connect 1.0 UserService>>
 
+[[oauth2resourceserver]]
+== OAuth 2.0 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].
+
+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.
+
+=== Dependencies
+
+Most Resource Server support is collected into `spring-security-oauth2-resource-server`.
+However, the support for decoding and verifying JWTs is in `spring-security-oauth2-jose`, meaning that both are necessary in order to have a working resource server that supports JWT-encoded Bearer Tokens.
+
+[[oauth2resourceserver-minimalconfiguration]]
+=== Minimal Configuration
+
+When using https://spring.io/projects/spring-boot[Spring Boot], configuring an application as a resource server consists of two basic steps.
+First, include the needed dependencies and second, indicate the location of the authorization server.
+
+==== Specifying the Authorization Server
+
+To specify which authorization server to use, simply do:
+
+```yaml
+security:
+  oauth2:
+    resourceserver:
+      jwt:
+        issuer-uri: https://the.issuer.location
+```
+
+Where `https://the.issuer.location` 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 and subsequently validate incoming JWTs.
+
+[NOTE]
+To use the `issuer-uri` property, it must also be true that `https://the.issuer.location/.well-known/openid-configuration` is a supported endpoint for the authorization server.
+This endpoint is referred to as a https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[Provider Configuration] endpoint.
+
+==== Startup Expectations
+
+When this property and these dependencies are used, Resource Server will automatically configure itself to validate JWT-encoded Bearer Tokens.
+
+It achieves this through a deterministic startup process:
+
+1. Hit the Provider Configuration endpoint, `https://the.issuer.location/.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://the.issuer.location`.
+
+A consequence of this process is that the authorization server must be up and receiving requests in order for Resource Server to successfully start up.
+
+[NOTE]
+If the authorization server is down when Resource Server queries it (given appropriate timeouts), then startup will fail.
+
+==== Runtime Expectations
+
+Once the application is started up, Resource Server will attempt to process any request containing an `Authorizatization: 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 a well-formed JWT token, Resource Server will validate the JWTs `exp` and `nbf` timestamps and the JWTs `iss` claim.
+It will also validate the signature against a public key obtained from the `jwks_url` endpoint and matched against the JWTs header.
+
+The resulting `Authentication#getPrincipal`, by default, is a Spring Security `Jwt` object, and `Authentication#getName` map's to the JWT's `sub` property, if one is present.
+
+From here, consider jumping to:
+
+<<oauth2resourceserver-jwkseturi,How to Configure without Tying Resource Server startup to an authorization server's availability>>
+
+<<oauth2resourceserver-sansboot,How to Configure without Spring Boot>>
+
+[[oauth2resourceserver-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`:
+
+```yaml
+security:
+  oauth2:
+    resourceserver:
+      jwt:
+        jwk-set-uri: https://the.issuer.location/.well-known/jwks.json
+```
+
+[NOTE]
+The JWK Set uri is not standardized, but can typically be found in the authorization server's documentation
+
+Consequently, Resource Server will not ping the authorization server at startup.
+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 <<oauth2resourceserver-jwkseturi-dsl,DSL>>.
+
+[[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 `WebSecurityConfigurerAdapter` that configures the app as a resource server:
+
+```java
+protected void configure(HttpSecurity http) {
+    http
+        .authorizeRequests()
+            .anyRequest().authenticated()
+            .and()
+        .oauth2ResourceServer()
+            .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
+@EnableWebSecurity
+public class MyCustomSecurityConfiguration extends WebSecurityConfigurerAdapter {
+    protected void configure(HttpSecurity http) {
+        http
+            .authorizeRequests()
+                .mvcMatchers("/admin/**").hasAuthority("SCOPE_admin")
+                .anyRequest().authenticated()
+                .and()
+            .oauth2ResourceServer()
+                .jwt()
+                    .jwtAuthenticationConverter(myConverter());
+    }
+}
+```
+
+Methods on the `oauth2ResourceServer` DSL will also override or replace auto configuration.
+
+For example, the second `@Bean` Spring Boot creates is a `JwtDecoder`, which decodes `String` tokens into validated instances of `Jwt`:
+
+```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.
+
+And its configuration can be overridden using `jwkSetUri()` or replaced using `decoder()`.
+
+[[oauth2resourceserver-jwkseturi-dsl]]
+==== Using `jwkSetUri()`
+
+An authorization server's JWK Set Uri can be configured <<oauth2resourceserver-jwkseturi,as a configuration property>> or it can be supplied in the DSL:
+
+```java
+@EnableWebSecurity
+public class DirectlyConfiguredJwkSetUri extends WebSecurityConfigurerAdapter {
+    protected void configure(HttpSecurity http) {
+        http
+            .authorizeRequests()
+                .anyRequest().authenticated()
+                .and()
+            .oauth2ResourceServer()
+                .jwt()
+                    .jwkSetUri("https://the.issuer.location/.well-known/jwks.json");
+    }
+}
+```
+
+Using `jwkSetUri()` takes precedence over any configuration property.
+
+[[oauth2resourceserver-decoder-dsl]]
+==== Using `decoder()`
+
+More powerful than `jwkSetUri()` is `decoder()`, which will completely replace any Boot auto configuration of `JwtDecoder`:
+
+```java
+@EnableWebSecurity
+public class DirectlyConfiguredJwkSetUri extends WebSecurityConfigurerAdapter {
+    protected void configure(HttpSecurity http) {
+        http
+            .authorizeRequests()
+                .anyRequest().authenticated()
+                .and()
+            .oauth2ResourceServer()
+                .jwt()
+                    .decoder(myCustomDecoder());
+    }
+}
+```
+
+This is handy when deeper configuration, like <<oauth2resourceserver-validator,validation>>, <<oauth2resourceserver-claimsetmapping,mapping>>, or <<oauth2resourceserver-timeouts,request timeouts>>, is necessary.
+
+[[oauth2resourceserver-decoder-bean]]
+==== Exposing a `JwtDecoder` `@Bean`
+
+Or, exposing a `JwtDecoder` `@Bean` has the same effect as `decoder()`:
+
+```java
+@Bean
+public JwtDecoder jwtDecoder() {
+    return new NimbusJwtDecoderJwkSupport(jwkSetUri);
+}
+```
+
+[[oauth2resourceserver-authorization]]
+=== Configuring Authorization
+
+A JWT that is issued from an OAuth 2.0 Authorization Server will typically either have a `scope` or `scp` attribute, indicating the scopes (or authorities) it's been granted, for example:
+
+`{ ..., "scope" : "messages contacts"}`
+
+When this is the case, Resource Server will attempt to coerce these scopes into a list of granted authorities, prefixing each scope with the prefix "SCOPE_".
+
+This means that to protect an endpoint or method with a scope derived from a JWT, the corresponding expressions should include this prefix:
+
+```java
+@EnableWebSecurity
+public class DirectlyConfiguredJwkSetUri extends WebSecurityConfigurerAdapter {
+    protected void configure(HttpSecurity http) {
+        http
+            .authorizeRequests()
+                .mvcMatchers("/contacts/**").hasAuthority("SCOPE_contacts")
+                .mvcMatchers("/messages/**").hasAuthority("SCOPE_messages")
+                .anyRequest().authenticated()
+                .and()
+            .oauth2ResourceServer()
+                .jwt();
+    }
+}
+```
+
+Or similarly with method security:
+
+```java
+@PreAuthorize("hasAuthority('SCOPE_messages')")
+public List<Message> getMessages(...) {}
+```
+
+[[oauth2resourceserver-authorization-extraction]]
+==== Extracting Authorities Manually
+
+However, there are a number of circumstances where this default is insufficient.
+For example, some authorization server's don't use the `scope` attribute, but instead have their own custom attribute.
+Or, at other times, the resource server may need to adapt the attribute or a composition of attributes into internalized authorities.
+
+To this end, the DSL exposes `jwtAuthenticationConverter()`:
+
+```java
+@EnableWebSecurity
+public class DirectlyConfiguredJwkSetUri extends WebSecurityConfigurerAdapter {
+    protected void configure(HttpSecurity http) {
+        http
+            .authorizeRequests()
+                .anyRequest().authenticated()
+                .and()
+            .oauth2ResourceServer()
+                .jwt()
+                    .jwtAuthenticationConverter(grantedAuthoritiesExtractor());
+    }
+}
+
+Converter<Jwt, AbstractAuthenticationToken> grantedAuthoritiesExtractor() {
+    return new GrantedAuthoritiesExtractor();
+}
+```
+
+which is responsible for converting a `Jwt` into an `Authentication`.
+
+We can override this quite simply to alter the way granted authorities are derived:
+
+```java
+static class GrantedAuthoritiesExtractor extends JwtAuthenticationConverter {
+    protected Collection<GrantedAuthorities> extractAuthorities(Jwt jwt) {
+        Collection<String> authorities = (Collection<String>)
+                jwt.getClaims().get("mycustomclaim");
+
+        return authorities.stream()
+                .map(SimpleGrantedAuthority::new)
+                .collect(Collectors.toList());
+    }
+}
+```
+
+For more flexibility, the DSL supports entirely replacing the converter with any class that implements `Converter<Jwt, AbstractAuthenticationToken>`:
+
+```java
+static class CustomAuthenticationConverter implements Converter<Jwt, AbstractAuthenticationToken> {
+    public AbstractAuthenticationToken convert(Jwt jwt) {
+        return new CustomAuthenticationToken(jwt);
+    }
+}
+```
+
+[[oauth2resourceserver-validation]]
+=== Configuring Validation
+
+Using <<oauth2resourceserver-minimalconfiguration,minimal Spring Boot configuration>>, indicating the authorization server's issuer uri, Resource Server will default to verifying the `iss` claim as well as the `exp` and `nbf` timestamp claims.
+
+In circumstances where validation needs to be customized, Resource Server ships with two standard validators and also accepts custom `OAuth2TokenValidator` instances.
+
+[[oauth2resourceserver-validation-clockskew]]
+==== Customizing Timestamp Validation
+
+JWT's typically have a window of validity, with the start of the window indicated in the `nbf` claim and the end indicated in the `exp` claim.
+
+However, every server can experience clock drift, which can cause tokens to appear expired to one server, but not to another.
+This can cause some implementation heartburn as the number of collaborating servers increases in a distributed system.
+
+Resource Server uses `JwtTimestampValidator` to verify a token's validity window, and it can be configured with a `clockSkew` to alleviate the above problem:
+
+```java
+@Bean
+JwtDecoder jwtDecoder() {
+     NimbusJwtDecoderJwkSupport jwtDecoder = (NimbusJwtDecoderJwkSupport)
+             JwtDecoders.withOidcIssuerLocation(issuerUri);
+
+     OAuth2TokenValidator<Jwt> withClockSkew = new DelegatingOAuth2TokenValidator<>(
+            new JwtTimestampValidator(Duration.ofSeconds(60)),
+            new IssuerValidator(issuerUri));
+
+     jwtDecoder.setJwtValidator(withClockSkew);
+
+     return jwtDecoder;
+}
+```
+
+[NOTE]
+By default, Resource Server configures a clock skew of 30 seconds.
+
+[[oauth2resourceserver-validation-custom]]
+==== Configuring a Custom Validator
+
+Adding a check for the `aud` claim is simple with the `OAuth2TokenValidator` API:
+
+```java
+public class AudienceValidator implements OAuth2TokenValidator<Jwt> {
+    OAuth2Error error = new OAuth2Error("invalid_token", "The required audience is missing", null);
+
+    public OAuth2TokenValidatorResult validate(Jwt jwt) {
+        if (jwt.getAudience().contains("messaging")) {
+            return OAuth2TokenValidatorResult.success();
+        } else {
+            return OAuth2TokenValidatorResult.failure(error);
+        }
+    }
+}
+```
+
+Then, to add into a resource server, it's a matter of specifying the `JwtDecoder` instance:
+
+```java
+@Bean
+JwtDecoder jwtDecoder() {
+    NimbusJwtDecoderJwkSupport jwtDecoder = (NimbusJwtDecoderJwkSupport)
+        JwtDecoders.withOidcIssuerLocation(issuerUri);
+
+    OAuth2TokenValidator<Jwt> audienceValidator = new AudienceValidator();
+    OAuth2TokenValidator<Jwt> withIssuer = JwtValidators.createDefaultWithIssuer(issuerUri);
+    OAuth2TokenValidator<Jwt> withAudience = new DelegatingOAuth2TokenValidator<>(withIssuer, audienceValidator);
+
+    jwtDecoder.setJwtValidator(withAudience);
+
+    return jwtDecoder;
+}
+```
+
+[[oauth2resourceserver-claimsetmapping]]
+=== Configuring Claim Set Mapping
+
+Spring Security uses the https://bitbucket.org/connect2id/nimbus-jose-jwt/wiki/Home[Nimbus] library for parsing JWTs and validating their signatures.
+Consequently, Spring Security is subject to Nimbus's interpretation of each field value and how to coerce each into a Java type.
+
+For example, because Nimbus remains Java 7 compatible, it doesn't use `Instant` to represent timestamp fields.
+
+And it's entirely possible to use a different library or for JWT processing, which may make its own coercion decisions that need adjustment.
+
+Or, quite simply, a resource server may want to add or remove claims from a JWT for domain-specific reasons.
+
+For these purposes, Resource Server supports mapping the JWT claim set with `MappedJwtClaimSetConverter`.
+
+[[oauth2resourceserver-claimsetmapping-singleclaim]]
+==== Customizing the Conversion of a Single Claim
+
+By default, `MappedJwtClaimSetConverter` will attempt to coerce claims into the following types:
+
+
+|============
+| Claim | Java Type
+| `aud` | `Collection<String>`
+| `exp` | `Instant`
+| `iat` | `Instant`
+| `iss` | `URL`
+| `jti` | `String`
+| `nbf` | `Instant`
+| `sub` | `String`
+|============
+
+An individual claim's conversion strategy can be configured using `MappedJwtClaimSetConverter.withDefaults`:
+
+```java
+@Bean
+JwtDecoder jwtDecoder() {
+    NimbusJwtDecoderJwkSupport jwtDecoder = new NimbusJwtDecoderJwkSupport(jwkSetUri);
+
+    MappedJwtClaimSetConverter converter = MappedJwtClaimSetConverter
+            .withDefaults(Collections.singletonMap("sub", this::lookupUserIdBySub));
+    jwtDecoder.setJwtClaimSetConverter(converter);
+
+    return jwtDecoder;
+}
+```
+This will keep all the defaults, except it will override the default claim converter for `sub`.
+
+[[oauth2resourceserver-claimsetmapping-add]]
+==== Adding a Claim
+
+`MappedJwtClaimSetConverter` can also be used to add a custom claim, for example, to adapt to an existing system:
+
+```java
+MappedJwtClaimSetConverter.withDefaults(Collections.singletonMap("custom", custom -> "value"));
+```
+
+[[oauth2resourceserver-claimsetmapping-remove]]
+==== Removing a Claim
+
+And removing a claim is also simple, using the same API:
+
+```java
+MappedJwtClaimSetConverter.withDefaults(Collections.singletonMap("legacyclaim", legacy -> null));
+```
+
+[[oauth2resourceserver-claimsetmapping-rename]]
+==== Renaming a Claim
+
+In more sophisticated scenarios, like consulting multiple claims at once or renaming a claim, Resource Server accepts any class that implements `Converter<Map<String, Object>, Map<String,Object>>`:
+
+```java
+public class UsernameSubClaimAdapter implements Converter<Map<String, Object>, Map<String, Object>> {
+    private final MappedJwtClaimSetConverter delegate =
+            MappedJwtClaimSetConverter.withDefaults(Collections.emptyMap());
+
+    public Map<String, Object> convert(Map<String, Object> claims) {
+        Map<String, Object> convertedClaims = this.delegate.convert(claims);
+
+        String username = (String) convertedClaims.get("user_name");
+        convertedClaims.put("sub", username);
+
+        return convertedClaims;
+    }
+}
+```
+
+And then, the instance can be supplied like normal:
+
+```java
+@Bean
+JwtDecoder jwtDecoder() {
+    NimbusJwtDecoderJwkSupport jwtDecoder = new NimbusJwtDecoderJwkSupport(jwkSetUri);
+    jwtDecoder.setJwtClaimSetConverter(new UsernameSubClaimAdapter());
+    return jwtDecoder;
+}
+```
+
+[[oauth2resourceserver-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, `NimbusJwtDecoderJwkSupport` accepts an instance of `RestOperations`:
+
+```java
+@Bean
+public JwtDecoder jwtDecoder(RestTemplateBuilder builder) {
+    RestOperations rest = builder
+            .setConnectionTimeout(60000)
+            .setReadTimeout(60000)
+            .build();
+
+    NimbusJwtDecoderJwkSupport jwtDecoder = new NimbusJwtDecoderJwkSupport(jwkSetUri);
+    jwtDecoder.setRestOperations(rest);
+    return jwtDecoder;
+}
+```
+
 [[jc-authentication]]
 == Authentication