Chapter 15: Implementing an OAuth 2 resource server
The introduction identifies the OAuth 2 resource server as the backend that uses tokens from an authorization server and explains why its security must be implemented even when the authorization server is provided by a third party.
After this chapter you will be able to
- OAuth 2 resource server role. Explain that a resource server is the backend service in an OAuth 2 system and that it uses a token generated by the authorization server.
- JWT authenticity and token data. Explain that the resource server must verify a JWT came from the expected authorization server and can read the data in the non-opaque token for authorization.
- Public key set validation. Trace how the resource server obtains the authorization server’s public key set URI and uses a retrieved key to validate a JWT signature.
- Resource server security configuration. Describe how the example configures JWT authentication and requires authentication for its test endpoint.
- Custom claim in access tokens. Explain why the authorization server adds a custom claim to an access token and how this example adds the priority claim.
- Custom authentication conversion. Describe how the resource server represents the priority claim in its authentication object and converts a JWT into that object.
- When introspection is needed. Explain why a resource server uses introspection when it handles opaque tokens or needs token revocation at the authorization server.
- Resource server client credentials. Explain why the resource server must be registered as a client at the authorization server and have its own credentials.
- Opaque token authentication configuration. Describe the values and Spring Security configuration used to authenticate requests through introspection, including the separate requirement to protect endpoints.
- Resource server authentication delegation. Trace the authentication path from an intercepted HTTP request through the authentication manager to the authentication provider, and explain where a resource server can change that path.
- Mixed token authentication routing. Explain how the example routes requests between JWT and opaque-token authentication, and when further customization requires a custom provider.
What it builds on
- The big picture of OAuth 2 and OpenID Connect (chapter 13) · The roles in an OAuth 2 system.
- Using non-opaque tokens (chapter 13) · Introduces non-opaque tokens.
- Implementing basic authentication using JSON web tokens (chapter 14) · Provides an authorization server that issues JSON web tokens.
- Implementing filters in the Spring Security architecture (chapter 5) · Introduces Spring Security filter-chain configuration.
- Running the authorization code grant type (chapter 14) · Shows how to obtain a token using the authorization code grant type.
- Using opaque tokens and introspection (chapter 14) · The previously discussed opaque-token and introspection process.
- Selecting requests to apply authorization restrictions (chapter 8) · Applying authorization restrictions to requests.
- Running the client credentials grant type (chapter 14) · Obtaining an access token with the client credentials grant type.
Section by section
Introduction
The introduction identifies the OAuth 2 resource server as the backend that uses tokens from an authorization server and explains why its security must be implemented even when the authorization server is provided by a third party.
- OAuth 2 resource server role: Explain that a resource server is the backend service in an OAuth 2 system and that it uses a token generated by the authorization server.
Why it matters: This distinction places the backend’s responsibility within the OAuth 2 system. - Backend security responsibility: Explain why choosing a third-party authorization server does not remove the need to implement authentication and authorization properly on the backend.
Why it matters: Using an existing authorization server does not eliminate the backend security work.
Key terms: resource server, authorization server, token, authentication, authorization, backend
15.1 Configuring JWT validation
This section configures a Spring Security resource server to validate JWT access tokens and tests a protected endpoint with a token from an authorization server.
- JWT authenticity and token data: Explain that the resource server must verify a JWT came from the expected authorization server and can read the data in the non-opaque token for authorization.
Why it matters: Reading a token’s data is not enough unless the server can trust its issuer. - Public key set validation: Trace how the resource server obtains the authorization server’s public key set URI and uses a retrieved key to validate a JWT signature.
Why it matters: This connects the configured key-set location to the actual signature check. - Resource server security configuration: Describe how the example configures JWT authentication and requires authentication for its test endpoint.
Why it matters: JWT validation will not test access control unless the endpoint is configured to require authentication. - Bearer token endpoint test: Describe how the example obtains an access token from the authorization server and sends it to the protected /demo endpoint.
Why it matters: Sending a token to a protected endpoint demonstrates whether the resource server configuration works.
Key terms: JWTs, non-opaque tokens, authorization server, well-known configuration endpoint, public key set URI, access token’s signature, resource server starter, SecurityFilterChain, oauth2ResourceServer(), jwt()
15.2 Using customized JWTs
The section shows how to add a custom priority claim to a JWT and make its value available in a resource server’s authentication object.
- Custom claim in access tokens: Explain why the authorization server adds a custom claim to an access token and how this example adds the priority claim.
Why it matters: The resource server can use application-specific token values when applying authorization rules. - Custom authentication conversion: Describe how the resource server represents the priority claim in its authentication object and converts a JWT into that object.
Why it matters: Putting token details in the security context’s authentication object makes them accessible to authorization configurations. - Converter configuration and verification: Trace how the resource server enables the custom converter and checks that priority reaches the security context’s authentication object.
Why it matters: The endpoint response confirms that the custom token value reached the authentication object used by the resource server.
Key terms: custom claim, priority, OAuth2TokenCustomizer, access token, JwtAuthenticationToken, CustomAuthentication, Converter, Jwt, authorities, jwtAuthenticationConverter()
15.3 Configuring token validation through introspection
This section shows how to configure and test an OAuth 2 resource server that validates access tokens through introspection.
- When introspection is needed: Explain why a resource server uses introspection when it handles opaque tokens or needs token revocation at the authorization server.
Why it matters: It explains why this resource server validates tokens through the authorization server rather than relying on signature-based validation. - Resource server client credentials: Explain why the resource server must be registered as a client at the authorization server and have its own credentials.
Why it matters: The introspection request needs its own authenticated connection between the two servers. - Opaque token authentication configuration: Describe the values and Spring Security configuration used to authenticate requests through introspection, including the separate requirement to protect endpoints.
Why it matters: These settings tell Spring Security where and how to check tokens, while authorization rules make the endpoints require authentication. - Bearer token demonstration: Describe how the section tests the configured resource server and why its introspection setup does not depend on the grant type used to obtain the token.
Why it matters: The demonstration checks that a token obtained from the authorization server can access a protected resource.
Key terms: opaque tokens, introspection, token revocation, resource server, client credentials, RegisteredClientRepository, introspection endpoint, introspection URI, client ID, client secret
15.4 Implementing multitenant systems
This section explains how a resource server selects authentication logic when it must work with multiple authorization servers or nonstandard integrations.
- Resource server authentication delegation: Trace the authentication path from an intercepted HTTP request through the authentication manager to the authentication provider, and explain where a resource server can change that path.
Why it matters: This delegation explains how one resource server can accommodate different authentication requirements. - Multiple JWT issuer configuration: Describe when the provided JwtIssuerAuthenticationManagerResolver can be used and what the example supplies to configure it.
Why it matters: The provided resolver avoids writing a custom resolver for the multiple-JWT-issuer case. - Mixed token authentication routing: Explain how the example routes requests between JWT and opaque-token authentication, and when further customization requires a custom provider.
Why it matters: It distinguishes choosing the authentication path from implementing the logic used on that path.
Key terms: filter, authentication manager, authentication provider, authentication manager resolver, JwtIssuerAuthenticationManagerResolver, authenticationManagerResolver(), authorization servers, JWTs, type header, JwtAuthenticationProvider
15.5 Summary
Where this is used later
- Creating a reactive OAuth 2 resource server (chapter 17) · JWT validation by an OAuth 2 resource server
- Testing authentication (chapter 18) · resource-server use of opaque tokens
Concepts explained in this chapter
- oauth2ResourceServeroauth2ResourceServer is a Spring Security configuration method for enabling and configuring OAuth 2 resource-server authentication.
- opaque tokenAn opaque token is an access token whose contents do not reveal claims or other usable information to the resource server, which must obtain its validity and associated details from the authorization server.
- JSON Web TokenA JSON Web Token is a compact token format that represents claims as a digitally signed or otherwise protected JSON-based value.
- resource serverA resource server is an OAuth server that hosts protected resources and accepts valid access tokens for authorized requests.
- public key set URIA key set endpoint is an authorization-server endpoint that exposes the cryptographic keys used to validate signed tokens.
- claimA claim is a named assertion about a subject or other token property carried in a JSON Web Token.
- jwkSetUrijwkSetUri is a JWT resource-server configuration method that specifies the URI from which public signing keys are obtained.
- public key setA public key set is a collection of public cryptographic keys available for verifying digital signatures.
- token introspectionToken introspection is an OAuth protocol operation in which a resource server asks an authorization server whether a token is valid and requests its associated metadata.
- introspection uriAn introspection endpoint is an OAuth endpoint that accepts requests to validate a token and return its associated metadata.
- JWT authentication converterA JWT authentication converter is a converter that transforms a decoded JWT into an application-specific authentication object.
- JwtAuthenticationTokenJwtAuthenticationToken is a Spring Security authentication-token class representing an authenticated principal derived from a JWT.
- OAuth2TokenCustomizerOAuth2TokenCustomizer is a Spring Authorization Server callback interface for modifying OAuth 2 token claims or other token attributes before issuance.
- custom authentication objectA custom authentication object is an application-defined authentication-token subtype that carries identity, authorities, and additional authentication data.
- authentication manager resolverauthenticationManagerResolver() is a Spring Security configuration method that supplies an authentication manager resolver for resource-server authentication.
- client credentialA client credential is secret or otherwise verifiable information that identifies an OAuth client to an authorization system.
- client idA client identifier is an externally visible value that uniquely identifies an OAuth client to an authorization server.
- revocationToken revocation is the process of invalidating a token before its normal expiration so that it can no longer be used.
← Chapter 14: Implementing an OAuth 2 authorization server
Chapter 16: Implementing an OAuth 2 client →
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.