OAuth2

Squizy authenticates users through an external OAuth2/OIDC provider. After successful authentication with the provider, Squizy retrieves the user's profile information (email, name, picture) and stores it as a user record in its own database. All authorization decisions (roles, authorities) are then managed within Squizy.

Any provider supported by Spring Security's OAuth2 client can be used (Google, GitHub, Okta, etc.).

Setup

1. Add the Starter

Include the OAuth2 database starter in your pom.xml:

<dependency>
    <groupId>io.twentyninetech</groupId>
    <artifactId>squizy-server-oauth2-database-starter</artifactId>
</dependency>

This brings in:

• spring-boot-starter-oauth2-client — Spring Security OAuth2 client support
• squizy-server-security-oauth2-database — Squizy's database-backed user/role management

2. Configure a Provider

Squizy uses Spring Security's standard OAuth2 client configuration. See below for provider-specific instructions.

3. Configure the Token Seed

The token-seed property is used to derive the cryptographic keys (password, salt, and secret) for JWT token generation. Squizy uses HMAC256 to sign JWT tokens.

squizy.oauth2.token-seed=your-random-seed-here

WARNING

If token-seed is not set, a random UUID is generated at each startup. This means all existing JWT tokens are invalidated on restart. Always set a fixed seed in production.

The seed value is hashed to deterministically generate the signing secret. Any string value works — use something random and keep it secret.

Provider Configuration

Google

1. Go to the Google Cloud Console
2. Create a new project (or select an existing one)
3. Navigate to APIs & Services → Credentials
4. Create an OAuth 2.0 Client ID (Web application)
5. Add authorized redirect URI: http://localhost:8080/login/oauth2/code/google
6. Copy the Client ID and Client Secret

Add to application.properties:

spring.security.oauth2.client.registration.google.client-id=YOUR_CLIENT_ID
spring.security.oauth2.client.registration.google.client-secret=YOUR_CLIENT_SECRET

TIP

For production, replace localhost:8080 in the redirect URI with your actual domain.

Adding Other Providers

Squizy supports any OAuth2/OIDC provider that Spring Security supports. To add a different provider, follow Spring Security's OAuth2 client configuration documentation and add the corresponding spring.security.oauth2.client.registration.* and spring.security.oauth2.client.provider.* properties.

Configuration

All OAuth2-related properties are configured under the squizy.oauth2 prefix:

Property	Description	Default
squizy.oauth2.token-seed	Seed for deriving JWT signing keys. Set in production.	Random UUID
squizy.oauth2.success-login-url	URL path to redirect after successful login	login-success
squizy.oauth2.short-live-token-name	Query parameter name for the short-lived token	token
squizy.oauth2.short-live-token-ttl	TTL for short-lived tokens	30s
squizy.oauth2.jwt-cookie-name	Name of the JWT cookie	user_access_jwt
squizy.oauth2.jwt-cookie-max-age	Maximum age of the JWT cookie	1d
squizy.oauth2.oauth2-request-cookie-name	Name of the OAuth2 authorization request cookie	oauth2_auth_request
squizy.oauth2.oauth2-request-cookie-ttl	TTL for the OAuth2 authorization request cookie	30s
squizy.oauth2.store-user-picture	Whether to store the user's profile picture from the OAuth2 provider	true

WARNING

If token-seed is not set, a random UUID is generated at each startup. This means all existing JWT tokens are invalidated on restart. Always set a fixed seed in production.