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

# ServiceNow access

> Learn how to connect Opal to ServiceNow to manage users, groups, group nesting, and grantable roles.

With the ServiceNow access integration, you can manage who has access in ServiceNow from Opal:

* Allow users to request just-in-time access to a ServiceNow group or grantable role from the web and Slack
* Sync active users, groups, parent/child group nesting, and the roles each group grants
* Grant and revoke group membership, direct role assignments, and group roles
* Optionally create and deactivate ServiceNow users from Opal
* Automatically revoke access when a time-bound grant expires

Opal connects to one ServiceNow instance through OAuth client credentials as a dedicated web-service-only integration user.

> [!NOTE]
>
> This is separate from the [ServiceNow ticketing](https://docs.opal.dev/integrations/servicenow.md) integration, which creates and updates ServiceNow catalog requests for Opal access requests. You can use either or both.

## Supported resources

| Resource | Read | Grant and revoke access |
| - | - | - |
| ServiceNow groups (membership) | ✔️ | ✔️ |
| Group nesting (parent / child) | ✔️ | |
| Roles a group grants its members | ✔️ | ✔️ |
| Grantable roles (direct user assignments) | ✔️ | ✔️ |

Opal syncs active users who have an email. By default it doesn't create or deactivate users, so your identity provider can keep provisioning ServiceNow. You can turn user create and deactivate on in the app settings.

### How ServiceNow access maps to Opal

* **Groups**: each active `sys_user_group` appears as a **ServiceNow Group**. You can add and remove members (`sys_user_grmember`).
* **Group nesting**: a child group with a `parent` is nested under that parent in Opal. Members of the child inherit the parent's roles through that nesting.
* **Group roles**: roles a group grants with `inherits=true` appear on the group. Opal adds or deletes those `sys_group_has_role` rows. Rows copied from a parent group (where ServiceNow sets `granted_by`) aren't listed or revoked; the child nesting covers them instead. Rows with `inherits=false` aren't listed, because members get nothing from them.
* **Roles**: each grantable `sys_user_role` appears as a **ServiceNow Role**. Direct, active grants (`sys_user_has_role` with `inherited=false`) can be granted and revoked. Roles held only through a group or a containing role show as inherited and aren't treated as direct grants. Requested or pending role grants aren't access yet.
* **Users**: when user management is enabled, granting access to someone who isn't in ServiceNow creates a `sys_user`, and removing them deactivates and locks the account rather than deleting it. Opal never reactivates a deactivated user, because that would quietly restore their old groups and roles.

### Limitations

* Roles contained by another role (`sys_user_role_contains`) aren't modeled separately; ServiceNow writes them like inherited group roles, with no field telling the two apart.
* Elevated roles such as `admin` may require `security_admin` on the integration user; Opal surfaces ServiceNow's refusal if the grant isn't allowed.
* Custom domains still use the `instance.service-now.com` (or `servicenowservices.com`) API host in Opal.

## Requirements

Before you begin, you must:

* Be an Opal Admin
* Be a ServiceNow admin who can create a user, assign roles or ACLs, and register an OAuth application
* Ask the Opal team to enable the ServiceNow access integration for your organization

## Configuration steps

### 1. Create a ServiceNow integration user

In ServiceNow, go to **All** > **Users and Groups** > **Users**, and create a user for Opal.

1. Select **Web service access only**.
2. Set a **User ID** and password (you'll use the user with OAuth, not basic auth, in Opal).
3. Grant the user read access to these tables, and write access when the connection is read/write:

| Table | Read | Write (read/write mode) |
| - | - | - |
| `sys_user` | ✔️ | ✔️ if Opal creates and deactivates users |
| `sys_user_group` | ✔️ | |
| `sys_user_grmember` | ✔️ | ✔️ |
| `sys_user_role` | ✔️ | |
| `sys_user_has_role` | ✔️ | ✔️ |
| `sys_group_has_role` | ✔️ | ✔️ |

You can grant these through ACLs on a custom role. The `user_admin` role also works, and lets the integration user edit every non-admin user.

![](https://mintcdn.com/opalsecurity/E-CmJXh0QNjZUl4g/images/docs/700415a-small-Screen_Shot_2023-05-03_at_3.15.03_PM.png?fit=max\&auto=format\&n=E-CmJXh0QNjZUl4g\&q=85\&s=8402a63c6357c3b60bddf2d9d472002a)

![Record the User ID for the OAuth application user in the next step.](https://mintcdn.com/opalsecurity/lt0M-hBs5yNe5ff5/images/docs/9d5601e-image.png?fit=max\&auto=format\&n=lt0M-hBs5yNe5ff5\&q=85\&s=f07524e316b47fbf3e4be9f836be517f)

### 2. Enable OAuth client credentials and create an OAuth application

1. Turn on the system property `glide.oauth.inbound.client.credential.grant_type.enabled` so ServiceNow accepts the client-credentials grant.
2. Go to **System OAuth** > **Application Registry**, select **New**, then **Create an OAuth API endpoint for external clients**.

![](https://mintcdn.com/opalsecurity/E-CmJXh0QNjZUl4g/images/docs/698474c-image.png?fit=max\&auto=format\&n=E-CmJXh0QNjZUl4g\&q=85\&s=4071da516a2edae4990637dc1d91e2d1)

3. Set the application's **OAuth Application User** to the integration user from step 1.
4. Record the **Client ID** and **Client Secret**.

### 3. Create the ServiceNow app in Opal

In Opal, go to **Inventory** > **+ App** and select **ServiceNow**. Fill in the following fields:

| Field | Value |
| - | - |
| App name | A name for the ServiceNow app in Opal, for example `ServiceNow`. |
| App admin | The owner who administers the app in Opal. |
| Description | A short description that helps requesters understand what this app is. |
| Visibility | Who in your organization can see the app. |
| Instance name | The name in your instance URL, for example `acme` in `https://acme.service-now.com`. |
| Instance domain | `service-now.com`, or `servicenowservices.com` for a government or regulated instance. |
| OAuth client ID | The Client ID from step 2. |
| OAuth client secret | The Client Secret from step 2. |
| Access | **Read and write** to grant and revoke, or **Read only** to sync without changing ServiceNow. |
| Users | **Managed outside Opal** (default), or **Opal creates and deactivates users**. |
| Roles | **Sync** (default) or **Don't sync**. |
| Groups | **Sync** (default) or **Don't sync**. |

Opal checks the OAuth credentials when you save the app. On the **Setup** tab, app validations confirm the integration user can read each required table. ServiceNow ACLs hide rows rather than returning 403, so an empty users or roles result fails validation.

![The ServiceNow app's Setup tab in Opal, with the Users, Roles, Groups, OAuth client ID, and OAuth client secret settings and passing app validations.](https://mintcdn.com/opalsecurity/pBQpCMT_mO-nsJVp/images/docs/servicenow-access-opal-setup.png?fit=max\&auto=format\&n=pBQpCMT_mO-nsJVp\&q=85\&s=ed6900eceab08baac3bde8e6c7a6a1b1)

### 4. Import groups and roles

After you save the app, import the groups and roles you want to manage: on the app's **Assets** tab, select **Import assets**, and turn on requests for them. Opal pulls membership and role grants only for imported items, so they appear after the next sync.

## Troubleshooting

| Error or symptom | Fix |
| - | - |
| Authentication fails when you save the app | Confirm client credentials grant is enabled, the Client ID and secret are correct, and the OAuth Application User is set. |
| Read users or Read roles validation fails | Grant read access to `sys_user` / `sys_user_role`. ACLs that hide every row look like an empty tenant. |
| A grant or revoke fails naming `sys_user_grmember` | Grant write access to `sys_user_grmember`. |
| A grant or revoke fails naming `sys_user_has_role` or `sys_group_has_role` | Grant write access to that table. Elevated roles may also need `security_admin`. |
| Creating a user fails with 403 | A `sys_user` with that user name may already exist (any letter case), including deactivated users. Resolve it in ServiceNow. |
| A child's copied role isn't listed on the child group | Expected. Opal nests the child under the parent and skips `granted_by` copies so you don't revoke a role the parent still grants. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.