GeneralBots/botserver
2
1
Fork 0
Code Issues Pull requests Projects Releases 323 Packages Wiki Activity Actions
botserver/docs/src/chapter-11/password-security.md

7.4 KiB
Raw Blame History

Password Security

BotServer delegates all password security to Zitadel, an enterprise-grade identity management platform. No passwords are ever stored, hashed, or managed within BotServer itself.

Overview

Password security is handled entirely by Zitadel, which provides:

  • Industry-standard password hashing (Argon2/bcrypt)
  • Configurable password policies
  • Password history and rotation
  • Breach detection
  • Self-service password recovery

No Internal Password Management

What BotServer Does NOT Do

  • No password storage: No password or hash columns in database
  • No hashing implementation: No Argon2/bcrypt code in BotServer
  • No password validation: All validation done by Zitadel
  • No password reset logic: Handled through Zitadel workflows
  • No password policies: Configured in Zitadel admin console

What BotServer DOES Do

  • Redirects to Zitadel for authentication
  • Stores Zitadel user IDs
  • Manages local session tokens
  • Caches user profile information
  • Validates sessions locally for performance

Zitadel Password Security

Hashing Algorithm

Zitadel uses industry-standard algorithms:

  • Default: Argon2id (recommended)
  • Alternative: bcrypt (for compatibility)
  • Configurable: Parameters can be adjusted
  • Automatic: Rehashing on algorithm updates

Password Policies

Configured in Zitadel admin console:

  • Minimum length (default: 8 characters)
  • Maximum length (configurable)
  • Character requirements (uppercase, lowercase, numbers, symbols)
  • Complexity rules
  • Common password blacklist
  • Password history (prevent reuse)
  • Expiration policies

Password Storage in Zitadel

Zitadel stores:

  • Hashed passwords (never plaintext)
  • Salt per password
  • Algorithm identifier
  • Hash parameters
  • Password history
  • Last changed timestamp

Configuration

Setting Password Policies

Access Zitadel admin console:

  1. Navigate to Settings → Password Complexity
  2. Configure requirements:
    • Min/max length
    • Required character types
    • Expiry settings
  3. Save changes (applies immediately)

Example Policy Configuration

In Zitadel UI or API:

{
  "minLength": 12,
  "maxLength": 128,
  "hasUppercase": true,
  "hasLowercase": true,
  "hasNumber": true,
  "hasSymbol": true,
  "passwordHistory": 5,
  "expiryDays": 90
}

Password Reset Flow

User-Initiated Reset

  1. User clicks "Forgot Password" on Zitadel login
  2. Email sent with reset link
  3. User clicks link (time-limited)
  4. New password entered in Zitadel UI
  5. Password validated against policy
  6. Hash updated in Zitadel database
  7. User can login with new password

Admin-Initiated Reset

  1. Admin accesses Zitadel console
  2. Navigates to user management
  3. Triggers password reset
  4. User receives reset email
  5. Same flow as user-initiated

Security Features

Breach Detection

Zitadel includes:

  • Have I Been Pwned integration
  • Checks passwords against breach databases
  • Warns users of compromised passwords
  • Forces reset if detected in breach

Multi-Factor Authentication

Additional security beyond passwords:

  • TOTP (Google Authenticator, etc.)
  • WebAuthn/FIDO2 keys
  • SMS OTP (if configured)
  • Email verification codes

Account Protection

  • Account lockout after failed attempts
  • CAPTCHA after threshold
  • IP-based rate limiting
  • Suspicious activity detection
  • Passwordless options available

Integration Points

Bootstrap Process

During setup, BotServer:

  1. Installs Zitadel
  2. Configures database connection
  3. Creates admin account with default password
  4. Default: BotServer123! (must be changed)

Authentication Flow

  1. User enters credentials in Zitadel UI
  2. Zitadel validates password
  3. OIDC tokens issued
  4. BotServer receives tokens
  5. No password ever touches BotServer

Session Management

After Zitadel authentication:

  • BotServer creates local session
  • Session token generated (not password-related)
  • User ID linked to Zitadel ID
  • No password data stored

Default Credentials

Initial Admin Account

Created during bootstrap:

  • Username: admin
  • Password: BotServer123!
  • MUST BE CHANGED on first login
  • Enforced by Zitadel if configured

Initial User Account

Created during bootstrap:

  • Username: user
  • Password: User123!
  • Should be changed by user
  • Subject to configured policies

Best Practices

For Administrators

  1. Change Defaults: Immediately change default passwords
  2. Configure Policies: Set appropriate password requirements
  3. Enable MFA: Require for admin accounts
  4. Monitor Logs: Review authentication attempts
  5. Update Regularly: Keep Zitadel updated
  6. Test Recovery: Verify password reset works

For Developers

  1. Never Touch Passwords: Let Zitadel handle everything
  2. Use OIDC Flow: Standard OAuth2/OpenID Connect
  3. Validate Tokens: Check with Zitadel when needed
  4. Cache Carefully: Don't cache sensitive data
  5. Log Safely: Never log authentication details

For Users

  1. Use Strong Passwords: Follow policy requirements
  2. Enable MFA: Add extra security layer
  3. Unique Passwords: Don't reuse across services
  4. Regular Updates: Change periodically if required
  5. Report Issues: Alert admins of problems

Compliance

Zitadel's password handling helps meet:

  • GDPR: Data protection requirements
  • NIST 800-63B: Modern password guidelines
  • OWASP: Security best practices
  • PCI DSS: Payment card standards
  • HIPAA: Healthcare requirements
  • SOC 2: Security controls

Troubleshooting

Common Password Issues

  1. Password Reset Not Working

    • Check email configuration
    • Verify SMTP settings in Zitadel
    • Check spam folders

  2. Policy Not Enforced

    • Review Zitadel configuration
    • Check policy is active
    • Verify user's organization settings

  3. Account Locked

    • Check lockout policy
    • Admin can unlock via console
    • Wait for timeout period

  4. MFA Issues

    • Verify time sync for TOTP
    • Check backup codes
    • Admin can reset MFA

Security Benefits

Delegated Security

  • Professional Implementation: Security experts maintain Zitadel
  • Regular Updates: Security patches applied by Zitadel team
  • Compliance: Certifications maintained by Zitadel
  • No Liability: Password breaches not BotServer's responsibility

Reduced Attack Surface

  • No password code to exploit
  • No hashing vulnerabilities
  • No timing attacks possible
  • No password database to breach

Advanced Features

Available through Zitadel:

  • Passwordless authentication
  • Biometric support
  • Hardware key support
  • Risk-based authentication
  • Adaptive security

Migration Guide

From Internal Passwords

If migrating from a system with internal passwords:

  1. Export Users: Username and email only (no passwords)
  2. Import to Zitadel: Create accounts
  3. Force Reset: All users must set new passwords
  4. Remove Old Code: Delete password-related code
  5. Update Docs: Reflect new authentication flow

Password Policy Migration

  1. Document existing policy
  2. Configure equivalent in Zitadel
  3. Test with sample accounts
  4. Communicate changes to users
  5. Provide support during transition

Summary

BotServer achieves enterprise-grade password security by not handling passwords at all. Zitadel provides professional identity management with all the security features needed for production deployments. This separation of concerns allows BotServer to focus on bot functionality while delegating security to a specialized platform.