Step 2: Create a Client Login Link

Overview

There are two main steps to providing login links to your users:

1. Generating a set of required values
2. Creating the login link based on those values

Step 1: Generating a Set of Required Values

In your existing dashboard, you must include a link or button that logs the user into 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 (e.g., 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. The signature should always be lowercase.
  • Example: ffba83a33623398b051d675060745ea3f48a1e4d

Optional values

In addition to the required values, you can also have the system generate any of the following values for a user:

• useSha256
  • This allows for the use of SHA-256 hash when generating the signature (sign). SHA-256 works the same way as SHA-1 but is stronger and more secure.
  • Example: true or false, if the parameter is not present the system will automatically default the value to false
• embed
  • This is a parameter that can hide the top navigation bar or the top navigation bar and sub navigation bar depending on the value provided
  • Example: nosubnav, true, or false. nosubnav will hide both the top and sub navigation bars. true will hide the top navigation bar. false will show both navigation bars. If the parameter is not present the system will automatically default the value to true.
• nav
  • This allows you to deep link to certain sections of the Yext dashboard.
  • Below are the accepted values and what they deep link to:
    

Below are three reference implementations for generating the signature: one in Python, one in Java, and one in C#:

Python

import hashlib
import time

def sessionUrl(accountid, code, timestamp, secret, nav, embed):
	messageDigest = hashlib.sha256()
	message = "{0:d}|{1:s}|{2:d}|{3:s}".format(accountid, code, timestamp, secret)
	messageDigest.update(message)
	signature = messageDigest.hexdigest()
	url = "https://www.yext.com/users/corplogin?accountid={0:d}&code={1:s}&timestamp={2:d}&sign={3:s}&useSha256=true"
	url = url.format(accountid, code, timestamp, signature)
	navParam = ""
	embedParam = ""
	if nav is not None and nav != "":
		navParam = "&nav=" + nav
	if embed is not None and embed != "":
		embedParam = "&embed=" + embed
	return url + navParam + embedParam;


def main():
	accountid = [insert accountid]
	code = [insert code]
	secret  = [insert secret]
	timestamp = int(time.time())
	nav = [insert nav]
	embed = [insert embed]
	print(sessionUrl(accountid, code, timestamp, secret, nav, embed))

if __name__ == '__main__':
	main()

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");  //"SHA-256" if useSha256 is set to true
    } 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();
}

Step 2: Creating the login link based on those values

After the signature is generated, pass the required values to www.yext.com/users/corplogin .

Example

https://www.yext.com/users/corplogin?accountid=78369&code=567A83&timestamp=1331847978&sign=ffba83a33623398b051d675060745ea3f48a1e4d

If using SHA-256 hashing algorithm:

https://www.yext.com/users/corplogin?accountid=78369&code=567A83&timestamp=1331847978&sign=ffba83a33623398b051d675060745ea3f48a1e4d&useSha256=true

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.