Skip to main content
Truthlocks supports native SAML 2.0 single sign-on so your team can authenticate through your existing identity provider (IdP). When SAML is configured, users are automatically routed to your IdP during login.
SAML SSO is available on the Business plan and above.

​
How it works

1

Configure your IdP

Register Truthlocks as a service provider (SP) in your identity provider. You need the SP Entity ID and Assertion Consumer Service (ACS) URL from the setup screen.
2

Add connection in Truthlocks

In the console, go to Settings > SSO and create a new SAML connection. Enter your IdP metadata URL or manually provide the IdP entity ID, SSO URL, and signing certificate.
3

Users sign in via IdP

Once active, users who visit the console login page are redirected to your IdP. After authenticating, they are returned to Truthlocks with a session.

​
Service provider details

Provide these values to your IdP when registering Truthlocks:
FieldValue
SP Entity IDurn:truthlocks:<your_tenant_id>
ACS URLhttps://console.truthlocks.com/api/auth/saml/acs
NameID formaturn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
BindingHTTP-POST

​
IdP configuration fields

When creating a SAML connection in the console, you can configure your IdP in two ways:

​
Option A: metadata URL

Provide your IdP metadata URL and Truthlocks automatically fetches the entity ID, SSO URL, and signing certificate.

​
Option B: manual configuration

FieldDescription
IdP Entity IDYour identity provider’s unique identifier
IdP SSO URLThe URL where Truthlocks sends SAML authentication requests
IdP CertificateThe X.509 signing certificate from your IdP (PEM format)

​
Creating a connection via the API

curl -X POST https://api.truthlocks.com/v1/sso/connections \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "SAML",
    "idp_metadata_url": "https://idp.example.com/metadata",
    "role_mapping_mode": "GROUPS"
  }'
If you prefer manual configuration, omit idp_metadata_url and provide idp_entity_id, idp_sso_url, and idp_certificate instead.

​
Role mapping

Truthlocks maps IdP group assertions to internal roles during sign-in. Two modes are available:
ModeBehavior
STATICAll SAML users receive a fixed default role (e.g., viewer)
GROUPSIdP group names are mapped to Truthlocks roles (admin, editor, auditor) automatically
Set the mode when creating or updating the SSO connection.

​
User provisioning

When a user authenticates via SAML for the first time, Truthlocks automatically creates their account using attributes from the SAML assertion (email, first name, last name). This is called just-in-time (JIT) provisioning. For bulk user sync and deprovisioning, use SCIM provisioning.

​
Session details

  • Sessions last 12 hours after SAML login.
  • Session cookies are HttpOnly and SameSite=Lax.
  • A 2-minute clock skew tolerance is applied when validating SAML assertions.

​
Testing a connection

After creating a SAML connection, test it before enabling for all users: 
curl -X POST https://api.truthlocks.com/v1/sso/connections/<connection_id>/test \
  -H "Authorization: Bearer <admin_token>"
This validates that Truthlocks can reach your IdP and parse the metadata correctly.

​
Disabling SSO

To revert to standard email/password authentication: 
curl -X POST https://api.truthlocks.com/v1/sso/connections/<connection_id>/disable \
  -H "Authorization: Bearer <admin_token>"