Zephr User Guide

The Zephr OpenWeb SSO plugin provides an API endpoint with which one can conduct the server-to-server section of the OpenWeb Comments SSO flow.

Pre-Requisites

• OpenWeb admin account
• You will need to register the domain(s) on which you will be serving the OpenWeb Comments module in your OpenWeb account. At time of writing, this could be configured by signing into your OpenWeb admin account, then navigating to Settings > Advanced > Authorized URLs.

Configuring the OpenWeb SSO Extension

To enable the OpenWeb Extension within Zephr, navigate to Settings > Extensions > OpenWeb. If you cannot see the OpenWeb SSO option in your list of Extensions, email support@zephr.com.

Click into the OpenWeb SSO Config section. You will need to provide:

• An OpenWeb SSO Access Token
• Backend base URL (usually https://www.spot.im/api/sso/v1/register-user)

There are some further settings to control what data the extension will send to OpenWeb.

There is a checkbox to control whether user emails are shared with OpenWeb. Further to this, there are a number of text fields where you can nominate Zephr user schema fields to set:

• The OpenWeb user name (required)
• The OpenWeb display name (required)
• The OpenWeb user image URL
• User notification preference: notify when mentioned in a comment
• User notification preference: notify when a comment is liked
• User notification preference: notify when there is a reply to a comment

The fields nominated for user name and display name should be of type ‘Text’, the field for image URL may be of type ‘URL’ or ‘Text’ whilst the fields nominated for notification preferences should be of type ‘Checkbox’.

NOTE: It is your responsibility to ensure you have secured the necessary consent from your end-users to sign them into the OpenWeb Comments system when they sign into Zephr.

Once entered, click Done.

Activate Plugin

Once you’ve input the relevant details, confirm which of your Sites the extension should be active on. To do this, use the toggles for each site under the Activate Plugin section, or choose Select All Sites.

Once completed, click Save. Your extension is now enabled.

Using the OpenWeb SSO Extension

When the plugin is activated, a new HTTP listener will be registered at:
https://<tenant_id>.cdn.zephr.com/plugins/public/openweb/sso

Also (if you are using the Zephr CDN), the listener will be accessible at:
https://<your_domain>/plugins/public/openweb/sso

Your frontend should call this endpoint once the code_a code has been provided by the SPOTIM module. An example of this (based on the example flow from the OpenWeb SSO documentation) might look like this:

<div data-spotim-module="pitc"></div><script async data-spotim-module="spotim-launcher" src="https://launcher.spot.im/spot/{{spot-id}}" data-post-id="12345"></script>
<script>
    if (window.SPOTIM && window.SPOTIM.startSSO) {
        startSSO();
    } else {
        document.addEventListener('spot-im-api-ready', startSSO, false);
    }

    // Prior to initiating this function, ensure that the user
    // is actively logged into your site
    function startSSO() {
        var callback = function(codeA, completeSSOCallback) {
            // call your backend to receive codeB and return it
            // to OpenWeb via completeSSOCallback function
            fetch('{{base-url}}/plugins/public/openweb/sso', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({
                    code_a: codeA,
             }),
             credentials: 'include'
        }).then(res => res.json()).then(res => {
             if(res.codeB){
                 completeSSOCallback(res.codeB)
             }
          });
        };
        window.SPOTIM.startSSO(callback).then(function(userData) {
            console.log(userData)
        }).catch(function(reason) {
            console.error(reason)
        });
    }
</script>

The /plugins/public/openweb/sso endpoint expects headers and a payload like so:

POST /plugins/public/openweb/sso HTTP/1.1
Host: <your_domain_or_zephr_cdn_domain>
Content-Type: application/json
Cookie: blaize_session=<session_id>
Content-Length: 55

{
    "code_a": "<code_a_from_SPOTIM_module>",
}

• To authenticate the call, a Cookie header with the user’s session ID must be provided: if the Cookie header is omitted, or an invalid session is provided, a 401 will be returned. If you are using the Zephr CDN then the credentials: 'include' setting in the Fetch API should supply the relevant header.
• The code_a property is required in the payload: if it is omitted a 400 will be returned.

Please also remember to sign the user out from OpenWeb when the user is signed out of Zephr. You can find more details on how to do this here.