Configuration Model

Default configuration

OAuth2AuthorizationServerConfiguration is a @Configuration that provides the minimal default configuration for an OAuth2 authorization server.

OAuth2AuthorizationServerConfiguration uses OAuth2AuthorizationServerConfigurer to apply the default configuration and registers a SecurityFilterChain @Bean composed of all the infrastructure components supporting an OAuth2 authorization server.

OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(HttpSecurity) is a convenience (static) utility method that applies the default OAuth2 security configuration to HttpSecurity.

The OAuth2 authorization server SecurityFilterChain @Bean is configured with the following default protocol endpoints:

The JWK Set endpoint is configured only if a JWKSource<SecurityContext> @Bean is registered.

The following example shows how to use OAuth2AuthorizationServerConfiguration to apply the minimal default configuration:

@Configuration
@Import(OAuth2AuthorizationServerConfiguration.class)
public class AuthorizationServerConfig {

	@Bean
	public RegisteredClientRepository registeredClientRepository() {
		List<RegisteredClient> registrations = ...
		return new InMemoryRegisteredClientRepository(registrations);
	}

	@Bean
	public JWKSource<SecurityContext> jwkSource() {
		RSAKey rsaKey = ...
		JWKSet jwkSet = new JWKSet(rsaKey);
		return (jwkSelector, securityContext) -> jwkSelector.select(jwkSet);
	}

}

The authorization_code grant requires the resource owner to be authenticated. Therefore, a user authentication mechanism must be configured in addition to the default OAuth2 security configuration.

OpenID Connect 1.0 is disabled in the default configuration. The following example shows how to enable OpenID Connect 1.0 by initializing the OidcConfigurer:

@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
	OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(http);

	http.getConfigurer(OAuth2AuthorizationServerConfigurer.class)
		.oidc(Customizer.withDefaults());	// Initialize `OidcConfigurer`

	return http.build();
}

In addition to the default protocol endpoints, the OAuth2 authorization server SecurityFilterChain @Bean is configured with the following OpenID Connect 1.0 protocol endpoints:

The OpenID Connect 1.0 Client Registration endpoint is disabled by default because many deployments do not require dynamic client registration.

OAuth2AuthorizationServerConfiguration.jwtDecoder(JWKSource<SecurityContext>) is a convenience (static) utility method that can be used to register a JwtDecoder @Bean, which is REQUIRED for the OpenID Connect 1.0 UserInfo endpoint and the OpenID Connect 1.0 Client Registration endpoint.

The following example shows how to register a JwtDecoder @Bean:

@Bean
public JwtDecoder jwtDecoder(JWKSource<SecurityContext> jwkSource) {
	return OAuth2AuthorizationServerConfiguration.jwtDecoder(jwkSource);
}

The main intent of OAuth2AuthorizationServerConfiguration is to provide a convenient method to apply the minimal default configuration for an OAuth2 authorization server. However, in most cases, customizing the configuration will be required.

Customizing the configuration

OAuth2AuthorizationServerConfigurer provides the ability to fully customize the security configuration for an OAuth2 authorization server. It lets you specify the core components to use - for example, RegisteredClientRepository, OAuth2AuthorizationService, OAuth2TokenGenerator, and others. Furthermore, it lets you customize the request processing logic for the protocol endpoints – for example, authorization endpoint, device authorization endpoint, device verification endpoint, token endpoint, token introspection endpoint, and others.

OAuth2AuthorizationServerConfigurer provides the following configuration options:

@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
	OAuth2AuthorizationServerConfigurer authorizationServerConfigurer =
		new OAuth2AuthorizationServerConfigurer();
	http.apply(authorizationServerConfigurer);

	authorizationServerConfigurer
		.registeredClientRepository(registeredClientRepository) (1)
		.authorizationService(authorizationService) (2)
		.authorizationConsentService(authorizationConsentService)   (3)
		.authorizationServerSettings(authorizationServerSettings) (4)
		.tokenGenerator(tokenGenerator) (5)
		.clientAuthentication(clientAuthentication -> { })  (6)
		.authorizationEndpoint(authorizationEndpoint -> { })    (7)
		.deviceAuthorizationEndpoint(deviceAuthorizationEndpoint -> { })    (8)
		.deviceVerificationEndpoint(deviceVerificationEndpoint -> { })  (9)
		.tokenEndpoint(tokenEndpoint -> { })    (10)
		.tokenIntrospectionEndpoint(tokenIntrospectionEndpoint -> { })  (11)
		.tokenRevocationEndpoint(tokenRevocationEndpoint -> { })    (12)
		.authorizationServerMetadataEndpoint(authorizationServerMetadataEndpoint -> { })    (13)
		.oidc(oidc -> oidc
			.providerConfigurationEndpoint(providerConfigurationEndpoint -> { })    (14)
			.logoutEndpoint(logoutEndpoint -> { })  (15)
			.userInfoEndpoint(userInfoEndpoint -> { })  (16)
			.clientRegistrationEndpoint(clientRegistrationEndpoint -> { })  (17)
		);

	return http.build();
}

1	`registeredClientRepository()`: The `RegisteredClientRepository` (REQUIRED) for managing new and existing clients.
2	`authorizationService()`: The `OAuth2AuthorizationService` for managing new and existing authorizations.
3	`authorizationConsentService()`: The `OAuth2AuthorizationConsentService` for managing new and existing authorization consents.
4	`authorizationServerSettings()`: The `AuthorizationServerSettings` (REQUIRED) for customizing configuration settings for the OAuth2 authorization server.
5	`tokenGenerator()`: The `OAuth2TokenGenerator` for generating tokens supported by the OAuth2 authorization server.
6	`clientAuthentication()`: The configurer for OAuth2 Client Authentication.
7	`authorizationEndpoint()`: The configurer for the OAuth2 Authorization endpoint.
8	`deviceAuthorizationEndpoint()`: The configurer for the OAuth2 Device Authorization endpoint.
9	`deviceVerificationEndpoint()`: The configurer for the OAuth2 Device Verification endpoint.
10	`tokenEndpoint()`: The configurer for the OAuth2 Token endpoint.
11	`tokenIntrospectionEndpoint()`: The configurer for the OAuth2 Token Introspection endpoint.
12	`tokenRevocationEndpoint()`: The configurer for the OAuth2 Token Revocation endpoint.
13	`authorizationServerMetadataEndpoint()`: The configurer for the OAuth2 Authorization Server Metadata endpoint.
14	`providerConfigurationEndpoint()`: The configurer for the OpenID Connect 1.0 Provider Configuration endpoint.
15	`logoutEndpoint()`: The configurer for the OpenID Connect 1.0 Logout endpoint.
16	`userInfoEndpoint()`: The configurer for the OpenID Connect 1.0 UserInfo endpoint.
17	`clientRegistrationEndpoint()`: The configurer for the OpenID Connect 1.0 Client Registration endpoint.

Configuring Authorization Server Settings

AuthorizationServerSettings contains the configuration settings for the OAuth2 authorization server. It specifies the URI for the protocol endpoints as well as the issuer identifier. The default URI for the protocol endpoints are as follows:

public final class AuthorizationServerSettings extends AbstractSettings {

	...

	public static Builder builder() {
		return new Builder()
			.authorizationEndpoint("/oauth2/authorize")
			.deviceAuthorizationEndpoint("/oauth2/device_authorization")
			.deviceVerificationEndpoint("/oauth2/device_verification")
			.tokenEndpoint("/oauth2/token")
			.tokenIntrospectionEndpoint("/oauth2/introspect")
			.tokenRevocationEndpoint("/oauth2/revoke")
			.jwkSetEndpoint("/oauth2/jwks")
			.oidcLogoutEndpoint("/connect/logout")
			.oidcUserInfoEndpoint("/userinfo")
			.oidcClientRegistrationEndpoint("/connect/register");
	}

	...

}

AuthorizationServerSettings is a REQUIRED component.

@Import(OAuth2AuthorizationServerConfiguration.class) automatically registers an AuthorizationServerSettings @Bean, if not already provided.

The following example shows how to customize the configuration settings and register an AuthorizationServerSettings @Bean:

@Bean
public AuthorizationServerSettings authorizationServerSettings() {
	return AuthorizationServerSettings.builder()
		.issuer("https://example.com")
		.authorizationEndpoint("/oauth2/v1/authorize")
		.deviceAuthorizationEndpoint("/oauth2/v1/device_authorization")
		.deviceVerificationEndpoint("/oauth2/v1/device_verification")
		.tokenEndpoint("/oauth2/v1/token")
		.tokenIntrospectionEndpoint("/oauth2/v1/introspect")
		.tokenRevocationEndpoint("/oauth2/v1/revoke")
		.jwkSetEndpoint("/oauth2/v1/jwks")
		.oidcLogoutEndpoint("/connect/v1/logout")
		.oidcUserInfoEndpoint("/connect/v1/userinfo")
		.oidcClientRegistrationEndpoint("/connect/v1/register")
		.build();
}

The AuthorizationServerContext is a context object that holds information of the Authorization Server runtime environment. It provides access to the AuthorizationServerSettings and the “current” issuer identifier.

If the issuer identifier is not configured in AuthorizationServerSettings.builder().issuer(String), it is resolved from the current request.

The AuthorizationServerContext is accessible through the AuthorizationServerContextHolder, which associates it with the current request thread by using a ThreadLocal.

Configuring Client Authentication

OAuth2ClientAuthenticationConfigurer provides the ability to customize OAuth2 client authentication. It defines extension points that let you customize the pre-processing, main processing, and post-processing logic for client authentication requests.

OAuth2ClientAuthenticationConfigurer provides the following configuration options:

@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
	OAuth2AuthorizationServerConfigurer authorizationServerConfigurer =
		new OAuth2AuthorizationServerConfigurer();
	http.apply(authorizationServerConfigurer);

	authorizationServerConfigurer
		.clientAuthentication(clientAuthentication ->
			clientAuthentication
				.authenticationConverter(authenticationConverter)   (1)
				.authenticationConverters(authenticationConvertersConsumer) (2)
				.authenticationProvider(authenticationProvider) (3)
				.authenticationProviders(authenticationProvidersConsumer)   (4)
				.authenticationSuccessHandler(authenticationSuccessHandler) (5)
				.errorResponseHandler(errorResponseHandler) (6)
		);

	return http.build();
}

1	`authenticationConverter()`: Adds an `AuthenticationConverter` (pre-processor) used when attempting to extract client credentials from `HttpServletRequest` to an instance of `OAuth2ClientAuthenticationToken`.
2	`authenticationConverters()`: Sets the `Consumer` providing access to the `List` of default and (optionally) added `AuthenticationConverter`'s allowing the ability to add, remove, or customize a specific `AuthenticationConverter`.
3	`authenticationProvider()`: Adds an `AuthenticationProvider` (main processor) used for authenticating the `OAuth2ClientAuthenticationToken`.
4	`authenticationProviders()`: Sets the `Consumer` providing access to the `List` of default and (optionally) added `AuthenticationProvider`'s allowing the ability to add, remove, or customize a specific `AuthenticationProvider`.
5	`authenticationSuccessHandler()`: The `AuthenticationSuccessHandler` (post-processor) used for handling a successful client authentication and associating the `OAuth2ClientAuthenticationToken` to the `SecurityContext`.
6	`errorResponseHandler()`: The `AuthenticationFailureHandler` (post-processor) used for handling a failed client authentication and returning the `OAuth2Error` response.

OAuth2ClientAuthenticationConfigurer configures the OAuth2ClientAuthenticationFilter and registers it with the OAuth2 authorization server SecurityFilterChain @Bean. OAuth2ClientAuthenticationFilter is the Filter that processes client authentication requests.

By default, client authentication is required for the OAuth2 Token endpoint, the OAuth2 Token Introspection endpoint, and the OAuth2 Token Revocation endpoint. The supported client authentication methods are client_secret_basic, client_secret_post, private_key_jwt, client_secret_jwt, tls_client_auth, self_signed_tls_client_auth, and none (public clients).

OAuth2ClientAuthenticationFilter is configured with the following defaults:

AuthenticationConverter — A DelegatingAuthenticationConverter composed of JwtClientAssertionAuthenticationConverter, X509ClientCertificateAuthenticationConverter, ClientSecretBasicAuthenticationConverter, ClientSecretPostAuthenticationConverter, and PublicClientAuthenticationConverter.
AuthenticationManager — An AuthenticationManager composed of JwtClientAssertionAuthenticationProvider, X509ClientCertificateAuthenticationProvider, ClientSecretAuthenticationProvider, and PublicClientAuthenticationProvider.
AuthenticationSuccessHandler — An internal implementation that associates the “authenticated” OAuth2ClientAuthenticationToken (current Authentication) to the SecurityContext.
AuthenticationFailureHandler — An internal implementation that uses the OAuth2Error associated with the OAuth2AuthenticationException to return the OAuth2 error response.

Customizing Jwt Client Assertion Validation

JwtClientAssertionDecoderFactory.DEFAULT_JWT_VALIDATOR_FACTORY is the default factory that provides an OAuth2TokenValidator<Jwt> for the specified RegisteredClient and is used for validating the iss, sub, aud, exp and nbf claims of the Jwt client assertion.

JwtClientAssertionDecoderFactory provides the ability to override the default Jwt client assertion validation by supplying a custom factory of type Function<RegisteredClient, OAuth2TokenValidator<Jwt>> to setJwtValidatorFactory().

JwtClientAssertionDecoderFactory is the default JwtDecoderFactory used by JwtClientAssertionAuthenticationProvider that provides a JwtDecoder for the specified RegisteredClient and is used for authenticating a Jwt Bearer Token during OAuth2 client authentication.

A common use case for customizing JwtClientAssertionDecoderFactory is to validate additional claims in the Jwt client assertion.

The following example shows how to configure JwtClientAssertionAuthenticationProvider with a customized JwtClientAssertionDecoderFactory that validates an additional claim in the Jwt client assertion:

@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
	OAuth2AuthorizationServerConfigurer authorizationServerConfigurer =
		new OAuth2AuthorizationServerConfigurer();
	http.apply(authorizationServerConfigurer);

	authorizationServerConfigurer
		.clientAuthentication(clientAuthentication ->
			clientAuthentication
				.authenticationProviders(configureJwtClientAssertionValidator())
		);

	return http.build();
}

private Consumer<List<AuthenticationProvider>> configureJwtClientAssertionValidator() {
	return (authenticationProviders) ->
		authenticationProviders.forEach((authenticationProvider) -> {
			if (authenticationProvider instanceof JwtClientAssertionAuthenticationProvider) {
				// Customize JwtClientAssertionDecoderFactory
				JwtClientAssertionDecoderFactory jwtDecoderFactory = new JwtClientAssertionDecoderFactory();
				Function<RegisteredClient, OAuth2TokenValidator<Jwt>> jwtValidatorFactory = (registeredClient) ->
					new DelegatingOAuth2TokenValidator<>(
						// Use default validators
						JwtClientAssertionDecoderFactory.DEFAULT_JWT_VALIDATOR_FACTORY.apply(registeredClient),
						// Add custom validator
						new JwtClaimValidator<>("claim", "value"::equals));
				jwtDecoderFactory.setJwtValidatorFactory(jwtValidatorFactory);

				((JwtClientAssertionAuthenticationProvider) authenticationProvider)
					.setJwtDecoderFactory(jwtDecoderFactory);
			}
		});
}

Customizing Mutual-TLS Client Authentication

X509ClientCertificateAuthenticationProvider is used for authenticating the client X509Certificate chain received when ClientAuthenticationMethod.TLS_CLIENT_AUTH or ClientAuthenticationMethod.SELF_SIGNED_TLS_CLIENT_AUTH method is used during OAuth2 client authentication. It is also composed with a "Certificate Verifier", which is used to verify the contents of the client X509Certificate after the TLS handshake has successfully completed.

PKI Mutual-TLS Method

For the PKI Mutual-TLS (ClientAuthenticationMethod.TLS_CLIENT_AUTH) method, the default implementation of the certificate verifier verifies the subject distinguished name of the client X509Certificate against the setting RegisteredClient.getClientSettings.getX509CertificateSubjectDN().

If you need to verify another attribute of the client X509Certificate, for example, a Subject Alternative Name (SAN) entry, the following example shows how to configure X509ClientCertificateAuthenticationProvider with a custom implementation of a certificate verifier:

@Bean
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
	OAuth2AuthorizationServerConfigurer authorizationServerConfigurer =
			new OAuth2AuthorizationServerConfigurer();
	http.apply(authorizationServerConfigurer);

	authorizationServerConfigurer
			.clientAuthentication(clientAuthentication ->
					clientAuthentication
							.authenticationProviders(configureX509ClientCertificateVerifier())
			);

	return http.build();
}

private Consumer<List<AuthenticationProvider>> configureX509ClientCertificateVerifier() {
	return (authenticationProviders) ->
			authenticationProviders.forEach((authenticationProvider) -> {
				if (authenticationProvider instanceof X509ClientCertificateAuthenticationProvider) {
					Consumer<OAuth2ClientAuthenticationContext> certificateVerifier = (clientAuthenticationContext) -> {
						OAuth2ClientAuthenticationToken clientAuthentication = clientAuthenticationContext.getAuthentication();
						RegisteredClient registeredClient = clientAuthenticationContext.getRegisteredClient();
						X509Certificate[] clientCertificateChain = (X509Certificate[]) clientAuthentication.getCredentials();
						X509Certificate clientCertificate = clientCertificateChain[0];

						// TODO Verify Subject Alternative Name (SAN) entry

					};

					((X509ClientCertificateAuthenticationProvider) authenticationProvider)
							.setCertificateVerifier(certificateVerifier);
				}
			});
}

Self-Signed Certificate Mutual-TLS Method

For the Self-Signed Certificate Mutual-TLS (ClientAuthenticationMethod.SELF_SIGNED_TLS_CLIENT_AUTH) method, the default implementation of the certificate verifier will retrieve the client’s JSON Web Key Set using the setting RegisteredClient.getClientSettings.getJwkSetUrl() and expect to find a match against the client X509Certificate received during the TLS handshake.

The RegisteredClient.getClientSettings.getJwkSetUrl() setting is used to retrieve the client’s certificates via a JSON Web Key (JWK) Set. A certificate is represented with the x5c parameter of an individual JWK within the set.

Client Certificate-Bound Access Tokens

When Mutual-TLS client authentication is used at the token endpoint, the authorization server is able to bind the issued access token to the client’s X509Certificate. The binding is accomplished by computing the SHA-256 thumbprint of the client’s X509Certificate and associating the thumbprint with the access token. For example, a JWT access token would include a x5t#S256 claim, containing the X509Certificate thumbprint, within the top-level cnf (confirmation method) claim.

Binding the access token to the client’s X509Certificate provides the ability to implement a proof-of-possession mechanism during protected resource access. For example, the protected resource would obtain the client’s X509Certificate used during Mutual-TLS authentication and then verify that the certificate thumbprint matches the x5t#S256 claim associated with the access token.

The following example shows how to enable certificate-bound access tokens for a client:

RegisteredClient mtlsClient = RegisteredClient.withId(UUID.randomUUID().toString())
		.clientId("mtls-client")
		.clientAuthenticationMethod(ClientAuthenticationMethod.TLS_CLIENT_AUTH)
		.authorizationGrantType(AuthorizationGrantType.CLIENT_CREDENTIALS)
		.scope("scope-a")
		.clientSettings(
				ClientSettings.builder()
						.x509CertificateSubjectDN("CN=mtls-client,OU=Spring Samples,O=Spring,C=US")
						.build()
		)
		.tokenSettings(
				TokenSettings.builder()
						.x509CertificateBoundAccessTokens(true)
						.build()
		)
		.build();