Signed-in Visitors

​

How it works

1. A customer signs in to your portal.
2. The widget asks your page for a token. Your page gets a token for the customer from your identity provider or from your backend.
3. The platform checks the signature, the issuer, the audience and the age of the token.
4. The platform reads the user id and the context parameters from the claims of the token, with the paths that you set.
5. The conversation starts. Functions in the flow read the context parameters as internal parameters.

​

Who can chat

​

Add a sign-in provider

​

Keys

​

What the token must have

• iss, equal to Issuer (iss).
• aud, equal to Audience (aud), or an array that holds it.
• exp and iat.
• The claim that User id path finds. It must be text that is not empty, or a number.

​

Map claims with JSONPath queries

{
  "sub": "user-123",
  "iss": "https://portal.example.com",
  "https://portal.example.com/claims": { "account": "A-1" },
  "x-tenant": "east",
  "profile": { "email": "a@example.com", "name": { "given": "Ada" } },
  "accounts": [
    { "number": "1001", "primary": true },
    { "number": "1002", "primary": false }
  ],
  "roles": ["a", "b", "c"]
}

​

Rules for a path

• A path starts with $, the root of the claims. Do not put a space before $ or after the end of the path.
• Use .name for a member whose name has only letters, digits and _, and does not start with a digit. For other names, use ['name'] or ["name"].
• [*] selects each element of an array, and .* selects each member of an object. Thus they find one value for each element or member. To select one element, use an index or a filter.
• A filter can use the functions of RFC 9535. For example, $.accounts[?search(@.number, '2$')].number finds "1002".
• A path has a maximum of 1000 characters.

​

Outcomes

• A path cannot fail on the claims. A comparison of two values of different types is false. For example, $.accounts[?@.number > 1000].number finds no value, because each number is text and 1000 is a number.
• A filter without a comparison only tests that the member is there. For example, $.accounts[?@.primary].number finds two values, because both accounts have primary. To test the value, write $.accounts[?@.primary == true].number.
• A path into a value of a different type finds no value. For example, $.sub.inner finds no value, because sub is text.
• An array or an object is one value. For example, $.roles is found, and gives the array ["a", "b", "c"].
• A JSON null is a value, so a path to null is found. A context parameter then gets null if its schema permits it.

​

The check when you save

• $., because the path ends with a dot.
• $.accounts[?@.number = '1001'], because a comparison uses ==, not =.
• $.accounts[?like(@.number, '1')], because RFC 9535 has no function like.

​

Map claims to context parameters

1. In Context parameters, click Add a parameter.
2. Select the parameter. To make a new parameter, type its name and select Add ‘name’.
3. Type the JSONPath query to the value in the claims, such as $.accounts[0].number.

​

Give the widget a token

<script>
  window.DialAI = window.DialAI || function () { (DialAI.q = DialAI.q || []).push(arguments) };
  DialAI("init", {
    tenant: "<tenant>",
    widgetId: "<widget id>",
    host: "https://<api host>",
    identity: async function () {
      // Your backend checks the portal session and returns a new token as text.
      const response = await fetch("/session/widget-token", { credentials: "same-origin" });
      if (!response.ok) return null;
      return (await response.text()) || null;
    },
  });
</script>
<script async src="https://<api host>/widget/loader.js"></script>

• Return a new token on each call.
• Return null when nobody is signed in.
• Return in less than 10 seconds. The widget counts no answer as null.
• Keep the token under 32 KiB.

​

Your backend can sign the token

1. Your backend checks the portal session of the customer.
2. It signs a JWT with HS256 and the shared secret of the provider. Or it signs with its own private key, and you give the public key or a JWKS URL to the provider.
3. It puts the verified values in the claims, for example the account number.
4. It returns the token to the identity function of your page.

​

Test the paths with Act as a customer

• Visitor id — Found, or the reason the sign-in fails:
  • “The path finds nothing in the claims. The sign-in fails.”
  • “Not an id. Use text that is not empty, or a number. The sign-in fails.”
  • For an ambiguous path, the number of values and the first values. For example, the user id path $.accounts[*].number on the example claims above gives The path finds 2 values: "1001", "1002". It must find one. The sign-in fails.
• Each context parameter — one of these:
  • Set.
  • “The path finds nothing in the claims”.
  • “Does not fit: …” with the schema problem.
  • For an ambiguous path, the number of values and the first values, then “It must find one, so the parameter is left out.”

​

When a sign-in fails

​

Best practices

​

Related