SAML 2.0

Connect any SAML 2.0 identity provider, including Okta, Entra ID, AD FS, JumpCloud, OneLogin, PingOne and Keycloak. Team plan and above, as part of your own sign-in connection (Microsoft Entra, OpenID Connect or SAML, plus SCIM provisioning). For: Admins and Owners.

Before you start

Verify your email domain under Settings → Verification. SafeHanded accepts a SAML sign-in only for email addresses in domains your organisation has verified.

Connect

Go to Settings → Integrations → Connect and choose SAML 2.0.
Give SafeHanded your provider’s metadata URL (recommended), paste its metadata XML, or enter the entity ID, single sign-on URL and signing certificate by hand.
Sign-in is invite-only unless you turn on Provision new members on first sign-in for your verified domains. Then Save.
On the connection’s Settings tab, register the SP metadata URL (or the ACS URL and entity ID) with your provider. Send the email address as an attribute named email, or as the NameID.

SafeHanded sends sign-in requests with the HTTP-Redirect binding, or HTTP-POST if your provider offers only that; you can switch on the Settings tab. Set NameID format to request to match the Name ID format configured in your provider (Unspecified suits most).

If your provider asks for SafeHanded’s URLs first (Okta, Entra ID and others do), save the connection with the provider details empty. It waits, signing nobody in, while you copy the ACS URL and SP entity ID from the Settings tab into your provider; then add the provider’s metadata there to finish.

Signing in

Members choose Continue with single sign-on on the sign-in page and enter their work email, or start from your provider’s app tile. The SP-initiated sign-in URL on the Settings tab starts a sign-in directly.

Certificates

Settings → Certificates and metadata on the connection’s page lists every signing certificate SafeHanded trusts, with its expiry. An assertion signed by any of them is accepted, so a rollover needs no downtime:

Imported from a metadata URL: SafeHanded refreshes the metadata daily and picks up a new certificate as soon as your provider publishes it. If the metadata ever describes a different provider, the change is refused and flagged instead.
Entered by hand or pasted: paste both the old and the new certificate during the rollover.

Owners are emailed when every trusted certificate expires within 30 days.

Signed requests and encrypted assertions

Turn these on under Certificates and metadata only if your provider needs them. With signed requests, Okta also insists that the requested NameID format matches the app’s Name ID format.

Sign authentication requests: SafeHanded signs each request with its own key.
Require encrypted assertions: your provider encrypts the assertion to SafeHanded’s certificate.

SafeHanded creates a key pair for the connection the first time you turn either on and publishes the certificate in the SP metadata. Update the metadata in your provider afterwards.

SafeHanded accepts an assertion when the IdP signs the Response, the Assertion or both, and refuses SHA-1 signatures: set your provider to SHA-256.

Provider notes

Okta and Keycloak have been tested end to end. The notes for the others are checked against each provider’s own documentation; if what you see doesn’t match, email support@safehanded.com. Single logout isn’t supported, so leave any logout URL blank. SafeHanded allows three minutes of clock difference.

Microsoft Entra ID. Most organisations should use the built-in Microsoft connection. For a SAML app under Enterprise applications:

Identifier (Entity ID) = SafeHanded’s SP entity ID, Reply URL = the ACS URL, and Sign on URL = the SP-initiated sign-in URL (this makes the My Apps tile work). Leave Relay State blank.
Set NameID format in SafeHanded to Email or Don’t ask, and make sure the email address claim has a value (user.mail, or user.userprincipalname for people with no mailbox).
Keep signing at SHA-256; any of the signing options works.
Import the App Federation Metadata Url, so certificate changes are picked up automatically.
Groups arrive as object IDs (GUIDs) by default, so use those in group → role mapping. Choose Groups assigned to the application to stay under Entra’s 150-group limit (above it, no groups are sent and the member gets your default role), or Cloud-only group display names to map by name.
Signed requests: upload SafeHanded’s certificate under Verification certificates. Entra then turns off its Test button and IdP-initiated sign-in. Encrypted assertions need Entra ID P1 or P2.

JumpCloud.

Use the SP entity ID and ACS URL from the Settings tab, and the SP-initiated sign-in URL as the Login URL.
Keep NameID as the email, and add an attribute named email.
For groups, tick the group attribute and name it groups.
Keep RSA-SHA256, and import the Metadata URL.
Only upload an SP certificate to JumpCloud once you’ve turned on Require encrypted assertions in SafeHanded, so SafeHanded holds the matching key.

OneLogin (SAML Custom Connector, Advanced).

Audience = the SP entity ID and Recipient = the ACS URL (not the entity ID).
ACS (Consumer) URL Validator: the ACS URL as an anchored pattern, for example ^https://safehanded\.com/saml/<id>/acs$.
Set SAML Signature Algorithm to SHA-256.
Add an email parameter with Include in SAML assertion ticked, and for groups a groups parameter with Multi-value parameter ticked.
Import the Issuer URL as the metadata URL.

Groups

SafeHanded reads groups from the usual attribute names (groups, memberOf, and the Microsoft and AD FS group claims). Use them for provision by group and group → role mapping.

Automatic provisioning (SCIM)

Issue a token on the connection’s SCIM tab and paste the tenant URL and token into your provider, so joiners and leavers are handled automatically. See Automatic provisioning (SCIM) for each provider’s steps.