Skip to main content

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​

  1. In the Entra admin centre, go to App registrations > New registration.

  2. Give it a name, for example Delegaris, and choose Single tenant.

  3. Under Redirect URI, choose type Web and enter:

    https://<your host>/auth/oidc/callback

    The address is your PUBLIC_URL followed by /auth/oidc/callback. Settings > Sign-in shows the exact address to use, in the Microsoft Entra ID section.

  4. Under Certificates & secrets, choose New client secret and copy its value.

  5. 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.
  6. From the app's Overview, note the Directory (tenant) ID and the Application (client) ID.

warning

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:

FieldWhat to enter
Tenant IDThe Directory (tenant) ID
Application (client) IDThe Application (client) ID
Client secretThe secret's value. Stored in the database and never shown again. Leave empty to keep the saved one
Button labelThe text on the sign-in button. Default Sign in with Microsoft
ScopesDefault openid profile email. Add User.Read if people are in more than 200 groups (see below)

Then:

  1. Under Ways in, tick Microsoft Entra ID (or leave every box unticked to use whatever is filled in).
  2. 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.
  3. Name your administrators under Administrators, by group object ID (see below).
  4. 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
SettingDefaultPurpose
OIDC_TENANT_IDnoneYour tenant ID
OIDC_CLIENT_ID, OIDC_CLIENT_SECRETnoneThe app registration's ID and secret
OIDC_SCOPESopenid profile emailWhat is asked of Microsoft
OIDC_BUTTON_LABELSign in with MicrosoftThe button's text
OIDC_AUTO_SIGN_INfalseSkip the sign-in page (see below)
OIDC_GROUPS_CLAIMgroupsWhich token claim holds the groups
OIDC_USERNAME_CLAIMpreferred_usernameWhich token claim is the sign-in name
OIDC_ISSUERnoneAnother OpenID Connect provider, instead of a tenant ID

What you save under Settings > Sign-in overrides .env.

note

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:

MessageUsual 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 example https://adfs.corp.example/adfs. Use it instead of a tenant ID.
  • Groups claim: the claim that carries group names, if it is not groups.

Next steps​