Single Sign-On and SCIM

An organization can let its members sign in to Holarch with their work account. Holarch is the service provider; your organization's identity provider (Okta, Microsoft Entra ID, Google Workspace, Ping Identity or any SAML 2.0 provider) checks who they are. The identity provider can also create, update and deactivate Holarch accounts through SCIM 2.0.

Single sign-on is set up by an org admin under Organization Settings → the organization → Single sign-on. It works on the hosted service only.

Concepts

How to use it

Verify an email domain

1. Open Organization Settings, select the organization and find Single sign-on.
2. Under Email domains, enter the domain of your members' addresses and choose Add Domain.
3. Publish the TXT record shown: the name _holarch-challenge.<domain> with the value holarch-domain-verification=….
4. Choose Check. DNS changes can take some minutes to arrive; check again until the domain shows Verified.

Add every domain your members use (for example example.com and eng.example.com). Up to 20 domains per organization.

Connect the identity provider

1. In your identity provider, create a SAML 2.0 application (see the provider sections below) with the values under Identity provider in Holarch:
   • Entity ID (audience): https://app.holarch.app/api/auth/saml/<organization id>/metadata
   • ACS URL (reply URL): https://app.holarch.app/api/auth/saml/<organization id>/acs
   • Metadata URL: the same as the entity ID; providers that import SP metadata can use it.
2. Copy the provider's metadata XML or its metadata URL into the box at the top and choose Read Metadata. Holarch fills the entity ID, sign-in URL and certificate. Or enter them yourself.
3. Under Attributes and roles, set the attribute names if your provider uses unusual ones (see Attributes), the Role of new members, and optional Groups to roles.
4. Choose Save Identity Provider and enter your password.

Turn single sign-on on

1. Tick Single sign-on for this organization. It needs a saved identity provider and a verified domain.
2. Give members the Sign-in link for members, or tell them to choose Sign in with single sign-on on the sign-in screen and enter their work email address.
3. Try it with one member first.

On a member's first sign-in, Holarch creates the account (confirmed, without a password) and adds it to the organization, also while sign-up needs an invitation. When an account with that address exists, single sign-on is linked to it and its owner gets an email.

Require single sign-on

Tick Require single sign-on for members in the verified domains after single sign-on works.

• Managed members then sign in only through the identity provider. Password, passkey, Google and Microsoft sign-in answer that the organization requires single sign-on, with a button that goes there. Their current sessions from other sign-in methods end at once.
• Org admins are not required: they keep their password or passkey with two-step sign-in, so they can fix a broken identity provider setup (break-glass). Keep at least two org admins.
• Members whose address is outside the verified domains (outside collaborators) are not affected.
• A password reset still sets the new password but does not sign the member in; they then sign in through the identity provider.
• API tokens and connected apps of managed members keep working. Deactivate the account (SCIM, or a site administrator) to end them.

Provision accounts with SCIM

1. Under Provisioning (SCIM 2.0), choose Create SCIM Token and enter your password.
2. Copy the token and the Base URL (https://app.holarch.app/scim/v2) into your identity provider's provisioning settings. Holarch shows the token once.
3. Turn on creating, updating and deactivating users in the provider.

Up to 5 tokens per organization. Revoke ends a token at once.

When the identity provider's certificate changes

1. Paste the new certificate under the old one (two certificates are allowed) and save.
2. Switch the provider to the new certificate.
3. Remove the old certificate and save again.

The certificate list shows each certificate's subject, expiry date and fingerprint.

Sign-in rules

Holarch checks every answer from the identity provider strictly. A sign-in is refused when:

• the assertion is not signed with a configured certificate, or is signed with SHA-1;
• the issuer, audience (the organization's entity ID), destination or recipient (the ACS URL) do not match;
• the assertion is not yet valid or has expired (2 minutes of clock difference are allowed);
• it answers a sign-in that was not started in the same browser, or one that was already used (each sign-in starts once and expires after 10 minutes);
• the same assertion arrives a second time (replay);
• the email address is missing or outside the organization's verified domains;
• the account is disabled.

The sign-in screen then says what went wrong, and the organization's audit log records it as auth.sso-failed.

Sign-in from the identity provider's portal (IdP-initiated, when members start from the provider's app dashboard) is off by default, because such an answer is not tied to a sign-in the browser started. Turn on Allow sign-in from the identity provider's portal only when your members need it. Replay protection and all other checks still apply.

Two-step sign-in

By default a single sign-on is the first step. Accounts with two-step sign-in on still confirm a passkey or code, and the organization's Require two-step sign-in setting still asks members for it.

With Trust the identity provider's multi-factor sign-in on, a sign-in whose assertion reports multi-factor authentication needs no Holarch second step, and it meets this organization's two-step requirement for that session (not other organizations'). Holarch accepts these authentication contexts as multi-factor:

Entra ID's http://schemas.microsoft.com/claims/authnmethodsreferences claim with multipleauthn counts as well. A sign-in with only a password at the identity provider is not multi-factor, even with trust on.

Attributes

The account is found by the identity provider's NameID (persistent or email format). When the NameID changes but the email address stays, the account is relinked.

Groups to roles

Write one mapping per line: holarch-admins = admin or engineering = member. At every sign-in, a member in a group mapped to admin becomes an org admin; otherwise a member in a mapped group becomes a member. Members in no mapped group keep their role. The last org admin is never demoted.

SCIM

The SCIM API follows RFC 7643 and RFC 7644 at https://app.holarch.app/scim/v2 with Authorization: Bearer hsc_….

• Only addresses in the organization's verified domains can be created or changed.
• Deactivating (active: false, or DELETE) removes the person from the organization, disables the account, ends all its sessions, and revokes its API tokens and connected apps. Reactivating enables the account and restores its organization role. An account a site administrator disabled stays disabled.
• Enterprise extension attributes are accepted and ignored.
• Each token may make 600 requests a minute. Every change is recorded in the organization's audit log (scim.create, scim.deactivate, and so on).

Set up your identity provider

Okta

1. Applications → Create App Integration → SAML 2.0.
2. Single sign-on URL: the ACS URL. Keep Use this for Recipient URL and Destination URL ticked. Audience URI (SP Entity ID): the entity ID.
3. Name ID format: EmailAddress or Persistent. Application username: Email.
4. Attribute statements: email → user.email, displayName → user.displayName. Group attribute statements (optional): groups, filter as you need.
5. Finish, then copy the Metadata URL from the Sign On tab into Holarch and choose Read Metadata.
6. For SCIM: in the app's General tab, enable SCIM provisioning; in Provisioning, SCIM connector base URL is the Base URL, Unique identifier field userName, Authentication Mode HTTP Header with the SCIM token; enable Create Users, Update User Attributes and Deactivate Users.

Microsoft Entra ID

1. Enterprise applications → New application → Create your own application (non-gallery), then Single sign-on → SAML.
2. Identifier (Entity ID): the entity ID. Reply URL (Assertion Consumer Service URL): the ACS URL.
3. Attributes & Claims: the default emailaddress claim works; add a group claim if you map groups.
4. Under SAML Certificates, copy the App Federation Metadata Url into Holarch and choose Read Metadata.
5. To trust Entra's multi-factor sign-in, require MFA in a Conditional Access policy for the app; Entra then sends multipleauthn.
6. For SCIM: Provisioning → Automatic; Tenant URL is the Base URL and Secret Token the SCIM token. Test Connection, then start provisioning.

Google Workspace

1. Admin console → Apps → Web and mobile apps → Add app → Add custom SAML app.
2. Copy the IdP metadata (download it, then paste the XML into Holarch).
3. ACS URL: the ACS URL. Entity ID: the entity ID. Name ID format: EMAIL, Name ID: Basic Information › Primary email.
4. Attribute mapping: Primary email → email; First name → givenName; Last name → sn. Group membership → groups (optional).
5. Turn the app ON for everyone (or for an organizational unit).
6. Google Workspace does not send an MFA authentication context; leave Trust the identity provider's multi-factor sign-in off. Google's SCIM provisioning works only with gallery apps; create accounts by single sign-on instead.

Ping Identity

1. PingOne: Applications → Add Application → SAML Application (PingFederate: an SP connection).
2. Import Holarch's Metadata URL, or enter the ACS URL and Entity ID.
3. Attribute mapping: saml_subject → Email Address; add email and displayName.
4. Copy the IdP metadata URL into Holarch and choose Read Metadata.
5. For SCIM: PingOne provisioning with a SCIM connection; the Base URL and OAuth 2 Bearer Token authentication with the SCIM token.

Limits and security notes

• Settings changes need a recent password check, are emailed to all org admins and are recorded in the audit log (sso.saml-save, sso.enable, sso.require, sso.domain-verify, scim.token-create…).
• Metadata URLs must use https on the public internet; Holarch fetches them once, when you choose Read Metadata.
• SCIM tokens are stored only as a hash.