Configure the Portable Web Client chat widget to run Virtual Agent on third-party web pages.

Before you begin

Note: For new customers onboarding from Vancouver onward, the web client is only accessible to authenticated users by default. To allow unauthenticated users to access the web client, you must enable the sn_va_web_client_app_embed page for public access. For more information, see Make UI pages public or private.

Role required: admin

About this task

ServiceNow only supports the Portable Virtual Agent when the top-level domain and domain name match the site that is loading the web client. SSO is only supported through the service-now.com URL. Anything beyond that will require custom solution and implementation.

Procedure

  1. Navigate to All, and then enter sys_properties.list in the filter.
  2. In the System Properties [sys_properties] table, search for the com.glide.cs.embed.csp_frame_ancestors property by name.
  3. Click the property name to open the form and specify the directive values.
    Field Description
    Type string

    This is the default value.
    Value Source value of the HTTP header directive: Content-Security-Policy:frame-ancestors<source>This property applies to most major browsers, except for Internet Explorer.
    Specify one or more sources, including the following:
    • 'self': Indicates that the origin is the same as the page being served. For example, if the value is 'self' http://mywebsite.com, then the iframe is embedded within the parent domain as well as mywebsite.com. This is the default value.
    • host-source: The domains in which the external web page can be embedded. Specify the Internet host site by name, IP address, or optional URL and/or port number. Site address can start with a wildcard (asterisk) character. Example value: http://*.example.com
    • scheme-source: A schema. For example: http: or https:
    • none: No matching URLs.

    For more information about source values that you can specify, see CSP:frame-ancestors and Virtual agent embedded client content security policy (instance security hardening) in Instance Security Hardening Settings.

  4. Return to the System Properties [sys_properties] table to search for the com.glide.cs.embed.xframe_options property by name.
  5. Click the property name to open the form and specify the directive values.
    Field Description
    Type string

    This is the default value.
    Value Value of the of the X-Frame-Options header directive, to indicate whether the browser can render an external web page in a frame.
    Specify one of the following values:
    • sameorigin: Displays the page in a frame that has the same origin as the page itself. This is the default value. This property applies to older browsers, such as Internet Explorer 11. Example value: allow from https://example.com
    • deny: Does not display the page in a frame.
    • allow-from uri: Displays the page only in a frame on the specified origin.
      Note: This value no longer works in modern browsers.

    For more information about source values that you can specify, see X-Frame-Options and Virtual agent embedded client X-Frame-Options (instance security hardening) in Instance Security Hardening Settings.

  6. Configure CORS Rules for the REST API to give access across domains.
    This rule gives the web domain you specify the rights to call the API that gives it access to the chat widget on the web page without a security restraint. All domains must share a common parent domain. Also, you must create a new CORS Rule for each subdomain that you want to support.
    1. Navigate to All > System Web Services > REST > CORS Rules.
    2. Click New.
    3. On the form, fill in the fields.
      FieldDescription
      Name Unique name for the rule.
      Application Scope of the application. Global is the default value.
      REST API Name of the REST API. Select Conversation Consumer Account [now/cs].
      Domain The domain for your website. For example: https://mycompany.com

      If you have multiple subdomains for your website, you must create a CORS Rule for each. For example, support.mycompany.com and products.mycompany.com would require two separate CORS Rules.

      Note: Wildcards are not allowed.
      Max age The number of seconds to cache the client session. After an initial CORS request, further requests from the same client within the specified time do not require a preflight message.

      If you do not specify a value, the default value of 0 indicates that all requests require a preflight message.
    4. On the HTTP Methods tab, select GET.
      The Portable Web Client will only receive requests.
    5. Click Submit.
    6. (Optional) Repeat these steps if you want to add the Portable Web Client to another subdomain on your website.
  7. (Optional) Create a JavaScript script that uses the window.postMessage() method (Web API) to define event conditions that trigger SSO authentication in a user interface page and returns users to a web client page that you specify.
    To redirect users to a web client page, use the following string: "https://<your-instance>.service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=’ + encodeURIComponent(<your-page>)
    Note: Before you run the script, use the com.glide.cs.web_client_login_redirect_urls system property to specify the URLs that can be passed in the script. The redirection works only when you specify one or more allowed URLs in the property value. Specify the full redirect URLs or the host part of the URL. For example: https://example.com .
    Example script
    <script>
    window.addEventListener("message", function(e) {
       // redirect to SSO login if the web client logs in but is logged in as a guest user(unauthenticated)
      if(e.data.type==="SESSION_CREATED" && e.data.authenticated === false)
        window.location.href = "https://<your-instance>.service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=<’ + encodeURIComponent(<your-page>);
      
      // redirect to SSO login if the ServiceNow platform logs out from underneath the web client
      if(e.data.type==="SESSION_LOGGED_OUT")
        window.location.href = "https://<your-instance>service-now.com/"https://<your-instance>service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=’ + encodeURIComponent(<your-page>);
    });
  </script>

    In this example, authentication is triggered in the specified instance when the SESSION_CREATED or SESSION_LOGGED_OUT events occur. After authentication (when the SSO credentials for users are accepted), users are redirected to the embedded web client page that you specified in sn_va-web_client_login.do?sysparm_redirect_uri=’ + encodeURIComponent(<your-page>), as long as you also specified the page URL in the com.glide.cs.web_client_login_redirect_urls property.

What to do next

Add the Portable Virtual Agent chat widget to a third-party website.