ServiceNow

This guide will teach you how to set up the connector between ServiceNow and Clarity Security.

Estimated time to complete: 30 minutes

Supported Connector Capabilities

Below are capabilities supported by the connector at this time.

What the Connector Syncs

Every sync is a full sync of the ServiceNow instance. The connector reads the following tables:

• sys_user: all users, active and inactive. For each user Clarity imports the name, first name, middle name, last name, email, user name, employee number, active status, locked out status, last login time, created date, and the VIP, Internal Integration User and Web services access only flags. Clarity also imports the user's title, department, location, company, cost center and country, and the manager's record ID, email, user name and employee number.

• sys_user_group: all groups, imported as Group entitlements. The group's Manager is imported as the entitlement owner.

• sys_user_role: all roles, imported as Role entitlements, including the role description and whether the role is marked as elevated privilege.

• sys_user_grmember: group memberships.

• sys_user_has_role: active role assignments. Roles a user inherits through a group appear as Role entitlements on that user. To remove an inherited role, remove the group membership instead of the role.

The three account flags above (VIP, Internal Integration User, Web services access only) also appear in the entitlement catalog as Setting entitlements.

Importing Additional User Fields

By default, Clarity imports a fixed set of details from each ServiceNow user record. If you need other columns from the user record, including custom (u_) columns, list them in the Additional user fields setting.

To add columns:

1. In Clarity, open the ServiceNow application's settings, where the api_url, username and password are entered.

2. In Additional user fields, enter the ServiceNow column names separated by commas, for example u_position_number, u_agency.name.

3. Save. The columns are imported on the next sync and appear as attributes on each ServiceNow user in Clarity.

Things to know when choosing columns:

• Use the column name, not the label shown on the ServiceNow form. A field labelled Position Number is usually u_position_number. To find a column name, right-click the field's label on the ServiceNow user form.

• A name that ServiceNow does not recognise is imported as empty. If a column stays empty after a sync, check the spelling of the column name first.

• A column that points to another record is imported as that record's ID. Add .name to import the record's name instead, for example u_agency.name. The attribute then appears in Clarity as u_agency_name.

• Choice fields are imported as their stored code, not the label shown in ServiceNow.

• Dates are imported as YYYY-MM-DD, and date-times are in UTC.

• Standard columns can be added too, such as phone or mobile_phone.

• A name that matches something Clarity already imports, such as department, is ignored.

Example: u_position_number, u_employee_type, u_agency.name, manager.name, phone

Provisioning Behavior

• Provision User creates a sys_user record with the identity's first name, last name, full name, email, and a user name generated by the application's username rule. The account is created active with a temporary password and Password needs reset set, and the temporary password is emailed to the identity's email address. If the application is configured to use an SSO application in Clarity, the SSO entitlement is granted instead of emailing a password.

• Push User Attributes updates first name, last name, email and active on the ServiceNow user. The Manager field is set when the identity's supervisor in Clarity also has a linked ServiceNow account.

• Deactivate User sets the user to Active = false and Locked out = true. Reactivation reverses both.

• Delete User permanently deletes the sys_user record.

Using ServiceNow as a Source of Truth

ServiceNow can be selected as a Source of Truth in the application's trust settings. When it is, every active ServiceNow user that does not match an existing identity creates a new identity in Clarity, including integration and service accounts.

Identities created from ServiceNow carry the title, department, location, company, cost center and manager from the ServiceNow user record, along with any columns named in Additional user fields. To set each identity's Supervisor from ServiceNow, map the ServiceNow manager attribute to Supervisor in your identity attribute configuration. The Supervisor is linked when the manager is also a synced ServiceNow user with an identity in Clarity.

ServiceNow works as a Source of Truth only if your user records hold the HR details you need. If they do not, use your HR system (or an HR export through the CSV connector) as the Source of Truth and connect ServiceNow as a standard application. Talk to your Customer Success team before enabling Source of Truth on ServiceNow.

Required ServiceNow Permissions

The service account authenticates with basic authentication (username and password) against the ServiceNow Table API. It needs:

• Read access to sys_user_group and sys_user_role

• Read and write access to sys_user, sys_user_grmember and sys_user_has_role

The user_admin role grants all of the above. If your instance has customized the user_admin role, verify these tables in Step 12.

How to Setup the Connector

Step 1. Log into ServiceNow.

Note: Copy the instance URL (for example https://yourcompany.service-now.com). It is used when connecting the application to Clarity.

Step 2. Click the All dropdown > search for the word 'organization' > click on Users.

Step 3. Click New to create a new user.

Step 4. Fill in the form to create the service user account.

User ID: clarity_service_account

First name: Clarity 

Last name: Service Account

Verify that the Active box is checked.

Check the box for Web services access only.

Once completed, click Submit.

Copy the User ID, which will be used when connecting the application to Clarity.

Step 5. After creating the service account, you'll be redirected back to the Users table.

Step 6. Search for the created service account clarity_service_account by User ID and click the User ID.

Step 7. Click Set Password to generate a password for the service account.

Step 8. Generate a new password. 

Click the Generate button to generate a unique password.

Click the copy icon button to copy the password to your clipboard.

Click the Save Password button.

Click the Close button once done.

Copy the Password, which will be used when connecting the application to Clarity.

Step 9. At the bottom of the service account's profile, there will be a table with tabs. Verify that you're in the Roles tab, then click the Edit button.

Step 10. In the Collection search box, search for the role user_admin. Click the right arrow button to add the role to the user. Once completed, click Save.

Step 11. After saving the user_admin role to the service account, you'll be redirected to the profile page. Click the user_admin role link in the Roles tab to access the role settings.

Step 12. Click on the Modules with Role tab and verify that the user, group and role tables listed under Required ServiceNow Permissions are accessible, as shown in the image below. 

Step 13. Log into Clarity Security.

Step 14. Click on Applications and select Marketplace.

Step 15. Scroll to find ServiceNow and click Connect.

Step 16. Fill out the Connect App form with the proper credentials. 

Details for fields common to all applications can be found in the following article: Common App Configuration Steps.

• api_url: Paste the instance URL that was copied from Step 1. Do not include a path after the hostname.

• username: Paste the User ID from Step 4.

• password: Paste the password from Step 8.

• Additional user fields: Optional. Enter any extra ServiceNow user columns to import, separated by commas, for example u_position_number, u_agency.name. Use the column names, not the labels shown on the ServiceNow form. You can leave this blank and add columns later. See Importing Additional User Fields Section above.

Step 17. Fill out the App Settings form.

Complete the App Settings form.  Details for each field can be found in the following article: Common App Configuration Steps.

Step 18. Fill out the User Settings form.

Complete the User Settings form, and check the capabilities table at the top of this article to see if any features are unsupported.  Details for each field can be found in the following article: Common App Configuration Steps.

Step 19. Validate Your Selections and Save.

Need Help?