Authentication Overview

Rack Gateway uses a multi-layered authentication system combining OAuth 2.0 for identity, session tokens for authorization, and multi-factor authentication, which is required for every user by default.

Authentication Methods

OAuth 2.0

For human users

Google Workspace OAuth with PKCE for secure sign-in. Domain restrictions ensure only authorized users can access.

Learn more →

API Tokens

For automation

Long-lived tokens for CI/CD pipelines, scripts, and integrations. Each token has its own permissions, limited by its owner’s role.

Learn more →

Authentication Flow

Web vs CLI Authentication

The gateway supports two authentication channels:

Aspect	Web Browser	CLI
OAuth Flow	Standard code flow	PKCE code flow
Session Storage	HTTP-only cookie	Local config file
Session Lifetime	Ends after inactivity (default 5 min)	90 days
MFA	Browser-based prompts	Terminal prompts
CSRF Protection	Required (cookie-based)	Not needed (token-based)

Web Authentication

1. User clicks Continue with Google
2. Redirected to Google OAuth consent screen
3. After approval, redirected back with authorization code
4. Gateway exchanges code for ID token
5. Session created and stored in HTTP-only cookie
6. If MFA enabled, prompted for verification

CLI Authentication

1. User runs rack-gateway login; the CLI listens on http://127.0.0.1:<random port>/callback
2. CLI generates its PKCE code verifier and sends only the S256 challenge, its state and the loopback redirect URI to the gateway
3. Browser opens to Google OAuth (the URL is also printed in the terminal)
4. The gateway exchanges Google’s code at the callback, then binds the login to that browser
5. After MFA, the browser is redirected to the CLI’s loopback listener with a single-use login code
6. The CLI redeems the login code with its code verifier and receives a session token
7. Session token stored in ~/.config/rack-gateway/config.json
8. The CLI sends the browser on to the gateway’s result page (success, or the reason the login failed)

See OAuth Flow for details.

Session Management

Sessions are the primary authentication mechanism after initial OAuth:

• Token-based: Opaque tokens stored in database, hashed
• Revocable: Sessions can be revoked at any time
• Sliding expiration: Activity refreshes the session
• Device tracking: IP address and user agent logged

See Sessions for details.

Security Features

Domain Restriction

Only users from your Google Workspace domain can authenticate:

# Environment variable
GOOGLE_ALLOWED_DOMAIN=yourcompany.com

Users from other domains receive an error during OAuth callback.

Email Verification

The gateway verifies that:

• Email is verified in Google’s ID token
• Email domain matches the allowed domain
• User account exists and is not locked

Token Hashing

Session tokens are never stored in plaintext:

Stored: SHA-256(session_token)
Client: session_token (raw)

Even if the database is compromised, tokens cannot be recovered.

CSRF Protection

Web requests require CSRF tokens to prevent cross-site request forgery:

• Token derived from session using HMAC
• Validated on all state-changing requests
• Automatically handled by the web UI

MFA Integration

MFA adds a second factor after OAuth authentication:

MFA is required for every user by default (mfa_require_all_users). With that setting off, users who haven’t enrolled can sign in to the web UI without MFA, but the CLI still requires every user to enroll. Either way, actions that need MFA ask for it (see MFA Requirements).

See MFA Overview for setup details.

Token vs Session Authentication

Characteristic	Session (Human)	API Token (Automation)
Creation	OAuth flow	Created in the web UI or with rack-gateway api-token create (deployers for themselves, admins for anyone)
Lifetime	Web: idle timeout; CLI: 90 days from last use	Until deleted or its optional expiry
Revocation	Logout (web or rack-gateway logout), or revoking it from the user’s sessions	Delete token
MFA	Required	N/A (limited by permissions instead)
CSRF	Required (web)	Not required
Use Case	Interactive access	CI/CD, scripts

Configuration

Key authentication settings:

Setting	Description	Default
GOOGLE_CLIENT_ID	OAuth client ID	Required
GOOGLE_CLIENT_SECRET	OAuth client secret	Required
GOOGLE_ALLOWED_DOMAIN	Allowed email domain	Required
APP_SECRET_KEY	Secret for sessions/CSRF	Required
RGW_SETTING_SESSION_TIMEOUT_MINUTES	Idle session timeout	5

See Configuration for complete reference.

Security Checklist

• HTTPS enabled with valid certificate
• GOOGLE_ALLOWED_DOMAIN set to your domain
• APP_SECRET_KEY is strong and unique
• Session timeout appropriate for your security needs
• MFA required for all users (the default)
• Audit logging configured

Next Steps

• OAuth Flow - OAuth implementation details
• Sessions - Session management
• API Tokens - Token security
• MFA Overview - Multi-factor authentication