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 the Yext platform (the platform can also be white-labeled) into your existing user dashboard, giving your users direct access to their information in Yext.

We support two types of Single Sign-On (SSO) integrations: Signed Link and SAML.

Signed Link Single Sign-On

Prerequisites

Before utilizing Signed Link Single Sign-On, you must have completed the following steps.
  • You have created users in Yext (e.g. every user in your system can have a corresponding Yext user).
    • You can use the Users: Create endpoint to create a user. Please see the Manage Users Guide for examples. Alternatively, you can create Users manually in the dashboard.
    • Please take note of the ID (id in the Users: List endpoint of the Knowledge API) of the User that you create. You will need this ID when generating the Signed Single Sign-On Link. NOTE: if you have a 1:1 relationship between user and location/account, then the user ID should be equal to the location ID or account ID
    • For most clients, the roleId is typically 9 or 20, Account Manager. Please contact your Yext Account Manager if you require a custom role.
  • Your account has been explicitly configured by Yext Technical Operations to use the Signed Link Single Sign-On option. Please email apisupport@yext.com, with your Account Manager copied, to enable this for 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
    • The user ID for the customer who should be logged in.
    • Example: 567A83
  • timestamp
    • The current time, in seconds, since the epoch
    • Example: 1331847978
  • sign
    • 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.
    • Example: FFBA83A33623398B051D675060745EA3F48A1E4D
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 Single Sign-On

SAML (Security Assertion Markup Language) is the industry-standard SSO solution. If you are already using a SAML Identity Provider such as Okta or Active Directory Federation Services, then you should authenticate via SAML rather than the Signed Link method.

Specifically, we support IDP-initiated Single Sign-On POST Binding. We are expecting a signed SAML Response with a signed SAML Assertion which should be Base64 encoded. The NameID attribute should match the username of the Yext user (see below).

Prerequisites

Before utilizing SAML Single Sign-On, you must have completed the following steps.
  • You have created users in Yext (e.g. every user in your system can have a corresponding Yext user).
    • You can use the Users: Create endpoint to create a user. Please see the Manage Users Guide for examples.
    • The sso field must be set to true.
    • The username field must match the user’s username in the Identity Provider; the username should be the same value as the NameID which is passed in the SAML assertion.
    • For most clients, the roleId is typically 9 or 20, Account Manager. Please contact your Yext Account Manager if you require a custom role.
  • Your account has been explicitly configured by Yext Technical Operations to use the SAML Single Sign-On option. Please contact your Yext Account Manager to enable this for 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 Identity Provider URL (Identity Provider Entity ID) and Certificate from your Identity Provider.

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 two things shown on the new page that comes up:
    1. Identity Provider Issuer (goes into the Provider URL field on the “SSO Configuration” page in the Dashboard)
    2. 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.