Skip to content
English
  • There are no suggestions because the search field is empty.

Setting up single sign-on

Connect your own identity provider to Recruit and map your email domains to it, so staff sign in with their usual work account.

Connect your own identity provider to Recruit and map your email domains to it, so staff sign in with their usual work account.

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, added under Settings then Users. 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.
FieldWhat to enter
Display nameThe name your users see on the sign-in button, for example "Acme Corp". The button reads "Continue with" followed by this name.
Issuer URLThe address of your identity provider, copied from the provider. For Microsoft Entra ID it has the form https://login.microsoftonline.com/ followed by your directory ID and /v2.0.
Client IDThe application (client) ID from the app you registered in your provider.
Client secretThe secret value from the same app. It is stored encrypted and is never shown again after you save. Copy it from your provider when you create it, as many providers only show it once.

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. If you type a leading @ it is removed, so @acme.com is saved as acme.com.
  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.

If your organisation is the parent company of a group, group administrators of the parent company also see a Group SSO domain routing card. It works the same way, 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, and a clash shows "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 Keep me signed in 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. The user's own view is also covered in "Signing in with single sign-on".

Related articles