Legacy: Custom SAML authentication setup

Last Updated: September 27, 2023

🔍 Please note: This article is for customers on Standard Bundle, Enrichment, or Clearbit Platform plans.

Clearbit supports Single-Sign On (SSO) through SAML 2.0 authentication, increasing security, simplifying the login process, and reducing the risk of lost or forgotten login information.

The SAML 2.0 integration is designed to be vendor agnostic, meaning it is compatible with any identity provider (IdP) that supports a standard SAML configuration, including custom identity systems.

This article outlines how to configure a custom SAML application, regardless of provider.

SAML setup instructions by identity provider

If you use one of the identity providers listed below, follow the link provided for step-by-step instructions on how to set up SAML through that provider. Otherwise, read on.

Custom SAML authentication setup

Clearbit supports a wide range of SSO providers who support SAML 2.0, including home-growth sign-in solutions, assuming they meet the requirements detailed below.

Create a custom SAML application

Clearbit will provide the following input values when you set up your your custom SAML 2.0 app: 

  Description Other Names Example
Single Sign-On URL

This is the endpoint where Clearbit will send SAML Responses (containing Assertions).

The Clearbit team will supply you with this value during implementation.

Assertion Consumer Service URL

ACS URL

Consume URL

SAML Assertion Endpoint URL

Destination

Recipient

https://dashboard.clearbit.com/saml/pk_a1ab2ab3fabc1234ab123abcde1234a1/consume
Service Provider Entity ID

This is the unique, case-sensitive identifier used to identify Clearbit as the service provider.

The Clearbit team will supply you with this value during implementation.

SP Entity ID

Entity ID

Service Provider Issuer

Identifier

Audience

Audience Restriction

https://dashboard.clearbit.com/saml/pk_a1ab2ab3fabc1234ab123abcde1234a1/metadata

Required attribute mappings

Clearbit uses just-in-time (JIT) provisioning to create new users in your account when they are added to your SAML application and attempt to log in for the first time.

Clearbit requires that you map the following user attributes for all SAML app setups:

Attribute Clearbit Value
First Name firstName
Last Name lastName

 

*Clearbit does not support any other attribute mappings at this time.

Other required configuration fields

  • Name ID Format → Email Address - Clearbit uses the email address to identify users. If prompted, choose the email address name ID format during SAML application setup. 
  • Signed response → True - Clearbit requires that all SAML responses are signed. If they are not, Clearbit will not complete the authentication process and we will return an error message in our logs.

Share your configuration metadata

Clearbit requires specific configuration details in order to integrate with a custom SAML 2.0 application.

After you have created your custom SAML application, Clearbit will ask you to share the following metadata about your app:

  Description Other Names Example
Email Domain The email domain that Clearbit will enforce SSO SAML authentication on.   clearbit.com
Identity Provider SSO URL The single sign-on service URL that is initiated at the identity provider site.

IdP SSO URL

IdP Initiated URL

IdP Initiated SSO

https://acmeco.okta.com/app/acmeco_clearbit_1/abc4d5efghIjKLM6n789/sso/saml
Identity Provider Issuer The unique, case-sensitive identifier used by Clearbit to identify the provider of the custom SAML app.

Identity Provider

IdP Entity ID

Issuer

Identifier

http://www.okta.com/abc1d2efghIjKLM3n456
SP Certificate The public certificate used to validate the digital signature on this service provider's SAML Requests. X509 Certificate

-----BEGIN CERTIFICATE----

-----END CERTIFICATE-----

Enable SAML authentication

SAML authentication must be enabled by a Clearbit employee using the information you shared in the previous step.

Once you have successfully created the SAML app, assigned users, shared your app details with the Clearbit team, and are ready to enable SAML authentication, contact us and we will complete the setup process!

If you would like to coordinate the enablement and testing of your app, our team is happy to arrange a call to complete the setup together and answer any questions you may have.

Learn More