Skip to main content
English (Canada) English (United Kingdom) English (Malaysia) English (New Zealand) English (Singapore)

Manage single sign-on (SSO)

Updated

Available for the following plans: Plus, Unlimited HR, Elite, Unlimited HR+Payroll
Available for the following HR plan: Platinum
Available for the following user access level: Admin, IT staff (via CSS Permission)

With SAML-based single sign-on (SSO), employees can access Employment Hero through an identity provider (IdP) of their choice. You can set this up through Microsoft Entra, Google, or Okta.

  Interactive learning

Demo: How to turn SSO on for your organisation

How to set up SSO SAML on Okta

Step 1: Set up your IdP

To begin, you should establish a connection between Employment Hero and Okta. To do this you will need to log in to the Okta Admin console and create a new app integration using the credentials below. For more information, refer to this article.
 

  1. Within the Okta Admin console, click the Applications menu.
  2. Click Create App integration.
  3. For the sign-in method, select SAML 2.0.
  4. Click Next. 
  5. Set up the SAML SSO general settings, including:
    • App name.
    • App logo (optional)
    • App visibility.
      Create SAML screen 1.jpg 
  6. Click Next.
  7. Configure your SAML using the following credentials:
    • Single sign-on URL: https://secure.employmenthero.com/sso/saml/consume
    • Audience URI (SP Entity ID): EmploymentHero
    • Default RelayState: Leave blank
    • Name ID format: Unspecified
    • Application username: Okta username
    • Update application username on: Create and update
    • Tick the checkbox called "Use this for Recipient URL and Destination URL.
    • Complete setup.
      SAML set up (1).jpg 
  8. After you have set up the Okta SAML SSO App, you will need to click on "View SAML setup instructions" and use the Identity Provider Single Sign-On URL, Identity Provider Issuer and X.509 certificate in the next step of your set up.
    SAML instructions.jpg 

Important

Your provider may ask for the following information to configure ‌the IdP:

Please note that the above URL is not an active URL and just needs to be input for the SSO set up process.

Step 2: Connect your IdP to your Employment Hero account
  1. Click the Settings button in the menu on the left-hand side of your homepage.
  2. Click the Single Sign-on button under the General Settings heading.
    Screenshot of homepage with Single Sign on settings button highlighted
  3. Enter your SAML Sign-on URL (you can find this in the View SAML set-up instructions screen in step 1).
  4. Enter your Issuer URL (you can find this in the View SAML set-up instructions screen in ‌step 1).
  5. Enter your Key x509 Certificate (you can find this in the View SAML set-up instructions screen in ‌step 1).
  6. Click Test Configuration & Save.
    Screenshot of the Manage SSO page with the input fields and Test configuration button highlighted
  7. You will be taken to Okta's login page.
  8. Enter your username and password, along with any additional security measures required by Okta.
  9. Once complete, you will be taken back to your Manage SSO page, where you will see a green Verified tick next to the SSO/SAML Configuration header.
    Screenshot of the Manage SSO page with verification tick highlighted
Step 3: Turn on Single Sign-on for employees
  1. Scroll down on the Manage SSO page, to the section titled SSO/SAML.
  2. Press the Not Enabled toggle on the right-hand side.Screenshot of SSO oage with Not enabled toggle highlighted
  3. An email will automatically be sent to all employees with a company email address linked to their account. They will now be able to use Single Sign-on.

How to set up SSO SAML using Google

Step 1: Set up your IdP

To begin, you should establish a connection between Employment Hero and Google. To do this you will need to log in to the Google Admin Portal and create a new app integration using the credentials below. For more information see this link. 

  1. Navigate to the Google Admin Portal.
  2. Click Web and mobile apps on the side menu.
  3. Click Add custom SAML app from the drop-down Add App menu.
  4. Type in your preferred App name for Employment Hero SAML SSO and click Continue.
      Add custom SAML app 
  5. Following Option 2, copy the SSO URL, Entity ID and Certificate to be used later. Click Continue.
    Add custom SAML screen 2.jpg 
  6. Under the Service provider details, input the following details:
    ACS URL: https://secure.employmenthero.com/sso/saml/consume
    Entity ID: EmploymentHero
    Custom screen 3.jpg 
  7. Click Continue.
  8. You will not be required to do attribute mapping. You can finish the setup process by clicking Finish.
      Custom screen 4.jpg 
Step 2: Connect your IdP to Employment Hero
  1. Click the Settings button in the menu on the left-hand side of your homepage.
  2. Click the Single Sign-on button under the General Settings heading.
    Screenshot of homepage with Single Sign on settings button highlighted
  3. Enter your SAML Sign-on URL (you can find this in the View SAML set-up instructions screen in step 1).
  4. Enter your Issuer URL (you can find this in the View SAML set-up instructions screen in ‌step 1).
  5. Enter your Key x509 Certificate (you can find this in the View SAML set-up instructions screen in ‌step 1).
  6. Click Test Configuration & Save.
    Screenshot of the Manage SSO page with the input fields and Test configuration button highlighted
  7. You will be taken to Google's login page.
  8. Enter your username and password, along with any additional security measures required by Google.
  9. Once complete, you will be taken back to your Manage SSO page, where you will see a green Verified tick next to the SSO/SAML Configuration header.
    Screenshot of the Manage SSO page with verification tick highlighted
Step 3: Turn on Single Sign-on for employees
  1. Scroll down on the Manage SSO page, to the section titled SSO/SAML.
  2. Press the Not Enabled toggle on the right-hand side.Screenshot of SSO oage with Not enabled toggle highlighted
  3. An email will automatically be sent to all employees with a company email address linked to their account. They will now be able to use Single Sign-on.

How to set up SSO SAML using Microsoft

Step 1: Create a new application

To begin, you should establish a connection between Employment Hero and Microsoft. To do this you will need to log in to the Microsoft Entra admin center and create a new app integration using the credentials below.

  1. Sign in to the Microsoft Entra admin center.
  2. Click the Applications menu, then Enterprise Applications, then All Applications.
  3. Click New Application.
    Microsoft Entra admin 1.jpg
  4. If you are redirected to Browse Microsoft Entra Gallery, select Create your own Application.
    Create your own application
  5. Enter a name for your Employment Hero SSO Application.
  6. Click on the checkbox: Integrate any other application you don't find in the gallery (Non-gallery).
  7. Click Create.
    Create new application (1).jpg

    Important

    Do not select any app suggested by Microsoft, such as "Employment Hero", even if it matches your entry. Since you are creating your own application for your specific requirements, it's important to avoid selecting these suggestions.
Step 2: Configure the application
You will now configure your newly created app for SSO. To do this:
  1. Select Single sign-on from the side bar.
  2. Select SAML.
    Select SAML
  3. Click Edit next to the application you created.
    Basic SAML configuration.jpg
  4. Configure your SAML configurations with the following Identifier(EntityID): EmploymentHero 

    Reply URL ( Assertion Consumer Service URL): https://secure.employmenthero.com/sso/saml/consume

    Sign-on URL: https://secure.employmenthero.com/sso/saml/initBasic SAML Config.jpg

  5. Once completed, copy the following information provided by Microsoft Entra to set up your SSO on Employment Hero:
    - Login URL
    - Microsoft Entra Identifier
    - Logout URL
    Copy information

Step 3: Connect the application to Employment Hero
  1. Click the Settings button in the menu on the left-hand side of your homepage.
  2. Click the Single Sign-on button under the General Settings heading.
    Screenshot of homepage with Single Sign on settings button highlighted
  3. Enter your SAML Sign-on URL (you can find this in the View SAML set-up instructions screen in step 1).
  4. Enter your Issuer URL (you can find this in the View SAML set-up instructions screen in ‌step 1).
  5. Enter your Key x509 Certificate (you can find this in the View SAML set-up instructions screen in view ‌step 1).
  6. Click Test Configuration & Save.
    Screenshot of the Manage SSO page with the input fields and Test configuration button highlighted
  7. You will be taken to Microsoft's login page.
  8. Enter your username and password, along with any additional security measures required by Microsoft.
  9. Once complete, you will be taken back to your Manage SSO page, where you will see a green Verified tick next to the SSO/SAML Configuration header.
    Screenshot of the Manage SSO page with verification tick highlighted
Step 4: Turn on Single Sign-on for employees
  1. Scroll down on the Manage SSO page, to the section titled SSO/SAML.
  2. Press the Not Enabled toggle on the right-hand side.Screenshot of SSO oage with Not enabled toggle highlighted
  3. An email will automatically be sent to all employees with a company email address linked to their account. They will now be able to use Single Sign-on.

Dual Certificate Support

How to add a secondary certificate

Employment Hero supports dual certificates to ensure zero downtime during certificate rotation. This allows you to upload a new certificate while the existing one remains active.

  1. Navigate to Settings > SSO.
  2. If one certificate is already configured, you will see an option to Add another certificate.
  3. Upload your secondary certificate and click Test Configuration & Save.
  4. The system will verify each certificate independently. Authentication will succeed as long as one of the configured certificates is valid.
Understanding certificate status and health badges

When viewing your SSO configuration, the platform displays visual indicators for your certificates:

  • Active Badge: A green "Active" badge identifies which certificate was most recently used to successfully verify a user or configuration.
  • Expiry Badges: Colour-coded badges indicate the time remaining until a certificate expires:
    • Green: More than 60 days to expiry.
    • Yellow: 14 to 60 days to expiry.
    • Red: Less than 14 days to expiry or already expired.
Safe certificate deletion

To prevent accidental system lockouts, Employment Hero includes validation safeguards for certificate removal:

  • When you attempt to delete a certificate, the system will re-verify the remaining certificate.
  • If the remaining certificate fails verification (e.g., it is expired or invalid), the system will block the deletion and notify you that a valid certificate must remain in place.

General information about Single Sign-on

Can I use any other identity providers?
Currently, you can use Okta, Google and Microsoft.
Will my employees be able to Single Sign-on to Employment Hero via the app dashboard of our IDP provider (Okta, Google, Microsoft)?
Yes, once you’ve created the Employment Hero SSO application on your chosen IDP and assigned it to your employees, they will be able to sign in directly from the app dashboard of your preferred IDP.
What happens when my organisation is no longer on a Single Sign-on supported plan?

The SSO feature will be automatically turned off, and those with administrative or ownership privileges will be informed of this automatic process. Additionally, impacted users will be notified of the changes to how they log in.

Will an employee going through onboarding be required to use single sign-on?
Single Sign On will not be enforced on your new employee who are still going through onboarding. However, when an employee has finished onboarding or have passed their employment start date, they will be required to use single sign-on.
Can I grant access to SSO settings without giving full Admin rights?
Yes. A specific CSS Permission for "Single Sign-On (SSO) Settings" can be granted to IT staff or other users. This allows them to manage, update, and enable/disable SSO configurations without requiring full administrative access to the platform.

Troubleshooting issues during setup

Why is my Key X-509 Certificate not working?
Check that you have included the entire certificate, including the "----BEGIN CERTIFICATE----" and "-----END CERTIFICATE----" sections. 
Why does a user need to complete 2FA through ‌IdP and Employment Hero?
We cannot determine when a user finishes 2FA using the IdP or what 2FA regulations the client follows with their IdP. Therefore, we will still insist on users completing 2FA through Employment Hero to meet our high-security standards for 2FA.

Troubleshooting issues after setup

What should I do if my SSO certificate has expired and everyone is locked out?
Administrators or users with SSO Configuration permissions can use the Self-Service Recovery path. Navigate to the standard login page and use your Employment Hero credentials (email, password, and 2FA) to log in. You will be redirected to the SSO Enforcement page where you can temporarily disable SSO or upload a new certificate to restore access immediately.
Why have I lost the ability to edit my/other member’s company email?
As login is now associated with a member’s company email, we have restricted the ability to update this value to Admins and Owners only. This is to reduce the risk of a malicious update, which may result in a member being unable to log in or another user gaining unauthorised access.
What happens when an employee leaves the business if Single Sign-on is enforced on their account?
Once an employee is terminated in Employment Hero, SSO will no longer apply to their account. The terminated employee can still access their profile using their personal email and password, which they set up during onboarding.

Handling errors and multiple accounts

Where does Employment Hero log in users with multiple accounts across various organisations, all using the same SSO-enabled email?
The organisation with the lowest ID. The user will be able to switch between organisations upon successful authentication for that organisation.
Where does Employment Hero log multiple user accounts with the same SSO-enabled email, but in different organisations, when they need Single Sign-on into all?

The organisation with the lowest ID. Only one user will be able to log in via SSO, other users will have to:

  • Have SSO disabled in their other organisation, so they can login via account email and password
  • Have no company email in their other organisation, so then can login via account email and password
  • Have a different company email address in their other organisation so they can login via SSO using a different email address
Why are some employees getting error code 403: Error: app_not_enabled_for_user ?

If some employees encounter an error saying the app is not enabled for user, please ensure the Employment Hero app is assigned to the user in Google Workspace. You can manage which Google Groups/Organisational Units the app is enabled for by navigating to Google Workspace Admin -> Apps -> Web and mobile apps -> Employment Hero -> User access.  For more information on how to set up Google SSO, see Google's support page.
error message.jpg

Related articles