Single Sign-On (SSO)

When Opterius Mail is installed alongside Opterius Panel, users can open webmail directly from the Panel without re-entering their email password. This is Single Sign-On (SSO) — the Panel vouches for the user's identity and Opterius Mail trusts that voucher without requiring independent credential verification.

How It Works#

1. User clicks "Open Webmail" in Opterius Panel
         ↓
2. Panel generates a signed JWT token
   { email: "user@example.com", exp: now+60s, nonce: "abc123" }
   Signed with OPTERIUS_SSO_SECRET (shared secret, HMAC-SHA256)
         ↓
3. Panel redirects user's browser to:
   https://mail.example.com:8090/sso/login?token={jwt}
         ↓
4. Opterius Mail receives the request at /sso/login
         ↓
5. Opterius Mail verifies:
   a. Signature is valid (using OPTERIUS_SSO_SECRET from its own .env)
   b. Token has not expired (exp check — must be within 60 seconds)
   c. Nonce has not been used before (stored in cache to prevent replay)
         ↓
6. Token passes → Opterius Mail establishes IMAP session
   using the email address from the token + the encrypted IMAP
   credentials that were stored during the last normal login
         ↓
7. User lands in their inbox with no login prompt

Security Properties#

Automatic Configuration (Opterius Panel Installer)#

When Opterius Mail is installed via the Panel installer, SSO is configured automatically:

1. The installer generates a 32-character hex OPTERIUS_SSO_SECRET.
2. The secret is written to both:
   • Panel's agent config: mail_sso_secret=...
   • Mail's .env: OPTERIUS_SSO_SECRET=...
3. The "Open Webmail" button in Panel immediately works.

No manual steps are needed for a standard installer-based deployment.

Manual Configuration#

If you are setting up SSO manually (e.g., after reinstalling Mail on a new server, or on a non-standard deployment):

Step 1 — Generate a shared secret#

openssl rand -hex 32
# Example output: a3f8d7c2b1e945...

Step 2 — Set the secret in Opterius Mail's .env#

OPTERIUS_SSO_SECRET=a3f8d7c2b1e945...

Step 3 — Set the same secret in Opterius Panel#

In the Panel's configuration (usually /opt/opterius/config/mail.conf or via the Panel admin UI):

mail_sso_secret=a3f8d7c2b1e945...

The values must be identical. Even a single character difference will cause all SSO logins to fail with a 401 Invalid signature error.

Step 4 — Clear the config cache in Opterius Mail#

cd /opt/opterius-mail
php artisan config:clear

Testing SSO#

After configuration:

1. Log into Opterius Panel as a user who has an email account.
2. Navigate to Panel → Email → Accounts.
3. Click Open Webmail next to the account.
4. Verify you are redirected to Opterius Mail and land directly in the inbox without a login prompt.

Troubleshooting#

"Invalid SSO token" (401)#

• The OPTERIUS_SSO_SECRET values do not match between Panel and Mail.
• The token has expired (more than 60 seconds passed between Panel generating it and Mail receiving it). Usually caused by a large clock difference between servers — ensure NTP is running on both.
• The nonce was already used (the link was clicked twice). Generate a fresh link from the Panel.

"SSO not configured" (404)#

OPTERIUS_SSO_SECRET is not set in Opterius Mail's .env. The /sso/login route returns 404 when the secret is not configured.

Clock Skew#

If your Panel and Mail servers are on different machines, their clocks must be synchronised. A difference of more than ~30 seconds will cause tokens to appear expired on arrival.

# Check current time and NTP status
timedatectl status

# Force NTP sync
sudo systemctl restart systemd-timesyncd

Disabling SSO#

Remove OPTERIUS_SSO_SECRET from Opterius Mail's .env (or leave it empty). The /sso/login route will return 404. Users will be directed to the standard webmail login page at /.

sed -i '/^OPTERIUS_SSO_SECRET=/d' /opt/opterius-mail/.env
php artisan config:clear