Setting up single sign-on

Connect your own identity provider to Recruit, map your email domains to it, and decide whether everyone must sign in through it.

Single sign-on lets your staff sign in to Recruit with the same account they use for the rest of your systems, such as Microsoft Entra ID or Okta. Only a System Admin can set it up. Everything is done on one page: Settings then Security.

Before you start

• Recruit connects to providers that support OpenID Connect. This is the only type available. SAML is not supported.
• You need permission to register an application in your identity provider, because you will create a client ID and client secret there.
• Every person who will use SSO needs a user in Recruit first (see below). SSO proves who someone is. It does not create accounts or give anyone access.

Add an identity provider

Register a new application in your identity provider first. Recruit does not show a redirect address on its Security page, so ask HireRoad support for the redirect address to enter as the allowed redirect in your provider's application settings. Then collect three values from the provider: the issuer URL, the client ID and the client secret.

1. Go to Settings then Security and find the Single sign-on card.
2. Select Add provider (if you already have a provider, the button is below the list).
3. Fill in the Add SSO provider form. Every field is required.
4. Select Save. You will see "SSO provider saved." and the provider appears in the list with an Enabled badge.

Recruit asks your provider for the openid, email and profile scopes, so the provider must return the user's email address.

Map your email domains

A provider does nothing until at least one email domain points to it. On the same page, use the Domain routing card.

1. In Domain, type the domain, for example acme.com. Enter it without the @ sign.
2. In Provider, choose the provider from the list.
3. Select Add mapping.

Recruit trims spaces and ignores capital letters. A domain can be mapped once. If it is already mapped, you will see "This domain is already mapped to another provider." next to the field, and you need to remove the existing mapping before adding it again. The match is on the exact domain after the @ sign, so a mapping for acme.com does not cover mail.acme.com. Add each domain your staff use.

To remove a mapping, select the bin icon on its row and confirm with Remove mapping. People with that domain go back to signing in with a password.

Group-level domain mapping

If your organisation is the parent company of a group, the Security page also shows a Group SSO domain routing card to group administrators of the parent company. It works the same way as domain routing, but the Provider list contains your group's providers, so subsidiary users sign in through the right one. Within a group, one domain can point to only one provider. If you try to add a domain that is already mapped to a different provider you will see "This domain is already mapped to another provider in the group." Group administrators can also pick a subsidiary from the company selector at the top of the Security page to manage that company's own provider and domain mappings.

What your users see

The sign-in page asks for an email address first. When the domain is mapped to an enabled provider, the user gets a Continue with button for it and is sent to your provider to sign in. There is a Remember me for 30 days tick box next to it, and unticking it applies to SSO sign-ins too. Unless SSO is enforced, the user can choose Use password instead. Users can go back with Use a different email.

Test before you enforce

There is no test button. Test by signing in.

1. Open a private browser window and go to the Recruit sign-in page.
2. Enter the work email of a user who already exists in Recruit and whose domain you mapped, then select Continue.
3. Check that Continue with and your display name appears, select it, and complete the sign-in at your provider.
4. You should land in Recruit signed in as that user.

Do this with at least one person other than yourself, ideally with a different role, before enforcing.

Enforce single sign-on

The Enforce single sign-on card has one switch: Require single sign-on for all users. When it is on, password sign-in is disabled for people whose email domain is mapped to a provider. A password attempt returns "You must sign in with single sign-on". You will see "SSO enforcement updated." when the change saves.

Consequences to plan for:

• Enforcement follows the domain mapping. People whose domain is not mapped can still use a password, so an unmapped contractor domain is not locked out.
• It applies to you as well. Enforcing before the provider works can lock every mapped user out, including administrators. Test first, and keep the switch off until a colleague has signed in successfully.
• If enforcement is on and the provider is disabled, mapped users see "Your organisation requires single sign-on, but no provider is configured. Contact your administrator." and cannot sign in until you enable a provider or turn enforcement off.
• Turning the switch off puts password sign-in straight back.

Edit, disable or remove a provider

• Edit: select the pencil icon. You can change the display name, issuer URL and client ID. Leave Client secret blank to keep the existing secret, or type a new one to replace it, for example when the secret in your provider expires. Select Save.
• Disable or enable: select Disable on the provider row, and Enable to switch it back on. A disabled provider is never offered at sign-in, though its domain mappings stay in place.
• Delete: select the bin icon and confirm with Delete provider. Users routed to it can no longer sign in with SSO. Turn enforcement off first if those users would otherwise be left with no way in.

How users are matched

Recruit matches the person by email address. The person must already exist as a user in Recruit, added through Settings then Users. A successful sign-in at your provider for an email that has no Recruit user is refused, and nothing is created. Role and access are always the ones set in Recruit.

Removing someone from your identity provider stops their next SSO sign-in. It does not end a session they already have open, so also remove their access in Recruit when someone leaves.

Errors and fixes