Microsoft Entra ID sign-in

With Microsoft Entra ID sign-in, people click Sign in with Microsoft on the portal, sign in at Microsoft with their usual work account and any multi-factor checks your organisation requires, and arrive in the portal as their own Active Directory account. This page explains what you need and walks through the setup in Microsoft Entra and in the console.

What it does New in 2.1

• The portal sign-in page shows a Sign in with Microsoft button, or sends people straight to Microsoft if you choose.
• Microsoft confirms who the person is. Their Entra ID account policies, including conditional access and multi-factor authentication, apply at that point.
• DartRelay asks Microsoft which on-premises Active Directory account the person is synchronised from, checks that account in your domain, and signs them in as that domain account.
• From then on everything works exactly as for a password sign-in: their Active Directory groups decide what they see, and seats, addresses and auto-launch rules all apply as usual.

Microsoft sign-in applies to the portal. Administrators sign in to the console with their username and password as before.

Before you begin

• Hybrid accounts. Your users must be synchronised from on-premises Active Directory to Entra ID (for example with Microsoft Entra Connect Sync). A cloud-only Entra account has no Windows account to map to, and is refused with a message saying it is not linked to a Windows account.
• Domain Users switched on in Authentication → Authentication Methods.
• The users' domain on the Directories list. The on-premises domain the accounts come from must be on Authentication → Directories, enabled, and offered on the address people use. See Active Directory and multiple domains.
• A portal address on HTTPS that people's browsers can reach. Microsoft sends them back to this address after sign-in. See Endpoints and certificates.
• Rights in Entra. You need an Entra account that can register applications and grant admin consent.

Where it lives in the console

Microsoft Entra ID sign-in is set up as a pass on Authentication → Relay Pass. That page lists every way people can sign in with an outside provider, in the order their buttons appear on the sign-in page, with ▲ and ▼ to reorder them. Each Microsoft Entra ID pass has its own detail page with these cards:

1. How to register DartRelay with Microsoft, including the redirect address and a Copy button.
2. Connect: the pass's name, the tenant ID, the client ID and the client secret.
3. Match to a Windows account: for Entra, this is always the synchronised on-premises account.
4. Sign-in page: the button text, whether the button is on, and whether to send people straight to Microsoft.
5. Windows logon: whether to log people on to hosts with a certificate instead of a password. This is covered on Relay Pass.

You can add more than one Microsoft Entra ID pass, for example one for each of two Entra tenants. Each gets its own button.

Step 1: register DartRelay in Microsoft Entra

First add a pass in DartRelay so you can copy its redirect address, then register the application at Microsoft.

1. Add the pass. In the console, go to Authentication → Relay Pass and add a Microsoft Entra ID pass. Its detail page opens.
2. Copy the redirect address. The registration card shows the redirect address for the address you are using the console on, ending in /portal/signin-entra (further Entra passes end in /portal/signin-entra/ followed by the pass's short name). Click Copy. If people reach the portal on a different address, use that address instead; it must match exactly.
3. Open App registrations. In the Microsoft Entra admin centre, go to Identity → Applications → App registrations and choose New registration.
4. Name it and choose who may use it. Enter a name such as DartRelay. Under supported account types choose Accounts in this organizational directory only (single tenant).
5. Add the redirect address. Under Redirect URI, choose the platform Web and paste the address you copied. Click Register.
6. Note the two IDs. On the application's Overview page, copy the Application (client) ID and the Directory (tenant) ID.
7. Create a client secret. Go to Certificates & secrets → Client secrets → New client secret, give it a description and an expiry, and click Add. Copy the secret's Value straight away; Microsoft shows it only once.
8. Check the permission and grant consent. Go to API permissions. The Microsoft Graph delegated permission User.Read is normally present already; add it if it is not. Click Grant admin consent for your organisation so users are not asked to consent one by one.

Step 2: connect the pass

1. Return to the pass's detail page under Authentication → Relay Pass.
2. Fill in the Connect card. Enter a name (people will not see it unless you leave the button text empty), the Directory (tenant) ID, the Application (client) ID and the client secret value.
3. Fill in the Sign-in page card. Set the button text if you want something other than the default, make sure the button is enabled, and decide whether to send people straight to Microsoft (see below).
4. Save.
5. Click Test sign-in on the Test card. It asks Microsoft for a token with the saved tenant, client ID and secret, which proves the three belong together. Fix any error it reports before going on.
6. Try it. Open the portal sign-in page in a private browser window, click the Microsoft button and sign in as a synchronised user. You should land on My Resources with that person's resources.

Sending people straight to Microsoft

With this on, people who open the portal are taken to Microsoft without seeing DartRelay's sign-in page. Staff who need the ordinary username and password form can add ?signin=1 to the sign-in address. The form is also shown when there is an error to display, and for a few minutes after somebody signs out, so signing out does not silently sign them straight back in.

The button in your theme

Shipped themes show the Microsoft button under the Sign in button of the sign-in block, at the same width. In your own themes the sign-in block has a setting to show or hide it and to change its label. See Building the sign-in and home pages.

Choosing which buttons appear on each address New in 2.1

If you serve several organisations on different addresses, each can show a different set of sign-in buttons. Go to Appearance → Tenancy & Branding, open the address, choose Access, and use Sign-in buttons on this address.

An address can narrow the list, never widen it: a pass whose button is off on the Relay Pass page never appears. This is enforced, not just hidden: a bookmark to a pass the address does not offer returns to the sign-in page with "Microsoft sign-in is not available".

How a Microsoft account is matched to a Windows account

After Microsoft confirms the person, DartRelay reads the on-premises account name, domain and security identifier that Entra Connect synchronised for them, and then:

1. finds that domain on the Directories list among the domains offered on this address;
2. looks the account up in your Active Directory and checks that it exists, is enabled, and has the same name and security identifier;
3. applies the address's sign-in rules, as for any sign-in;
4. signs the person in as DOMAIN\name.

Checking Active Directory, not only what Entra says, means an account that has been disabled on-premises but not yet synchronised is still refused.

Launching resources after a Microsoft sign-in

DartRelay never sees the person's password when they sign in with Microsoft. That matters for how they are logged on to hosts:

• Resources with Fixed Credentials work exactly as usual.
• Resources with Pass-Through need the person's Windows logon. By default the portal asks for their Windows password once, in a small prompt, the first time they launch such a resource; later launches in the same sign-in do not ask again.
• With Relay Pass certificate logon switched on for the pass, there is no prompt at all: DartRelay logs the person on with a short-lived certificate. See Relay Pass.

Signing out

Signing out of the portal ends the DartRelay session. It does not sign the person out of Microsoft, in the same way as most web applications that use Microsoft sign-in. On a shared computer, people should also sign out of their Microsoft account or close the browser.

If something goes wrong

Every Microsoft sign-in, successful or refused, is written to System → Audit Log with the reason.

Related pages