User Authentication

General Bots uses a directory service component for user authentication and authorization. No passwords are stored internally in General Bots.

Overview

Authentication in General Bots is handled entirely by the directory service, which provides:

User identity management
OAuth 2.0 / OpenID Connect (OIDC) authentication
Single Sign-On (SSO) capabilities
Multi-factor authentication (MFA)
User and organization management
Role-based access control (RBAC)

Architecture

Directory Service Integration

General Bots integrates with the directory service through:

DirectoryClient: Client for API communication
AuthService: Service layer for authentication operations
OIDC Flow: Standard OAuth2/OIDC authentication flow
Service Account: For administrative operations

No Internal Password Storage

No password_hash columns: Users table only stores directory user IDs
No Argon2 hashing: All password operations handled by directory service
No password reset logic: Managed through directory service’s built-in flows
Session tokens only: General Bots only manages session state

Authentication Flow

User Registration

User Registration Flow

User General Bots Directory

User registration request sent to directory service
Directory service creates user account
User ID returned to BotServer
General Bots creates local user reference
Session established with General Bots

User Login Flow

Browser General Bots Directory

GET /login 302 Redirect to Directory Show Login Form Submit Credentials ► Validate ► Generate Tokens Redirect + Tokens /auth/callback ► Validate Tokens ► Create Session ► Store in DB Set Cookie Redirect to App

User redirected to directory service login page
Credentials validated by directory service
OIDC tokens returned via callback
General Bots validates tokens
Local session created
Session token issued to client

Token Validation

Token Validation Flow

Request Flow

Validation Pipeline

Request + Cookie Extract Token from Cookie/Header General Bots Validates Check Session in Local Cache

► Valid? Continue ► Expired?

Directory Refresh Refresh with Directory API Process Request Load User Context Apply Permissions

Client includes session token
General Bots validates local session
Optional: Refresh with directory service if expired
User context loaded from directory service
Request processed with user identity

Directory Service Configuration

Auto-Configuration

During bootstrap, General Bots automatically:

Installs directory service via installer.rs
Configures directory service with PostgreSQL
Creates default organization
Sets up service account
Creates initial admin user
Configures OIDC application

Database Schema

Users Table (Simplified)

Column	Type	Description
id	UUID	Internal General Bots ID
directory_id	TEXT	User ID in directory service
username	TEXT	Cached username
email	TEXT	Cached email
created_at	TIMESTAMPTZ	First login time
updated_at	TIMESTAMPTZ	Last sync with directory

Note: No password_hash or any password-related fields exist.

User Sessions Table

Column	Type	Description
id	UUID	Session ID
user_id	UUID	Reference to users table
session_token	TEXT	General Bots session token
directory_token	TEXT	Cached OIDC token
expires_at	TIMESTAMPTZ	Session expiration
created_at	TIMESTAMPTZ	Session start

Authentication Endpoints

GET /auth/login

Redirects to Zitadel login page with OIDC parameters.

OAuth Callback

GET /auth/callback?code=...&state=...

Handles return from Zitadel after successful authentication.

Logout

POST /auth/logout

Terminates local session and optionally triggers Zitadel logout.

Session Validation

GET /auth/validate
Headers: Authorization: Bearer {session_token}

Directory Service Features

User Management

Create, update, delete users
Password reset flows
Email verification
Profile management
Password policies (managed in Zitadel)
Account locking
Password recovery

Multi-Factor Authentication

Configured in Zitadel:

TOTP (Time-based One-Time Passwords)
WebAuthn/FIDO2
SMS OTP (if configured)
Email OTP

Single Sign-On

One login for all applications
Session management across services
Centralized user directory
External IdP integration

Organizations

Multi-tenant support
Organization-specific policies
Delegated administration
User isolation

Directory Service Integration

Directory Client Implementation

Located in src/directory/client.rs:

Manages API communication
Handles token refresh
Caches access tokens
Provides user operations

AuthService

Located in src/directory/mod.rs:

High-level authentication operations
Session management
User profile caching
Group/role management

Security Benefits

Centralized Security

Professional identity platform
Regular security updates
Compliance certifications
Audit logging

No Password Liability

No password storage risks
No hashing implementation errors
No password database leaks
Reduced compliance burden

Advanced Features

Passwordless authentication
Adaptive authentication
Risk-based access control
Session security policies

User Operations

Creating Users

Creating users via Directory Client:

Username: john_doe
Email: john@example.com
First name: John
Last name: Doe
Password: Set through Directory UI or email flow

Getting User Info

User information is fetched from the Directory service using the directory ID.

Managing Sessions

Sessions are managed locally by General Bots but authenticated through Directory Service:

Session creation after Directory auth
Local session tokens for performance
Periodic validation with Zitadel
Session termination on logout

Default Users

During bootstrap, the system creates:

Admin User
- Username: admin (configurable)
- Email: admin@localhost
- Password: Randomly generated (displayed once during setup)
- Role: Administrator
Regular User
- Username: user
- Email: user@default
- Password: Randomly generated (displayed once during setup)
- Role: Standard user

Groups and Roles

Organization Management

Organizations created in Zitadel
Users assigned to organizations
Roles defined per organization
Permissions inherited from roles

Role-Based Access

Admin: Full system access
User: Standard bot interaction
Custom roles: Defined in Zitadel

Monitoring and Audit

Directory Service Audit Logs

All authentication events logged
User actions tracked
Administrative changes recorded
Security events monitored

Session Metrics

General Bots tracks:

Active sessions count
Session creation rate
Failed authentication attempts
Token refresh frequency

Troubleshooting

Common Issues

Zitadel Connection Failed
- Check Zitadel is running on port 8080
- Verify ZITADEL_ISSUER_URL
- Check network connectivity
Authentication Fails
- Verify client credentials
- Check redirect URI configuration
- Review Zitadel logs
Session Issues
- Clear browser cookies
- Check session expiry settings
- Verify token refresh logic

Best Practices

Use Zitadel UI: Manage users through Zitadel interface
Configure MFA: Enable multi-factor for admin accounts
Regular Updates: Keep Zitadel updated
Monitor Logs: Review authentication logs regularly
Session Timeout: Configure appropriate session duration
Secure Communication: Use HTTPS in production

Migration from Other Systems

When migrating from password-based systems:

Export user data (without passwords)
Import users into Zitadel
Force password reset for all users
Update application to use OIDC flow
Remove password-related code

Summary

General Bots’ integration with the Directory Service provides enterprise-grade authentication without the complexity and risk of managing passwords internally. All authentication operations are delegated to the Directory Service, while General Bots focuses on session management and bot interactions.

Keyboard shortcuts

General Bots Documentation