# CyberArk setup

CyberArk connects through the **unified HRIS connector**. This page covers the
CyberArk-side configuration you complete first. Once it's done, add the
connector in Mesh by following [Connect your HR
system](../connect-your-hr-system.md).

You finish with four values:

| Value | Where it comes from |
|---|---|
| **Tenant URL** | Your organization's CyberArk sign-in host |
| **OAuth client application ID** | The application ID you choose in Step 3 |
| **Client ID** | The service user you create in Step 4 |
| **Client secret** | Set when you create the service user |

## Before you start

You need **administrator access** to your company's CyberArk instance, or a
colleague who has it.

> **warning**

These steps reflect Axiad's current understanding of CyberArk's configuration.
Because CyberArk is a third-party product, there may be variations between your
experience and what this guide describes, depending on the version in use and
recent updates.

If you find a significant difference, or anything that doesn't make sense, let
us know through Axiad support.

## Step 1 — Open the admin portal

1. Sign in to CyberArk at your organization's tenant URL.

   ![The CyberArk portal home page](/img/connectors/hr/providers/8545851-07924a91c6.jpg)

2. Select the grid symbol next to **Identity User Portal** and choose **Admin
   Portal**.

   ![Switching to the CyberArk admin portal](/img/connectors/hr/providers/8545851-55020b80cb.jpg)

   ![The admin portal view](/img/connectors/hr/providers/8545851-52f797de86.jpg)

## Step 2 — Create a SCIM client role

1. Go to **Core Services → Roles**.

   ![The Core Services menu open at Roles](/img/connectors/hr/providers/8545851-e119fc827a.jpg)

2. Select **Add Role**, name it `SCIM Client`, and select **Save**.

3. Under **Administrative Rights**, select **Add**, then find and select **User
   Management**.

   :::caution Choose User Management, not Read Only User Management

   The read-only variant does not grant enough for the connection to work.

   :::

   ![Adding the User Management administrative right to the role](/img/connectors/hr/providers/8545851-e5f0315316.jpg)

4. Select **Save**.

## Step 3 — Create a custom OAuth2 client

1. Go to **Apps & Widgets → Web Apps**.

   ![The Apps and Widgets menu open at Web Apps](/img/connectors/hr/providers/8545851-a9e27955a6.jpg)

2. Select **Add Web Apps**, open the **Custom** tab, and select **Add** next to
   **OAuth2 Client**.

   ![Adding a custom OAuth2 client from the Custom tab](/img/connectors/hr/providers/8545851-7226ca3323.jpg)

3. Confirm with **Yes**, then close the dialog. CyberArk opens the client's
   configuration.

4. On **Settings**, set an **Application ID** — any value you like, for example
   `scim_oauth_client`. This becomes part of the OAuth endpoint URL, and it is
   the value you enter in Mesh, so note it down.

5. On **General Usage**, set **Client ID Type** to **Confidential** and check
   **Must be OAuth Client**.

   ![The General Usage page with the client ID type set](/img/connectors/hr/providers/8545851-e481e5c9eb.jpg)

6. On **Tokens**, set:

   | Field | Value |
   |---|---|
   | Token Type | `JwtRS256` |
   | Auth methods | Client Creds |
   | Access token lifetime | 5 hours |

   ![The Tokens page with the token type and auth method set](/img/connectors/hr/providers/8545851-df43fbb29e.jpg)

7. On **Scope**, select **Add** and create a scope named `SCIMAPIScope`, then
   add an allowed REST API entry with the text `scim`.

   :::caution Enter these values exactly

   Both the scope name and the REST API entry are matched literally. A typo here
   surfaces later as an authorization failure that looks unrelated.

   :::

   ![The Scope page with the SCIM API scope defined](/img/connectors/hr/providers/8545851-9d08c72914.jpg)

8. On **Permissions**, add the **SCIM Client** role from Step 2 and check the
   **Run** permission.

9. Select **Save**.

## Step 4 — Create a service user

Go to **Core Services → Users** and create a service user for the connection.
Note its client ID and secret — these are the credentials Mesh authenticates
with, and they belong to the SCIM Client role you created.

## Step 5 — Connect in Mesh

Follow [Connect your HR system](../connect-your-hr-system.md), choose CyberArk in
the connection window, and supply the tenant URL, application ID, client ID, and
client secret.

## After connecting

The connector appears in your connectors list with **Health: Initializing**
while the first collection runs, then moves to **Good**. Access is
**read-only**: Mesh does not write back to CyberArk.

If it doesn't come online, see [Troubleshoot HR
connectors](../troubleshoot-hr-connectors.md).

## Troubleshooting

| What you see | Likely cause | Fix |
|---|---|---|
| Authorization is rejected | The scope name or the `scim` REST API entry has a typo | Re-check both on the client's Scope page, exactly as shown |
| The connector authorizes but reads nothing | The role has **Read Only User Management** rather than **User Management** | Change the administrative right on the SCIM Client role |
| The client cannot be used | The SCIM Client role was not added on the Permissions page, or **Run** is unchecked | Add the role and check **Run**, then save |