OpenID Connect sign-in
OpenID Connect sign-in adds a button such as Sign in with Okta or Sign in with Google to the portal. People sign in at the provider, with its own multi-factor checks, and DartRelay matches them to exactly one Active Directory account. This page explains how the matching works and how to set up a provider.
What it does New in 2.1
- Each provider you add gets its own button on the portal sign-in page.
- The person signs in at the provider. Its policies and multi-factor checks apply there.
- The provider tells DartRelay something about the person, such as their email address. DartRelay looks for exactly one enabled Active Directory account with that value and signs the person in as that account.
- From then on it is an ordinary domain sign-in: Active Directory groups decide what they see, and seats, addresses and auto-launch rules apply as usual.
Microsoft Entra ID has its own pass kind, because Entra can name the exact on-premises account a person is synchronised from. Use Microsoft Entra ID sign-in for Microsoft accounts, and this page for everything else.
Before you begin
- Domain Users switched on in Authentication → Authentication Methods, and the users' domains on Authentication → Directories. Only domains offered on the address the person uses are searched. See Active Directory and multiple domains.
- Every person who will use the provider needs an Active Directory account that holds the same value the provider sends, for example the same email address in the account's
mailattribute. - A portal address on HTTPS that browsers can reach. The provider sends people back to it.
- An administrator account at the provider that can create an application (sometimes called a client or an app integration).
How a provider account is matched to a Windows account
This is the part to get right. On each pass you choose two things: which piece of information from the provider to use (the claim), and which Active Directory attribute it must equal.
| Claim from the provider | Active Directory attribute |
|---|---|
email, preferred_username, upn, sub, or another claim you name | userPrincipalName, mail, sAMAccountName, employeeID, or another attribute you name |
DartRelay then applies these rules, and refuses the sign-in if any of them fails:
- Exactly one account. The value must match exactly one enabled account across the domains this address offers. No match, or two accounts with the same value, is refused.
- Verified email. When the claim is
emailand the provider says the address is not verified, the sign-in is refused. - Allowed domains. For email-style values, the part after the
@must be on the pass's Allowed domains list. For Google, the person's Google Workspace domain must be on the list too, and the list is required. - Protected administrator accounts. By default, accounts that Active Directory marks as protected (members of groups such as Domain Admins) are refused, so a provider account can never become a domain administrator. This is the Refuse protected administrator accounts setting.
- The address's own sign-in rules apply afterwards, as for any sign-in.
When the attribute is sAMAccountName, any DOMAIN\ in front of the value or @suffix after it is removed before matching.
Whoever controls the claim at the provider controls which Windows account a person becomes. Match on a value that only your organisation can set, such as a verified company email, and keep Allowed domains as narrow as possible. Make sure users cannot edit the Active Directory attribute you match on.
Ready-made starting points
On Authentication → Relay Pass you can add an Okta pass, a Google pass, or an other OpenID Connect pass. Each starts with sensible values that you can change.
| Kind | Issuer | Starting match | Notes |
|---|---|---|---|
| Okta | https://your-org.okta.com/oauth2/default | preferred_username → userPrincipalName | Replace your-org with your Okta organisation name. |
https://accounts.google.com | email → mail | Allowed domains is required. With one domain listed, Google's account chooser is limited to that domain. | |
| Other OpenID Connect | Your provider's issuer address | email → userPrincipalName | Any provider that publishes standard OpenID Connect discovery information. |
Set up a provider
- Add the pass. In the console, go to Authentication → Relay Pass and add an Okta, Google or other OpenID Connect pass. Its detail page opens.
- Copy the redirect address. The first card explains how to register DartRelay with the provider and shows the redirect address, ending in
/portal/signin-oidc/followed by the pass's short name (for example/portal/signin-oidc/google). Click Copy. - Create the application at the provider. Create a web application that uses the authorisation code flow with a client secret, and add the redirect address you copied as an allowed sign-in redirect. For Google, this is an OAuth client of type Web application in Google Cloud, with the address under Authorised redirect URIs. Note the client ID and client secret the provider gives you.
- Fill in the Connect card. Enter a name, the issuer address, the client ID and the client secret. Leave the scopes as suggested unless your provider needs others. The issuer must be exactly the value the provider publishes.
- Fill in Match to a Windows account. Choose the claim and the Active Directory attribute, list your Allowed domains, and leave Refuse protected administrator accounts ticked.
- Fill in the Sign-in page card. Set the button text and make sure the button is enabled.
- Save, then click Test sign-in. It reads the provider's published information and signing keys from the issuer address. Fix any error before going on.
- Try it. In a private browser window, open the portal sign-in page, click the new button and sign in as a person whose Active Directory account holds the matching value.
| Field | What it does | Default |
|---|---|---|
| Name / short name | Identify the pass. The short name forms the end of the redirect address. | From the kind |
| Issuer | The provider's issuer address. DartRelay reads its discovery information from this address. | From the kind |
| Client ID / client secret | From the application you created at the provider. The secret is stored encrypted and never shown again. | — |
| Scopes | What DartRelay asks the provider for. | Suggested by the kind |
| Claim / attribute | What is matched to what. See How a provider account is matched. | From the kind |
| Allowed domains | Email domains that may sign in through this pass. | Empty (required for Google) |
| Refuse protected administrator accounts | Refuses accounts Active Directory marks as protected administrators. | On |
| Button text / enabled | The words on the button, and whether it appears. | — |
Several passes of each kind are allowed. Their buttons appear in the order shown on Authentication → Relay Pass; use ▲ and ▼ to change it.
Example: Google Workspace for a school
A school uses Google Workspace on school.example, and every pupil and teacher also has an Active Directory account whose mail attribute holds their school address.
- The administrator adds a Google pass, keeps the match
email→mail, and sets Allowed domains toschool.example. - A teacher clicks Sign in with Google, picks their school account, and arrives in the portal as their domain account with their usual resources.
- A personal Gmail account is refused, because its domain is not on the list.
Which buttons appear on each address
Each address under Appearance → Tenancy & Branding can show every enabled pass, or only some of them, and can send people straight to one provider. Use Sign-in buttons on this address on the address's Access page; the settings are described on Microsoft Entra ID sign-in. A pass the address does not offer is refused there even from a bookmark. With "send people straight to" set, staff can still reach the password form by adding ?signin=1 to the sign-in address.
Launching resources
As with Microsoft sign-in, DartRelay never sees a password. Resources with Fixed Credentials work as usual. For Pass-Through resources the portal asks for the person's Windows password once per sign-in, unless certificate logon is switched on for the pass on its Windows logon card; then there is no prompt. See Relay Pass.
If something goes wrong
| Problem | Cause and fix |
|---|---|
| Test sign-in fails. | The issuer address is wrong or unreachable from the DartRelay server. It must match the provider's published issuer exactly, including any path such as /oauth2/default. |
| The provider reports a redirect address mismatch. | Register the exact redirect address shown on the pass, for the address people actually use. |
| Refused: no matching account. | No enabled account in the domains offered on this address holds that value in the chosen attribute. Check the attribute in Active Directory and the claim the provider sends. |
| Refused: more than one account. | Two accounts hold the same value. Make the value unique, or match on a different attribute. |
| Refused: domain not allowed. | Add the person's email domain to Allowed domains, if they should be able to sign in. |
| An IT administrator is refused. | Their account is a protected administrator account. This is deliberate; they can sign in with their password instead. |
| The button does not appear. | The pass is disabled, Domain Users is off, the address does not offer the pass, or the theme's sign-in block hides provider buttons. |
Every sign-in through a provider, successful or refused, is written to System → Audit Log with the reason.
Related pages
Microsoft Entra ID
Sign in with Microsoft work accounts.
Relay Pass
Certificate logon to hosts, with no password prompt.
Active Directory
The domains a provider account can be matched in.
Logs and audit
Find out why a sign-in was refused.