Spring Security Samples

This sample demonstrates an OAuth 2.0 Authorization Server implementation using Spring Security. It supports the following features:

• Grant Types: authorization_code and client_credentials.
• Protocols: OpenID Connect 1.0.
• Token Format: JWT tokens signed with the RS256 algorithm.

The sample includes functionality for issuing tokens via a token endpoint and verifying them via a token introspection endpoint.

This repository contains a comprehensive catalog of code samples for Spring Security. The samples are organized by security concept and technology stack (e.g., Spring Boot, WebFlux, Servlet, Java Configuration, XML, Kotlin).

Key categories include:

• Getting Started: Basic security implementations like 'Hello Security', Method Security, and Spring Data integration.
• OAuth 2.0: Authorization Servers, Login flows, Resource Servers (including JWE, Multi-tenancy, Opaque Token, and Static), and client implementations using RestClient or WebClient.
• SAML 2.0: Login and Logout implementations.
• Authentication: Pre-authentication, Remember-me, X.509, and various Username/Password strategies (Form Login, In-memory, JDBC, LDAP, MFA, and Custom UserDetails).
• JWT: JSON Web Token login flows.

The sample implements the following core SAML 2.0 capabilities using Spring Security:

SAML 2.0 Login

Using saml2Login(), the application acts as a Service Provider (SP) that:

• Receives and validates SAML 2.0 Responses containing assertions via HTTP-POST and HTTP-REDIRECT bindings.
• Creates corresponding Spring Security authentications.
• Sends SAML 2.0 AuthNRequest messages to the Identity Provider (IdP).
• Provides a configurable framework for SAML 2.0 authentication components.

SAML 2.0 Single Logout

Using saml2Logout(), the application supports both Relying Party (RP)-initiated and Asserting Party (AP)-initiated Single Logout via HTTP-POST and HTTP-REDIRECT bindings. In this specific sample, the logout flow uses the HTTP-POST binding.

When federating against hundreds of endpoints, managing individual registrations manually is inefficient. This sample demonstrates how to use RelyingPartyRegistrations#collectionFromMetadata to automatically copy a base relying party configuration across several arbitrary asserting party configurations returned from a single endpoint.

In this implementation, the registrationId is set to be the entity ID for each asserting party, which is a critical requirement for large-scale federation.

To support dynamic updates to Identity Provider (IdP) metadata, the application implements a custom RelyingPartyRegistrationRepository.

This implementation leverages an OpenSAML component to automatically refresh the Asserting Party (AP) metadata, ensuring the Service Provider stays synchronized with changes at the IdP without requiring a manual application restart.

To enable OAuth 2.0 login, you must configure two sets of properties in application.yml: registration (defining the client credentials and behavior) and provider (defining the authorization server endpoints).

Property Structure

• spring.security.oauth2.client.registration: The base prefix for client-specific settings. Each registration must have a unique ID (e.g., google, github, login-client).
• spring.security.oauth2.client.provider: The base prefix for provider-specific settings. The ID used here must match the provider property defined within a registration block.

Redirect URI Template

The default redirect URI template is {baseUrl}/login/oauth2/code/{registrationId}. You must register this exact URI in your OAuth provider's console (e.g., Google API Console, GitHub Settings) to allow successful authentication.

To run the application as a standalone service to explore OAuth 2.0 Bearer Token security, use the following command:

./gradlew bootRun

Or, import the project into your IDE and run OAuth2StaticResourceServerApplication.

Once the application is running, you can test the endpoints using the provided sample tokens via curl.

This application uses Spring Boot Docker Compose to automatically start a Maildev container for testing email flows.

To test the magic link authentication flow:

1. Request a token by visiting http://localhost:8080/login.
2. Access the Maildev web interface at http://localhost:1080 to view the sent email.
3. Click the magic link within the email to complete the authentication process.

This sample implements Multi-Factor Authentication (MFA) using two factors: username/password and a one-time token (OTT). You can start with either factor; once the first is authenticated, you will be prompted for the second.

Username/Password Credentials

• Username: user
• Password: password

One-Time-Token (OTT) Credentials

• Username: user
• Token: The token is generated and printed to the application logs. Look for the following pattern in your console output:

********************************************************

Use this one-time token: <YOUR_TOKEN_HERE>

********************************************************