Authentication & SSO

Eloquent uses JWT-based authentication with OAuth/SSO support. All API requests are authenticated at the gateway level before reaching backend services.

Authentication Flow

1. User signs in — via Web or Mobile using OAuth (Google), SAML, or credentials
2. Identity verified — SSO provider authenticates and returns a session
3. JWT issued — a signed token is generated containing the user's organization, role, and permissions
4. Gateway validates — the API Gateway checks the JWT on every request, enforces scopes and rate limits, and injects organization context
5. Request reaches services — only authenticated, authorized requests are forwarded to backend services

Critical Configuration

The jwtSecret value in Helm secrets must be identical across all services. A mismatch causes authentication failures:

secrets:
  jwtSecret: "<same-secret-everywhere>"

If JWT validation fails across services, this is the first thing to check.

OAuth / SSO Providers

Google OAuth (Default)

Configure in Helm secrets:

secrets:
  authGoogleId: "<google-oauth-client-id>"
  authGoogleSecret: "<google-oauth-client-secret>"

To set up Google OAuth:

1. Create a project in Google Cloud Console
2. Enable the OAuth consent screen
3. Create OAuth 2.0 credentials (Web Application type)
4. Set authorized redirect URI to https://<your-app-domain>/api/auth/callback/google
5. Copy the Client ID and Client Secret to your Helm secrets

Session Encryption

User sessions are encrypted with:

secrets:
  authSecret: "<random-secret>"

Generate a strong random value (at least 32 characters).

Scope-Based Authorization

The API Gateway enforces permission scopes per route. Common scopes include:

Scopes are embedded in the JWT and validated on each request before it reaches the backend service.

Security Considerations

• Token expiry — JWTs have a limited lifetime; the client automatically refreshes tokens
• HTTPS only — all authentication traffic must be encrypted in transit
• Secret rotation — changing jwtSecret invalidates all active sessions and requires all users to re-authenticate
• Org isolation — JWT claims bind the user to a specific organization context; switching orgs issues a new token