Docs › Authentication

Authentication

Garden CMS supports two authentication methods for the admin interface: password login and OAuth2/OIDC.

Set the ADMIN_PASSWORD environment variable:

ADMIN_PASSWORD=your-secure-password

Navigate to /admin/login and enter the password. The session is stored in an encrypted cookie.

Garden CMS also supports Piccolo's built-in BaseUser table. If a matching user exists in the database, authentication is checked against the stored password hash.

OAuth2/OIDC

Garden CMS supports any OAuth2/OIDC provider that implements the standard discovery endpoint (.well-known/openid-configuration). The implementation uses PKCE (S256) for security.

Configuration

Set these environment variables:

Variable	Description
`OAUTH_CLIENT_ID`	OAuth client ID
`OAUTH_CLIENT_SECRET`	OAuth client secret
`OAUTH_ISSUER_URL`	Provider issuer URL (e.g. `https://auth.example.com`)
`OAUTH_REDIRECT_URI`	Callback URL (e.g. `https://yoursite.com/admin/oauth/callback`)
`OAUTH_ALLOWED_GROUP`	Restrict access to users in this group (required in production)

Flow

User clicks "Sign in with OAuth" on the login page
Redirected to the provider's authorization endpoint with PKCE challenge
After authentication, redirected back to /admin/oauth/callback
The application exchanges the authorization code for tokens and validates group membership
Session is established

Group-based access control

If OAUTH_ALLOWED_GROUP is set, only users belonging to that group (via the groups claim in userinfo) are allowed access. This works with providers like Authentik, Keycloak, and Pocket ID that include group membership in the userinfo response.

Warning: If OAUTH_ALLOWED_GROUP is empty or unset, any user who can authenticate against the issuer is granted admin access. Always set it in production. The app logs a warning at startup when this is the case.

CSRF protection

All admin mutating endpoints (POST forms, HTMX hx-post/hx-delete requests) are protected by CSRF tokens. The token is set in a csrftoken cookie on safe (GET) requests and validated via either the x-csrftoken header (HTMX) or a hidden _csrf_token form field on submission. No action is required from template authors — the admin layout attaches the token to every outbound HTMX request automatically.

Session management

Sessions are stored in encrypted cookies using Litestar's CookieBackendConfig. The signing key is derived from the SECRET_KEY environment variable via SHA-256. Use a strong, random value (≥32 bytes) in production — the app refuses to start with the insecure dev default in non-dev deployments.

Rate limiting

The password login endpoint is rate-limited to 5 attempts per minute to prevent brute-force attacks.

Logout

Click Log out in the admin sidebar or POST to /admin/logout. The session is cleared and you are redirected to the login page.