- General information about the technology
- Basic information about integration
- Example 1: EddyDesk+ OneLogin
- Example 2: EddyDesk + Okta
- Debug mode in EddyDesk
- Customizable attributes: departments_ids, custom_group_id, custom_departments_ids. Mapping groups and departments.
1. GENERAL INFORMATION
SSO (Single Sign-On) is a single sign-on technology, through which a user can visit many different services with just one account.
SAML is a popular XML protocol for SSO implementation. Typically used in large organizations (enterprise) as a proven and reliable option. In organizations where centralized database of users is used, the security policies, accordingly, access to content in the service becomes more secure and controlled.
There are three parties involved in authentication through SAML SSO:
- SAML identity Provider (IdP).
- SAML Service Provider (SP)
- user's browser (User Agent)
The scheme of interaction itself is presented on the figure below:
2. BASIC INFORMATION:
- Login occurs by email, NameID is described in metadata;
- There are 3 custom parameters (optional, if not specified they will not be updated):
- group_id - number, allows to change group on authorization;
- organization - a string, allows to change the organization for authorizations;
- name - a string, the full name, can be changed with authorization.
You can authorize in two ways:
- login from the system - additional login button on the login form:
- authorization from the service itself:
3. An example of integration through the OneLogin service (onelogin.com)
At the moment, you can integrate with EddyDesk by setting up and connecting the test connector SSO SAML, provided by OneLogin service. We plan to add our own EddyDesk connector application and simplify the integration to a few clicks.
1. Create an account at OneLogin service (email can be only at corporate domain, no Gmail or Yahoo)
2. Go to Administration:
3. And add the application:
4. Search for saml test and select SAML Test Connector (Advanced):
5. Next you will need to specify the name of the connector, a description if necessary, and save:
6. After saving, other settings of the connector will become available.
Let's touch on the basic settings regarding integration with EddyDesk.
The settings on the service side of the OneLogin, which are taken from EddyDesk (SP):
- RelayState (optional) - link for redirection in case authorization was from the service. You can leave it empty or specify direct link to Omnichannel or Knowledge base (if necessary).
- Audience (EntityID) - insert metadata from EddyDesk, also "Audience Restriction" - insert "Audience (EntityID)" field from SSO connection in EddyDesk.
- Recipient - the receiver of the login calls, aka "Single Sign On URL" or "ACS" or "Assertion consumer service URL", in this field we insert "Assertion consumer service URL (ACS)" from EddyDesk.
- ACS (Consumer) URL Validator* - link validator (protection). By default we put .* (point + asterisk).
- ACS (Consumer) URL* - calling to the login from the service. In this field add "Assertion consumer service URL (ACS)" from EddyDesk.
- Single Logout URL - link for call to logout (exit), this is "Single logout URL" from EddyDesk. To this link goes a call when leaving the service in the background (works differently everywhere). This is also the link where the user is redirected after successfully exiting from the EddyDesk logout button.
This data is taken from EddyDesk by creating SSO connection:
EddyDesk side settings (ldP), which are taken from OneLogin (Applications - Connector - SSO):
OneLogin terminology is used, the fields are numbered for convenience:
- Issuer URL - meta-information, this link contains all the necessary connection points. In EddyDesk the field is also called.
- SAML 2.0 Endpoint (HTTP) - is a link where EddyDesk redirects user to authorize in service. In EddyDesk the field is also called.
- SLO Endpoint (HTTP) - The link that sends the EddyDesk logout. In EddyDesk the field is also called.
- Certificate - there are other security methods, but currently EddyDesk only uses X.509 Certificate.
Add this data to the SSO connection in EddyDesk:
7. EddyDesk custom fields + OneLogin:
4. Example of connecting the integration via the Okta service (okta.com)
1. Sign up, log in to your account and create an application.
Okta settings:
1) Single sign on URL - the link to sign in to the service, this is "Assertion consumer service (ACS)" in EddyDesk. If you leave it unchecked, there will be another Recipient URL field it can also be filled with the same link.
2) Audience URI (SP Entity ID) - metadata, insert "Audience (EntityID)" field from EddyDesk.
3) Single Logout URL - Okta is not interested in EddyDesk side outputs. But they can drop user from system when you're logging out from their application, setting is optional (you may not use it) - "Single logout service (SLS)" field from EddyDesk. Since Okta does not fully support SLO, you can use a link with the ending /slo instead of /sls . The difference will be that the user will be logged out immediately, but if the SLO link is not specified on EddyDesk side, it will just switch to EddyDesk start page.
4) SP Issuer - Single logout service (SLS) field from EddyDesk. It is mandatory if SLO is used.
5) Certificate, it must be downloaded if SLO is used and you must add it to step 6 .
6) Certificate download field from step 5.
EddyDesk settings.
Necessary settings on EddyDesk side you can find in the settings of the created application:
1) RelayState - this field might be left blank. If you specify it, the user will be redirected there after authorization in EddyDesk.
2) Link to metadata and certificate. When going to View Setup Instructions the required data will be opened (see the following screenshot).
Then go to instructions.
3) Setup email.
View Setup Instructions:
2.1) Identity Provider Single Sign-On URL = SAML 2.0 Endpoint (HTTP) in EddyDesk;
2.2) Identity Provider Single Logout URL = SLO Endpoint (HTTP) in EddyDesk;
2.3) Identity Provider Issuer = Issuer URL in EddyDesk;
2.4) Certificate - plug the certificate into the EddyDesk.
After saving the settings and adding users for this application you will be able to login through the Okta service.
5. DEBUG MODE IN HDE
When debug mode is activated, transmitted attributes will be written in the log during authorization.
Can serve as an aid in setting up new connections by displaying exactly what information is being sent to EddyDesk.
Example:
Activated by the Debug mode button in the SSO connection in EddyDesk.
6. CUSTOMIZABLE ATTRIBUTES: departments_ids, custom_group_id, custom_departments_ids
departments_ids - the ability to define a list of accesses to departments. It accepts arrays. Passes department IDs to HDE.
Mapping groups and departments:
The same group or department can be assigned to different roles, or vice versa, different roles from SSO can assign the same group in EddyDesk.
ulti-digit attribute separator - parameter is used if the transmission is lowercase, for example the separator is a comma and the string "role,role2,role3" is transmitted. If not a string - only the first parameter will be read and there will be an attempt to divide it.
custom_group_id - allows to assign a group to user depending on SSO roles. Works on the first match of the role from SSO. What matters here is the order in which the group-role pairs are set in EddyDesk
I.e. if you pass custom_group_id = "admin;manager;operator", the user will get the Agent group because it is of higher priority in the list.
custom_departments_ids - allows you to set accesses to the departments on the basis of SSO roles. Adds all departments from all passed roles. The order does not matter.
So passing custom_departments_ids = "operator;manager" will give the user accesses to 7 departments, i.e. for both matches on "departments - role".
Example of settings on the OKTA side.
In the SAML Settings section of the application, add declaration of variables and specify what variables they should refer to - https://support.okta.com/help/s/article/How-to-define-and-configure-a-custom-SAML-attribute-statement?language=en_US
These fields will have to be created beforehand:
And specify the necessary values for the accounts