Skip to content

Auto-Provisioning Mailboxes on First Login

Messages can automatically create a mailbox when a user logs in for the first time via OIDC. This eliminates the manual step of creating mailboxes in the Django admin.

How It Works

When a user logs in via Keycloak for the first time:

  1. OIDC_CREATE_USER=True creates their Messages user account
  2. autojoin_mailbox() checks if their email domain has oidc_autojoin=True
  3. If yes, a mailbox is created with the user's email local part
  4. The user gets Admin access to their own mailbox
  5. The mailbox is synced back to Keycloak (if identity_sync=True)

Configuration

1. Enable OIDC User Creation

Already configured in .env:

OIDC_CREATE_USER=True

2. Enable Auto-Join on the Mail Domain

After creating a mail domain in the Django admin, enable auto-join via the Django shell:

# Open Django shell
docker compose exec backend python manage.py shell

# Enable auto-join
from core.models import MailDomain
domain = MailDomain.objects.get(name='<domain>')
domain.oidc_autojoin = True
domain.identity_sync = True
domain.save()

Or set it when creating the domain via API:

MailDomain.objects.create(
    name='<domain>',
    oidc_autojoin=True,
    identity_sync=True
)

3. Create Keycloak Users

  1. Go to https://auth.messages.<domain>/admin
  2. Realm: messages
  3. Users → Create user
  4. Set email to user@<domain> (must match the auto-join domain)
  5. Set password under Credentials tab

4. User Logs In

When the user logs in at https://messages.<domain> for the first time:

  • Their Messages account is created automatically
  • A mailbox user@<domain> is created with Admin access
  • The mailbox appears in their inbox immediately

Verification

Check that the mailbox was created:

docker compose exec backend python manage.py shell -c "
from core.models import Mailbox
for m in Mailbox.objects.all():
    print(f'{m.local_part}@{m.domain.name} — owner: {m.accesses.first().user.email if m.accesses.first() else \"none\"}')
"

Keycloak Sync

When identity_sync=True, the mailbox is synced to Keycloak:

  • A Keycloak user is created/updated with attributes: mailbox_id, local_part, domain_name, maildomain_id
  • A Keycloak group /maildomain-<domain> is created for the mail domain
  • The user is added to the group

This enables Keycloak-based authorization and group management for mailboxes.

Test Domain (Development)

Messages has a MESSAGES_TESTDOMAIN setting for development environments. When set, it auto-creates the test domain with auto-join enabled and creates mailboxes for any user logging in with a matching email:

MESSAGES_TESTDOMAIN=example.local

This is not recommended for production — use oidc_autojoin=True on real domains instead.

Without Auto-Join

If a user logs in but their email domain doesn't have oidc_autojoin=True:

  • Their Messages account is still created (OIDC_CREATE_USER=True)
  • No mailbox is created — an admin must manually create one and grant access
  • The user sees an empty inbox until a mailbox is assigned