SSO Migration & Authentication Modes
Single Sign-On (SSO) lets users sign in to AION with their company Microsoft or Google account instead of a separate AION password. This page explains what happens when an administrator switches AION from password login to SSO (or back), what each user sees during the switch and how new accounts are handled. It is for administrators; the user-facing steps are in Migration Flow (User Perspective).
This document explains how the AION platform handles the migration from local password-based authentication to external SSO providers (like Microsoft Entra ID or Google Workspace).
The Core Philosophy
When AION is switched from "Password Mode" to "SSO Mode" (e.g., Microsoft or Google), it enters a Migration State.
- No Auto-Provisioning for Existing Accounts: AION will never automatically link an incoming SSO login to an existing local account merely based on a matching email address. This prevents account takeover attacks.
- Explicit Linking: A user with an existing local account must first authenticate using their local password, and then explicitly authorize the SSO provider to link the identities.
- SSO Enforced: Once migration is active, users who have not yet linked their accounts will be denied access to the chat until they complete the linking flow.
1. Migration Flow (User Perspective)
When the administrator switches the system to "Microsoft" or "Google":
- The user visits the login page. The SSO button (e.g., "Accedi con Microsoft", i.e. "Sign in with Microsoft") is displayed.
- If the user clicks the SSO button but they haven't linked their account yet, login fails with
sso_not_linked: while the migration is active no new account is created from an unlinked identity (this avoids duplicate ghost accounts). - Therefore, existing users must log in using the username and password form.
- Upon successful password login, the API detects that the system requires SSO and the user hasn't linked their account. The API returns
sso_link_required: true. - The Chat UI intercepts this flag and displays the Security Update Modal (SSO Link Modal), blocking access to the chat.
- The user clicks "Collega account Microsoft". They are redirected to the Microsoft login page.
- After authenticating with Microsoft, they are redirected back to AION. The backend securely verifies the SSO token, links the Microsoft identity to their local AION user, and logs them in.
2. Admin Perspective & Password Setup Links
The administrator never sees or chooses a user's password. Switching to an SSO mode does not create passwords. Users who already have a password keep it and link their SSO identity at their next login (step 6 above).
Users who can't log in (no password, or a forgotten one) need a password setup link. The administrator sends it from Security → SSO migration with "Invia link" (POST /admin/auth/setup-links). The platform emails the user a one-time link to /set-password, where they choose their own password. After that they sign in with it and the normal SSO link flow starts. See Password setup by email.
- Delivery and expiry
- Links need SMTP to be configured (admin-ui → Settings → SMTP). Without it the endpoint generates a temporary password per user instead and returns
{delivery: "temp_password", temp_passwords: [...]}; admin-ui shows them once. See Without SMTP. - The response only reports the outcome:
{sent, failed, missing_email}, never the link or the token. - A link expires after
AION_SSO_TEMP_PASSWORD_TTL_DAYSdays (default 7). - Sending a new link invalidates the previous one.
- Users without an email address are listed in
missing_email. - A user who already linked the active provider gets
409 user_already_linked:<id>.
- Links need SMTP to be configured (admin-ui → Settings → SMTP). Without it the endpoint generates a temporary password per user instead and returns
- Pending count. A user counts as pending while they have a password or an active setup link. This keeps the migration, and the password form in chat-ui, open until they set the password and link. The
sso-migration/users?status=pendinglist reportshas_password,setup_link_pending,setup_link_expires_atandsetup_link_send_error. - Mode switches. When the switch is SSO → password or SSO → another SSO provider, users without a usable password receive the link automatically.
PUT /admin/auth/login-modereturnsdeliveryand the delivery summary insetup_links, or, without SMTP, the generatedtemp_passwords(shown once, to be changed at first sign-in).GET /admin/auth/login-mode/simulatereportsaffected_users,missing_email_count,smtp_configuredand the expecteddelivery, so admin-ui can warn before confirming.
- Temporary passwords. They are generated only when SMTP is missing, and expire after
AION_SSO_TEMP_PASSWORD_TTL_DAYS. An expired one is rejected withtemp_password_expired. Linking SSO removes them. - When
clear_password_on_linkis on (default), the local password is removed as soon as the user links SSO, admins included. The admin who activates SSO (afteradmin_validate) counts as migrated immediately and loses the password when the switch is applied. Emergency access goes through the recovery CLI (see Break-glass). - While the migration is active (
origin = migration, not completed) an IdP identity that is not yet linked can not create a new user: login fails withsso_not_linked. Only an explicit, authenticated link can attach an identity; there is never auto-linking by email. - The migration completes automatically when no user is pending; the password form then disappears from chat-ui.
- Reopening. Unlinking a user's identity for the active provider, or sending a setup link, after the migration has completed (or after a
first_setup) reopens it:migration_completed_atis cleared,originbecomesmigrationandmigration_started_atis kept, so users who are already linked stay migrated. The password form comes back in chat-ui until that user links again, and then the migration closes by itself. - Unlink = standard relink.
DELETE /admin/auth/users/{id}/sso-identities/{identity_id}on an identity of the active provider puts the user back into the normal flow: password →sso_link_required→ link the work account. A user without a password receives a setup link by email (setup_linksin the response), or a temporary password without SMTP (temp_passwords);setup_link_erroris set when neither could be issued: the unlink still happens and the link can be sent later from the migration list. A user who still has a password keeps it. Unlinking an identity of another provider changes nothing. While the migration is active, an SSO login whose email matches an existing account answerssso_not_linked(sign in with the password and link), whatever the new-account policy says. - Admin sign-in from admin-ui sends
client: "admin": the SSO/password restrictions of the chat client do not apply to users with theadminrole. - In SSO mode the admin-ui login page shows an "Accedi con Microsoft/Google" button (
/auth/sso/start?client=admin, callback purposeadmin_login, handoff to/admin/login/sso). Only users with theadminrole are accepted; new identities are never provisioned from this flow. The password form is shown only while at least one admin still has a local password (admin_password_logininGET /auth/status: migration still pending for an admin, or a password restored with the recovery CLI) or withAION_SSO_FORCE_PASSWORD=1. Once every admin has migrated, only the SSO button is shown. - Each switch to SSO with
origin = migrationstarts a new migration: only identities confirmed (linked or used to sign in) aftermigration_started_atcount, so identities left over from a previous migration must be confirmed again.
Break-glass
Set AION_SSO_FORCE_PASSWORD=1 and restart the backend to restore password login for everyone (SSO gates, link requirement and migration lock are ignored). Remove it once the IdP is fixed.
Since migrated admins no longer have a local password, set a temporary one with the recovery CLI (prints a generated password, to be changed at first login):
# local checkout
python -m src.auth.recover set-password admin
# Docker install (install.sh), from the install directory
docker compose -f docker-compose.ghcr.yml exec backend python -m src.auth.recover set-password admin
The admin login page then shows the password form again (an admin has a password). --password <value> sets a specific password instead of a generated one.
3. New accounts in SSO mode
With an SSO mode active, accounts are created only by single sign-on, at each person's first login (auto-provisioning, after the migration has completed or with origin = first_setup):
POST /admin/usersreturns409 {"code": "sso_active_user_creation_disabled"}: no new password accounts. The admin-ui hides the "Add user" button and points to the new-account policy instead.- The default-admin bootstrap (
AION_SETUP_ADMIN_BOOTSTRAP, backend startup andsetup_aion_env.py) and the setup wizard's chat user are skipped. Emergency access still goes through the recovery CLI (see Break-glass).
New-account policy
Since every account of the company tenant/domain could sign in, the administrator decides who may get a new account (admin-ui → Users → Sign-in → New accounts). Stored per tenant in auth_settings.sso_signup_policy / sso_signup_allowlist:
| Policy | Effect on a first SSO login | Error code |
|---|---|---|
open (default) | Every identity accepted by the provider (and its allowed_domains) gets an account | — |
allowlist | Only listed full emails (mario.rossi@azienda.it) or whole domains (@azienda.it, exact match, no subdomains) | sso_signup_not_allowed |
closed | No new accounts | sso_signup_closed |
- The policy applies only to new accounts: a user whose identity is already linked keeps signing in. To revoke access, delete the user (this also removes their SSO identities, and closes the migration if they were the last pending user).
- It is checked before the migration gate: while a migration is active an unknown identity that the policy rejects gets
sso_signup_closed/sso_signup_not_allowed; one the policy accepts getssso_not_linked(it must link from an existing account first). The admin-ui SSO login never creates accounts and always answerssso_not_linked. - It can be configured while still in password mode (e.g. before switching), and is enforced only in SSO mode. The list is kept when switching to
closed, so a gradual rollout can be paused and resumed. - Entries are case-insensitive and deduplicated; at most 2000.
- chat-ui shows a translated message for both error codes (
login.sso_error.*).
4. The handoff State
Because the SSO callback flow happens in a separate browser context (or requires redirects), AION uses a handoff mechanism.
When the user completes the SSO login or link flow, they are redirected to /login/sso#code=.... The frontend reads the short-lived code (valid for 60 seconds) and POSTs it to /v1/auth/sso/exchange.
This endpoints exchanges the code for a full access_token and user_id, preventing tokens from leaking in the URL history or referer headers.
5. API Endpoints for Migration
The administrator UI interacts with the following endpoints:
GET /v1/admin/auth/login-mode: Returns the current mode (password,microsoft,google), the migration status (sso_migration_active), and counts of pending/migrated users.PUT /v1/admin/auth/login-mode: Changes the mode. Requires a provider validated in the last 30 minutes and an admin already linked to it. Re-selecting the current mode does not restart the migration.GET /v1/admin/auth/sso-migration/users?status=pending|migrated|exempt|no_access: User lists per migration state.POST /v1/admin/auth/sso-migration/users/{id}/exempt: Exempt/reinstate a user.GET /v1/admin/auth/login-mode/simulate?mode=...:{affected_users, missing_email_count, smtp_configured, delivery}: who would receive a setup link (or a temporary password) on that switch.POST /v1/admin/auth/setup-links{user_ids: [...]}: Email a password setup link to the selected users. Returns{delivery: "email", setup_links: {sent, failed, missing_email}}, or without SMTP{delivery: "temp_password", temp_passwords: [...]};409 user_already_linked:<id>.DELETE /v1/admin/auth/users/{id}/sso-identities/{identity_id}: Unlink an identity. For the active provider it reopens the migration and, if the user has no password, emails a setup link (setup_links/setup_link_errorin the response).GET /v1/admin/auth/signup-policy:{policy, allowlist, applies, max_entries}(appliesis true when an SSO mode is active).PUT /v1/admin/auth/signup-policy{policy: "open"|"allowlist"|"closed", allowlist: [...]}: Saves the new-account policy.400withinvalid_signup_policy,invalid_allowlist_entry(+entry) orallowlist_too_long(+max).GET /v1/admin/sso/providers/redirect-uri: Redirect URI to register at the IdP (derived from the backend public URL).- The active provider cannot be disabled or deleted directly (
use_login_mode,provider_in_use); changing its client id/secret requires re-validation but keeps it active.
5. Security Measures
- Unique Constraints: The database enforces a unique constraint
(tenant_id, user_id, provider)on theuser_sso_identitiestable to prevent linking issues. - CSRF Protection: The
/auth/sso/link/startendpoint strictly checks the authorized user context before generating the OAuthstatetoken, preventing attackers from linking their SSO to a victim's account. - Short-Lived Codes: Handoff codes are single-use (consumed atomically, a replay returns
code_already_used) and expire after 60 seconds.
6. Interaction with Two-Factor Authentication
The optional TOTP 2FA policy applies only while login_mode = password and cannot be enabled while an SSO mode is active. Switching to SSO does not remove existing TOTP enrollments: a user who already configured 2FA keeps it, and the code is still required at every password login until they link their SSO account. The TOTP secret is removed only when the user links (or signs in via SSO); nobody is asked to enroll during a migration.