Implementing Single Sign-On
Yext’s APIs make it possible for you to deliver Yext features to your users entirely via our API interface. However, you may prefer to integrate a white-labeled version of the Yext platform into your existing user dashboard, giving your users direct access to their information in Yext.

To implement this alternative method, you need to include a link in each user’s dashboard login that opens the Yext platform and logs the user in to Yext. Upon logging in to your dashboard, the user is automatically logged in to the correct account in Yext without having to supply a username and password.

Prerequisites

The following steps vary depending on your account type. You can either have an Enhanced Dashboard account, Enterprise account, or a Partner Portal account.
NOTE: If you are a Yext Partner and are unsure if you are on Partner Portal or Enhanced Dashboard, please contact your Yext representative. We recommend configuring this directly against production since it’s read only. If you prefer testing in a sandbox environment first, please contact your Yext representative.

This guide assumes that you have already completed the following steps:

Enhanced Dashboard or Enterprise
  • Each location has been set up in Yext and has service for Listings or other Yext features.
    • You can complete these steps via the API:
    • You can also complete these steps manually through the Dashboard.
  • You have the the location ID (id in the Locations: List endpoint of the Knowledge API) of each location that will be using the integrated dashboard.
  • You have ensured that each location has at least one user associated with it that has location-level access permissions.
    • You can use the Users: Create endpoint to create a user for each location. The onType must be LOCATION. Either omit the sso field or set it to false. For most of our partners, the roleId is typically 20, Account Admin for Enhanced Dashboard Customers and 9, Account Manager for Enterprise Customers. Please see the Manage Users Guide for examples.
    • You can also use the Dashboard to create a user for each location.
  • Finally, your account must be explicitly configured by Yext Technical Operations to use this “single sign-on” option. Please contact your Yext representative to add this option to your account. Yext will provide you with a secret code (secret) that you will use to sign login requests, as described in the next section.

Partner Portal
  • Each customer account has been set up in Yext and has service for Listings or other Yext features. You can complete these steps in one of two ways:
  • You have the the account ID (accountId in the Accounts: List endpoint of the Administrative API) of each customer who will be using the integrated dashboard.
  • You have ensured that each customer account has at least one user associated with it that has account-level access permissions.
    • You can use the Users: Create endpoint to create a user for each customer account. The onType must be ACCOUNT. Either omit the sso field or set it to false. For most of our partners, the roleId is typically 20, Account Admin. Please see the Manage Users Guide for examples.
    • You can also use the Partner Portal to create a user for each customer account.
  • Finally, your account must be explicitly configured by Yext Technical Operations to use this “single sign-on” option. Please contact your Yext representative to add this option to your account. Yext will provide you with a secret code (secret) that you will use to sign login requests, as described in the next section.

Creating a client login link

There are two main steps to providing login links to your users: generating a set of required values and creating the login link based on those values.

Required values

In your existing dashboard, you must include a link or button that logs the user in to Yext. When a user clicks this link or button, the system should generate the following four values:
  • accountid
    • Your account ID with Yext. This value remains the same for every login link you create.
    • Example: 78369
  • code
    • Enhanced Dashboard and Enterprise Customers: the user ID for the customer who should be logged in (NOTE: if you have a 1:1 relationship between user and location, then the user ID should be equal to the location ID)
    • Partner Portal Customers: the account ID of the customer who should be logged in
    • Example: 567A83
  • timestamp
    • The current time, in seconds, since the epoch
    • Example: 1331847978
  • sign
    • The signature, explained below
    • Example: FFBA83A33623398B051D675060745EA3F48A1E4D
The signature (sign) should be the SHA-1 hash of “accountid | code | timestamp | secret“, hexlified (i.e., converted to a string where each byte is represented by two hex digits). This signature will be valid for 60 seconds on either side of the time in timestamp, but servers should be kept relatively on time. The signature must be generated on the server, which will need to keep track of the secret value. Below are two reference implementations for generating the signature: one in Java and one in C#:

Java
private static String sign(
    long accountid, String code, long timestamp, String secret)
{
    String message = String.format(
        "%d|%s|%d|%s", accountid, code, timestamp, secret);

    MessageDigest md;
    try {
        md = MessageDigest.getInstance("SHA-1");
    } catch (NoSuchAlgorithmException ex) {
        // SHA-1 is a built-in algorithm and should never be missing.
        throw new RuntimeException(ex);
    }

    byte[] digest;
    try {
        digest = md.digest(message.getBytes("UTF-8"));
    } catch (UnsupportedEncodingException ex) {
        // UTF-8 is a built-in charset and should never be missing.
        throw new RuntimeException(ex);
    }

    StringBuilder result = new StringBuilder();
    for (byte b : digest) {
        result.append(String.format("%02x", b));
    }
    return result.toString();
}
C#
private static String sign(
    long accountid, String code, long timestamp, String secret)
{
    String message = String.Format(
        "{0:d}|{1:s}|{2:d}|{3:s}", accountid, code, timestamp, secret);

    HashAlgorithm algorithm = SHA1.Create();

    byte[] digest = algorithm.ComputeHash(Encoding.UTF8.GetBytes(message));

    StringBuilder result = new StringBuilder();
    foreach (byte b in digest)
    {
        result.Append(b.ToString("x2"));
    }
    return result.ToString();
}

Putting it all together

After the signature is generated, pass the required values to https://www.yext.com/users/corplogin. Example:
https://www.yext.com/users/corplogin?accountid=78369&code=567A83&timestamp=1331847978&sign=FFBA83A33623398B051D675060745EA3F48A1E4D
This “signed” link could open the Yext platform in the same tab as your customer dashboard or in a new tab, depending on the desired experience.

Do not generate link upon page load: Because the link includes a timestamp, it should be generated after the user clicks your on-screen link or button to log in to Yext, not when the page is first loaded. Otherwise, the link may have expired by the time the user clicks it.

SAML

SAML (Security Assertion Markup Language) is the industry-standard SSO solution. If you are already using a SAML identity provider such as Okta, then you should authenticate via SAML rather than the signed-link method above.

You will add Yext as an app in your identity provider. Once the app is added, a user will be able to log in to their identity provider and choose to visit Yext. The identity provider will send Yext an assertion saying who the user is, along with a signature that Yext can verify.

Prerequisites

  1. Each location has been set up in Yext and has service for Listings or other Yext features.
    1. You can complete these steps via the API:
      1. Enhanced Dashboard Customers: see Administrative API for creating and adding service to a location
      2. Enterprise Customers: see Knowledge Manager for creating locations
    2. You can also complete these steps manually through the Dashboard.
  2. You have ensured that each location has at least one user associated with it.
    1. You can use the Users: Create endpoint to create a user for each location. The sso field must be set to true. The username field must match the user’s username in the identity provider. Please see the Manage Users Guide for examples.
    2. You can also use the Dashboard to create a user for each location.
  3. Finally, your account must be explicitly configured by Yext Technical Operations to use this “single sign-on” option. Please contact your Yext representative to add this option to your account. Once your account has been configured, you will be able to access a “SSO Configuration” page within your Account Settings. You will be able to access your Yext SAML assertion consumer service URL and Yext SAML audience URI (service provider entity ID) that will be needed by your identity provider. Yext will need the SSO Login URL, Id Provider URL, and Certificate from your identity provider. See the Okta example below.

Setting up a Yext App in your Identity Provider

The steps below describe how to set up a Yext app if your identity provider is Okta. The steps will be similar if you are using a different identity provider.
  1. Log in to the Okta admin interface.
  2. From the top menu, go to the “Applications | Applications” screen.
  3. Click the Add Application button.
  4. Click the Create New App button.
  5. Select SAML 2.0 as the type of application integration.
  6. For “General Settings,” select:
    1. App name: Yext
    2. App visibility: Check Do not display application icon in the Okta Mobile app.
  7. For “SAML Settings,” enter:
    1. Single sign on URL: https://www.yext.com/users/ssologin?businessId=<BUSINESS ID>
    2. Audience URI: https://www.yext.com/users/ssologin?businessId=<BUSINESS ID>
    3. All other settings can be left blank or at their defaults.
  8. Either ignore the optional “Feedback” step, or note that it is required to contact the vendor to enable SAML.
  9. Your new app should be ready for use, and the administrator should be redirected to the Sign On tab of the app details.
  10. In the Sign On tab of the app details, there should be a section that says, “SAML 2.0 is not configured until you complete the setup instructions.” Click the View Setup Instructions button in that section.
  11. We at Yext will need the three things shown on the new page that comes up:
    1. Identity Provider Single Sign-On URL (goes into the SSO Login URL field on the “SSO Configuration” page in the Dashboard)
    2. Identity Provider Issuer (goes into the Provider URL field on the “SSO Configuration” page in the Dashboard)
    3. X.509 Certificate (goes into the Certificate field on the “SSO Configuration” page in the Dashboard)
  12. Finally, assign the new Yext app to your users in Okta.
    • Please see step 2a under Prerequisites above. In Okta, the user’s username is their primary email address.