Configure authentication for Hanzo Chat — Hanzo IAM, OAuth2/OIDC, social login, and local auth.

Authentication

Hanzo Chat supports multiple authentication methods. The recommended approach is Hanzo IAM (OAuth2/OIDC), but social login and local email/password auth are also available.

Hanzo IAM (Recommended)

Hanzo IAM at hanzo.id provides centralized authentication with SSO across all Hanzo services.

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│  Hanzo Chat │────▶│  Hanzo IAM  │────▶│ Social Providers│
│  (3081)     │     │  (hanzo.id) │     │ Google, GitHub  │
└─────────────┘     └─────────────┘     └─────────────────┘

Configuration

# Hanzo IAM as OpenID Connect provider
OPENID_ISSUER=https://hanzo.id
OPENID_CLIENT_ID=hanzo-chat-client
OPENID_CLIENT_SECRET=your-client-secret
OPENID_CALLBACK_URL=/oauth/openid/callback
OPENID_SCOPE=openid profile email
OPENID_BUTTON_LABEL=Login with Hanzo

Setting Up IAM

Go to Applications → New Application

Create an OAuth application:

Name: Hanzo Chat
Client ID: hanzo-chat-client
Redirect URIs: https://chat.yourdomain.com/oauth/openid/callback
Grant Types: Authorization Code

Copy the Client Secret to your .env

Google

GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=/oauth/google/callback

Setup:

Go to Google Cloud Console

Create OAuth 2.0 credentials

Add authorized redirect URI: https://chat.yourdomain.com/oauth/google/callback

GitHub

GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GITHUB_CALLBACK_URL=/oauth/github/callback

Setup:

Go to GitHub Developer Settings

Create a new OAuth App

Set callback URL: https://chat.yourdomain.com/oauth/github/callback

Discord

DISCORD_CLIENT_ID=your-discord-client-id
DISCORD_CLIENT_SECRET=your-discord-client-secret
DISCORD_CALLBACK_URL=/oauth/discord/callback

Facebook

FACEBOOK_CLIENT_ID=your-facebook-app-id
FACEBOOK_CLIENT_SECRET=your-facebook-app-secret
FACEBOOK_CALLBACK_URL=/oauth/facebook/callback

Local Authentication

Email/password authentication is enabled by default:

# Allow new user registration
ALLOW_REGISTRATION=true

# Require email verification (needs SMTP)
ALLOW_UNVERIFIED_EMAIL_LOGIN=true

# Email verification SMTP settings
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_ENCRYPTION=starttls
EMAIL_USERNAME=[email protected]
EMAIL_PASSWORD=your-app-password
EMAIL_FROM=[email protected]

Registration Control

# Allow/disallow new registrations
ALLOW_REGISTRATION=true

# Allow only specific email domains
ALLOWED_REGISTRATION_DOMAINS=hanzo.ai,yourcompany.com

# Social login on registration page
ALLOW_SOCIAL_REGISTRATION=true
ALLOW_SOCIAL_LOGIN=true

# chat.yaml - configure social login buttons
registration:
  socialLogins:
    - google
    - github
    - hanzo
  allowedDomains: []

Session Configuration

# Session secret (change in production!)
JWT_SECRET=your-jwt-secret-change-this
JWT_REFRESH_SECRET=your-refresh-secret-change-this

# Session duration
SESSION_EXPIRY=900000          # 15 minutes in ms
REFRESH_TOKEN_EXPIRY=604800000 # 7 days in ms

Production Security

Change all default secrets — JWT_SECRET, CLIENT_SECRET, etc.

Use HTTPS — required for OAuth redirects

Configure CORS — restrict to your domain

Enable rate limiting — see Moderation

Disable registration if your instance is private

Use IAM for centralized user management across services

Authentication

On this page