Skip to main content

SSO Configuration

Microsoft Entra ID (Azure AD) Single Sign-On setup for Chatty AI.

Overview​

Chatty AI supports Microsoft SSO, allowing users to log in with their Microsoft/Office 365 accounts. This provides:

  • Single Sign-On experience
  • No password management
  • Integration with Microsoft identity
  • Multi-factor authentication (if enabled in Azure)

SSO Variables​

MICROSOFT_CLIENT_ID​

  • Type: String (UUID)
  • Required: No (only if using SSO)
  • Default: None
  • Example: 12345678-1234-1234-1234-123456789012
  • Description: Microsoft Entra ID (Azure AD) Application (client) ID for SSO login
  • Used in: chattyai service
  • Setup: Azure Portal → App Registrations

MICROSOFT_CLIENT_SECRET​

  • Type: String (secret)
  • Required: No (only if using SSO)
  • Default: None
  • Security: 🔴 HIGH - Keep secret
  • Example: abc123~XYZ...
  • Description: Microsoft Entra ID client secret for SSO authentication
  • Used in: chattyai service
  • Setup: Azure Portal → Certificates & secrets

MICROSOFT_CLIENT_TENANT_ID​

  • Type: String (UUID or "common")
  • Required: No (only if using SSO)
  • Default: None
  • Example:
    • common - Multi-tenant (any Microsoft account)
    • 12345678-1234-1234-1234-123456789012 - Single tenant
  • Description: Microsoft Entra ID tenant ID
  • Used in: chattyai service

MICROSOFT_OAUTH_SCOPE​

  • Type: String (space-separated scopes)
  • Required: No
  • Default: openid email profile
  • Example: openid email profile User.Read
  • Description: OAuth scopes to request during Microsoft SSO login
  • Used in: chattyai service

MICROSOFT_REDIRECT_URI​

  • Type: String (URL)
  • Required: No (auto-generated)
  • Default: ${CHATTYAI_URL}/oauth/microsoft/callback
  • Example: https://chat.example.com/oauth/microsoft/callback
  • Description: OAuth redirect URI for Microsoft SSO (must match Azure App Registration)
  • Used in: chattyai service
  • Note: Set this manually in .env to match your Azure configuration

Azure App Registration Setup​

Step 1: Create App Registration​

  1. Go to Azure Portal
  2. Navigate to Azure Active Directory → App registrations
  3. Click New registration
  4. Configure:
    • Name: Chatty AI
    • Supported account types:
      • Single tenant: Accounts in this organizational directory only
      • Multi-tenant: Accounts in any organizational directory
    • Redirect URI:
      • Platform: Web
      • URI: https://chat.example.com/oauth/microsoft/callback
  5. Click Register

Step 2: Get Client ID and Tenant ID​

After registration:

  1. Copy Application (client) ID → This is MICROSOFT_CLIENT_ID
  2. Copy Directory (tenant) ID → This is MICROSOFT_CLIENT_TENANT_ID

Step 3: Create Client Secret​

  1. Go to Certificates & secrets
  2. Click New client secret
  3. Configure:
    • Description: Chatty AI Secret
    • Expires: 24 months (recommended)
  4. Click Add
  5. Copy the secret value immediately → This is MICROSOFT_CLIENT_SECRET
    • ⚠️ You can't view it again after leaving the page!

Step 4: Configure API Permissions​

  1. Go to API permissions
  2. Click Add a permission
  3. Select Microsoft Graph
  4. Select Delegated permissions
  5. Add these permissions:
    • openid - Sign in
    • email - Read email address
    • profile - Read basic profile
    • User.Read - Read user profile (optional)
  6. Click Add permissions
  7. Click Grant admin consent (if you have admin rights)

Step 5: Configure Authentication​

  1. Go to Authentication
  2. Under Platform configurations → Web:
    • Redirect URIs: https://chat.example.com/oauth/microsoft/callback
    • Front-channel logout URL: (leave empty)
    • Implicit grant and hybrid flows:
      • ✅ ID tokens (used for implicit and hybrid flows)
  3. Under Advanced settings:
    • Allow public client flows: No
  4. Click Save

Configuration Examples​

Single Tenant (One Organization)​

MICROSOFT_CLIENT_ID=12345678-1234-1234-1234-123456789012
MICROSOFT_CLIENT_SECRET=abc123~XYZ...
MICROSOFT_CLIENT_TENANT_ID=87654321-4321-4321-4321-210987654321
MICROSOFT_OAUTH_SCOPE=openid email profile
MICROSOFT_REDIRECT_URI=https://chat.example.com/oauth/microsoft/callback

Multi-Tenant (Any Microsoft Account)​

MICROSOFT_CLIENT_ID=12345678-1234-1234-1234-123456789012
MICROSOFT_CLIENT_SECRET=abc123~XYZ...
MICROSOFT_CLIENT_TENANT_ID=common
MICROSOFT_OAUTH_SCOPE=openid email profile
MICROSOFT_REDIRECT_URI=https://chat.example.com/oauth/microsoft/callback

With Additional Scopes​

MICROSOFT_CLIENT_ID=12345678-1234-1234-1234-123456789012
MICROSOFT_CLIENT_SECRET=abc123~XYZ...
MICROSOFT_CLIENT_TENANT_ID=common
MICROSOFT_OAUTH_SCOPE=openid email profile User.Read
MICROSOFT_REDIRECT_URI=https://chat.example.com/oauth/microsoft/callback

Chatty AI Configuration​

Add to .env File​

# Microsoft SSO Configuration
MICROSOFT_CLIENT_ID=12345678-1234-1234-1234-123456789012
MICROSOFT_CLIENT_SECRET=abc123~XYZ...
MICROSOFT_CLIENT_TENANT_ID=common
MICROSOFT_REDIRECT_URI=https://chat.example.com/oauth/microsoft/callback

Restart Services​

docker compose down
docker compose up -d

Test SSO Login​

  1. Go to Chatty AI login page
  2. Click Sign in with Microsoft
  3. Authenticate with Microsoft account
  4. Grant permissions if prompted
  5. You should be logged into Chatty AI

Security Best Practices​

1. Protect Client Secret​

# Never commit to git
echo "MICROSOFT_CLIENT_SECRET=*" >> .gitignore

# Rotate secret every 12-24 months
# Azure Portal → App Registration → Certificates & secrets → New client secret

2. Use Single Tenant for Production​

# More secure - only your organization
MICROSOFT_CLIENT_TENANT_ID=87654321-4321-4321-4321-210987654321

# Less secure - any Microsoft account
MICROSOFT_CLIENT_TENANT_ID=common

3. Minimal Scopes​

Only request scopes you need:

# Minimal (recommended)
MICROSOFT_OAUTH_SCOPE=openid email profile

# With user info
MICROSOFT_OAUTH_SCOPE=openid email profile User.Read

4. HTTPS Required​

SSO only works with HTTPS:

# Required
CHATTYAI_URL=https://chat.example.com

# Won't work
CHATTYAI_URL=http://chat.example.com

5. Correct Redirect URI​

Must match exactly in Azure and .env:

# In Azure App Registration
https://chat.example.com/oauth/microsoft/callback

# In .env
MICROSOFT_REDIRECT_URI=https://chat.example.com/oauth/microsoft/callback

Troubleshooting​

Redirect URI Mismatch​

Error: AADSTS50011: The redirect URI specified in the request does not match

Solution:

  1. Check MICROSOFT_REDIRECT_URI in .env matches Azure
  2. Verify CHATTYAI_URL is correct
  3. Ensure using HTTPS
# Check current config
grep MICROSOFT_REDIRECT_URI .env
grep CHATTYAI_URL .env

# Should match Azure App Registration redirect URI exactly

Invalid Client Secret​

Error: AADSTS7000215: Invalid client secret provided

Solution:

  1. Client secret may have expired
  2. Create new secret in Azure Portal
  3. Update MICROSOFT_CLIENT_SECRET in .env
  4. Restart services

Tenant Not Found​

Error: AADSTS90002: Tenant not found

Solution:

  • Check MICROSOFT_CLIENT_TENANT_ID is correct
  • Use common for multi-tenant
  • Use specific tenant ID for single-tenant

Permissions Not Granted​

Error: AADSTS65001: The user or administrator has not consented

Solution:

  1. Go to Azure Portal → App Registration → API permissions
  2. Click Grant admin consent
  3. Or have users consent during first login

SSO Button Not Showing​

Check Chatty AI logs:

docker compose logs chattyai | grep -i microsoft

Verify variables are set:

docker compose exec chattyai env | grep MICROSOFT

SSO + Local Users​

Chatty AI supports both SSO and local users:

  • SSO users: Authenticate via Microsoft
  • Local users: Authenticate via database (admin, etc.)
  • Admin account: Always local (not SSO)

Admin Account​

Admin account is always local:

CHATTYAI_ADMIN_EMAIL=admin@company.com
CHATTYAI_ADMIN_PASSWORD=admin-password

This ensures you can always log in even if SSO is misconfigured.

SSO vs LDAP​

FeatureMicrosoft SSOLDAP
SetupAzure App RegistrationLDAP server required
User SourceMicrosoft/Office 365Corporate LDAP/AD
MFA SupportYes (via Azure)Depends on LDAP
Password ManagementMicrosoft handlesLDAP handles
Best ForOffice 365 usersOn-premise AD users

You can enable both SSO and LDAP simultaneously.

Advanced Configuration​

Custom Scopes​

Request additional Microsoft Graph permissions:

MICROSOFT_OAUTH_SCOPE=openid email profile User.Read Calendars.Read Mail.Read

Remember to add these permissions in Azure App Registration.

Multi-Tenant Configuration​

Allow users from any organization:

MICROSOFT_CLIENT_TENANT_ID=common

Or specific organizations:

MICROSOFT_CLIENT_TENANT_ID=organizations

Or consumers only:

MICROSOFT_CLIENT_TENANT_ID=consumers