Skip to content

OAuth 2.0 Migration Guide

Steve Riesenberg edited this page Jun 5, 2024 · 13 revisions
Note
This document is a work in progress. Check back regularly for updates.

This document contains guidance for moving OAuth 2.0 Clients and Resource Servers from Spring Security OAuth 2.x to Spring Security 5.2.x. Since Spring Security doesn’t provide Authorization Server support, migrating a Spring Security OAuth Authorization Server is out of scope for this document.

Because the two approaches are as different as they are, this document will tend to cover patterns more than precise search-and-replace steps.

Client

Changes In Approach

Spring Security takes a slightly different approach from Spring Security OAuth in a few notable ways.

Simplified Enablement

Spring Security OAuth’s Client support for the Authorization Code flow is enabled by adding the @EnableOAuth2Client annotation. For other flows, an OAuth2ClientContext instance needs to be constructed and exposed.

Spring Security’s OAuth 2.0 Client support is enabled via the Spring Security oauth2Client DSL method.

A Simplified RestTemplate and WebClient

Spring Security OAuth extends RestTemplate, introducing OAuth2RestTemplate. This class needs to be instantiated and exposed as a @Bean.

Spring Security chooses to favor composition and instead exposes an OAuth2AuthorizedClientService, which is useful for creating RestTemplate interceptors or WebClient exchange filter functions. Spring Security provides ExchangeFilterFunction s for both Servlet- and WebFlux-based applications that both leverage this service.

Simplified Client Resolution

To retrieve the currently authorized client in Spring Security OAuth, you autowire an OAuth2ClientContext instance. Spring Security OAuth makes use of Spring MVCs request and session scope to store the OAuth2ClientContext instance.

To retrieve the currently authorized client in Spring Security, you use the @RegisteredOAuth2AuthorizedClient method parameter annotation. Spring Security stores the authorized client in its own OAuth2AuthorizedClientRepository.

Enhanced Client Registration

Spring Security OAuth exposes a single client configuration via Spring Boot properties.

Spring Security uses its ClientRegistrationRepository to represent clients, which can be supplied via the Spring Security DSL. Or, these can likewise be configured via Spring Boot.

Simplified JWT Support

Spring Security OAuth provides its own JWT support via spring-security-jwt.

Spring Security relies on Nimbus for its JWT support.

Examples Matrix

Both Spring Security and Spring Security OAuth2 have examples for how to configure Client:

Use case Spring Security Spring Security OAuth

Authorization Code

Sample

Sample

Refresh Token

Sample

Sample

Client Credentials

Sample

Sample

Resource Owner Password Credentials

Sample

Sample

Login

Changes In Approach

Spring Security takes a slightly different approach from Spring Security OAuth in a few notable ways.

Note
Spring Security refers to this feature as OAuth 2.0 Login while Spring Security OAuth refers to it as SSO

Simplified Enablement

Spring Security OAuth’s SSO support is enabled by adding the @EnableOAuth2Sso annotation.

Spring Security’s OAuth 2.0 Login support is enabled via the Spring Security oauth2Login() DSL method.

Resource Server

Changes In Approach

Spring Security takes a slightly different approach from Spring Security OAuth in a few notable ways.

Simplified Enablement

Spring Security OAuth’s Resource Server support is enabled by adding the @EnableResourceServer annotation.

Spring Security’s Resource Server support is enabled via the Spring Security oauth2ResourceServer DSL method.

A Simplified DSL

Spring Security OAuth exposes two different DSLs for Resource Server. These are configured by extending ResourceServerConfigurerAdapter.

Spring Security exposes the same functionality via the Spring Security DSL, which is configured by extending WebSecurityConfigurerAdapter.

Simplified Enablement

Spring Security OAuth’s Resource Server support is enabled by adding the @EnableResourceServer annotation.

Spring Security’s Resource Server support is enabled via the Spring Security DSL.

Simplified Authorization Configuration

Spring Security OAuth indicates two locations for specifying authorization rules. The first is via ResourceServerConfigurerAdapter - any rules supplied here are for when a bearer token is present. The second is via WebSecurityConfigurerAdapter - any rules supplied here are for requests where a bearer token is absent.

Spring Security indicates that all authorization rules be configured via one or many WebSecurityConfigurerAdapter s.

Simplified SpEL

Spring Security OAuth supports a custom SpEL variable called oauth2. To authorize requests or methods based on scope, you write an expression like access("#oauth2.hasScope('scope')").

Spring Security converts scopes that follow the granted authority naming convention. To authorize requests or methods based on scope, you write an expression like hasAuthority("SCOPE_scope").

Examples Matrix

Both Spring Security and Spring Security OAuth2 have examples for how to configure Resource Server:

Use case Spring Security Spring Security OAuth

JWT + JWK

Sample

Sample

JWT + Key

Sample

Doc

Opaque Token

Sample

Sample

w/ Actuator

Doc

Sample

Audience Validation

Doc

Authorizing Requests

Doc

Doc

Unported Features

There are some features that we currently have no plans to port over.

In Spring Security OAuth, you can configure a UserDetailsService to look up a user that corresponds with the incoming bearer token. There are no plans for Spring Security’s Resource Server support to pick up a UserDetailsService. This is still simple in Spring Security, though, via the jwtAuthenticationConverter DSL method. Notably, one can return a BearerTokenAuthentication which takes an instance of OAuth2AuthenticatedPrincipal for a principal.

In Spring Security OAuth, you can assign an identifier to the resource server via the ResourceServerSecurityConfigurer#resourceId method. This configures the realm name used by the authentication entry point as well as adds audience validation. No such identifier is planned for Spring Security. However, audience validation and a custom realm name are both simple to achieve by configuring an OAuth2TokenValidator and AuthenticationEntryPoint respectively.