Articles in this section

Integration Instructions: OKTA

  • 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

 

Step 1: Set up OKTA as SAML identity provider (IDP)

  1. Log in to your OKTA account as an OKTA administrator.
  2. From the Admin console Home page, go to Applications > Add Application
  3. Select Create New App on the top right-hand side of the Application Directory.
  4. Set Platform to Web and SAML 2.0 as the sign on method. Click Create.
  5. Set “Chartbeat” as the App Name. Grab the logo from here and upload it to OKTA.
  6. Since Chartbeat does not support IDP-initiated flow, we suggest you do not display application icon to users in OKTA’s app portal.
  7. Enter the following values into the appropriate fields of the SAML Settings page.
    1. Single sign on URL: https://chartbeat.auth0.com/login/callback?connection=CONNECTION_NAME
    2. Audience URI (SP Entity ID): urn:auth0:chartbeat:CONNECTION_NAME
    3. Name ID Format: EmailAddress
  8. In the Attribute Statements section, set the name field to “email” and the value field to user.email (Please use all lowercase, i.e. "email", not "Email")
  9. (Optional) Add name attributes. OKTA can use name attributes to pass information to Chartbeat during user authentication.
    1. For the first name, set the name field to “first_name” and the value field to user.firstName
    2. For the last name, set the name field to “last_name” and the value field to user.lastName
  10. (Optional) Click Preview the SAML Assertion to generate a sample XML to verify that your provided settings are correct.
  11. On the next page finalize set up by selecting I’m an OKTA customer adding an internal app.
  12. Click Finish.
  13. You will be redirected to your app’s Sign On page. Click View Setup Instructions.
  14. Copy the Identity Provider Single Sign-On URL and put it in a safe place so you can access it later. Download the X.509 Certificate.

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.

 

Step 2: Enable Chartbeat SAML App

  1. Log in to your OKTA account as an OKTA administrator.
  2. From the Admin console Home page, go to Applications
  3. Select Chartbeat
  4. To turn Chartbeat SSO on for a user or group of users in your organization, click Assign followed by Assign to People or Assign to Groups.
  5. Choose which users or groups should have access to Chartbeat SSO and select Done.

Onboard your organization to Chartbeat SSO quickly and easily by importing your current Chartbeat user directory to OKTA using our SCIM API.

If you don’t have SCIM available to your organization using OKTA Lifecycle Management, export a CSV of your current Chartbeat user directory from our User Management interface to import into OKTA.

 

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

Once you’ve finished configuring OKTA as your IDP, your Chartbeat organization Owner or an IAM Admin can integrate OKTA with Chartbeat.

  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 Identity Provider Single Sign-On URL you copied at the end of step 1.
  7. In the X.509 Certificate field, paste the entire contents of the file you downloaded in step 1. This is an X.509 Certificate that’s required for SSO setup. You might need to rename the file extension to “.txt” so you can open the file with a text editor.
  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

 

Step 4: 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 organization’s OKTA 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 OKTA account.

Related articles