Manage SmartRecruiters user accounts and access at scale, on-demand

As you expand your organization and bring more users into SmartRecruiters, user management can be a daunting task, especially if your organization leverages multiple systems and softwares in the hiring or post-hiring process. The Users API enables you to programmatically manage your user profiles in SmartRecruiters that includes managing user roles, access groups to jobs and candidates and their sign-in experience.

Create User Accounts at Scale

In a mid to large size or enterprise company, you have to create a volume of users often because hiring team members come and go or new jobs opened and require new interviewers to be added onto the system. While SmartRecruiters offers a user management module within the SmartRecruiters back offices, it can be inefficient to add user one-by-one.

Using the CreateUser endpoint, you service can programmatically create SmartRecruiters users when other system's accounts are created at the same time.

Before you start building an integration for this use case, you may need to use the following Users API endpoints:

POST /user-api/v201804/users
GET /user-api/v201804/access-groups
GET /user-api/v201804/system-roles
PUT /user-api/v201804/users/id/activation

And be sure that the credential you obtained include the user_read and user_manage access scopes if you are using OAuth credentials.

If you are not sure how to obtain a SmartRecruiters API credential, read the authentication overview

There are many different ways to build the integration, below are some suggestions on key interactions with the endpoints:

  1. Before you create any users, be sure the appropriate SmartRecruiters system roles are properly defined within your back office. You will need to provide at least when creating a SmartRecruiters user and you can retrieve this property and value from the ListSystemRoles endpoint.
  2. Similar to system role, the access group of a user determines applications, candidates and jobs he/she has access to. So be sure the appropriate access groups the user need to use are properly defined within the back office. You can retrieve labels and values of access groups from the ListAccessGroups endpoint.
  3. Once you created a user, do not forget to activate the user account. An inactive user cannot sign into the SmartRecruiters back office.

Improve User Sign-In Experience with SSO

Another common use case amongst SmartRecruiters customers is that the hiring team members often interact with different systems and platforms (e.g HRIT systems or assessment solution provider) and would like to ensure these users have a smooth experience switching between systems.

To help provide this smooth system switching experience, you can configure SAML 2.0 enabled Web Single Sign-On (SSO) in SmartRecruiters so that your users only need to sign in once.

Before you start, be sure:

  • You have the appropriate system role to access the Web SSO module in the SmartRecruiters back office. You will need to obtain the SmartRecruiters metadata in that module.
  • You have or you know another user who access to your Identity Provider (IdP) services (e.g. Okta) or your Active Directory Federated Services (ADFS) Management tool on your ADFS server.

Generally, there are 3 parts to configure and enable SSO function for your users:

  1. Obtain SmartRecruiters metadata
  2. Import metadata into your IdP or ADFS configuration
  3. Bind users to corresponding ssoIdentifier

Obtain SmartRecruiters Metadata

  1. To begin, sign in to your SmartRecruiters account and find the 'Web SSO' module under the Configuration section of the 'Settings / Admins' page.
  2. Open the Web SSO module page and toggle on 'Enable Web SSO' switch.
  3. Select one of the two signature algorithms. Both RSH-SHA1 and RSA-SHA256 are supported for SP-initiated and IdP-initiated flows.
  1. Copy your IdP Url and certificate
    • If you are using an IdP, you can find both IdP Url from your IdP metadata
  • If you are using ADFS Management, you can find them under ADFS > Service > Endpoints > Section: Metadata.
  1. Paste the IdP Url and the certificate respectively into the Identity Provider Configuration section and click 'Save Web SSO configuration.

Import SmartRecruiters Metadata into IdP or ADFS Configuration

Depending if you are using IdP or ADFS, the steps on this part vary slightly

Configure in IdP

  1. From the same Web SSO module page, select 'Download SmartRecruiters metadata' and copy your SmartRecruiters metadata onto the clipboard.
  2. In your IdP, locate the function or module that manages service providers. And add a new service provider using SAML 2.0 XML metadata.
  1. Paste and import the SmartRecruiters metadata in your IdP configuration
  1. Add SmartRecruiters as a new service provider and save the configuration

Configure in ADFS

  1. From the same Web SSO module page, select 'Download SmartRecruiters metadata' and save it as an XML file. Be sure this XML file is locally available to your ADFS server.
  2. Open ADFS Management module on your ADFS server and navigate to Relying Party Trusts under ADFS > Trust Relationships and select 'Add Relying Party Trust'
  1. Click 'Start' and select 'Import data about the replying party from a file' and add the SmartRecruiters metadata XML file and click 'Next'
  1. Add SmartRecruiters as the display name
  1. Click 'Next' on the next few steps and click 'Finish' on Ready to Add Trust step
  2. Right-click on SmartRecruiters and select 'Edit Claim Rules' to add more rules
  1. In the Claim rule template, select 'Send LDAP Attributes as Claims' and click 'Next'
  1. Enter a claim rule name. Select 'Active Directory' in the Attribute store and then select 'Email-Addresses' for LDAP Attribute and 'Common Name' for Outgoing Claim Type. Click 'Finish'
  1. Right-click on SmartRecruiters again and select 'Edit Claim Rules' to add more rules
  2. In the Claim rule template, select 'Transform an Incoming Claim' and click 'Next'
  1. Enter a claim rule name. Select 'Common Name' under Incoming claim type and then select 'Name ID' in Outgoing claim type and also select 'Persistent Identifier' as the Outgoing name ID format. Click 'Finish' and then 'OK'.

Bind users to corresponding SSO Identifier

In the last part to set up SSO for your users, you may need to use the following Users API endpoints:

POST /user-api/v201804/users
GET /user-api/v201804/users
PATCH /user-api/v201804/users/id

So be sure that the credential you obtained include the user_read and user_manage access scopes if you are using OAuth credentials.

The key in this part is to ensure users who will be using SSO to sign in to SmartRecruiters have the appropriate SSO identifier attached to their accounts by editing their account information using the Users API.

There are two different scenarios:

  1. The user account has not yet been created. And therefore you can attach the SSO identifier when creating the user using the CreateUser endpoint.
  2. The user account had been created. And you have to update the user's SSO identifier by first retrieving the user using the ListUsers endpoint and then update the user using the UpdateUser endpoint


About SSO Identifier

In either scenarios, the property you are looking to edit in the User object is the ssoIdentifier. The case-sensitive value for each user's ssoIdentifier must match the one you have configured in your IdP or ADFS Manager.

SmartRecruiters recommend using the user's email address as the value for the user's ssoIdentifier.

Once you completed all 3 parts. Your users are ready to sign into SmartRecruiters back office with SSO.

Manage User Access at Scale

User account creation is just the beginning of the user account management cycle. There are times your organization may need to update user information, adjust users' access to jobs and candidates, or temporarily deactivate users.

Using a combination of UpdateUser and UpdateAccessGroupUser endpoints, you can update and manage your SmartRecruiters users access at ease.

Before you start, you may want to consider the following Users API endpoints:

GET /user-api/v201804/users
POST /user-api/v201804/users/id
DELETE /user-api/v201804/access-groups/accessGroupId/users/id
POST /user-api/v201804/access-groups/accessGroupId/users
DELETE /user-api/v201804/users/id/activation
PUT /user-api/v201804/users/id/activation

And be sure that the credential you obtained include the user_read and user_manage access scopes if you are using OAuth credentials.

Again, there are many different ways to build the integration, below are some suggestions on leveraging the endpoints:

  • You want to search for the user you want to update using ListUsers endpoint.
  • After you obtained the id of the user, you can update the user information via the UpdateUser endpoint or deactivate the user using DeactivateUser endpoint. You may also re-activate the user using the ActivateUser endpoint if the user deactivation is temporary (e.g. User taking on long vacation or medical leave)
  • In case where you need to update a user's access groups, be sure you have already defined the access group in the SmartRecruiters back office. You can use the UpdateAccessGroupUser to grant the user additional access or remove the DeleteAccessGroupUser to remove a user's access from certain jobs and candidates.

Did this page help you?