How to set up and manage single sign-on (SSO) integration

Delivery supports user Single Sign-on (SSO) both via Security Assertion Markup Language (SAML) or OpenID Connect protocol (OIDC), any of these two can be used to integrate with at your convenience. Once your Identity platform is configured you’ll need to open a ticket on the Satalia support desk so that the tech team can enable SSO functionality in the Control Room. Making any other changes on your Identity platform setup or removing it will also make it necessary to create a request on the Satalia support desk to re-configure the solution accordingly.

1. Client settings required for initial set up

When SSO SAML is set up on your platform, below are the settings that we’ll need to receive in order to integrate Delivery to your Identity platform:

1. Entity ID

2. Single Sign-on URL

3. Public certificate

In case of SSO OIDC we’ll need:

1. Client ID

2. Issuer URL

Please send these details to our tech team by raising a ticket on the support desk.

2. What to consider when setting up SSO

For user SSO login to work, default business role must be configured and kept enabled in the Control Room, otherwise you’ll see an error encouraging you to setup such a role. Default user role can be created at Setup - Roles -> Add New Role -> activate toggle button “Enable default business role”.

If you have multiple Delivery environments running (e.g. dev, test, staging, production) - we recommend to keep them and their user groups isolated from one another. This means you will need to prepare the set up for all 4 environments as per example above and send us multiple sets of settings as outlined in this section #1. You will also need to assign users to every group separately for every Delivery environment your users will be signing in. Please note that depending on your internal SSO and user group management policies we can also accept 2 sets of SSO settings, e.g.:

• The first one called pre-prod for dev, test and staging environments. 

• The second one called for production environment. 

However, such setup will mean that the same user in pre-prod will have the same ability to access Control Room in test and in staging environments.

Testing is as straightforward as clicking the “Continue with SSO” button on Control Room. Once a user authenticates against your Identity Platform in a separate pop up window, gets a successful login message and manages to see the landing page - you can be sure that SSO works. In the same manner, you can observe that SSO login to Delivery will not work when you remove a user from your Identity Platform user group.

3. How to troubleshoot

If you can’t see your new user in the list of Control Room Users page but you are sure they are assigned an appropriate group on your Identity Platform - make sure that SSO login for that user has been done first as user records in Control Room users page are created only on demand and not in advance.

If SSO login for a specific user does not work, double check your Identity Platform settings to see that the user was added to the correct group.

In case of receiving authorization errors on the landing page after the first SSO login, make sure the default business role has the necessary permissions set, which can be done by using the admin account and opening Roles page.

Also note that by design password-based login for the same account will stop working once a user logs in via SSO successfully. In such case a user should continue logging in with SSO.

Keep in mind that SSO user details on Control Room Users page are not allowed to be changed other than the assigned role. Therefore it’s recommended to delete and recreate the user via SSO if you need the same user with a different email set.

When changing an existing user’s email address on your Identity Platform and once they login via SSO, Delivery will treat them as a new user and a new user record will be created. Therefore it’s recommended to revisit the role for such a user if that needs changing from the default business role.

User entries from Delivery Control Room Users page can be deleted but this operation does not propagate to your Identity Platform. I.e. if the SSO user is not explicitly removed from your Identity Platform (or corresponding user group) but just removed from Control Room they will still be able to login via SSO and a new record of the user will be again created in Control Room. Only users with standard authentication type (email & password authentication) will not be able to log in after deletion. 

4. How to disable SSO integration

All authentication via SSO passes through your Identity Platform, so once you disable the setup in your Identity Platform’s settings page by unchecking the “enabled” checkbox or toggling back to disabled state or deleting the configuration - SSO will stop working. Removing all users from related Delivery groups in your Identity Platform will also make SSO logins stop working. Re-enabling or placing the users back to groups will enable SSO login functionality back.

5. How to migrate to another Identity Platform

If you need to deprecate existing Identity Platform setup and move to another one, please follow the steps outlined in section #1. Once we integrate Delivery against your newly configured Identity Platform setup, deprecated Identity Platform can be safely disabled on your side as outlined in section #4.