Single sign-on (SAML) and provisioning

With single sign-on (SSO) your people sign in to Hermetry with their company account, and leavers lose access when you switch them off in your directory. Each organisation can connect its own SAML 2.0 identity provider and keep members in step with SCIM 2.0. This page explains the setup.

You need the Owner role for SAML and the Admin role for SCIM tokens.

SAML 2.0

Open SAML SSO (address /admin/saml). The overview shows the Status (Active, Disabled or Not configured), Successful logins, JIT-provisioned users, Last login and SSO Activity from the audit log. Select Settings to configure.

1. Give Hermetry’s details to your identity provider

The Service Provider Info card: “Provide these values to your Identity Provider during SAML app setup”.

Field	Use in your identity provider
Entity ID (Audience URI)	The audience / SP entity ID
ACS URL (Reply URL)	Where the provider posts the assertion
Metadata URL	Import this instead of typing the fields, if your provider supports it

SP Metadata XML offers Copy XML and Download XML.

2. Enter your identity provider’s settings

Identity Provider Settings:

Field	Value
IdP Entity ID	Your provider’s entity ID
IdP SSO URL	Your provider’s sign-in address
IdP Certificate (PEM or Base64)	The provider’s signing certificate. “Include or omit the —–BEGIN CERTIFICATE—– header — both formats are accepted.”

Select Save IdP Settings. Where allowed, you can pre-fill these fields by importing your provider’s published metadata (SAML Advanced Settings).

3. Map the attributes

Attribute Mapping: “Map SAML assertion attributes to user profile fields”.

Field	Meaning
Email Attribute	“Attribute name from your IdP that contains the user email”
Name Attribute	“Attribute name for the user’s display name”
NameID Format	The format of the subject’s NameID (the e-mail format by default)
Sign Authentication Requests	Sign the requests Hermetry sends with its own key
Allow IdP-initiated SSO	“Permit logins started from the IdP dashboard without an SP request”. Off is safer.

Select Save Mapping.

4. Provision members just in time

Just-In-Time Provisioning: “Unknown users that authenticate via your IdP will be auto-provisioned into this tenant.”

Field	Meaning
Enable Just-In-Time provisioning	Create the member at their first SSO sign-in. Off: only existing members can sign in with SSO.
Role attribute name (optional)	“Values containing ‘owner’ map to OWNER, ‘admin’ to ADMIN.”
Default member role	The role when no role attribute is mapped.

Select Save Provisioning Settings. Think carefully before you map the Owner role from your directory: anyone your directory marks so becomes an owner.

5. Turn it on

Under SAML Status, turn on Enable SAML SSO: “Allows members to log in via your Identity Provider”.

Test with a second browser before you sign out, so a mistake cannot lock you out.

Security of SAML

• Assertions must be signed, with SHA-256 or SHA-512. SHA-1 and unsigned assertions are refused. A connection stored with weaker settings is switched off until you save it again: “SAML sign-in is off for this connection: its signature settings are too weak…”
• With Assertion Replay Detection on, an assertion whose ID was seen before is refused.
• The clock skew allowed is a few seconds; keep your provider’s clock right.
• Hermetry’s private key for SAML is stored encrypted and never exported. A second certificate can be added for a key rotation.
• Single Logout (SLO), where enabled, propagates sign-out between Hermetry and your provider. It needs your provider’s SLO address.
• A warning is written to the audit log when your provider’s signing certificate is close to expiry (by default 30 days before).

An existing account is linked to SAML only when the e-mail in the assertion matches. Pending invitations to a verified address are accepted at the first SSO sign-in.

SCIM 2.0 provisioning

SCIM lets your identity provider create, update and deactivate members automatically.

1. Open Settings > SCIM Provisioning. Copy the SCIM 2.0 Endpoint (Copy SCIM endpoint): https://<your host>/tenant/<tenantId>/api/scim/v2.
2. Select Generate SCIM token. “Copy this token now — it will not be shown again.” It carries the scim:read and scim:write scopes.
3. In your identity provider, enter the endpoint as the connector base address and the token as an HTTP header Authorization: Bearer <token>.

SCIM	Hermetry
userName, primary e-mail	The account e-mail
externalId	SCIM external ID on the member page
active: false	Member status Inactive (access ends at once)
Delete	The member is removed; the account stays for other organisations

Names sent by SCIM are not stored. Groups are not supported: the Groups endpoints answer an empty list, so assign roles and groups in Hermetry. Revoke a token to stop the provider at once: “name stops working at once…”. The token list shows Last used and expiry.

Social sign-in

Members can also sign in with social sign-in through common providers, using OpenID Connect or OAuth, where the platform offers them. Your organisation can limit them:

• Settings > Authentication & SSO lists the providers; installing and configuring providers is done in the marketplace.
• A member links a provider under My Profile > Connected Accounts; the provider’s e-mail must match. See Your profile, language and time zone.

Related

• Two-factor sign-in and passkeys
• Users and roles