Identity providers
An identity provider lets a company's people sign in with the company's single sign-on. Merge Pilot supports OpenID Connect (Keycloak, Microsoft Entra ID, Okta and others) and SAML 2.0 (ADFS and others). The directories behind the provider (one or several LDAPs, Active Directory) stay the provider's business: Merge Pilot sees only the provider.
- Where: Company → Sign-in → Identity providers.
- Who: company admins and platform admins, in a signed-in session.
- A company can have several providers. Each has its own Enabled switch, and each provider's type must also be allowed on the platform (Settings → Sign-in, see Platform settings). A provider whose type is off there shows Turned off on the platform.
- Each enabled provider appears on the sign-in page as Continue with its name, for this company.
Adding a provider
Select + OpenID Connect or + SAML, fill in the dialog, and select Save provider. The list then offers, for each provider:
- Test: Merge Pilot reads the provider's discovery document (OpenID Connect) or metadata (SAML) and says whether the provider answered;
- Edit;
- Delete: people who sign in only through the provider lose their way in. Their accounts and other sign-in methods stay; the provider is unlinked from every account. Accounts whose role the provider gave keep that role, and an admin can change it from then on.
Settings for every provider
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Name on the sign-in page | The button text on the sign-in page; also the suffix of new user names that are already taken | — | Required, at most 100 characters, unique within the company | Company admin, platform admin | name |
| Enabled | Whether people may sign in with this provider | On | On or off | Company admin, platform admin | enabled |
| Only these groups | Only members of one of these groups sign in. Empty lets in everyone the provider signs in. Checked at every sign-in and when the session renews | Empty | Group names separated by commas or new lines; at most 50, each 1 to 256 characters. Compared without regard to case | Company admin, platform admin | allowed_groups |
| New people | Who gets an account at their first sign-in | Create an account at the first sign-in | See the options below | Company admin, platform admin | provisioning.mode |
| Only these email domains get an account | Limits Create an account at the first sign-in to these email domains | Empty (any) | Comma-separated email domains | Company admin, platform admin | provisioning.email_domains |
| Role when no group matches | The role of an account this provider created when none of its groups is mapped | User | Company admin, Policy manager, Auditor, User | Company admin, platform admin | roles.default_role |
| Group → role (Add group) | Maps one provider group to a role | None | A group name and one of Company admin, Policy manager, Auditor, User | Company admin, platform admin | roles.mappings (group, role) |
New people options:
- Create an account at the first sign-in (
auto): someone who signs in for the first time gets a new account in the company, if their email is in the allowed domains. - Only people who linked the provider in My profile (
existing): only existing accounts that linked this provider sign in. Nobody new gets in.
OpenID Connect settings
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Issuer URL | The provider's issuer. Merge Pilot reads the discovery document at <issuer>/.well-known/openid-configuration | — | Required. An https:// URL (http:// only for localhost). Must equal the issuer in the provider's tokens | Company admin, platform admin | oidc.issuer |
| Client ID | The client registered for Merge Pilot at the provider | — | Required | Company admin, platform admin | oidc.client_id |
| Client secret | That client's secret. Never shown again; leave empty to keep the saved one | — | Required when the provider is created | Company admin, platform admin | oidc.client_secret |
| Extra scopes | Scopes requested besides openid | Empty: profile and email, plus allatclaims when the provider offers it (ADFS) | Scopes separated by spaces or commas. Once you type scopes, exactly those are sent (plus openid) | Company admin, platform admin | oidc.scopes |
| Groups claim | The claim that holds the person's groups | Empty: groups, group, role and roles are read | A claim name | Company admin, platform admin | oidc.groups_claim |
| Username claim | The claim that gives the user name | Empty: preferred_username, else upn, else unique_name | A claim name | Company admin, platform admin | oidc.username_claim |
| Email claim | The claim that gives the email | Empty: email, else upn | A claim name | Company admin, platform admin | oidc.email_claim |
| Display name claim | The claim that gives the display name | Empty: name, else unique_name | A claim name | Company admin, platform admin | oidc.display_name_claim |
| CA certificate (PEM) | Trusted for the provider's HTTPS besides the public CAs: an internal CA, or ADFS's own certificate | Empty | A PEM certificate | Company admin, platform admin | oidc.ca_certificate |
| Sign in again after (hours) | Used when the provider gives no refresh token: people sign in again after this many hours. With a refresh token, Merge Pilot asks the provider at every session renewal instead | 8 | 1 to 168 | Company admin, platform admin | oidc.session_hours |
| Redirect URI | Read-only. The address to register at the provider, before or after saving. It is the same for every OpenID Connect provider | — | — | — | — |
The redirect URI is <Public URL>/api/v1/auth/sso/oidc/callback, built from the platform's Public URL (or the Application URL when the Public URL is empty).
Merge Pilot uses the authorization code flow with PKCE (S256) and a confidential client (client secret). It reads claims from the ID token and adds what the provider's userinfo endpoint returns. An email the provider marks as not verified (email_verified false) is not used.
SAML 2.0 settings
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Provider metadata URL | Where Merge Pilot reads the provider's metadata | — | An https:// URL (http:// only for localhost). This or the metadata XML is required | Company admin, platform admin | saml.metadata_url |
| Or the metadata XML | The provider's metadata, pasted | — | XML. Used instead of the URL when set | Company admin, platform admin | saml.metadata_xml |
| Username attribute | The attribute that gives the user name | Empty: uid, username, the UPN claim type, the Windows account name claim type, else the NameID | An attribute name | Company admin, platform admin | saml.username_attribute |
| Email attribute | The attribute that gives the email | Empty: email, mail, or the emailaddress claim type | An attribute name | Company admin, platform admin | saml.email_attribute |
| Display name attribute | The attribute that gives the display name | Empty: displayName, name, or the name claim type | An attribute name | Company admin, platform admin | saml.display_name_attribute |
| Groups attribute | The attribute that holds the person's groups | Empty: groups, and the group and role claim types ADFS and Entra ID send | An attribute name | Company admin, platform admin | saml.groups_attribute |
| Sign in again after (hours) | SAML has no refresh: people sign in again after this many hours, or sooner when the provider's assertion ends the session sooner | 8 | 1 to 168 | Company admin, platform admin | saml.session_hours |
| CA certificate (PEM) | Trusted when fetching the metadata URL, besides the public CAs | Empty | A PEM certificate | Company admin, platform admin | saml.ca_certificate |
| Merge Pilot metadata URL (give it to the provider) | Read-only, shown once the provider is saved. Merge Pilot's service provider metadata; this URL is also Merge Pilot's entity ID | — | — | — | — |
| Assertion consumer service URL | Read-only, shown once the provider is saved. Where the provider posts its answer | — | — | — | — |
The two read-only addresses are <Public URL>/api/v1/auth/sso/<provider-id>/metadata and <Public URL>/api/v1/auth/sso/<provider-id>/acs. Each SAML provider gets its own signing key and certificate when it is created.
How Merge Pilot uses SAML:
- It sends the request with the HTTP-Redirect binding and receives the answer with HTTP-POST. The provider's metadata must have an HTTP-Redirect sign-in endpoint.
- It accepts only answers to its own requests. Sign-in started at the provider (IdP-initiated) is not supported.
- The assertion must be addressed to Merge Pilot's entity ID (audience) and name the assertion consumer service URL as its recipient. Each assertion is accepted once.
- Answers signed with SHA-1 are refused; use SHA-256.
- The NameID is the person's stable identifier at the provider.
What Merge Pilot reads from the provider
| Value | Used for |
|---|---|
Subject (OIDC sub, SAML NameID) | The stable link between the provider's person and the Merge Pilot account |
| User name | The user name of a new account. A domain is removed: CORP\alice and alice@corp.example both become alice. Without one, the part of the email before @ is used |
| The email of a new account, and the email domain check | |
| Display name | The display name of a new account |
| Groups | Only these groups and Roles from groups. A Keycloak group path such as /team/ops matches both /team/ops and ops |
Accounts the provider created take their display name and email from it at every sign-in. When the new email belongs to another account of the company, the old one is kept.
Who gets an account
At a sign-in, Merge Pilot looks for the account linked to this provider and this subject:
- Found: the person signs in, if the account is active.
- Not found, New people = Only people who linked the provider in My profile: refused.
- Not found, New people = Create an account at the first sign-in: an account is created, if the email is in the allowed domains. The user name is the provider's user name; when another account of the company already has it, the provider's name is added as a suffix (
alice-corporate-sign-in). When the email is already used by another account of the company, the sign-in is refused: that person signs in with their account and links the provider in My profile.
Accounts are never merged by email. To connect an existing account (local, LDAP or another provider) to a provider, the person signs in with it and selects Link under Single sign-on on My profile.
Roles from groups
Roles from groups apply at every sign-in, but only to accounts this provider created. Such accounts show role from IdP on the Users page, and their role cannot be changed there.
- The highest matching role wins (Company admin, then Policy manager, then Auditor, then User).
- Role when no group matches applies when no mapping matches.
- A provider never gives the platform admin role.
- The role is updated at sign-in, not at session renewal. A change is recorded in the audit log as
sso_role_changed. - Accounts that only linked the provider keep the role an admin gave them.
Every provider sign-in is recorded as sso_login, with the groups the provider sent and the resulting role. Use it to check a role mapping.
Sessions
- OpenID Connect with a refresh token: at every session renewal Merge Pilot asks the provider again. When the provider refuses (the person was disabled, signed out or removed), the session ends with your sign-in was withdrawn: sign in again. When the provider sends a new ID token, Only these groups is checked again.
- OpenID Connect without a refresh token: the session ends after Sign in again after (hours).
- SAML: the session ends after Sign in again after (hours), or earlier when the assertion's session end comes first.
A session never lasts longer than the platform's refresh token lifetime.
Four-eyes review
When the company turned on Review control changes (Company → Governance), saving, editing or deleting an identity provider does not apply the change. It shows Sent for review: a second administrator approves the change, and the change waits in the identity providers card.
- Another company admin or platform admin selects Approve (the change is applied) or Reject.
- Nobody decides their own change, and an admin whose account the requester created, gave its role or set the password of cannot decide it either.
- The same review covers how people sign in (the Sign-in tab), the company directory (LDAP), whether people may make personal API tokens, risk settings, change policies, approver pools and vulnerability exceptions. Turning the review off is itself reviewed.
Setup notes per provider
The notes below list what Merge Pilot needs from each provider. Menu names in the providers' consoles change over time; follow the provider's own documentation for the clicks.
In every case:
- Open + OpenID Connect (or + SAML) in Merge Pilot first and copy the Redirect URI; for SAML, save the provider first and reopen it to copy the two read-only addresses.
- Register Merge Pilot at the provider with that address.
- Fill in the dialog, Save provider, then Test.
- Sign in with a test user and check the
sso_loginentry in the audit log for the groups and the role.
Keycloak (OpenID Connect)
| At the provider | Value |
|---|---|
| Client | OpenID Connect, client authentication on (confidential), standard flow |
| Valid redirect URI | Merge Pilot's Redirect URI |
| Groups in the token | Add a group membership mapper to the client that puts the groups in the groups claim of the ID token |
| In Merge Pilot | Value |
|---|---|
| Issuer URL | https://<host>/realms/<realm>, exactly as Keycloak puts it in its tokens |
| Client ID, Client secret | From the Keycloak client |
| Extra scopes, Groups claim, Username claim, Email claim | Empty |
With full group paths on, Keycloak sends /team/ops; Merge Pilot matches both /team/ops and ops. Group names are compared without regard to case, so the same name in two federated directories counts as one group. Keycloak issues refresh tokens in the standard flow, so sessions are re-checked at every renewal.
Microsoft Entra ID (OpenID Connect)
| At the provider | Value |
|---|---|
| App registration | Single tenant, platform Web, redirect URI = Merge Pilot's Redirect URI |
| Client secret | Create one; use its value, not its ID. Replace it in Merge Pilot before it expires |
| Groups claim | Add a groups claim to the ID token. Entra sends group object IDs by default; groups synchronized from on-premises AD can be sent by name |
Add the email optional claim if the ID token lacks it |
| In Merge Pilot | Value |
|---|---|
| Issuer URL | https://login.microsoftonline.com/<tenant-id>/v2.0. The multi-tenant common and organizations addresses do not work, because the issuer must equal the one in the token |
| Extra scopes | profile email offline_access. Without offline_access Entra gives no refresh token, and sessions last Sign in again after (hours) |
| Groups claim, Username claim, Email claim | Empty (groups or roles, preferred_username and email are read) |
| Only these groups, Roles from groups | Use the values Entra sends: object IDs, or names for synchronized groups |
Merge Pilot does not call Microsoft Graph. When a person is in more groups than fit in the token, Entra leaves the groups out, and the person arrives with no groups (the default role; refused when Only these groups is set). Limit the token to the groups assigned to the application, or use app roles, to avoid this.
Okta (OpenID Connect)
| At the provider | Value |
|---|---|
| App integration | OIDC, web application, client secret authentication, grant type authorization code. Add the refresh token grant so sessions are re-checked at every renewal |
| Sign-in redirect URI | Merge Pilot's Redirect URI |
| Groups claim | A groups claim in the ID token, with a filter for the groups Merge Pilot should see |
| In Merge Pilot | Value |
|---|---|
| Issuer URL | https://<org>.okta.com for the org authorization server, or https://<org>.okta.com/oauth2/default for a custom one. The two issue tokens with different issuers |
| Extra scopes | Empty, or profile email offline_access if Okta issues no refresh token without it |
| Groups claim, Username claim, Email claim | Empty |
Okta's preferred_username is usually an email; Merge Pilot keeps the part before @ as the user name.
Microsoft AD FS (OpenID Connect or SAML 2.0)
AD FS sends groups as role claims (http://schemas.microsoft.com/ws/2008/06/identity/claims/role), which Merge Pilot reads by default. They reach Merge Pilot only when an issuance rule issues them, for example the Send LDAP Attributes as Claims template with:
| LDAP attribute | Outgoing claim type |
|---|---|
| User-Principal-Name | UPN |
| E-Mail-Addresses | E-Mail Address |
| Display-Name | Name |
| Token-Groups - Unqualified Names | Role |
Groups then arrive by their short names (such as mp-admins), including nested groups.
AD FS usually has a certificate from an internal CA or a self-signed one. Paste that CA, or the AD FS certificate, into CA certificate (PEM), then Test.
OpenID Connect:
| At the provider | Value |
|---|---|
| Application group | A server application (with a generated client secret) accessing a web API with the same identifier |
| Redirect URI | Merge Pilot's Redirect URI |
| Issuance rules | The rule above, on the web API |
| Permitted scopes | openid, profile, email, allatclaims |
| In Merge Pilot | Value |
|---|---|
| Issuer URL | https://<adfs-host>/adfs |
| Client ID, Client secret | From the server application |
| Extra scopes | Empty. Merge Pilot then also requests allatclaims, which puts the groups in the ID token. If you type scopes, include allatclaims yourself |
AD FS issues refresh tokens and returns the current groups when a session renews, so someone removed from Only these groups loses the session at the next renewal.
SAML 2.0:
| In Merge Pilot | Value |
|---|---|
| Provider metadata URL | https://<adfs-host>/FederationMetadata/2007-06/FederationMetadata.xml |
| Username, Email and Groups attribute | Empty (the AD FS claim types are read) |
| At the provider (relying party trust) | Value |
|---|---|
| Relying party identifier | Merge Pilot metadata URL |
| SAML assertion consumer endpoint | Assertion consumer service URL, binding POST |
| Secure hash algorithm | SHA-256 |
| Claim rules | The rule above, plus a rule that issues the Name ID (for example from the UPN, format unspecified) |