Using a SendSafely Workspace for Authenticated File Distribution with Zendesk Guide

This article outlines how to use a SendSafely Workspace for authenticated file downloads published through Zendesk Guide. Doing this allows you to leverage SendSafely in conjunction with Zendesk Guide to create an authenticated software distribution portal with product-level entitlements. Once configured, SendSafely will rely on Zendesk User Segments to determine which software products each user is entitled to access. 

Background 

A Zendesk Guide User Segment is a collection of end-users and/or agents defined by a specific set of attributes, used to determine access to Help Center content. User segments are the building blocks for user permissions that will be used to control access to different products. 

The most common way to manage segment membership is through the use of tags. You can create a tag for each segment, and then add that tag to a Zendesk user's profile in order to add them to the segment. Each user can belong to zero or more segments, so you can apply multiple tags to any given user to add them to multiple segments (or no tags to leave them out of all segments).  

In the following steps, we will outline how to define a specific user segment for each software product you want to distribute through the portal, and create a related article in Guide that can only be viewed by users within the corresponding user segment for that product. 

Within the Guide article, you will post a link to a SendSafely Workspace where the installation files for that specific product live (there will be a separate Workspace for each product). The list of users that have access to each Workspace will be synchronized with the User Segment Members from Zendesk to ensure that only authorized users have access.

Step 1 - Define Zendesk Product Tags 

In this step, you will create a tag for each product in Zendesk and add the tag to each Zendesk user that is authorized to download that product. This can be done from the user management screen (Admin > Manage > People).  You must have user tags enabled, for more information see Enabling user and organization tagging.

The screenshot below shows three end-users (customer1, customer2 and customer3) and three tags (product-1-users, product-2-users and product-3-users). Each customer is tagged with a single product. 

Step 2 - Define a Zendesk User Segment

Next, you will define a User Segment for each tag created in Step 1. Detailed instructions for doing this can be found here: 

https://support.zendesk.com/hc/en-us/articles/115007686307-Creating-user-segments-for-Guide-user-permissions-Guide-Professional-and-Enterprise-

The screenshot below shows three signed-in user segments, one for each product.

Note that for each segment, you should require the corresponding tag from Step 1 to indicate that the user is a member of the segment (refer to the Tags section in screenshot below). 

Step 3 - Create SendSafely Product Workspaces

Now, you will need to create a new SendSafely Workspace for each of the product segments. We recommend creating a dedicated service account (e.g. [e-mail]) in SendSafely and setting up the Workspace(s) under this account which makes the service account the Workspace Owner instead of an individual user account, which can create problems if the user leaves the company or as assigned to another team. 

Typically the Workspace should be named according to the product it represents and contain the current installation files for the product along with any other files you want to make available to users (user manuals, etc). You do not need to add any customers as collaborators to the Workspace as this will be handled automatically by the synchronization script in Step 6. You should take note of the shareable Workspace link (shown at the bottom of the Workspace screen) as this will be needed during the next step. 

Step 4 - Create Zendesk Guide Articles

In this step, you will create a Zendesk Guide article for each product and restrict access to its respective product segment. Detailed instructions on how to do this can be found here: https://support.zendesk.com/hc/en-us/articles/225031208

The screenshot below shows three articles (one for each product). Each article is restricted to its respective user segment (indicated by the blue box next to the article title). 

Note that within the content for each article, at the bottom of the page there is a “Download Now” link. This is a link to the SendSafely Workspace where the installation files are stored.

We recommend putting all of the product articles into a dedicated guide section (ie “Product Downloads”). If the logged in user does not have access to any of the articles in a section, then the entire section will not be visible. If the user has permission to view one or more articles in a section,  the section will become visible but only the accessible articles will be listed. 

Step 5 - Synchronize Workspace Collaborators and Zendesk Segment Members 

The last and final step is to run a script that will synchronize the list of Workspace collaborators in each of the product Workspaces with the list of segment members.

The script code (and installation instructions) can be found by clicking this link.

You will need to update the following properties before running the script: 

• ssHost - The URL to your SendSafely Portal 
• ssApiKey - The SendSafely API Key for the Workspace Owner account 
• ssApiSecret - The SendSafely API Secret for the Workspace Owner account 
• zdHost - The URL to your Zendesk Portal 
• zdAuthToken - The API Token for your Zendesk API User 

Additionally you will need to edit the tagToPackage array to reflect the name/value pairs associated with your product tags and the associated package ID for the Workspace containing the files for that product. The script can be run from the command line using the following syntax:

node ./SyncGuideToWorkspace.js 

Appendix - ZendeskSyncSendSafelyWorkspaces Script 

The full script source code and instructions on how to install its dependencies can be found in our Code Examples Github Repository.