SCIM

👤 This documentation is intended for Site Administrators. 

SCIM integration is an add-on feature and Sisense for Cloud Data Teams currently supports Okta. SCIM (System for Cross-domain Identity Management) is not yet available (coming soon!) but once finalized, will be available only for sites which have both RBAC and Okta SSO.

Note: Before performing a large-scale change, please reach out to supportdt@sisense.com to best coordinate the necessary changes.

<UL>‍
<LI><a href="#Setup">Setup</a></LI>
<LI><a href="#Issues">Troubleshooting and Common Issues</a></LI>
<UL>
<LI><a href="#Errors">Errors</a></LI>
<LI><a href="#NoPrivileges">No Privileges</a></LI>
</UL>
<LI><a href="#SupportedBehavior">Features</a></LI>
<UL>
<LI><a href="#ProvisioningUsers">Provisioning Users</a></LI>
<LI><a href="#UpdatingUsers">Making Updates to Users</a></LI>
<LI><a href="#DeprovisioningUsers">Deprovisioning Users</a></LI>
</UL>
</UL>

<a name="Setup"></a>

Setup

1. If RBAC is not already enabled, this should be enabled first. Site Administrators should reach out to their CDT Account Manager to enable RBAC.

2. Once RBAC is enabled, site admins will need to compile a list of their existing user and role assignments. This can be done via the User and Role Management API. Having this information handy will be key to ensuring that users are set up with their current role assignments.

An example Python script using the API to pull user names, emails, and roles and write them to a CSV is below:

import requests
import json
import csv
#insert site host and api_key
finished = False
next_page_start = ''
header = ['login', 'firstName', 'lastName', 'email', 'roles']
site_host = 'site host here'
#open a csv file with write access
with open('userlist25.csv', 'w') as outfile:
   writer = csv.writer(outfile, delimiter=',')
   writer.writerow(header)
   while finished is False:
       headers = {
           'HTTP-X-PARTNER-AUTH':'site host here:api key here',
           'Content-Type' : 'application/json'
       }
       url = 'https://api.periscopedata.com/api/v2/users/?next_page_start='+next_page_start
       response = requests.get(url, headers=headers)
       response = response.json()
       #loop through each user in json response and grab first name, last name, and email
       for line in response['users']:
           user =(line['email']+','+line['first_name']+','+line['last_name']+ ','+ line['email'])
           #loop through roles for each user and join roles with semi colon for easy csv output
           roles = ';'.join(site_host+':'+role['name'] for role in line['roles'])
           #write the user and role data together to a CSV
           outfile.write('{}, {}\n'.format(user, roles))
       if response['next_page_start']==None:
           finished = True
       else:
           next_page_start = response['next_page_start']

3. Using the role assignment information pulled from the API, the IT administrator should then assign roles to users in Okta using the steps listed below in Making Updates to Users.

4. Once the users have their role assignments in Okta, the site admin should then enable SCIM via the Billing and Authentication page. If SSO is being enabled for the first time the site admin will need to log out of Cloud Data Teams and log back in with SSO. For full Okta SSO setup documentation please see here. Upon logging back in, the 'Enable SCIM Provisioning' checkbox will be available in the Billing & Authentication page. Click the box to enable SCIM provisioning. A secondary confirmation is also required by clicking on the 'Enable' button after reading the 'Enable SCIM' message.

5. Copy the site host and API Key string. Note: This key is only visible in this modal. After the modal is closed the key can only be regenerated, not recovered.

At least one email address will need to be added for provisioning alerts. If any provisioning errors occur the error messages will be sent to the email address(es) entered here.

6. After copying the API Key, the IT Administrator must navigate to the Sisense for Cloud Data Teams application in Okta and enable Provisioning. The user must be an administrator in Okta to perform these steps.

When SCIM provisioning is enabled, a Provisioning tab appears. Within the Provisioning tab enter the API key and enable the “Push New Users” and “Push Profile Updates” options.

If the Base URL and API key are set correctly the “Connector configured successfully” message will appear when testing the connector configuration.

From the “Provisioning” tab the IT Administrator will need to click ‘To App’ and click ‘Edit’ in the upper right corner.

The user will then select the necessary flows:

For Provisioning to work correctly, the IT Administrator must define a role and platform (if using CDT Self-Service Dashboards) attribute on the User. This can be done in the user's Profile within Okta. This is detailed below in Making Updates to Users.

<a href="#top">Back to top</a>
<a name="Issues"></a>

Troubleshooting and Common Issues

Within Okta, the 'Application username format' must be set to 'Email'. Sisense for Cloud Data Team does not support updates to the 'Application username format' as we do not support changes to user email addresses in app.

Errors

Error messages associated with SCIM will be sent to the email addresses specified in Step 5 of the Setup instructions above. The email will consist of a list of errors associated with the user. For example:

<a href="#top">Back to top</a>
<a name="NoPrivileges"></a>

No Privileges

In the above email message example, the site host listed for the roles assigned to the user was not recognized and the IT admin will need to make changes in Okta before that user will be able to access CDT successfully.  The user will be able to login, however they will see this upon entry:

The above screen indicates that users are successfully able to access Sisense for Cloud Data Teams via Okta with SCIM however they have not been provisioned to any roles and therefore have no privileges.

Note: This behavior differs from sites that have Okta SSO enabled however do not utilize SCIM. Without SCIM enabled, when new users are provisioned in Okta the user is automatically added to the Everyone role and will have that level of access upon logging in for the first time. With SCIM enabled, users are not automatically added to the Everyone role - they must be granted any and all roles explicitly in Okta.

<a href="#top">Back to top</a>
<a name="SupportedBehavior"></a>

Features

<a name="ProvisioningUsers"></a>

Provisioning Users:

Cloud Data Teams only supports "just-in-time" user provisioning via SSO. A user will not exist in CDT until the first time they try to log in via SSO.

IT Administrators may see an error like the one depicted below in Okta until the user logs into CDT for the first time:

<a href="#top">Back to top</a>
<a name="UpdatingUsers"></a>

Making Updates to Users:

Roles are roles that exist in a site's Roles and Policies page including both the CDT default user roles (Everyone, Admin, Analyst, and Business User) as well as custom roles. Platforms are only relevant for sites with Self Service Dashboards and have one role, 'dashboards'.

To add a Role or Platform for a user in Okta, the user must first be provisioned in Okta. Once provisioned, the user will see the Sisense for Cloud Data Teams app in their Okta page.

At this point, the user will be able to login to Sisense for Cloud Data Teams, however they will not have any permissions, nor will they be able to see any data, until they are assigned a Role. Please see the above No Privileges section. To add a Role or Platform for a user in Okta, navigate to the user's profile in Okta and click on the 'Edit' button to edit.

Scroll down to the bottom of the profile where Roles and Platforms should now be available.

Roles and Platforms should be added in the following format: site_host:Role_name. Multiple roles should be comma separated. In this way, different Roles/Platforms can be added for different Spaces if a site has more than one Space available.

The site host can be found in the dashboard URL. i.e. if the URL looks like

https://app.periscopedata.com/app/example-site/10/example-dashboard-name

then the site host is example-site, and the Everyone role will look like this when entered

example-site:Everyone

Note: Role and Platform entries are case sensitive, so if a Role has both upper and lower case characters in app these same characters should be entered in the Roles and Platform fields.

After saving, the assigned Roles and Platforms will be visible in the user profile in Okta.

The user will then have access according to the Roles/Platforms to which they have been assigned. If the user has already logged in they may need to refresh their browser to see this change in their permissions. If a user is provisioned but has not been assigned roles they will see the 'No Privileges' screen mentioned above under No Privileges.

Note: This behavior differs from sites that have Okta SSO enabled however do not utilize SCIM. Without SCIM enabled, when new users are provisioned in Okta the user is automatically added to the Everyone role and will have that level of access upon logging in for the first time. With SCIM enabled, users are not automatically added to the Everyone role - they must be granted any and all roles explicitly in Okta.

<a href="#top">Back to top</a>
<a name="DeprovisioningUsers"></a>

Deprovisioning Users:

If a user is removed from the Okta app or deleted in Okta, the user will be deleted in CDT.  This differs from deprovisioning users in Okta when SCIM is not enabled.

<a href="#top">Back to top</a>

Our support team is ready to help