About Web SSO

SmartRecruiters has implemented a broadly supported industry standard for Web SSO – SAML 2.0.

It not only allows a quick setup and configuration but is also supported by a majority of Identity Providers on the market.

Key characteristics

Below are explained core SmartRecruiters SAML 2.0 implementation characteristics.

User Provisioning

The user must be created and activated in SmartRecruiters before logging in from an Identity Provider (IdP). This should be done by using our Users API. You can find detailed instructions on how to do it in our Creating new SSO-enabled user guide.

When you create the user in API:

• when no ssoIdentifier has been specified, API will assign the default one, based on the user’s email. This behavior is not recommended – please set the ssoIdentifier when creating the user via API
• when ssoIdeintifer has been specified, the defined one is used.

If you are using Okta for user provisioning, you may find this Okta-SmartRecruiters guide useful.

User Binding

The ssoIdeintifer is case sensitive and has to be exactly the same in your IdP application and in the SmartRecruiters system. This can be achieved in 3 ways:

1. ssoIdeintifer in SmartRecruiters can (and should) be assigned straight away at the moment of user’s creation in SmartRecruiters when you create the user in our Users API (as shown in the User Provisioning section above). You can find detailed instructions on how to do it in our Creating new SSO-enabled user guide.

2. ssoIdeintifer in SR can be changed by our Public API PATCH /users/{id} endpoint (https://developers.smartrecruiters.com/docs) with request body:

[
  {
    "op": "add",
    "path": "/ssoIdentifier",
    "value": "sso_identifier_for_the_user_usually_email"
  }
]

You can find detailed instructions on how to update the ssoIdentifier in our Updating ssoIdentifier guide.

3. Login binding: when SmartRecruiters is not able to recognize the identifier that IdP sends – the login form is presented. Once the user logs in, the IdP identifier is bound to the logged-in account.
   The next attempt to log in via IdP to SmartRecruiters will recognize this identifier with the user that logged in this way and the user will be signed in automatically without displaying a login page.
   Please note, that the system will bind this identifier with the user that will successfully login to SR, which might not necessarily be the one that initiated the logging process on your IdP’s side – this means that [email protected] can initiate the logging process on your company’s IdP end, and when asked to log in – user’s colleague [email protected] might do it. In this scenario, the [email protected] IdP user will be bound to the [email protected] SmartRecruiters user.

Signature Algorithm

Both RSA-SHA1 and RSA-SHA256 signature algorithms are supported for SP-initiated and IdP-initiated flows.

Assertion

For correct SAML 2.0 assertion, the NameId Format (nameId) and NameId Policy (nameIdPolicy) need to agree with the official SAML 2.0 standard, as per official documentation:

• the NameId Format: nameId format has to be either emailAddress or persistent (as per sections 8.3.2 and 8.3.7 of the documentation)

• the NameId Policy: NameIDPolicy needs to be correctly configured as per section 3.4.1.1 of the documentation

Callback

The callback is performed via the POST method.

Direct log-in to SmartRecruiters

Users also can log in directly to SmartRecruiters without going through an IdP.
In order to do it, a user must have an account set up within SmartRecruiters, ideally using the User API.

Federated logout

At the moment, Smartrecruiters doesn't support federated logout via Web SSO. This means, that logout from the platform destroys only the local session on the SmartRecruiters, but not the session on the IdP side. It's wide spread user experience from other IdPs like Google, Facebook, etc.

If you need to swap users using Web SSO, you have to either use Private browsing mode or logout from your account on the IdP side first.