SuoAuth - OpenID Connect with Spring Security

This is a Spring Boot application demonstrating OpenID Connect authentication using Spring Security.

Features

• OpenID Connect authentication with Google
• User profile display with OIDC information
• Secure endpoints with Spring Security
• Thymeleaf templates for UI

Prerequisites

• Java 21 or later
• Maven
• SuperOffice application in the Developer Portal

Configuration

Setting up SuperOffice OAuth credentials

1. Contact SuperOffice or access your SuperOffice developer account
2. Register a new application with SuperOffice
3. Configure the redirect URI as: http://localhost:8080/login/oauth2/code/superoffice
4. Get your client ID and client secret
5. Make note of the OAuth endpoints (these are already configured in the application.properties file)

Configuring the application

You can provide your OAuth 2.0 credentials in one of these ways:

1. Set environment variables:

   SUPEROFFICE_CLIENT_ID=your-superoffice-client-id
   SUPEROFFICE_CLIENT_SECRET=your-superoffice-client-secret
   

2. Or directly edit the application.properties file:

   spring.security.oauth2.client.registration.superoffice.client-id=your-superoffice-client-id
   spring.security.oauth2.client.registration.superoffice.client-secret=your-superoffice-client-secret
   

Running the application

1. Clone this repository
2. Navigate to the project directory
3. Run the application using Maven:

   ./mvnw spring-boot:run
   

   Or on Windows:

   mvnw.cmd spring-boot:run
   

4. Open your browser and go to http://localhost:8080

How it works

1. When a user accesses a protected resource, they are redirected to the login page
2. The user selects either the Google or GitHub authentication option
3. After authenticating with the chosen provider, the user is redirected back to the application
4. The application receives the OAuth2/OpenID Connect tokens and creates a security context
5. The user information is displayed on the profile page

Adding more OAuth2/OIDC providers

To add another OAuth2/OIDC provider (e.g., Microsoft, Okta, Auth0), add the appropriate configuration to application.properties. For example:

# Microsoft Azure AD
spring.security.oauth2.client.registration.azure.client-id=your-azure-client-id
spring.security.oauth2.client.registration.azure.client-secret=your-azure-client-secret
spring.security.oauth2.client.registration.azure.scope=openid,profile,email
spring.security.oauth2.client.provider.azure.issuer-uri=https://login.microsoftonline.com/{tenant-id}/v2.0

Then, add a button to the login page that links to /oauth2/authorization/azure (or the respective registration ID).

Session State and Token Management

Best Practices for OAuth2 Token Management

When working with OAuth2 access tokens and refresh tokens, follow these best practices:

1. Use Spring's Built-in Token Storage: Spring Security OAuth2 provides the OAuth2AuthorizedClientService to securely store and manage tokens.

2. Never Store Tokens in Client-Side Storage: Avoid storing tokens in cookies, local storage, or session storage on the client side.

3. Implement Token Refresh Logic: Configure automatic token refresh using Spring's OAuth2AuthorizedClientProvider with refresh token capabilities.

4. Secure API Calls: Create service classes that handle token retrieval and authentication for API calls.

5. Token Validation: Validate tokens before use by checking expiration and signature.

Using Tokens for API Calls

The application includes services for making authenticated API calls to external services:

• OAuth2TokenService: Retrieves tokens from the authorized client service
• ApiClientService: Uses tokens to make authenticated REST API calls
• ApiController: Example controller demonstrating API calls using tokens

Example API call:

// Get the access token from the current user's session
String accessToken = tokenService.getAccessToken(authentication);

// Add the token to the Authorization header
HttpHeaders headers = new HttpHeaders();
headers.setBearerAuth(accessToken);

// Make the authenticated API call
HttpEntity<?> entity = new HttpEntity<>(headers);
ResponseEntity<String> response = restTemplate.exchange(
    "https://api.example.com/resource",
    HttpMethod.GET, 
    entity, 
    String.class
);