Skip to main content
This article covers the ServiceNow User Provisioning connector for full account and role management (create, update, suspend, and delete users, plus assign and remove roles and group memberships). For read-only identity/entitlement visibility and ITSM ticket logging, use ServiceNow (ITSM) instead. The two connectors use different OAuth redirect URLs (see Phase 1).

​
After this article

You will be able to connect ServiceNow to Lumos to sync users and their roles, and to provision and deprovision accounts, creating, updating, suspending, and deleting ServiceNow users and managing their role and group assignments.

​
Capabilities

Provisioning behavior:
  • Create: Lumos creates the sys_user record with an email (required and validated), optional first and last name, and a username that defaults to the email. Mapped custom attributes are written to sys_user, and HR attributes create or update the user’s sn_hr_core_profile record. New users are created active. Entitlements can’t ride along on the create call. Lumos assigns roles and groups as separate actions.
  • Update: Lumos patches the changed sys_user fields (email, username, first and last name, custom attributes) and patches the HR profile for HR attributes. Email is optional on update. ServiceNow returns 200 even when it silently ignores a field, so Lumos compares the response against what it sent and reports any field that didn’t stick.
  • Assign a role or group: Lumos inserts the association record into sys_user_has_role or sys_user_grmember.
  • Remove a role or group: Lumos looks up the user’s association record and deletes it. Removing a role or group the user doesn’t hold fails with a not-found error.
  • Suspend and reactivate: Lumos patches the user’s active field to false or true.
  • Delete: Lumos permanently deletes the sys_user record.

​
Required plan and roles

  • ServiceNow plan: no minimum plan is required.
  • Connecting user: the integration inherits the permissions of the user who connects it. Connect while logged into ServiceNow as a dedicated service account with the roles below, not your personal admin account.
  • Required roles on the connecting user/service account:
  • Write required: provisioning requires the write-capable roles above to create, update, and delete accounts and role assignments. This is non-negotiable for the User Provisioning connector. For read-only visibility use ServiceNow (ITSM).

​
Instructions

Phase 1: Create an OAuth client in ServiceNow
  1. In ServiceNow, open the Application Registry and create a new application, choosing Create an OAuth API endpoint for external clients.
  2. Set Name to Lumos and set the Redirect URL to https://app.lumosidentity.com/integrations/ics_oauth2_callback.
  3. Leave all other settings as-is and save.
  4. Copy the Client ID and Client Secret.
Phase 2: Connect in Lumos
  1. Click the ServiceNow User Provisioning card in your Lumos integrations (reconnect an existing card or add a new one).
  2. Instance Subdomain: from your login URL (subdomain.service-now.com), enter the subdomain.service-now.com value.
  3. Enter the ServiceNow Client ID and Client Secret from Phase 1.
  4. Click Connect ServiceNow. When the ServiceNow login pop-up appears, make sure you’re logged in as the intended service account. The integration inherits that user’s permissions.

​
API Endpoints Used

​
Troubleshooting

“Failed to forward OAuth callback to ICS” when connecting. This generic message usually masks a 403 from ServiceNow: Missing required api access scope: tableapi on GET /api/now/table/sys_user, which Lumos calls immediately after OAuth to validate credentials. Grant the connecting service account rest_service (provides Table API access) and user_admin, then reconnect. 403 Forbidden / insufficient permissions during sync. Verify the connecting user holds every required role and has read access to sys_user, sys_user_group, sys_user_role, and sys_user_has_role. Temporarily testing with a full admin account can isolate whether the problem is role-based. A specific role (e.g. security_admin) never appears as an entitlement. ServiceNow platform limitation, not a sync bug. Elevated-privilege roles from the High Security plugin are hidden from any non-interactive session, so the connector’s OAuth-based role listing gets a clean response with the record omitted. A custom read ACL on sys_user_role does not fix it. Workarounds are ServiceNow-side (a scripted REST endpoint running as an elevated user, or relaxed High Security settings). Suspended user still consumes a license. Expected: suspending deactivates the account but does not reclaim the license. Only deleting (deprovisioning) the user reclaims it. Incomplete or missing data. Check active/inactive filter conditions, confirm the integration user can see the records in the ServiceNow UI, and review ACLs for row-level security. Connection or credential errors. Confirm the instance subdomain format, that the instance is reachable from the internet (firewall rules for on-premise), that the OAuth application is active, and that the Client ID/Secret are correct. Regenerate credentials if issues persist. Reconnecting with valid credentials clears an integration error state.