Single Sign-On (SSO) means that one centrally controlled identity can be used to access multiple third party applications. This type of authentication allows users in your organisation to rely on your own internal authentication system, such as your email provider, and seamlessly access all the different business systems in your environment with that single login.
In addition to setting up SSO, we also recommend whitelisting all of the intelliHR trusted domains to ensure communications from the platform are not marked as spam, to find out more read the following article: Amend the Organisation Settings; Name, logo, Email Form and Default Business Days.
This article covers:
- What does intelliHR support?
- What is SAML?
- How does intelliHR authenticate an incoming claim?
- Can users without SSO still log in with an intelliHR account?
- What Identity Providers have been tested?
- How do I configure the Service Provider (SP) settings?
- How do I access the Service Provider metadata XML file?
- How do I update the IdP certificate?
- Not sure how to get started. I don't have an IT team.
What does intelliHR support?
We support the Security Assertion Markup Language (SAML) 2.0 protocol as a Service Provider (SP). We support authorization but not user provisioning. This means you will be able to link user accounts from your Identity Provider (IdP) to your intelliHR user accounts (usually by email address), but we won’t be able to automatically create new users for you. This is because decisions need to be made by a human to set someone up properly in intelliHR, such as organisation structure, onboarding workflows and other data unlikely to be held in your IdP.
What is SAML?
Easy way to understand SAML roles and authentication flow with a simple analogy
SAML Roles and Authentification Flow
How does intelliHR authenticate an incoming claim?
When someone attempts to log into intelliHR from a SAML authentication flow, we check the incoming claim attribute NameID and create a session for a matching user account with the following rules. If a match cannot be found the next rule will be evaluated:
- If there is an intelliHR user account with an SSO ID configured that matches the incoming NameID
- If there is an intelliHR user account with a Primary Email Address that matches the incoming NameID
- If there is an intelliHR user account with the Username that matches the incoming NameID
- If there is an intelliHR user account with the Employee Number that matches the incoming NameID
If we cannot find a match for any of these four values, we throw an error for the user.
Once an SSO configuration is enabled, the login page will change allowing users to get redirected back to your identity provider (SP-initiated sign-on) rather than providing the normal username/password login form.
Can users without SSO still log in with an intelliHR account?
Yes, this is an organisational setting that can be controlled by your business.
Go to Settings >> System Settings >> Single Sign-On (SSO) >> See the image below
As a business, you can choose to allow logins via SSO only or allow logins via password and SSO.
- Allow login via password and SSO: With this option, users can select Sign in with SSO to sign in with those credentials or they can sign in with an intelliHR account (if the username and password have been provisioned for them). For example, a contractor requires access to intelliHR but is not set up with Single Sign-On as they do not require access to any other systems; the system admin can provide them with a username and password for intelliHR that they can use to manually log in.
- Allow Login via SSO only: Standard users will not be able to log in to intelliHR using any credentials other than their SSO credentials. The 'Sign in with intelliHR account' will remain on the page but users attempting to log in using this link will be presented with a message asking them to log in with their SSO credentials. System administrators will still be able to use this method to avoid issues with SSO preventing them from gaining access to the system in its entirety.
What Identity Providers have been tested?
We should be able to support any IdP that uses the SAML 2.0 protocol, but we have proven integrations with:
- On-premise Active Directory Federation Services (ADFS)
- Office 365 / Azure AD with the custom SAML connector
- Gmail with a Custom SAML App
- OneLogin
- Okta
*Google Specific Error during set-up
If during setup with Google you encounter the following error: Error:not_a_SAML_app
This is specific to Google SSO. If you just enabled your app and are trying to log in, you need to log out and clear your cache. Then log back in with the account that you are testing with. If you continue to get this error then you may need to wait a few minutes for Google to associate with the application.
How do I configure the Service Provider (SP) settings?
You will need two permissions on your intelliHR user account to use the configuration screen:
- Edit SSO IdPs
- View SSO IdPs
You will also need the following information from your Identity Provider, usually as part of creating a new SAML Service Provider configuration:
Entity ID - the unique identifier at the Identity Provider side, usually a URL. Allows the Identity Provider to know which configuration to use for processing an incoming SAML Request.
Single Sign-On URL - the URL at the Identity Provider we should redirect users to when attempting to use Service-Provider initiated sign on.
SLO Endpoint URL - the URL at the Identity Provider we should redirect users to when logging someone out of the intelliHR platform. Usually this is the same as the sign on URL above.
Name ID Format - usually configurable, often defaults to Persistent but defaults to Email Address for Google custom SAML apps. Must match what is configured at the Identity Provider side.
X509 Certificate - the public certificate used to sign SAML Assertions coming from the identity provider. Usually provided as a download as part of creating the SAML Service Provider configuration at the Identity Provider side. Can be found when visiting the Identity Provider metadata URL, which will provide an XML document that looks like the below:
AuthnContextClassRef - Allows you to configure multiple authentication methods that are allowed for Service-Provider initiated sign on. Usually User Name and Password should be configured. For windows domain joined computers also ensure Integrated Windows Authentication is allowed. Note: the AuthnContextClassRef can be ignored if it is not important what authentication method people use to login to Entra ID. This is the Microsoft recommendation.
Authn Comparison - Must be set to Exact for Azure AD. Most other Identity Providers should be set to Minimum.
How do I access the Service Provider metadata XML file?
Using the same root URL that your application is hosted from and appending /saml2/metadata will download the configured SSO metadata XML file
For example https://your-organisation.intellihr.net/saml2/metadata
How do I update the IdP certificate?
Maintaining an up-to-date record of your current IDP certificate on intelliHR will help you to ensure that users do not experience issues when logging into intelli.
Single sign-on settings can be found and managed in the settings area of your platform. We suggest providing access to your IT team to manage this and update the certificate when necessary. To provide an individual or group with access to the the SSO configuration on intelli navigate to:
1. Navigate to Settings >> Permissions
2. Click Create Group
3. Tick View & Edit SSO IdPs
4. Click Save
Not sure how to get started. I don't have an IT team
If your organization does not have an IT team that can assist in the set up of SSO but you are keen to begin setting this up the linked Google article below describes how you can begin setting up your own custom SAML application that is required before following the steps in this guide.
Setting up your own customer SAML application
Comments
0 comments
Please sign in to leave a comment.