Single Sign-on (SSO) - How to Set Up

Step 1: Set up Citation HR Software as a service provider

Before you get started, you’ll need to set up Citation HR Software as a Service Provider in your Identity Provider. We have guides to do this for common providers (G-Suite, Active Directory and ADFS or Azure Active Directory), but your own configuration and setup might be different from what we have in those guides. Once you’ve done that, you’ll need to grab the Federation Metadata from your IdP.

Guides for setting up Citation HR Software as a service provider for:

• Google G-Suite
• Azure Active Directory
• Okta
• ADFS

IMPORTANT: Please pay particular attention to the ‘Attributes’, these need to match exactly with what is provided in the guides above.

Please Note: For clients planning to use Microsoft Azure for Single Sign On, please be aware that there may be additional costs involved with upgrading your Azure subscription to the Premium offering before SAML Single Sign On is made available for Azure.

Step 2: (Option 1) Prepare your Users and eSS Users (Current Clients who have previously launched eSS)

For SSO to work smoothly, you will want to ensure that your User and eSS User details are consistent between Citation HR Software and your IdP (Not the employee record, as they are already a User/eSS User)

You will need to check the following details match (they are case sensitive) between the two systems:

• Username (Usually the managers/employees work email address)
• First name
• Last name
• Email address

To assist you with this, we recommend you navigate to Reporting and the Security section. You can pull the User List Report for your Management Users, selecting All Branches. For your employees, you can use the User Role Report and select the eSS Role you use, if you don’t have a custom role it is likely to be either eSS Employee or eSS Employee (No Payroll). If needed, you can copy this report into Excel so you can review your data in Citation HR Software with ease.

OR

Step 2: (Option 2) Prepare your Users and employee records (New clients or those who haven’t launched eSS)

For SSO to work smoothly, you will want to ensure that your User and employee record details are consistent between Citation HR Software and your IdP. For your Management Users, follow the steps for Step 2, Option 1 above. As you haven’t launched eSS to your employees yet, you won’t have eSS Users so the system will use the data recorded against the employee record.

You will need to check the following details match (they are case sensitive) between the two systems:

• First name
• Last name
• Email address

To assist you with this, we recommend you navigate to Reporting and the Record Management section. You can pull the Record Export CSV report for Employee Records, so you can review your data in Citation HR Software with ease.

Considerations for new clients, prior to switching on SSO or launching eSS

If you are a new client setting up SSO as part of your initial setup, you will want to consider the timeframe for when you turn on SSO between Citation HR Software and your IdP. You won’t want to turn it on too early if you use the ‘AuthenticationOnly’ setting, as you won’t want to inadvertently give any users access to Citation HR Software prior to your launch (If they login to Citation HR Software from your IdP, a user will be created if their details are located on an employee record or they will be linked if their details are matched to a User). You will however want to test it to check that it is working as expected for your orgnaisation and your requirements. To do this, we recommend turning it on to test your setup, then turn it off again until you are ready.

You might want to read Step 4, before you complete any actions in Step 3.

Step 3: Switch on SSO within the settings of Citation HR Software

After you have set up Citation HR Software as a Service provider, you can switch on Citation HR Software's SSO and enhance the experience for all your users. Follow the steps below, each step will advise what to use for your settings under the SSO tab:

1.  Navigate to Settings then Account Settings

2.  Select the Security tab then navigate to the SSO tab

3.  Select your Identity Provide (IdP) from the dropdown list

4. Tick Enable SAML Identity Provider, this will activate SSO for your account (this is also where you turn it off)

Your SSO settings will apply from this point forward, unless you untick this setting again.

5. SAML Identity Provider – paste the contents of the .XML file you received from your IdP, this is the federation metadata

6. Select the Authentication Mode. This setting determines which system will be the source of truth and set the roles and permissions.

Choose between:

‘Access – The remote Identity Provider is used to determine permissions’ – The Identity Provider becomes the source of truth in terms of determining what roles & permissions are provisioned to the user on a login-by-login basis. Any existing roles & permissions are wiped and re-determined upon the next login attempt. Please see the note at the end of this article. (ADVANCED SETUP)

‘AuthenticationOnly’ – Citation HR Software is used to determine permissions’ – (RECOMMENDED) Citation HR Software becomes the source of truth in terms of determining what roles & permissions are provisioned to the user as per standard functionality. For new users accessing Citation HR Software for the first time, their roles & permissions are determined by the system's automation rules (accounting for the new user access selection below) with subsequent successful login attempts maintaining their roles & permissions in the system until changed by an Account Admin or someone with access to user permissions.

7. New User Access - if ‘AuthenticationOnly’ is selected above, this setting determines what type of user is created in Citation HR Software, when someone logins in for the first time from the client’s SSO page. The user will be created with the default settings for that type of Citation HR Software user in your account. There are three options:

• ESS – eSS Employee - (RECOMMENDED) - A new eSS user will be created in Citation HR Software. The eSS User will have the default Roles for your account provisioned. The eSS User may need to be linked to their employee record once the user has been created. If they are going to be a management user, they will need to have their User Access upgraded by an Account Admin, after the creation of the User.
• NONE – Do not assign default user access - This setting determines that any and all new users should be fielded into the Citation HR Software main application first but with no roles, permissions or branches assigned (essentially, authenticated but nothing else). Once the user profile has been created, it is expected that Account Admins manage the users roles, permissions and branches on a user-by-user basis.
• ENABLEHR – enableHR User – A new management user will be created in Citation HR Software. The management user will have the default Roles for your account provisioned, they will not be provisioned with access to any branches within your account. These will need to be updated by an Account Admin after the creation of the User. (You might want to use this option initially if you have a lot of Management Users to set up, you can then update it to ESS- ESS Employee)

8. Login URL - Specify the login URL for your application (in case the user needs to be asked to authenticate again) - This is typically the page that users need to navigate to (from the Identity Provider) in order to see the option for Citation HR Software which allows them to login. The login URL is typically also specified somewhere within the IdP Metadata.

Please note: If you want to use full authentication and authorisation with your IdP being the source of truth, you'll also need to reach out to our Client Support team who will work with you on mapping access between the two systems. (ADVANCED SET UP - not recommended for the majority of our clients).

Please note: If you want your Users and eSS Users to be able to login to Citation HR Software's login page using their SSO credentials, you will need to email our Client Support Team and provide your domain name used in your employees email address, e.g. CitationHR.com

Step 4: How SSO can assist with launching eSS to your managers and employees (New clients)

For your Management Users, you have 4 options:

• Create your Management Users individually in your Citation HR Software account, setting up their User Access Control. Get them to login to Citation HR Software through your IdP, they will be synced as an SSO User. (This is one of our two recommended options. We suggest you choose this option if you don’t have too many Management Users to create).
• Using the ‘ESS – eSS Employee’ option in Step 3.7, get your managers to login to eSS from your IdP for their initial launch of Citation HR Software. This enables you to stage their introduction to Citation HR Software into 2 controlled parts. Once they have done this, you can upgrade their eSS User to a Management User and apply the appropriate User Access Roles. (This is one of our two recommended options. We recommend using this if you either have a high volume of Management Users, or if you want to stage your launch so your Management Users initially access the system as an employee).
• Using the ‘ENABLEHR – enableHR User’ option in Step 3.7, get your managers to login to Citation HR Software from your IdP. They will be able to access both the Management side and eSS as an employee, however on the Management side they won’t have been provisioned access to branches, so they won’t be able to see any employee records until an Account Admin updates their Branch Access. They will have been provisioned with the default User Access Roles of your account, these may need amending to align with your organisation’s needs.
• Using the ‘NONE’ option in Step 3.7, get your managers to login to Citation HR Software from your IdP. They will be able to access both the Management side and eSS as an employee, however on the Management side they won’t have been provisioned access to branches or any User Access Roles, so they won’t be able to see any employee records or functionality until an Account Admin updates their User Access including Branches and Roles.

For your employees:

• Using the ‘ESS – eSS Employee’ option in Step 3.7, get your employees to login to eSS from your IdP for their initial launch of Citation HR Software.