Single Sign-On
Setting Up SSOEnterprise
Creating an SSO connection: the identity provider, email domain, domain verification, connection details and access settings.
An SSO connection is set up on the Single Sign-On (SSO) page, opened from Authentication (SSO) in Account Settings. The account has one connection. Setting it up takes an app in the identity provider, a DNS record that proves the company owns its email domain, and the connection details from that app.
Before you start
Setting up SSO needs the following:
| Item | Detail |
|---|---|
| An OpenID Connect app in the identity provider | A web app with the sign-in redirect URI https://dashboard.multi-router.ai/sso/callback, or the dashboard address of a self-hosted installation, whose ID token includes the email claim. See the page for each identity provider. |
| Access to DNS for the email domain | To add a TXT record that proves ownership. |
| The issuer URL, client ID and client secret | From the identity provider app. |
Steps
- Open Settings, then Authentication (SSO), and turn on Enable SSO.
- Choose the Identity provider and enter the Email domain, such as
example.com. - Enter the connection details: Issuer / Discovery URL, Client ID and Client secret.
- Choose New-user access, the Default role for new users, and the organization under Provision users into.
- Select Test connection, and then Set up SSO to save.
- Add the DNS TXT record shown under Verify domain ownership, then select Verify domain.
Sign-in through SSO starts once the domain is verified and the connection is on. Until then, people sign in as before.
Fields
The connection has these fields:
| Field | Description |
|---|---|
| Identity provider | The provider, named on the sign-in step as Your team uses Okta. |
| Email domain | The domain whose people sign in through SSO, such as example.com. A domain belongs to one Multi-Router account. |
| Also allow subdomain emails | Includes subdomains such as eng.example.com. Turn it on only when the company controls every subdomain, since verification covers the main domain. |
| Issuer / Discovery URL | The identity provider's issuer, such as https://example.okta.com/oauth2/default. Multi-Router reads the provider's endpoints and signing keys from it. |
| Client ID | The client ID of the Multi-Router app in the identity provider. |
| Client secret | The client secret of that app. It is stored encrypted, and the page shows that one is configured without showing it. |
| New-user access | Auto-provision or Invite-only. See New-user access below. |
| Default role for new users | Member or Admin, the account role for people added by Auto-provision. |
| Provision users into | The organization people are added to and land in when they sign in. The account itself is listed first. |
| Require SSO for everyone | Turns off password and social sign-in for the domain. See Requiring SSO. |
The issuer must be a public https:// address, and it must match the issuer value in the provider's discovery document exactly. Multi-Router requests the openid, email and profile scopes.
Domain verification
Domain verification proves that the company owns the email domain, so that only the domain's owner can route its people through an identity provider. After the first save, the page shows a TXT record to add at the domain's DNS host:
| Type | Name | Value |
|---|---|---|
| TXT | _multi-router-verify.example.com | mr-verify-… |
Many DNS hosts add the domain to the name on their own, so the Name field takes _multi-router-verify alone. Verify domain checks for the record and shows Domain ownership verified when it is found. DNS changes can take a few minutes to appear; when the record is not found yet, wait and select Verify domain again. Changing the email domain creates a new record, and SSO sign-in pauses until it is verified.
Testing the connection
Test connection checks the Issuer / Discovery URL before or after saving. It reports two checks, Discovery document and Signing keys (JWKS), and shows Connection looks good when both pass; an issuer that is not a public https address shows the Issuer URL check instead. The client ID, client secret and redirect URI are checked during a real sign-in, so the last step of setup is signing in with SSO from a private browser window.
New-user access
New-user access decides what happens when someone signs in through SSO for the first time:
| Setting | Behavior |
|---|---|
| Auto-provision | Anyone the identity provider signs in from the domain is created and added to the organization under Provision users into, with the Default role for new users. |
| Invite-only | Only people already invited to the organization can sign in through SSO; their invitation is accepted on their first sign-in. |
The default role is the account role new people receive: Member, or Admin, which makes them admins of the whole account, every organization and its SSO settings included, whichever organization they are provisioned into. Auto-provision with Member suits most companies, with the identity provider's app assignments deciding who can sign in. See Roles and Access.
Changing and removing the connection
After saving, the connection's fields are locked; Edit unlocks them and shows Remove connection, and Save changes or Cancel finishes. The toggle in the card header turns the connection on and off at once. Remove connection deletes the connection and its domain verification, and people of the domain then sign in with a password or social sign-in; people created through SSO set a password first. While user provisioning with SCIM is connected, the domain, new-user access and the connection itself stay fixed until provisioning is disconnected.