> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ServiceNow Provisioning

*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)](/integrations/library/servicenow/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

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | Yes | User accounts from the `sys_user` table. Status mapping: `active` true → Active, `active` false → Suspended, no longer returned → Deprovisioned. Last login synced from `last_login_time` |
| Roles | Permission | Yes | Yes | Granted and inherited ServiceNow roles (inherited via role and group). Assign and remove role assignments |
| Groups | Permission | Yes | Yes | ServiceNow groups from `sys_user_group`. Assign and remove group memberships |

| AppStore | Offboarding | Access Reviews | License Management |
| - | - | - | - |
| No | Yes | Yes | Yes |

| Deprovisioning Action | Type | Description |
| - | - | - |
| Deactivate (Suspend) | User | Sets `active = false` on the user record, which blocks login. Does **not** reclaim a license |
| Delete | User | Permanently removes the user record and their data (the `sys_id` remains tied to historical records). Reclaims a license |

**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:

| Role | Purpose |
| - | - |
| `user_admin` | Administer users, groups, locations, skills, and companies |
| `rest_service` | Allows calls over the REST API (grants the `tableapi` scope) |
| `catalog_admin` | Manage the Service Catalog application, including catalog categories and items |
| `personalize_dictionary` | Fetch custom user attributes, including HR profiles |

* **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)](/integrations/library/servicenow/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

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## 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.