---

name: spring-authorization-server description: | Spring Authorization Server for building OAuth 2.1 and OpenID Connect providers.

USE WHEN: user mentions "OAuth2 server", "authorization server", "OIDC provider", "token endpoint", asks about "how to implement OAuth2", "create authorization server", "issue JWT tokens", "custom OAuth provider"

DO NOT USE FOR: OAuth2 client configuration - use spring-security instead, resource server JWT validation - use spring-security instead allowed-tools: Read, Grep, Glob, Write, Edit

Spring Authorization Server - Quick Reference

Full Reference: See advanced.md for JPA client persistence, JWT configuration, custom token claims, user info endpoint, consent controller, token revocation, resource server integration, and testing.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: spring-authorization-server for comprehensive documentation.

Dependencies

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-authorization-server</artifactId>
</dependency>

OAuth 2.1 Flows

Authorization Code + PKCE:

Client ──(1) Authorization Request + code_challenge──▶ Auth Server
      ◀──(2) Authorization Code──────────────────────
      ──(3) Token Request + code_verifier────────────▶
      ◀──(4) Access Token + Refresh Token + ID Token─

Basic Configuration

@Configuration
@EnableWebSecurity
public class SecurityConfig {

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

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

        http.exceptionHandling(exceptions -> exceptions
                .defaultAuthenticationEntryPointFor(
                    new LoginUrlAuthenticationEntryPoint("/login"),
                    new MediaTypeRequestMatcher(MediaType.TEXT_HTML)
                )
            )
            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));

        return http.build();
    }

    @Bean
    @Order(2)
    public SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(authorize -> authorize.anyRequest().authenticated())
            .formLogin(Customizer.withDefaults());
        return http.build();
    }
}

Client Registration

@Bean
public RegisteredClientRepository registeredClientRepository() {
    RegisteredClient webClient = RegisteredClient.withId(UUID.randomUUID().toString())
        .clientId("web-client")
        .clientSecret("{noop}secret")
        .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
        .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
        .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN)
        .redirectUri("http://localhost:8080/login/oauth2/code/web-client")
        .scope(OidcScopes.OPENID)
        .scope(OidcScopes.PROFILE)
        .scope("read")
        .clientSettings(ClientSettings.builder()
            .requireAuthorizationConsent(true)
            .requireProofKey(true)  // PKCE required
            .build())
        .tokenSettings(TokenSettings.builder()
            .accessTokenTimeToLive(Duration.ofMinutes(15))
            .refreshTokenTimeToLive(Duration.ofDays(7))
            .reuseRefreshTokens(false)
            .build())
        .build();

    return new InMemoryRegisteredClientRepository(webClient);
}

Best Practices

| Do | Don't | |----|-------| | Require PKCE for public clients | Allow plain authorization code | | Use short-lived access tokens | Long-lived access tokens | | Rotate refresh tokens | Reuse refresh tokens indefinitely | | Store keys securely (Vault) | Hardcode keys in config | | Validate redirect URIs strictly | Allow open redirects |

When NOT to Use This Skill

• OAuth2 Client Configuration - Use spring-security
• Resource Server - For validating JWT tokens use spring-security
• Basic Authentication - Use spring-security
• Session Management - Use spring-session

Anti-Patterns

| Anti-Pattern | Why It's Bad | Better Approach | |-------------|--------------|-----------------| | Reusing refresh tokens | Security risk if compromised | Rotate on each use | | Long-lived access tokens | Increased exposure window | Keep to 15-30 min | | Hardcoded client secrets | Secrets in version control | Use secret management | | No PKCE for SPAs | Code interception vulnerability | Always require PKCE | | Wildcard redirect URIs | Open redirect vulnerability | Whitelist exact URIs |

Quick Troubleshooting

| Issue | Possible Cause | Solution | |-------|---------------|----------| | 401 at /oauth2/authorize | User not authenticated | Check SecurityFilterChain order | | Invalid client error | Client not registered | Verify RegisteredClientRepository | | JWKS endpoint 404 | JWKSource bean missing | Ensure JWKSource configured | | Token validation fails | Issuer mismatch | Check issuer URL matches | | PKCE validation fails | code_verifier mismatch | Verify PKCE implementation |

Production Checklist

• [ ] HTTPS everywhere
• [ ] RSA keys in secure storage
• [ ] Client secrets encrypted
• [ ] PKCE required for public clients
• [ ] Token lifetimes configured
• [ ] Consent flow implemented
• [ ] Token revocation working
• [ ] Rate limiting enabled
• [ ] Audit logging configured

Reference Documentation

• Spring Authorization Server Reference
• OAuth 2.1 Specification