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?
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 https://duo.com/blog/the-beer-drinkers-guide-to-saml
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 we cannot find a match for any of these three 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. You can bypass this redirect and sign in with existing credentials only for user accounts with no SSO ID configured. While an SSO ID is configured on a user account, manual login with that username/password will not be accepted.
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 (requires premium license)
- Gmail with a Custom SAML App
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.
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
Note: To set up a 'Seamless' Sign On where employee's are taken directly into intelliHR (if already logged into SSO in an active session) from a link use https://yourtenant.intellihr.net/saml2/login.