Support Configuring Authorization Server in HttpSecurity.with(authorizationServer(), ...)

[rwinch]

Expected Behavior

It would be nice if all of the Authorization Server configuration options could be made/discoverable from a single entry point & on an existing SecurityFilterChain.

For example, it would be very nice if adding a default Authorization Server to an existing application could be done with a single invocation of the HttpSecurity DSL using something like this:

http
    .with(authorizationServer(), Customizer.withDefaults())
    // ...

If a user wanted to make changes to the defaults, then they would do so using the Customizer. For example, if OIDC was not enabled by default, then the user would be able to use:

http
    .with(authorizationServer(), authz -> authz
        .oidc(Customizer.withDefaults())
   )
   // ...

NOTE: I'm not saying that OIDC should or should not be a default, but I'm just using this as an example of how a user would be able to change the defaults.

Using this approach:

• Should feel familiar to Spring Security users
• It will make all of the features available via autocomplete after a single static import
• Should allow users to enable a feature (authorization server) rather than needing to know about the implementation details such as exception handling.

Current Behavior

Currently the recommendation is:

@Bean 
@Order(1)
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http)
		throws Exception {
	OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(http);
	http.getConfigurer(OAuth2AuthorizationServerConfigurer.class)
		.oidc(Customizer.withDefaults());	// Enable OpenID Connect 1.0
	http
		// Redirect to the login page when not authenticated from the
		// authorization endpoint
		.exceptionHandling((exceptions) -> exceptions
			.defaultAuthenticationEntryPointFor(
				new LoginUrlAuthenticationEntryPoint("/login"),
				new MediaTypeRequestMatcher(MediaType.TEXT_HTML)
			)
		)
		// Accept access tokens for User Info and/or Client Registration
		.oauth2ResourceServer((resourceServer) -> resourceServer
			.jwt(Customizer.withDefaults()));
		return http.build();
}

The disadvantages of this approach are:

• It is less concise
• Having multiple SecurityFilterChain is less familiar and adds additional complexity to understanding/debugging
• Using OAuth2AuthorizationServerConfiguration.applyDefaultSecurity is unfamiliar to users
• Using http.getConfigurer(OAuth2AuthorizationServerConfigurer.class) is also unfamiliar to users
• It is more difficult to discover. In the proposal, a user only needs to remember a single static import and every other option can be auto completed. With the current configuration a user must:
  • Remember to use multiple SecurityFilterChain
  • Remember to use @Order (and know where to import it from)
  • Remember OAuth2AuthorizationServerConfiguration.applyDefaultSecurity so it can be imported
  • Remember OAuth2AuthorizationServerConfigurer.class and how to get it from HttpSecurity and know that this is how to configure oidc (vs another static method import like applyDefaultSecurity or something returned from applyDefaultSecurity, etc).
• The user must remember to configure exceptionHandling and how to configure it.
• The user must enable the resource server support

Context

I'd like to only need to remember a single thing (ideally a concept) in order to add Spring Authorization Server to an existing SecurityFilterChain.

This came up a few times (in various contexts) around trying to simplify (remove) the additional SecurityFilterChain and align more with webauthn in @joshlong and my Goodbye Passwords Hello Security talk.

[jgrandja]

@rwinch Thanks for the extra details.

Regarding:

Using OAuth2AuthorizationServerConfiguration.applyDefaultSecurity is unfamiliar to users

Using http.getConfigurer(OAuth2AuthorizationServerConfigurer.class) is also unfamiliar to users

These have been available since Day 1 and is well documented in the reference doc and is also used throughout all the samples and tests. So it's quite familiar and natural to users.

With the current configuration a user must: Remember to use multiple SecurityFilterChain

A dedicated SecurityFilterChain for the Authorization Server endpoints is recommended, however, it is not required. An application can choose to configure the Authorization Server and their custom application features into a single SecurityFilterChain.

For example, looking at the sample configuration in the Getting Started section of the reference, one could combine the authorizationServerSecurityFilterChain @Bean and the defaultSecurityFilterChain @Bean into a single SecurityFilterChain, as follows:

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http)
		throws Exception {

	OAuth2AuthorizationServerConfigurer authorizationServerConfigurer =
			new OAuth2AuthorizationServerConfigurer();

	http.with(authorizationServerConfigurer, authorizationServer ->
			authorizationServer
					.oidc(Customizer.withDefaults()))	// Enable OpenID Connect 1.0
			.authorizeHttpRequests((authorize) -> authorize
					.anyRequest().authenticated()
			)
			.csrf((csrf) -> csrf
					.ignoringRequestMatchers(authorizationServerConfigurer.getEndpointsMatcher())
			)
			// Accept access tokens for User Info and/or Client Registration
			.oauth2ResourceServer((resourceServer) -> resourceServer
					.jwt(Customizer.withDefaults())
			)
			.formLogin(Customizer.withDefaults());

	return http.build();
}

Given the above configuration and your comment for expected behaviour:

If a user wanted to make changes to the defaults, then they would do so using the Customizer. For example, if OIDC was not enabled by default, then the user would be able to use:

This is already possible as demonstrated in the sample configuration.

At this point, I don't see anything that needs to be improved upon. Thoughts?

[rwinch]

Thanks @jgrandja! This appears to be a great start.

These have been available since Day 1 and is well documented in the reference doc and is also used throughout all the samples and tests. So it's quite familiar and natural to users.

The following lines are not used anywhere else within Spring Security:

OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(http);
http.getConfigurer(OAuth2AuthorizationServerConfigurer.class)
			.oidc(Customizer.withDefaults());	// Enable OpenID Connect 1.0

The feedback we have received is that it is difficult to remember to do this because it is not following the standard conventions of Spring Security for configuring extensions.

I agree. Looking at this configuration, it does not feel like Spring Security's configuration model. The standard way to configure a Spring Security extension can be found in the reference and aligns with what is suggested in this issue.

What's more is using the way that is suggested in this ticket only requires remembering a single static method. The remaining configuration can be autocompleted from the IDE.

The documented way of configuring Authorization Server requires remembering:

• a static method
• to use getConfigurer
• To pass in OAuth2AuthorizationServerConfigurer to the getConfigurer method
• to configure exceptionHandling (and how)
• to configure resourceServer
• to configure csrf.

A dedicated SecurityFilterChain for the Authorization Server endpoints is recommended, however, it is not required.

Why is it recommended to use a dedicated SecurityFilterChain? Is this documented somewhere?

For example, looking at the sample configuration in the Getting Started section of the reference, one could combine the authorizationServerSecurityFilterChain @bean and the defaultSecurityFilterChain @bean into a single SecurityFilterChain, as follows:

How does someone know how to combine them? For example, the documentation uses

OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(http);

However, when using a single @Bean this is no longer used.

Another example is that the documentation uses http.getConfigurer(OAuth2AuthorizationServerConfigurer.class) but this does not work without applyDefaultSecurity. How does a user know to use new OAuth2AuthorizationServerConfigurer()?

Why is it necessary to configure csrf and oauth2Resource server? This seems like unnecessary explicit configuration.

[jgrandja]

@rwinch

Why is it recommended to use a dedicated SecurityFilterChain? Is this documented somewhere?

IMO it is a recommended best practice to isolate all the authorization server capabilities in it's own SecurityFilterChain and not mix it up with the default (Spring Security) SecurityFilterChain.

In a production environment, the Identity Provider is a separately managed system and the same goes for an OAuth2/OIDC Authorization Server as it is also a completely separate system. Obviously, the 2 systems need to be integrated to enable the OAuth2 flows, but they should most definitely be completely isolated, especially the Identity Provider as it should never "sit with" another system, for security and privacy reasons. From a general architecture standpoint, a SecurityFilterChain allows you to establish security boundaries between different parts of the overall system, hence the use of a dedicated SecurityFilterChain for authorization server and it's specific configuration.

This is the main reason why we have documented this configuration pattern across the reference docs, samples and tests. However, it does appear that we have not formally documented (in words) this as a best practice in our docs.

Another reason worth mentioning, although not as important, is by combining the default (Spring Security) SecurityFilterChain and the authorization server SecurityFilterChain into one SecurityFilterChain would make the chain quite big at around 26x Filter's, because the OAuth2 Endpoints add an additional 13x Filter's, and therefore may introduce a lot of noise when troubleshooting/debugging issues.

[jgrandja]

@rwinch I've opened a Draft PR (gh-1725) to iterate on this.

Take a look at the 1st commit showing a simplified configuration with the existing 2x SecurityFilterChain setup.

Take a look at the 2nd commit showing a simplified configuration with a single SecurityFilterChain setup.

[rwinch]

Thanks @jgrandja! Let me know when you are ready for feedback.

[jgrandja]

@rwinch It's ready for feedback.