What is this about?
With single sign-on, users sign in to unixpass with their Microsoft 365 account — no separate password. unixpass uses OpenID Connect against Microsoft Entra ID. It uses the same Entra app registration (“UXP”) that also powers custom e-mail sending.
Who configures what?
Own unixpass installation (OnPremise / Master)
You configure everything yourself in UXP-Admin (part 2).
Tenant on the R3levance cloud
You complete part 1 (Microsoft Entra) and securely hand the values to R3levance support — they enable SSO for your tenant.
Prerequisites
- Microsoft 365 tenant with access to the Entra admin center (role: Global Administrator or Application Administrator)
- An app registration for unixpass (“UXP”) — can be shared with mail sending
- The redirect URIs of your unixpass installation: for cloud tenants part of the individual access data provided by R3levance, for self-hosted systems derived from your system URL
- Users sign in with e-mail addresses of your domain (e.g.
first.last@your-domain.com)
Part 1 — Microsoft Entra: configure the app
Open the app registration
In the Entra admin center, open Entra ID → App registrations and select the UXP app. If none exists yet: New registration → name “UXP”, account type “Accounts in this organizational directory only”.
Add the redirect URIs
Open Entra ID → App registrations → UXP → Authentication (possibly “Authentication (Preview)”). On the Redirect URI configuration tab, click Add redirect URI and choose platform type Web (in the old experience: Add a platform → Web). Enter the return URLs of your unixpass installation there — the configured URIs are later visible on the app Overview under “Redirect URIs”. Important: each language in use needs its own URI including the language parameter — offering German and English means two URIs:
https://<UNIXPASS-URL>/de/extranet/openid | German interface |
https://<UNIXPASS-URL>/en/extranet/openid | English interface |
/<language>/extranet/openid is fixed. URIs must match exactly — otherwise login fails with AADSTS50011.
Verify the delegated permissions
For sign-in, the app needs the delegated Microsoft Graph permissions email, openid, profile and User.Read (API permissions → Add a permission → Microsoft Graph → Delegated permissions). Then grant admin consent so users don’t see a consent prompt on first login. The Mail.Send permission (type “Application”) in the figure belongs to mail sending, not to SSO.
Create a client secret and note its expiry date
Under Certificates & secrets → New client secret, create a secret (unless one already exists for mail sending — the same secret can serve both). Copy the value immediately and also note the expiry date — it is stored in UXP-Admin in part 2 so unixpass reminds you in time to renew.
Assign users — preferably via groups
Go to Entra ID → Enterprise applications → UXP → Users and groups → Add user/group. Individual users can be assigned directly — for larger setups, controlling access via security groups is the better choice: new employees then get unixpass access simply through group membership (e.g. a “UXP users” group) without touching the app assignment.
- To ensure only assigned users can sign in: Enterprise applications → UXP → Properties → “Assignment required?” = Yes.
- Assigning security groups to applications requires Microsoft Entra ID P1 (included in many M365 Business/Enterprise plans).
- Nested groups are not resolved for app assignment — only direct members get access.
Optional: upload an app logo
Under Enterprise applications → UXP → Properties (or app registration → Branding & properties) you can upload a logo so the app is recognizable in the Microsoft “My Apps” portal and in consent dialogs. Recommended: square PNG, 215×215 px, max. 256 KB. Official unixpass assets for download:
You now have these values
| Application (client) ID | CLIENT_APP_ID — GUID from the app overview |
|---|---|
| Client secret | CLIENT_APP_SECRET — value from step 4 |
| Directory (tenant) ID | TENANT_ID — GUID from the app overview |
| Secret expiry date | from step 4 — stored in UXP-Admin as a reminder |
Part 2 — unixpass: enable SSO in UXP-Admin
In UXP-Admin, open the tenant settings and enable the Single Sign-On section:
The fields in detail
| Domain | the users’ mail domain. Sign-ins with addresses of this domain are routed to Microsoft via SSO. |
| Endpoint | OpenID Connect discovery URL of the tenant: https://login.microsoftonline.com/TENANT_ID/v2.0/.well-known/openid-configuration — replace TENANT_ID with the directory ID. |
| Client ID / Client Secret | application ID and secret of the UXP app from part 1. |
| SSO Certificate Expiration Date | expiry date of the client secret. unixpass sends a reminder 14 days before expiry — create a new secret in time and update it here and in Entra. |
Testing & troubleshooting
Sign in to unixpass in a private browser window with an assigned user. Typical issues:
Error AADSTS50011 (redirect URI mismatch) | Redirect URI missing or not matching exactly — forgot the language parameter (/de, /en)? |
Error AADSTS700016 (application not found) | Wrong client ID, or the endpoint points to the wrong tenant. |
Error AADSTS7000215 (invalid client secret) | Secret copied incorrectly or expired — create a new secret, update UXP-Admin and the reminder date. |
Error AADSTS50105 (user not assigned) | User is not assigned to the app — check group membership (nested groups don’t count). |
| Users see a consent prompt | Admin consent for the delegated permissions is missing (part 1, step 3). |
| Login form instead of SSO redirect | Domain in UXP-Admin doesn’t match the user’s mail address, or SSO is not enabled. |