Entra ID
With Microsoft Entra ID, people sign in with the Sign in with Microsoft button. Delegaris uses OpenID Connect: the standard authorization code flow with PKCE. The ID token is checked against Microsoft's published signing keys, and the person's groups and app roles come from the token.
1. Register the app in Entra
-
In the Entra admin centre, go to App registrations > New registration.
-
Give it a name, for example
Delegaris, and choose Single tenant. -
Under Redirect URI, choose type Web and enter:
https://<your host>/auth/oidc/callbackThe address is your
PUBLIC_URLfollowed by/auth/oidc/callback. Settings > Sign-in shows the exact address to use, in the Microsoft Entra ID section. -
Under Certificates & secrets, choose New client secret and copy its value.
-
Under Token configuration, choose Add groups claim:
- With Entra ID P1 or above, choose Groups assigned to the application, then assign the groups that matter under Enterprise applications > Users and groups.
- Otherwise choose Security groups.
-
From the app's Overview, note the Directory (tenant) ID and the Application (client) ID.
PUBLIC_URL must be the address people actually use, with https://. The redirect URI is built from it, so a wrong PUBLIC_URL sends Microsoft's reply to the wrong place. See Behind a reverse proxy.
2. Give Delegaris the details
Under Settings > Sign-in
Sign in as the local administrator, open Settings > Sign-in, and fill in the Microsoft Entra ID section:
| Field | What to enter |
|---|---|
| Tenant ID | The Directory (tenant) ID |
| Application (client) ID | The Application (client) ID |
| Client secret | The secret's value. Stored in the database and never shown again. Leave empty to keep the saved one |
| Button label | The text on the sign-in button. Default Sign in with Microsoft |
| Scopes | Default openid profile email. Add User.Read if people are in more than 200 groups (see below) |
Then:
- Under Ways in, tick Microsoft Entra ID (or leave every box unticked to use whatever is filled in).
- Press Test the identity provider. It fetches Entra's metadata and signing keys and says how many keys it found. Whether the client ID and secret are right is only known at the first real sign-in.
- Name your administrators under Administrators, by group object ID (see below).
- Press Save sign-in settings. It applies at once, on every copy of the service.
In .env
OIDC_TENANT_ID=11111111-2222-3333-4444-555555555555
OIDC_CLIENT_ID=66666666-7777-8888-9999-000000000000
OIDC_CLIENT_SECRET=paste-the-secret-value-here
ADMIN_GROUPS=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
| Setting | Default | Purpose |
|---|---|---|
OIDC_TENANT_ID | none | Your tenant ID |
OIDC_CLIENT_ID, OIDC_CLIENT_SECRET | none | The app registration's ID and secret |
OIDC_SCOPES | openid profile email | What is asked of Microsoft |
OIDC_BUTTON_LABEL | Sign in with Microsoft | The button's text |
OIDC_AUTO_SIGN_IN | false | Skip the sign-in page (see below) |
OIDC_GROUPS_CLAIM | groups | Which token claim holds the groups |
OIDC_USERNAME_CLAIM | preferred_username | Which token claim is the sign-in name |
OIDC_ISSUER | none | Another OpenID Connect provider, instead of a tenant ID |
What you save under Settings > Sign-in overrides .env.
Delegaris works with your own tenant only. The multi-tenant common and organizations endpoints are refused.
Groups and app roles
Entra sends groups as object IDs, not names. Use the object ID wherever Delegaris asks for a group: Administrator groups, access rules, approvers and roles. The field hints say so ("Entra group object IDs").
App roles work too. Whatever is in the token's roles claim can be used like a group name. If you define app roles on the registration and assign people to them, you can write rules against the role's value instead of an object ID.
People in many groups
Entra leaves the groups out of the token when someone is in too many (more than 200) and you chose Security groups. Delegaris then asks Microsoft Graph for the person's groups instead, which needs User.Read in the scopes. Add it to Scopes (or OIDC_SCOPES). Choosing Groups assigned to the application avoids the problem, because only the assigned groups are sent.
Finding groups and people
With Entra ID as the only directory, the Find… buttons cannot search Entra itself. They list the people who have signed in to Delegaris so far, and the groups those people belong to, with groups shown as their object IDs.
Sending people straight to Microsoft
When Entra ID is the only way in, tick Skip the sign-in page and go straight to Microsoft (when Entra is the only way in) (OIDC_AUTO_SIGN_IN=true). Opening Delegaris then goes straight to Microsoft's sign-in, without showing Delegaris's own page first.
- The local administrator does not count as another way in for this. It is still there, at
https://<your host>/?manual=1, which always shows the sign-in page. - If Microsoft sign-in fails, the sign-in page is shown with the reason, rather than trying again.
Two-step sign-in
Entra ID does its own multi-factor authentication through conditional access, so Delegaris never asks Entra users for a second code. Set MFA up in Entra. See Two-step sign-in.
Email addresses for Slack
The person's email address, used to find them in Slack, comes from the token's email claim, or failing that the sign-in name when it looks like an email address.
Running Active Directory and Entra ID together
Both can be on at once, for example during a move from one to the other. The sign-in page shows the Microsoft button and the password form, and a group from either works in rules. Remember that the same team has a name in AD and an object ID in Entra: a rule for both needs both.
When sign-in fails
The sign-in page shows one of these after a failed Microsoft sign-in:
| Message | Usual cause |
|---|---|
| Microsoft sign-in was cancelled or refused. | The person cancelled, or Entra refused them (for example, not assigned to the app) |
| That sign-in attempt timed out. Start again. | More than 10 minutes passed between leaving and coming back |
| Microsoft sign-in did not complete. | A wrong client secret, a redirect URI mismatch, or a token that failed its checks |
| Microsoft sign-in cannot be reached right now. | Delegaris could not reach Microsoft to start the sign-in |
The detailed reason is in the service log and in the activity log.
Another OpenID Connect provider
Open Another OpenID Connect provider, or a different groups claim to use, for example, AD FS:
- Issuer address: the provider's issuer, starting
https://, for examplehttps://adfs.corp.example/adfs. Use it instead of a tenant ID. - Groups claim: the claim that carries group names, if it is not
groups.