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 User Registration base URL (usually https://www.spot.im/api/sso/v1/register-user)

There is also a setting to control whether the OpenWeb SSO integration shares user email addresses with OpenWeb.

NOTE: Regardless of whether this option is selected or not, 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,
                    // You will need to get the user name from the user or generate something for them
                    user_name: "<user_name>"
             }),
             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>",
    "user_name": "<user_name_from_user>"
}

• 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 and user_name properties are required in the payload, omitting these will result in a 400 being returned by the API.

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.