Chapter 14: Implementing an OAuth 2 authorization server
Introduces the authorization server’s role in OAuth 2 and identifies Spring Security’s current approach to implementing one.
After this chapter you will be able to
- Authorization server role. Explain that the authorization server authenticates the user and client, then issues tokens the client can use to access protected backend resources, sometimes on a user’s behalf.
- Authorization server filter chains. Distinguish the filter for authorization-server protocol endpoints from the filter for ordinary authentication and authorization, and explain why their order is specified.
- User authentication components. Explain when the authorization server needs user details and which Spring Security components provide them in this example.
- Registered client details. Describe how the server represents and retrieves client applications, and what permissions and identifiers a client registration specifies.
- Non-opaque token key management. Explain why a server issuing non-opaque tokens needs a JWKSource and why the example's generated keys are unsuitable for production.
- Authorization request and code. Trace how the simulated client requests an authorization code and how the user’s login leads to a redirect containing that code. Describe what the authorization request’s principal parameters specify.
- Code exchange for tokens. Describe the token request made after the client receives an authorization code, including client authentication and the values that must match the authorization request. State what the response contains in this example.
- Client Credentials Token Request. Describe how a client obtains an access token with the client credentials grant type: it requests the token and a scope, and authenticates with its client ID and secret using HTTP Basic, without user authentication or consent.
- Separate Registrations and Scopes. Justify using different client registrations for user-dependent and client credentials grants, preferably with different, purpose-revealing scopes.
- Opaque access token characteristics. Describe how a registered client can be configured to receive opaque access tokens and how those tokens differ from JWTs in this example.
- Opaque token introspection. Explain how the authorization server helps check an opaque token through introspection and what its response says about validity.
- Token revocation and its effect. Explain that revocation invalidates a previously issued token, such as one discovered to be stolen, even before it expires. Describe the request needed to revoke it and how introspection reflects the result.
- Revocation validation tradeoff. Justify why using revocation also requires introspection on every call, including for non-opaque tokens, and why that extra protection may not always be worth its performance cost.
What it builds on
- The big picture of OAuth 2 and OpenID Connect (chapter 13) · The OAuth 2 actors and their roles.
- Implementing filters in the Spring Security architecture (chapter 5) · Spring Security's use of filters.
- Understanding the UserDetailsService contract (chapter 3) · The UserDetailsService contract.
- Using password encoders (chapter 4) · Password encoders.
- Getting a token using the authorization code grant type (chapter 13) · The authorization code grant type.
- Obtaining tokens through various grant types (chapter 13) · OAuth 2 grant types.
- Using non-opaque tokens (chapter 13) · The distinction between non-opaque and opaque tokens.
- Applying PKCE protection to the authorization code grant type (chapter 13) · PKCE protection for the authorization code grant
Section by section
Introduction
Introduces the authorization server’s role in OAuth 2 and identifies Spring Security’s current approach to implementing one.
- Authorization server role: Explain that the authorization server authenticates the user and client, then issues tokens the client can use to access protected backend resources, sometimes on a user’s behalf.
Why it matters: This role explains what the server built in this chapter is meant to accomplish. - Current Spring implementation approach: State that Spring Security provides the current, customizable way to implement an OAuth 2/OpenID Connect authorization server in Spring, and that this approach differs from older implementations.
Why it matters: It helps distinguish the chapter’s implementation approach from guidance for older Spring applications.
Key terms: authorization server, client, tokens, Spring Security authorization server, OAuth 2/OpenID Connect authorization server
14.1 Implementing basic authentication using JSON web tokens
This section explains the components and basic configuration of a Spring Security OAuth 2 authorization server that issues non-opaque tokens.
- Authorization server filter chains: Distinguish the filter for authorization-server protocol endpoints from the filter for ordinary authentication and authorization, and explain why their order is specified.
Why it matters: Separating the chains makes it clear which configuration handles protocol capabilities and which handles login and access rules. - User authentication components: Explain when the authorization server needs user details and which Spring Security components provide them in this example.
Why it matters: The authorization code example must authenticate a user, not just identify a client. - Registered client details: Describe how the server represents and retrieves client applications, and what permissions and identifiers a client registration specifies.
Why it matters: Client registration tells the server which application is requesting a token and which uses of the server are allowed for it. - Non-opaque token key management: Explain why a server issuing non-opaque tokens needs a JWKSource and why the example's generated keys are unsuitable for production.
Why it matters: Key handling affects both token authenticity and whether issued tokens survive a server deployment. - Authorization server endpoint settings: Describe the role of AuthorizationServerSettings in the minimal configuration.
Why it matters: It identifies where the server's exposed endpoint paths are configured without requiring custom paths for the example.
Key terms: SecurityFilterChain, @Order, applyDefaultSecurity(), oidc(), UserDetailsService, PasswordEncoder, NoOpPasswordEncoder, BCrypt, RegisteredClient, RegisteredClientRepository
14.2 Running the authorization code grant type
This section tests the authorization server by discovering its endpoints, obtaining an authorization code through browser login, and exchanging that code for tokens using PKCE.
- Authorization server endpoint discovery: Explain how to find the authorization server’s endpoint paths when no custom paths were configured.
Why it matters: The client needs the server’s endpoint paths before it can request a code or token. - Authorization request and code: Trace how the simulated client requests an authorization code and how the user’s login leads to a redirect containing that code. Describe what the authorization request’s principal parameters specify.
Why it matters: This is how the client obtains the code it will later exchange for an access token. - Code exchange for tokens: Describe the token request made after the client receives an authorization code, including client authentication and the values that must match the authorization request. State what the response contains in this example.
Why it matters: The code alone is not the access token; the client must exchange it using consistent request details. - PKCE verifier and challenge: Explain which party creates the PKCE verifier and challenge, how this example generates them, and which request carries each value.
Why it matters: The verifier links the later token request to the client’s earlier authorization request.
Key terms: OpenID configuration endpoint, defaults, authorization endpoint, response_type=code, client_id, scope, redirect_uri, authorization code, token endpoint, HTTP Basic
14.3 Running the client credentials grant type
This section shows how a registered client obtains an access token with the client credentials grant type and why its registration and scope should be distinct from user-dependent grants.
- Client Credentials Token Request: Describe how a client obtains an access token with the client credentials grant type: it requests the token and a scope, and authenticates with its client ID and secret using HTTP Basic, without user authentication or consent.
Why it matters: It identifies what the client must send to get a token when no user is involved. - Separate Registrations and Scopes: Justify using different client registrations for user-dependent and client credentials grants, preferably with different, purpose-revealing scopes.
Why it matters: The separation makes it easier to tell what kind of token use a registration and scope are intended for.
Key terms: client credentials grant type, access token, client ID and secret, HTTP Basic, scope, registered client, authorization code grant type
14.4 Using opaque tokens and introspection
This section shows that registered clients can receive opaque access tokens and explains how introspection checks those tokens, including how expiration affects the result.
- Opaque access token characteristics: Describe how a registered client can be configured to receive opaque access tokens and how those tokens differ from JWTs in this example.
Why it matters: The token’s lack of embedded data explains why a separate lookup is needed to learn about it. - Opaque token introspection: Explain how the authorization server helps check an opaque token through introspection and what its response says about validity.
Why it matters: Introspection lets a resource server check a token whose contents it cannot inspect directly. - Token lifetime choices: Explain the default token lifetime and why the section uses a longer lifetime for examples but advises against it for real applications.
Why it matters: A testing convenience should not become a production token-lifetime setting.
Key terms: opaque tokens, registered clients, JWT, client credentials grant type, introspection, introspection endpoint, HTTP Basic, active, active time, time to live
14.5 Revoking tokens
This section explains how to revoke an issued token and why relying on revocation adds a validation cost.
- Token revocation and its effect: Explain that revocation invalidates a previously issued token, such as one discovered to be stolen, even before it expires. Describe the request needed to revoke it and how introspection reflects the result.
Why it matters: Revocation gives you a way to respond when an issued token should no longer be usable. - Revocation validation tradeoff: Justify why using revocation also requires introspection on every call, including for non-opaque tokens, and why that extra protection may not always be worth its performance cost.
Why it matters: A revoked token is useful protection only if calls check its current status, and those checks have a cost.
Key terms: token revocation, token revocation endpoint, HTTP Basic authentication, introspection endpoint, revocation feature, introspection, non-opaque tokens, performance
14.6 Summary
Where this is used later
- Creating a reactive OAuth 2 resource server (chapter 17) · The authorization server as the source of access tokens
- Configuring JWT validation (chapter 15) · Provides an authorization server that issues JSON web tokens.
- Using a custom authorization server (chapter 16) · Registering a client for the authorization code grant type.
- Configuring token validation through introspection (chapter 15) · Obtaining an access token with the client credentials grant type.
- (chapter intro) (chapter 15) · The resource-server chapter addresses the authorization context in which tokens from the two grants might be hard to distinguish.
Concepts explained in this chapter
- Spring Authorization ServerSpring Security Authorization Server is a Spring-based library for implementing OAuth 2.0 and OpenID Connect authorization servers.
- authorization serverAn authorization server is the OAuth 2 component that issues tokens after processing an authorization grant and may provide identity-provider functions in OpenID Connect.
- JWKSourceJWKSource is a component that supplies JSON Web Keys for cryptographic operations such as signing authorization-server tokens.
- RegisteredClientRepositoryRegisteredClientRepository is a Spring Security Authorization Server interface for storing and retrieving registered OAuth clients and their configurations.
- AuthorizationServerSettingsAuthorizationServerSettings is a Spring Security Authorization Server object for configuring the paths and general settings of an authorization server.
- OAuth2AuthorizationServerConfigurerOAuth2AuthorizationServerConfigurer is a Spring Security Authorization Server configuration API for configuring OAuth 2 authorization-server protocol endpoints and features.
- RegisteredClientRegisteredClient is a Spring Security Authorization Server object that describes a client known to an authorization server.
- authorization server protocol configurationAuthorization server protocol configuration is the security configuration that defines and customizes an authorization server's protocol endpoints and capabilities.
- authorization endpointAn authorization endpoint is an OAuth endpoint where a client initiates an authorization request and a resource owner's authorization is obtained.
- openid configuration endpointAn OpenID configuration endpoint publishes an OpenID Connect provider's supported endpoints and protocol configuration metadata.
- token endpointA token endpoint is an OAuth endpoint where a client exchanges a grant or credential for tokens.
- 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.
- 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.
- client credentials grant typeThe client credentials grant type is an OAuth 2 grant in which a client obtains an access token using its own credentials without user involvement.
- revocationToken revocation is the process of invalidating a token before its normal expiration so that it can no longer be used.
- scopeAn OAuth scope is a named permission value that limits the access or identity information requested by a client.
- JSON Web TokenA JSON Web Token is a compact token format that represents claims as a digitally signed or otherwise protected JSON-based value.
- Spring SecuritySpring Security is an open-source framework for securing Spring applications through authentication, authorization, access control, and protection against common attacks.
- authorization code flowThe authorization code grant type is an OAuth flow in which a client obtains a token through an authorization code, commonly after user authentication.
- introspection uriAn introspection endpoint is an OAuth endpoint that accepts requests to validate a token and return its associated metadata.
- openid connectoidc is a configuration method that enables OpenID Connect support in an authorization server.
- client authentication methodA client authentication method is the protocol mechanism an OAuth client uses to authenticate when calling a provider's secured endpoints.
- client idA client identifier is an externally visible value that uniquely identifies an OAuth client to an authorization server.
- client secretA client secret is confidential information a client presents to authenticate itself to an authorization server.
- client credentialA client credential is secret or otherwise verifiable information that identifies an OAuth client to an authorization system.
← Chapter 13: What are OAuth 2 and OpenID Connect?
Chapter 15: Implementing an OAuth 2 resource server →
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.