Skip to main content

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 doesDefaultAllowed valuesWho can change itAPI field
Name on the sign-in pageThe 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 companyCompany admin, platform adminname
EnabledWhether people may sign in with this providerOnOn or offCompany admin, platform adminenabled
Only these groupsOnly 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 renewsEmptyGroup names separated by commas or new lines; at most 50, each 1 to 256 characters. Compared without regard to caseCompany admin, platform adminallowed_groups
New peopleWho gets an account at their first sign-inCreate an account at the first sign-inSee the options belowCompany admin, platform adminprovisioning.mode
Only these email domains get an accountLimits Create an account at the first sign-in to these email domainsEmpty (any)Comma-separated email domainsCompany admin, platform adminprovisioning.email_domains
Role when no group matchesThe role of an account this provider created when none of its groups is mappedUserCompany admin, Policy manager, Auditor, UserCompany admin, platform adminroles.default_role
Group → role (Add group)Maps one provider group to a roleNoneA group name and one of Company admin, Policy manager, Auditor, UserCompany admin, platform adminroles.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 doesDefaultAllowed valuesWho can change itAPI field
Issuer URLThe 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 tokensCompany admin, platform adminoidc.issuer
Client IDThe client registered for Merge Pilot at the provider—RequiredCompany admin, platform adminoidc.client_id
Client secretThat client's secret. Never shown again; leave empty to keep the saved one—Required when the provider is createdCompany admin, platform adminoidc.client_secret
Extra scopesScopes requested besides openidEmpty: 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 adminoidc.scopes
Groups claimThe claim that holds the person's groupsEmpty: groups, group, role and roles are readA claim nameCompany admin, platform adminoidc.groups_claim
Username claimThe claim that gives the user nameEmpty: preferred_username, else upn, else unique_nameA claim nameCompany admin, platform adminoidc.username_claim
Email claimThe claim that gives the emailEmpty: email, else upnA claim nameCompany admin, platform adminoidc.email_claim
Display name claimThe claim that gives the display nameEmpty: name, else unique_nameA claim nameCompany admin, platform adminoidc.display_name_claim
CA certificate (PEM)Trusted for the provider's HTTPS besides the public CAs: an internal CA, or ADFS's own certificateEmptyA PEM certificateCompany admin, platform adminoidc.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 instead81 to 168Company admin, platform adminoidc.session_hours
Redirect URIRead-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 doesDefaultAllowed valuesWho can change itAPI field
Provider metadata URLWhere Merge Pilot reads the provider's metadata—An https:// URL (http:// only for localhost). This or the metadata XML is requiredCompany admin, platform adminsaml.metadata_url
Or the metadata XMLThe provider's metadata, pasted—XML. Used instead of the URL when setCompany admin, platform adminsaml.metadata_xml
Username attributeThe attribute that gives the user nameEmpty: uid, username, the UPN claim type, the Windows account name claim type, else the NameIDAn attribute nameCompany admin, platform adminsaml.username_attribute
Email attributeThe attribute that gives the emailEmpty: email, mail, or the emailaddress claim typeAn attribute nameCompany admin, platform adminsaml.email_attribute
Display name attributeThe attribute that gives the display nameEmpty: displayName, name, or the name claim typeAn attribute nameCompany admin, platform adminsaml.display_name_attribute
Groups attributeThe attribute that holds the person's groupsEmpty: groups, and the group and role claim types ADFS and Entra ID sendAn attribute nameCompany admin, platform adminsaml.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 sooner81 to 168Company admin, platform adminsaml.session_hours
CA certificate (PEM)Trusted when fetching the metadata URL, besides the public CAsEmptyA PEM certificateCompany admin, platform adminsaml.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 URLRead-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​

ValueUsed for
Subject (OIDC sub, SAML NameID)The stable link between the provider's person and the Merge Pilot account
User nameThe 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
EmailThe email of a new account, and the email domain check
Display nameThe display name of a new account
GroupsOnly 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:

  1. Found: the person signs in, if the account is active.
  2. Not found, New people = Only people who linked the provider in My profile: refused.
  3. 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:

  1. 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.
  2. Register Merge Pilot at the provider with that address.
  3. Fill in the dialog, Save provider, then Test.
  4. Sign in with a test user and check the sso_login entry in the audit log for the groups and the role.

Keycloak (OpenID Connect)​

At the providerValue
ClientOpenID Connect, client authentication on (confidential), standard flow
Valid redirect URIMerge Pilot's Redirect URI
Groups in the tokenAdd a group membership mapper to the client that puts the groups in the groups claim of the ID token
In Merge PilotValue
Issuer URLhttps://<host>/realms/<realm>, exactly as Keycloak puts it in its tokens
Client ID, Client secretFrom the Keycloak client
Extra scopes, Groups claim, Username claim, Email claimEmpty

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 providerValue
App registrationSingle tenant, platform Web, redirect URI = Merge Pilot's Redirect URI
Client secretCreate one; use its value, not its ID. Replace it in Merge Pilot before it expires
Groups claimAdd 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
EmailAdd the email optional claim if the ID token lacks it
In Merge PilotValue
Issuer URLhttps://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 scopesprofile email offline_access. Without offline_access Entra gives no refresh token, and sessions last Sign in again after (hours)
Groups claim, Username claim, Email claimEmpty (groups or roles, preferred_username and email are read)
Only these groups, Roles from groupsUse 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 providerValue
App integrationOIDC, 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 URIMerge Pilot's Redirect URI
Groups claimA groups claim in the ID token, with a filter for the groups Merge Pilot should see
In Merge PilotValue
Issuer URLhttps://<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 scopesEmpty, or profile email offline_access if Okta issues no refresh token without it
Groups claim, Username claim, Email claimEmpty

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 attributeOutgoing claim type
User-Principal-NameUPN
E-Mail-AddressesE-Mail Address
Display-NameName
Token-Groups - Unqualified NamesRole

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 providerValue
Application groupA server application (with a generated client secret) accessing a web API with the same identifier
Redirect URIMerge Pilot's Redirect URI
Issuance rulesThe rule above, on the web API
Permitted scopesopenid, profile, email, allatclaims
In Merge PilotValue
Issuer URLhttps://<adfs-host>/adfs
Client ID, Client secretFrom the server application
Extra scopesEmpty. 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 PilotValue
Provider metadata URLhttps://<adfs-host>/FederationMetadata/2007-06/FederationMetadata.xml
Username, Email and Groups attributeEmpty (the AD FS claim types are read)
At the provider (relying party trust)Value
Relying party identifierMerge Pilot metadata URL
SAML assertion consumer endpointAssertion consumer service URL, binding POST
Secure hash algorithmSHA-256
Claim rulesThe rule above, plus a rule that issues the Name ID (for example from the UPN, format unspecified)