Articles in this section

Integration Instructions: Custom SAML

  • Updated

Supported Features

Chartbeat currently supports the following features:

  • Service Provider (SP) Initiated flow

Chartbeat does not support the following features:

  • Identity Provider (IDP) Initiated Flow
  • SAML JIT (Just In Time) Provisioning

 

Common Settings

SSO post-back up URL

Also known as the Assertion Consumer Service URL

https://chartbeat.auth0.com/login/callback?connection=CONNECTION_NAME

 

Entity ID

urn:auth0:chartbeat:CONNECTION_NAME

 

Considerations

  • Your IDP must ensure a user is both authenticated and authorized before sending an assertion. If a user isn't authorized, assertions should not be sent. We recommend your identity provider redirects people to an HTTP 403 page or something similar.

 

The CONNECTION_NAME is a unique identifier for your connection. It should only contain alphanumeric characters and hyphens and must be less than 128 characters in length.

We recommend that you include your company name as a part of the connection name to ensure that the name is unique. For example, Acme Corp may name their connection Acme-Login.

If you plan on setting up a TEST or STAGING connection first, give it the same connection name in Chartbeat as you plan to use for your live connection.

 

Certificates

Chartbeat requires that the SAML response is signed, and you will need to paste a valid X.509 Certificate to verify your identity.

Your Signature Algorithm should be set to RSA-SHA256 with a Digest Algorithm of SHA256.

 

Attributes

NameID REQUIRED

<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>

 

Email Attribute REQUIRED

<saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue xsi:type="xs:string">
userName@domain.com
</saml2:AttributeValue>
</saml2:Attribute>

 

First Name Attribute

<saml2:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue xsi:type="xs:string">
FirstName
</saml2:AttributeValue>
</saml2:Attribute>

 

Last Name Attribute

<saml2:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue xsi:type="xs:string">
LastName
</saml2:AttributeValue>
</saml2:Attribute>

 

Set up Chartbeat as a SAML 2.0 service provider (SP)

Once you’ve finished configuring your IDP, your Chartbeat organization Owner or an IAM Admin can finish the integration.

  1. Sign in to Chartbeat as your organization Owner or an IAM Admin.
  2. Hover over your avatar in the top right corner and click Settings.
  3. Click Authentication on the left side menu.
  4. Next to SAML authentication, click Set up.
  5. In the Connection Name field, enter the connection name you configured in step 1.

  6. In the SAML 2.0 Endpoint (HTTP) field, paste the SSO/Login URL. You can find this in the SingleSignOnService HTTP Redirect tag of your IDP-metadata XML file.

  7. In the X.509 Certificate field, paste the entire certificate from your IDP or located in your IDP-metadata XML file. This is an X.509 Certificate that’s required for SSO setup.

  8. Click Save.

You can access and review the SP-metadata generated by Chartbeat for your connection by going to https://chartbeat.auth0.com/samlp/metadata?connection=CONNECTION_NAME

 

Verifying that SSO is working

  1. Enable your connection by switching the connection from disabled to enabled.
  2. Go to Sign-in & Security
  3. Select Link Account. You should be redirected to your sign-in page.
  4. Enter your user name and password.

After your credentials are authenticated, you should be redirected back to the Sign-in & Security page. The SSO authentication section will now say that you’re authenticated.

 

What happens when SSO is enabled

After you’ve enabled SSO, users on your account will be able to bind their Chartbeat account with your IDP on the Sign-in & Security page. New Chartbeat users to your organization will also have the option to sign in using SSO when they activate their account.

By default, we will not force your team members to log in with SAML SSO. To require all users in your organization log in to Chartbeat using SAML SSO, learn more about enabling enforced SSO.

Once a user sets their authentication method to SSO:

  • Two-factor authentication (TFA) will be delegated to your identity service and no longer managed through Chartbeat. Please refer to your identity provider’s documentation on how to manage TFA.
  • User passwords will no longer be managed through Chartbeat. If a user attempts to reset their Chartbeat password it will have no effect. Please refer your users to your internal help desk for assistance recovering their SSO account for your IDP.

Related articles