SAML

SAML (Security Assertion Markup Language) is an open standard used to exchange authentication and authorization data between an Identity Provider (IdP) and a Service Provider (SP).

It enables Single Sign-On (SSO) by allowing users to authenticate once with a trusted IdP and then access multiple applications without re-entering their credentials.

When integrating with Trustbuilder as the Identity Provider, your application relies on Trustbuilder to authenticate users and issue a SAML Assertion, a digitally signed XML token containing identity information (e.g., name, email, unique identifier). This assertion allows your application to verify who the user is and what they are allowed to access.

Example

1. A user attempts to access your application (Service Provider).

2. The user is redirected to Trustbuilder, acting as the Identity Provider

3. After successful authentication, Trustbuilder sends a SAML Response containing a SAML Assertion.

4. Your application validates the response signature and grants access based on the information in the assertion.

Set up a SAML-based integration

1. Log in to the Admin Portal.

2. Go to Applications > Applications > + Set up app integration.

3. Select SAML.

   

4. Configure the application parameters:

5. For SP Metadata configuration, select one of the following options depending on whether the Service Provider has already provided its metadata:

   • Option A - Generate metadata automatically when the Service Provider hasn't shared its metadata. This will generate temporary Service Provider metadata. These metadata must be replaced later with the official SP metadata once they are available. You will be able to download Trustbuilder IdP metadata and provide it to the SP.

   • Option B - Import your metadata file when the Service Provider has already provided its metadata. This allows to provide the official SP metadata to Trustbuilder.

Option A - Generate metadata automatically

Use this option when the Service Provider hasn't shared its metadata yet.

1. Click Create.
   The application will be created with temporary SP metadata first.

2. Go to IdP Metadata tab to get the Trustbuilder IdP URL.

   

3. Go to your SP interface and provide the following URL to the Service Provider:
   ⚠️ The procedure defers depending on the SP.

   • Entity ID → Trustbuilder IdP identifier

   • Single Sign On URL → URL used by the SP to initiate SSO

   • Single Logout Service URL → URL used for SAML logout requests

   • You can also copy the full IdP Metadata URL from the header.

4. Once the SP returns its metadata, go back to Trustbuilder admin portal.

5. In the application you created, go to SP metadata tab.

   

6. Click Import XML to upload the SP metadata XML file.

   

   This automatically fills in the configuration with values from the SP metadata:

   1. Entity ID → the unique identifier of the SAML application on the SP side.

   2. ACS URL → Endpoint where Trustbuilder sends the SAML Response after authentication. At least one ACS URL is required.

   3. The security options settings define how SAML exchanges between the SP and Trustbuilder are secured.

      • Assertions:

        • Encrypted → when enabled, Trustbuilder encrypts the SAML Assertion using the SP encryption certificate. The SP uses its private key to decrypt the assertion.

        • Signed → when enabled, Trustbuilder signs the SAML Assertion using its signing certificate. The current certificate and its expiration date are displayed. Click Change certificate if needed.

      • AuthnRequests:

        • Signed → when enabled, Trustbuilder expects signed AuthnRequests from the Service Provider. Trustbuilder validates the signature using the configured SP signing certificates.

   4. Manage certificates used to secure SAML exchanges:

      • Encryption certificates are used by Trustbuilder to encrypt SAML Assertions for the Service Provider. Only one active encryption certificate is supported.

      • Signing certificates are used to verify signed AuthnRequests sent by the Service Provider. Multiple certificates can be configured to support certificate rotation. When multiple signing certificates are configured, Trustbuilder checks each one until the AuthnRequest signature is successfully validated.

        EXPIRED CERTIFICATES: Encryption and signing certificates are flagged when expired. You must replace them as soon as possible.

7. Click Save.

CURRENT LIMITATION
When importing metadata, certificates are not imported. This can cause an “invalid certificate” error even if the certificate is valid.

Workaround: Import or copy/paste the certificate manually in SP certificates by clicking + Add certificate.

CODE

-----BEGIN CERTIFICATE-----
{PASTE_CERTIFICATE}
-----END CERTIFICATE-----

This is a temporary issue and will be fixed in a future release.

Option B - Import SP metadata file

Use this option when the Service Provider has already provided its metadata file or metadata URL.

1. You can upload an XML file or paste the metadata content directly.

2. Click Continue.

3. This automatically fills in the configuration with values from the SP metadata:

   1. Entity ID → the unique identifier of the SAML application on the SP side.

   2. ACS URL → Endpoint where Trustbuilder sends the SAML Response after authentication. At least one ACS URL is required.

   3. The security options settings define how SAML exchanges between the SP and Trustbuilder are secured.

      • Assertions:

        • Encrypted → when enabled, Trustbuilder encrypts the SAML Assertion using the SP encryption certificate. The SP uses its private key to decrypt the assertion.

        • Signed → when enabled, Trustbuilder signs the SAML Assertion using its signing certificate. The current certificate and its expiration date are displayed. Click Change certificate if needed.

      • AuthnRequests:

        • Signed → when enabled, Trustbuilder expects signed AuthnRequests from the Service Provider. Trustbuilder validates the signature using the configured SP signing certificates.

   4. Manage certificates used to secure SAML exchanges:

      • Encryption certificates are used by Trustbuilder to encrypt SAML Assertions for the Service Provider. Only one active encryption certificate is supported.

      • Signing certificates are used to verify signed AuthnRequests sent by the Service Provider. Multiple certificates can be configured to support certificate rotation. When multiple signing certificates are configured, Trustbuilder checks each one until the AuthnRequest signature is successfully validated.

        EXPIRED CERTIFICATES: Encryption and signing certificates are flagged when expired. You must replace them as soon as possible.

4. Click Create.

5. Go to IdP Metadata tab to get the Trustbuilder IdP URL.

   

6. Go to your SP interface and provide the following URL to the Service Provider:
   ⚠️ The procedure defers depending on the SP.

   • Entity ID → Trustbuilder IdP identifier

   • Single Sign On URL → URL used by the SP to initiate SSO

   • Single Logout Service URL → URL used for SAML logout requests

   • You can also copy the full IdP Metadata URL from the header.

CURRENT LIMITATION
When importing metadata, certificates are not imported. This can cause an “invalid certificate” error even if the certificate is valid.

Workaround: Import or copy/paste the certificate manually in SP certificates by clicking + Add certificate.

CODE

-----BEGIN CERTIFICATE-----
{PASTE_CERTIFICATE}
-----END CERTIFICATE-----

This is a temporary issue and will be fixed in a future release.