Chapter 16: Implementing an OAuth 2 client
The introduction explains why a backend application may act as an OAuth 2 client when communicating with another backend application.
After this chapter you will be able to
- Backend OAuth 2 client role. Explain when a backend application acts as an OAuth 2 client and why the client credentials grant type is preferred for calls between applications in an OAuth 2 system.
- Standard OAuth Login Cases. Explain that Spring Boot makes OAuth 2 login authentication straightforward in standard cases, where the authorization server correctly follows OAuth 2 and OpenID Connect specifications.
- OAuth 2 login flow. Describe how the demo app enables OAuth 2 login and what happens when a user signs in with Google.
- Well-known provider configuration. Explain which provider details Spring Security supplies for a well-known provider and which details the developer must provide for Google.
- Multiple provider login setup. Explain how the app offers GitHub login alongside Google: register the app with GitHub, configure its client ID and secret while retaining the Google configuration, and let the user choose a provider.
- Custom provider endpoint discovery. Explain what the web app must know about a provider that Spring Security does not recognize by default, and how an OpenID Connect issuer URI can supply those details.
- Matching client registration details. Describe the custom provider's client registration and identify which web-app settings must agree with the authorization server's registered client.
- Client registration responsibilities. Distinguish the information held by a ClientRegistration from the retrieval logic supplied by a ClientRegistrationRepository.
- Custom registration bean setup. Describe how the example supplies client registrations to the application without Spring Boot configuring them from its standard property names.
- OAuth 2 Login Authentication Context. Explain that a successful oauth2Login() authentication places authentication details in the security context, just like other authentication methods, so the app can use them to identify the user or apply authorization restrictions.
- Authentication Detail Access Choices. Describe how to access OAuth 2 login authentication details and when to use the Authentication contract rather than its OAuth 2 implementation.
- Service-to-service client credentials. Explain why a service calling another app can use the client credentials grant type and what it needs to obtain an access token.
- OAuth 2 client configuration. Describe the Spring Security configuration identified for this client and the registration details needed when the authorization server is not a common provider.
- Client manager token retrieval. Trace how the example retrieves and demonstrates an access token, and distinguish its simplified controller placement from the suggested real-world placement.
What it builds on
- The big picture of OAuth 2 and OpenID Connect (chapter 13) · The OAuth 2 actors, including the client.
- Getting a token with the client credentials grant type (chapter 13) · The client credentials grant type.
- Getting a token using the authorization code grant type (chapter 13) · Introduces the authorization code grant type used by this login configuration.
- What OpenID Connect brings to OAuth 2 (chapter 13) · The distinction between OpenID Connect and OAuth 2.
- Running the authorization code grant type (chapter 14) · Registering a client for the authorization code grant type.
- Using the SecurityContext (chapter 6) · The security context holds authentication details.
- Applying preauthorization rules (chapter 11) · Using preauthorization annotations.
- Applying postauthorization rules (chapter 11) · Using postauthorization annotations.
Section by section
Introduction
The introduction explains why a backend application may act as an OAuth 2 client when communicating with another backend application.
- Backend OAuth 2 client role: Explain when a backend application acts as an OAuth 2 client and why the client credentials grant type is preferred for calls between applications in an OAuth 2 system.
Why it matters: It clarifies why an application that serves requests may also need client-side OAuth 2 security.
Key terms: OAuth 2 client, client credentials grant type, HTTP Basic, API Key
16.1 Implementing OAuth 2 login
This section introduces OAuth 2 login for Spring web apps and identifies when Spring Boot makes its configuration straightforward.
- Standard OAuth Login Cases: Explain that Spring Boot makes OAuth 2 login authentication straightforward in standard cases, where the authorization server correctly follows OAuth 2 and OpenID Connect specifications.
Why it matters: It identifies the condition under which the section describes login configuration as straightforward.
Key terms: Spring Boot, OAuth 2 login, authorization server, OAuth 2, OpenID Connect
16.1.1 Implementing authentication with a common provider
This section shows how to enable OAuth 2 login with Google and use Spring Security’s preset provider details to keep the configuration small.
- OAuth 2 login flow: Describe how the demo app enables OAuth 2 login and what happens when a user signs in with Google.
Why it matters: It explains why the app can hand off login to Google rather than handling the user’s login itself. - Well-known provider configuration: Explain which provider details Spring Security supplies for a well-known provider and which details the developer must provide for Google.
Why it matters: It distinguishes Spring Security’s preset provider settings from the credentials unique to your app.
Key terms: OAuth 2 client dependency, OAuth 2 login, authorization code grant type, well-known providers, CommonOAuth2Provider, client ID, client secret, Google Developer Console
16.1.2 Giving the user more possibilities
This section explains why an app might offer multiple OAuth 2 login providers and how adding GitHub alongside Google changes the user’s login experience.
- Multiple provider login setup: Explain how the app offers GitHub login alongside Google: register the app with GitHub, configure its client ID and secret while retaining the Google configuration, and let the user choose a provider.
Why it matters: It connects the provider configuration to what users see and do when they log in. - Reason for provider choice: Justify offering users more than one login provider using the differences in accounts people already have or prefer to use.
Why it matters: Offering a choice makes login usable for people with different provider accounts and preferences.
Key terms: provider, client ID, secret, application.properties, providers, log in
16.1.3 Using a custom authorization server
This section shows how to configure an OAuth 2 login with a custom authorization server and run it alongside the web app.
- Custom provider endpoint discovery: Explain what the web app must know about a provider that Spring Security does not recognize by default, and how an OpenID Connect issuer URI can supply those details.
Why it matters: It explains why a custom provider needs configuration that a common provider does not. - Matching client registration details: Describe the custom provider's client registration and identify which web-app settings must agree with the authorization server's registered client.
Why it matters: A login configuration must refer to the same client and permitted callback and scopes on both sides. - Local two-app setup: Explain the port, startup-order, and browser-hostname considerations when running the example authorization server and web app locally.
Why it matters: These setup choices let the local example start and keep both apps' browser sessions working.
Key terms: common providers, authorization endpoint, token endpoint, key set endpoint, OpenID Connect, issuer URI, client registration, provider name, client ID, client secret
16.1.4 Adding flexibility to your configurations
This section explains when property-based OAuth 2 client configuration is too limited and how to supply client registrations through a custom Spring bean.
- Limits of property-based configuration: Explain why an application might need to configure OAuth 2 providers itself rather than rely on Spring Boot’s standard properties.
Why it matters: It explains when the default configuration approach stops meeting an application’s needs. - Client registration responsibilities: Distinguish the information held by a ClientRegistration from the retrieval logic supplied by a ClientRegistrationRepository.
Why it matters: Separating registration details from their retrieval lets an application choose where those details come from. - Custom registration bean setup: Describe how the example supplies client registrations to the application without Spring Boot configuring them from its standard property names.
Why it matters: The example shows how an application can take responsibility for assembling and supplying its registrations.
Key terms: properties file, providers, credentials, ClientRegistration, ClientRegistrationRepository, authorization server, Spring bean, in-memory
16.1.5 Managing authorization for an OAuth 2 login
Explains how an app accesses OAuth 2 login authentication details to identify users and apply authorization restrictions.
- OAuth 2 Login Authentication Context: Explain that a successful oauth2Login() authentication places authentication details in the security context, just like other authentication methods, so the app can use them to identify the user or apply authorization restrictions.
Why it matters: OAuth 2 login does not require a separate way to find out who authenticated. - Authentication Detail Access Choices: Describe how to access OAuth 2 login authentication details and when to use the Authentication contract rather than its OAuth 2 implementation.
Why it matters: Using the common contract where possible keeps code maintainable while still allowing access to custom details when needed.
Key terms: oauth2Login(), authentication details, security context, Authentication, SecurityContextHolder.getContext().getAuthentication(), username, authorities, OAuth2AuthenticationPrincipal, pre-/post-annotations
16.2 Implementing an OAuth 2 client
This section shows how a Spring Security application obtains an access token as an OAuth 2 client using the client credentials grant type.
- Service-to-service client credentials: Explain why a service calling another app can use the client credentials grant type and what it needs to obtain an access token.
Why it matters: It explains why this service-to-service setup differs from a user login. - OAuth 2 client configuration: Describe the Spring Security configuration identified for this client and the registration details needed when the authorization server is not a common provider.
Why it matters: Both the client app and authorization server must be set up for the demonstrated token request. - Client manager token retrieval: Trace how the example retrieves and demonstrates an access token, and distinguish its simplified controller placement from the suggested real-world placement.
Why it matters: It identifies the component that obtains the token and clarifies what the demo endpoint is meant to prove.
Key terms: client credentials grant type, client credentials, token URI, access token, oauth2Client(), HttpSecurity, ClientRegistrationRepository, client registration, scope, OAuth2AuthorizedClientManager
16.3 Summary
Concepts explained in this chapter
- clientAn OAuth client is an application that requests authorization and accesses protected resources on behalf of a resource owner.
- oauth2 loginOAuth 2 login is an authentication flow in which an application obtains a user's identity through an OAuth 2 provider.
- 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.
- public key set URIA key set endpoint is an authorization-server endpoint that exposes the cryptographic keys used to validate signed tokens.
- client registrationA client registration is the configured association of an OAuth client with its provider, credentials, redirect URI, and requested scopes.
- OAuth2AuthorizedClientManagerOAuth2AuthorizedClientManager is a Spring Security component that manages authorized clients and obtains access tokens by executing OAuth 2 grant flows.
- ClientRegistrationRepositoryClientRegistrationRepository is a Spring Security component that stores and retrieves OAuth 2 client registration details.
- client authentication methodA client authentication method is the protocol mechanism an OAuth client uses to authenticate when calling a provider's secured endpoints.
- oauth2Clientoauth2Client is an HttpSecurity configuration method that enables an application to operate as an OAuth 2 client.
- AuthenticationProviderAuthenticationProvider is a Spring Security interface or component that encapsulates a specific authentication mechanism and returns an authentication result.
- 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.
- Spring SecuritySpring Security is an open-source framework for securing Spring applications through authentication, authorization, access control, and protection against common attacks.
- OAuthOAuth 2 is an authorization framework specification for delegated access to protected resources using access tokens.
- client credentialA client credential is secret or otherwise verifiable information that identifies an OAuth client to an authorization system.
- grant typeA grant type is an OAuth 2 protocol flow by which a client obtains a token from an authorization server.
← Chapter 15: Implementing an OAuth 2 resource server
Chapter 17: Implementing security in reactive applications →
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.