Authenticating Users via SSO
Single Sign-On (SSO) allows for users to pass between two systems without having to manually type in a username and password while maintaining trust between the two systems. Apart from the obvious of eliminating the need to remember multiple passwords or being accidentally locked out, SSO has numerous benefits, some are outlined below.
Configuring SSO in Cognise
To make a connection between your SSO Provider and Cognise, it's first necessary to create a new SSO application in your SSO provider. The individual steps for setting up a new application varies for each provider so consult your providers documentation you you are unfamiliar with setting up SSO applications using SAML 2.0.
Get the SSO config
First you will need to get two setting fields from cognise, you will use these fields later on when we set up the new SSO application. To do this, simply navigate to Cognise company settings by clicking Config in the main menu, and then SSO.
Once in SSO Config you will see two fields under SSO Setup tab, Reply URL and SP Entity ID, These settings will be asked for when setting up the SSO application.
Note: Reply URL is sometimes referred to as ‘ACS URL’ or ‘Single sign on URL’. Entity ID can be referred to as ‘Identifier’ or ‘Audience URI’.
Setup your SSO application
In your SSO provider create a new SSO application using SAML 2.0 with the fields provided in the previous step, and email as the Name ID.
During the setup it will ask if you want to map any attributes which can be sent to Cognise when users login. Cognise needs to be supplied three attributes to provision a license along with optional attributes which are added to a user’s profile.
Note: If your SSO provider uses a namespace for attributes leave this blank.
Below is a summary of the attributes which need to be and can be mapped:
Required Attributes
The user's first name should be mapped to ‘first_name’.
The user's last name should be mapped to ‘last_name’.
The user's email should be mapped to ‘email’.
Profile Attributes - these are optional
The user's role or job title can be mapped to ‘role’
The user's contact phone number can be mapped to ‘phone’
The date the staff member started at your company can be mapped to ‘start_date’ and must be in the format YYYY-MM-DD E.g. 1999-12-31.
The users business group (or commonly known as department in other systems) can be mapped to ‘primary_group’.
Meta Attributes
Meta fields already setup in Cognise can be mapped too.
To see what meta fields can be mapped for your company click on the ‘Attribute Mapping’ tab on the SSO Setup page and scroll to the bottom.
The profile and meta attributes will not be assigned to the users profile if the supplied attribute value is not valid or formatted incorrectly.
The user will still be logged in.
Setup in Cognise
After setting up the SSO application in your SSO provider you will be supplied with XML metadata. This XML needs to be pasted into SSO Setup tab.
To do this, simply navigate to the company settings by clicking Config in the main menu, and then SSO
Once in SSO Setup tab, paste the XML in the Update IDP Metadata field and click save
After clicking save two new read-only fields are displayed, just for informational purposes:.
You can now log out and test SSO is working for your company by visiting your company’s Cognise URL. You should automatically be redirected to your company’s SSO provider, authenticated and redirected back to Cognise as a logged in user.
Backdoor Access
If something goes wrong in the SSO setup process and you are not logged into Cognise you can use the Automatic link authentication method to get back in.
Navigate to your company's Cognise URL with /admin added at the end (E.g. company.cognise.com/admin).
Select Automatic Login from the two options displayed.
Enter your email address and click send. You will be emailed a one-time login link to get you back into cognise.