Overview

About Web SSO

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

It not only allows a quick set up 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:

User has to be created and activated in SmartRecruiters prior to logging in from an Identity Provider. This should be done by using our User API. You can find the detailed instruction on how to do it in our Creating new SSO-enabled user guide.

When you create the user in API:

a) when no ssoIdentifier has been specified, API will assign default one, based on user’s email – this is not  recommended – please set the ssoIdentifier when creating the user via API

b) when ssoIdeintifer has been specified, the defined one is used

User Binding:

The ssoIdeintifer needs to be exactly the same (case sensitive) in your IDP application and in SmartRecruiters system. This can be achieved in 3 ways:

1. ssoIdeintifer in SR can (and should) be assigned straight away at the moment of user’s creation in  SmartRecruiters when you create the user in our User API (as in User Provisioning above). You can find detailed instruction 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 with request body:

1
2
3
4
5
6
7
[
  {
    "op":"add",
    "path":"/ssoIdentifier",
    "value":"sso_identifier_for_the_user_usually_email"
  }
]

You can find detailed instruction 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 user logs in, the IDP identifier is bound to logged in account.

The next attempt to login via IDP to SmartRecruiters will recognize this identifier with the user that logged in this way and 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 logging process on your IDP’s side – this means that aaa@company.com can initiate logging process on your company’s IDP end, and when asked to login – user’s colleague bbb@company.com might do it. In this scenario aaa@company.com IDP user will be bound to bbb@company.com SmartRecruiters user.

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 it’s 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:

Callback is performed via POST method.

Direct log-in to SmartRecruiters

It’s possible for users to 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.