Summary
HandsHQ allows you to manage and authenticate user logins via Single sign-on (SSO). This means employees can use one set of login credentials to access multiple systems, including HandsHQ, which are managed centrally by your identity provider.
What's covered in this article?
Who can use this feature?
🏘 Supported on Small Team plans (previously Small Enterprise). Enforceable SSO is available on Enterprise plans.
👷♂️ Only account admins can configure SAML SSO
🔐 SAML SSO identity providers offered: Okta and Azure Active Directory
What is SAML Single sign-on?
Single Sign-on (SSO) allows users to log in to multiple applications or websites using the same identity provider (IdP). Security Assertion Markup Language (SAML) is a security standard for managing authentication and access.
What SSO providers can you configure on HandsHQ?
At the moment, HandsHQ allows SSO with Okta and Azure Active Directory.
You will need to use one of these identity providers to access this feature in HandsHQ. We are looking to expand the listed providers in the future.
Logging in to HandsHQ via SAML SSO
With single sign-on activated, the user will typically log in with the following steps:
On the HandsHQ login page, the user selects "Log in with SSO"
HandsHQ redirects the user to the identity provider
The user enters their SSO password
A 2FA request will also show if this is enabled on your IdP
If the user is set up in your identity provider, they will successfully log in to HandsHQ
Note: the user needs to be set up in your identity provider first and assigned to HandsHQ for logins to be successful via SSO
The first time a user logs in to HandsHQ via SSO:
If the user account previously existed in HandsHQ:
The user account will be integrated with the IdP and user will successfully log in
If the user account didn't exist previously in HandsHQ:
A new user account will instantly be generated in HandsHQ
For multi-division accounts: the user account will be generated, but they won't be assigned to any division. See more in the "Setting up new users with SAML SSO" section below.
Enabling single sign-on for your HandsHQ account
Note: you need to be an account administrator or owner to enable single sign-on
To set up single sign-on:
Contact your customer success manager
We will need your email domain(s) to configure the feature on our end
Your CSM will confirm when SSO is turned on your account
Go to Settings (in the parent division 🏠 if you have multiple ones)
Go to the Single sign-on tab
Tick "Enable Single sign-on"
Follow the setup guides below for further instructions on how to configure SSO depending on your provider
Enforcing SAML Single sign-on
🏘 Available on Enterprise plans
Even with SSO enabled, your users will still have the option to log in to HandsHQ using a traditional email and password as their login credentials.
If you want to block users from bypassing SSO, you can choose the option to enforce SSO on your account. This means users will only be able to log in via SSO, and any other login credentials will be disabled.
Simply navigate to Settings > Singe sign-on > tick "Enforce SSO"
Setting up new users with SAML SSO
Account admins can still create and invite new users to HandsHQ via Settings > Users as before.
However, for SAML SSO to work successfully, the user will also need to be set up in your identity provider and assigned to HandsHQ. If the user doesn't exist in the identity provider, they will not be able to log in using SSO.
HandsHQ uses just-in-time provisioning to instantly create a new account the first time a new user logs in via SAML SSO.
Option 1: Set up the user in HandsHQ first
Go to Settings > Users > Add user
Create the user profile, assign permissions and send the invite
Navigate to your IdP and set make sure the same user is set up and assigned to HandsHQ
The user will then be able to accept the user login invite using their SSO credentials
Option 2: Set up the user in your identity provider first
Navigate to your IdP and set up a new user, assigning them to HandsHQ (or assign an existing user to HandsHQ)
Okta configuration guide
Azure AD configuration guide
The user will be able to go straight to the HandsHQ login page and log in with SSO
For single-division accounts:
The user will be automatically logged in
The lowest level of access will automatically be given to the new user account
RAMS accounts: project editor access
Training register accounts: personnel viewer access
If the user needs a higher level of access, this can be edited by an admin in Settings > User
If your account has multiple divisions:
A user account will be instantly created
The new user will have no divisions or permissions assigned to them and thus won't be able to use HandsHQ
An email notification will be sent to all account admins to notify them a new user without permissions has been created
An admin needs to assign the new user to the right division(s) before they can use HandsHQ
To read more about setting up users in HandsHQ, here's our full guide.
Just-in-time provisioning
HandshQ uses Just-in-time (JIT) provisioning to allow users to be instantly created the first time they log in via an identity provider (Okta and Azure Active Directory). This eliminates the need to provision users or create user accounts manually.
Users provisioned JIT are created in the User section in HandsHQ. For a user to be created, their first name, last name, and email are required.
These fields will be filled in with data from the SSO response. This data must be configured in your IdP and made available through attributes or claims. More information on how to set it up is available in our Okta and Azure AD guides.