architect/_archive/2025-11-26-cleanup/templates/by-feature/auth/streamlit-auth-v1/MIGRATION_v1_to_v2.md

Migration Guide: Auth v1.0 → v2.0 (DRAFT)

Status: DRAFT (v2.0 not released yet)
Estimated Release: Q4 2025

This guide will help you migrate from streamlit-auth-v1 to v2 when it's released.

Breaking Changes Overview

1. config.yaml Structure Change

v1.0 (current):

credentials:
  usernames:
    admin:
      email: admin@example.com
      name: Admin
      password: $2b$12$...

cookie:
  name: app_auth
  key: secret_key
  expiry_days: 30

v2.0 (planned):

credentials:
  # Local users (same as v1)
  local:
    users:
      admin:
        email: admin@example.com
        name: Admin
        password: $2b$12$...
        roles: [admin]  # NEW: RBAC support

  # NEW: OAuth2 providers
  oauth2:
    google:
      client_id: "..."
      client_secret: "..."
      enabled: true
    github:
      client_id: "..."
      client_secret: "..."
      enabled: true

# NEW: 2FA settings
two_factor:
  enabled: false
  mandatory_for_roles: [admin]

cookie:
  name: app_auth
  key: secret_key
  expiry_days: 30

2. New Dependencies

Add to requirements.txt:

authlib>=1.2.0
pyotp>=2.9.0
sendgrid>=6.10.0  # if using email features

3. Authentication Function Changes

v1.0:

authenticator.login(location='main', key='Login')

v2.0:

authenticator.login(
    location='main',
    key='Login',
    providers=['local', 'google', 'github']  # NEW
)

Migration Steps

Step 1: Backup Current Setup

# Backup config
cp config.yaml config.yaml.v1.backup

# Backup code
cp -r utils/ utils.v1.backup/

Step 2: Update Dependencies

pip install authlib pyotp sendgrid

Step 3: Migrate config.yaml

# Use migration script
python scripts/migrate_config_v1_to_v2.py config.yaml

Or manually:
1. Wrap usernames in credentials.local.users
2. Add roles: [user] to each user
3. Add oauth2 section if needed
4. Add two_factor section

Step 4: Update Authentication Code

Before (v1.0):

# app.py
authenticator = stauth.Authenticate(
    config['credentials'],
    config['cookie']['name'],
    config['cookie']['key'],
    config['cookie']['expiry_days']
)

After (v2.0):

# app.py
authenticator = stauth.Authenticate(
    config,  # Pass full config now
    version='v2'
)

Step 5: Add OAuth2 (Optional)

If you want OAuth2:

  1. Create OAuth2 apps:
    - Google: https://console.cloud.google.com/
    - GitHub: https://github.com/settings/developers

  2. Add credentials to config.yaml

  3. Update login call:

authenticator.login(
    location='main',
    providers=['local', 'google', 'github']
)

Step 6: Add 2FA (Optional)

# After login
if config['two_factor']['enabled']:
    if not authenticator.verify_2fa():
        st.error("Invalid 2FA code")
        st.stop()

Step 7: Test Migration

# Start app
streamlit run app.py

# Test scenarios:
# 1. Login with local account
# 2. Login with OAuth2 (if enabled)
# 3. 2FA verification (if enabled)
# 4. Logout
# 5. Protected pages still work

Compatibility Mode

v2.0 will support v1.0 config for backward compatibility:

# app.py
authenticator = stauth.Authenticate(
    config,
    version='v1',  # Use v1 mode
    legacy=True
)

This allows gradual migration.

Rollback Plan

If migration fails:

# Restore backups
cp config.yaml.v1.backup config.yaml
rm -rf utils/
cp -r utils.v1.backup/ utils/

# Downgrade dependencies
pip install streamlit-authenticator==0.2.3

# Restart app
streamlit run app.py

Timeline

Getting Help

Note: This is a DRAFT migration guide for a future version.
Details may change when v2.0 is actually released.