About Web SSO using SAML protocol

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 the 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 ssoIdentifier 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 ssoIdentifier is case-sensitive and must be exactly the same in your IdP application and in the SmartRecruiters system. This can be achieved in 3 ways:

1. ssoIdentifier in SmartRecruiters can (and should) be assigned straight away at the moment of the 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. ssoIdentifier 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 recognise 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 recognise this identifier with the user who 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

RSA-SHA256 signature algorithm is supported for SP-initiated and IdP-initiated flows. Use of RSA-SHA1 is deprecated, and SmartRecruiters doesn't recommend its use. If your company is using this algorithm, we recommend updating it to RSA-SHA256. SmartRecruiters does not support RSA-SHA1 for new SSO configurations.

Assertion

For a 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 can also log in directly to SmartRecruiters without going through an IdP. To do this, a user must have an account set up in SmartRecruiters, ideally using the User API.

Single Logout

When Single Logout is enabled through the Web SSO configuration (and correctly configured in an Identity Provider), SmartRecruiters supports two types of logout flows:

• SP-initiated logout flow
• IdP-initiated logout flow

SAML SLO is supported only with the HTTP-POST front-channel binding.

Configuration

Single Logout is enabled or disabled through the Web SSO configuration. When enabled, the Identity Provider Single Logout URL is required. When the SLO is enabled, the metadata endpoint exposes the SmartRecruiters Single Logout configuration for use by Identity Providers.

Enabling Single Logout enables both SP-initiated and IdP-initiated logout flows.

Session Index

For the Single Logout to work, SmartRecruiters needs to receive a SessionIndex (a unique session identifier within the Identity Provider app) during the SAML login process. This value should be sent by the Identity Provider during a successful SAML login. If the SessionIndex is not received during login, SAML Single Logout won’t be possible, even if it’s enabled for the company.

The SessionIndex is received from the Identity Provider and is bound to the SmartRecruiters session for its lifetime. Please ensure your Identity Provider is correctly sending the SessionIndex during the login process.

SP-initiated logout flow

When a user logs out of SmartRecruiters, a Single Logout is initiated from SmartRecruiters to the Identity Provider. This happens after the user is logged out of SmartRecruiters (session and cookies are cleared), and only if:

• the user logged in to the current session using SAML,
• SmartRecruiters received a SessionIndex from the Identity Provider during the login flow.

The SessionIndex related to the current session is used to send a signed LogoutRequest to the Identity Provider during this logout flow.

If the IdP responds with a successful LogoutResponse, the user is redirected to the SmartRecruiters sign-in page, as in the usual logout flow.

If the IdP responds with an unsuccessful LogoutResponse, the user is redirected to the SmartRecruiters sign-in page with an error message indicating the failure.

IdP-initiated logout flow

When a user logs out of Identity Provider, a LogoutRequest is sent to SmartRecruiters. SmartRecruiters expects to receive a signed LogoutRequest with a single SessionIndex. LogoutRequest messages with an invalid signature are rejected. When the request is valid, the related sessions and cookies are cleared in SmartRecruiters, and a successful LogoutResponse is returned to the Identity Provider.

If RelayState is present in the incoming logout request, it's passed back to the Identity Provider along with the LogoutResponse.

If the Single Logout is configured and enabled, and any problems are encountered during the logout flow (like an invalid signature on the incoming LogoutRequest), a failed LogoutResponse is returned to the Identity Provider.

Mobile app support

The SmartRecruiters mobile app doesn’t support SAML Single Logout because it creates its own sessions in isolation. There are no pending Identity Provider sessions in the browser after the mobile app login completes.

Session expiration

If a session is removed by an action unrelated to the UI (for example, due to an internal session expiration), the SAML Single Logout is not performed – the SmartRecruiters session is removed as usual.