Single sign-on and SCIM provisioning

Single sign-on is included in the Enterprise plan and in self-hosted deployments. Owners and administrators with the security permission configure it under Settings → Security in the console.

Single sign-on

MergeHarbor connects to your identity provider with OpenID Connect (Okta, Microsoft Entra ID, Google Workspace, Ping, Keycloak, and others) or SAML 2.0.

1. Create the application at your identity provider.
   • OpenID Connect: a web application with the callback URL shown on the settings page, and the openid, email, and profile scopes. Add groups if you map roles, and offline_access if you turn on session re-validation.
   • SAML: give the identity provider the service-provider metadata URL, or the entity ID and ACS URL shown on the page. Sign the assertion, send the email address as the NameID or an email attribute, and add a groups attribute if you map roles.
2. Enter the provider details. For OpenID Connect, the issuer URL, client ID, and client secret (stored encrypted and never shown again). For SAML, the identity provider’s metadata URL (re-read daily) or its metadata XML.
3. Set allowed domains. Only users with email addresses in these domains can sign in through your identity provider. Allowed domains are required for SAML.
4. Optionally provision on first sign-in. Just-in-time provisioning creates members with the default role. Group → role and group → team mappings apply at every sign-in; the first matching mapping wins. Owners, and roles an administrator assigned by hand, are never changed. Preview role changes shows who would get which role before you save.
5. Test the connection. A new tab signs you in at the identity provider and shows what it sent — claims or attributes, groups, and the role you would get — without creating anything.
6. Choose break-glass owners. Up to five owners may still sign in without single sign-on, for example during an identity-provider outage. Every use is recorded in the audit log.
7. Enforce single sign-on. Other sign-in methods are then refused for the organization.
8. Optionally re-validate sessions (OpenID Connect). MergeHarbor refreshes each session with your identity provider at the interval you choose, so a user disabled there is signed out and group changes apply without waiting for the next sign-in.

Users reach your identity provider from the sign-in page by entering their work email.

SCIM provisioning

Settings → Security → Provisioning lets an owner create a SCIM token for Okta, Microsoft Entra ID, or any SCIM 2.0 client. In your identity provider’s provisioning settings, use:

• the SCIM base URL shown on the page (https://<your console>/scim/v2),
• bearer-token authentication with the token, which is shown only once,
• userName (the email address) as the unique identifier.

Push groups to map roles and teams with the same group mappings as single sign-on.

• Creating a user adds them to the organization.
• Deactivating or deleting a user removes them at once: their membership, their API keys in the organization, their sessions, and any pending invitations. The change is recorded in the audit log.
• Group membership changes update roles and teams immediately.
• The last owner of an organization cannot be deprovisioned.
• Rotate a token from the same page. The old token stops working immediately, so paste the new one into your identity provider right away.

Each token belongs to one organization, so an identity provider can never read or change another organization’s members.