Overview
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 thessoIdentifier
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:
-
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. -
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.
- 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 eitheremailAddress
orpersistent
(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.
Updated 8 months ago