How Authentication Works

Squizy supports pluggable authentication modules. Currently, the available implementation is OAuth 2.0 with database-backed user and role management.

Authentication Flow

When a user accesses the application:

1. Unauthenticated requests to /api/** receive a 401 Unauthorized response
2. The frontend redirects to the authentication provider's login page
3. After successful authentication, the provider redirects back to the application
4. Squizy looks up the user by email in its database
5. A short-lived token is generated and exchanged for a JWT cookie
6. Subsequent requests use the JWT cookie for authentication

The session is stateless — no server-side session is maintained. Authentication state is carried entirely in the JWT cookie.

User Creation on Login

The behavior when an authenticated user does not exist in the Squizy database depends on the application's configuration:

Deny Mode (Default)

If no SquizyGeneratedUsersDetailsProvider bean is defined (or its getOnDemandNewUserRoles method returns an empty list), unknown users are not created. The user authenticates successfully with the identity provider but receives no roles or permissions in Squizy, effectively denying access.

This is the default behavior, suitable for applications where administrators must pre-create users.

Auto-Create Mode

For applications where users should be created on first login (e.g., public-facing apps), implement the SquizyGeneratedUsersDetailsProvider interface and return a non-empty list of role names from getOnDemandNewUserRoles:

@Component
public class MyUsersDetailsProvider implements SquizyGeneratedUsersDetailsProvider {

    @Override
    public List<GeneratedUserDetails> getInitializationUsersDetails() {
        // Pre-created users at startup (optional)
        return List.of();
    }

    @Override
    public List<String> getOnDemandNewUserRoles(String email) {
        // Roles assigned to auto-created users
        return List.of("User");
    }
}

When an unknown user authenticates and getOnDemandNewUserRoles returns roles, Squizy automatically:

• Creates the user in the database
• Stores profile information (email, name, picture if enabled)
• Assigns the returned roles (they must already exist in the database)

If the returned roles do not exist or the list is empty, the user is not created and authentication fails — the same behavior as Deny Mode.

TIP

For details on how roles and authorities work after authentication, see Authorization.

Programmatic Access

For automated systems, integrations, and scripts that need API access without a browser-based login flow, Squizy provides App Tokens. App Tokens use a bearer token format (Authorization: AppToken <tokenId>.<secret>) and carry directly assigned authorities.