# Workday Identity Provider Setup Guide

This guide walks you through setting up a dedicated integration user, security group, and API client in Workday to enable the integration to read worker and organizational data from your tenant.

## Prerequisites

Before you begin, ensure you have:

- A Workday tenant where you have administrator access


## Step 1: Create an Integration System User (ISU)

1. In the Workday search bar, type **Create Integration System User** and select the task.
2. Enter a **User Name** for the account (e.g., `acmecorp_isu`).
3. Enter a **Password** and **Confirm Password**. Store this password securely — you may need it for reference.
4. Check **Do Not Allow UI Sessions**. This prevents the account from being used for interactive browser logins.
5. Leave all other settings at their defaults and click **OK**.


## Step 2: Create an Integration System Security Group (ISSG)

1. In the search bar, type **Create Security Group** and select the task.
2. For **Type of Tenanted Security Group**, select **Integration System Security Group (Unconstrained)**.
3. Enter a **Name** for the group (e.g., `acmecorp_issg`).
4. Click **OK**.
5. On the next screen (**Edit Integration System Security Group (Unconstrained)**), add the ISU you created in Step 1 to the **Integration System Users** field.
6. Click **OK** to save.


## Step 3: Grant Domain Security Permissions

1. In the search bar, type **Maintain Permissions for Security Group** and select the task.
2. Select the **Maintain** operation.
3. Within the **Source Security Group** box, select the ISSG you created in Step 2.
4. Click **OK** to open the permissions editor.
5. On the **Domain Security Policy Permissions** tab, add permissions according to the table below.
6. Click **OK** to save.


| View/Modify Access | Domain Security Policy | Functional Area |
|  --- | --- | --- |
| Get Only | Worker Data: Workers | Staffing |
| Get Only | Worker Data: Staffing | Staffing |
| Get Only | Worker Data: Public Worker Reports | Staffing |
| Get Only | Worker Data: Job Details | Staffing |
| Get Only | Worker Data: Directory | People Experience |
| Get Only | Worker Data: Current Staffing Information | Staffing |
| Get Only | Worker Data: All Positions | Staffing |
| Get Only | View: Supervisory Organization | Organizations and Roles |
| Get Only | System Auditing | System |
| Get Only | Reports: Organization | Organizations and Roles |
| Get Only | Reports: Matrix Manager | Staffing |
| Get Only | Reports: Manager | Staffing |


## Step 4: Activate Pending Security Policy Changes

1. In the search bar, type **Activate Pending Security Policy Changes** and select the task.
2. Enter a **Comment** describing the change (e.g., `Enable API integration access`).
3. Click **OK** to confirm activation.


The permissions you assigned in step #3 will not take effect until you use the activate pending security policy changes task.

## Step 5: Register an API Client for Integrations

1. In the search bar, type **Register API Client for Integrations** and select the task.
2. Enter a **Client Name** (e.g., `Identity Integration`).
3. (optional) Check **Non-Expiring Refresh Tokens** if you wish to prevent the refresh token from expiring and requiring manual rotation.
4. Leave **Disabled** unchecked.
5. For **Scope (Functional Areas)**, add all of the following:
  - System
  - Staffing
  - Personal Data
  - Organizations and Roles
  - Contact Information
  - Integration
6. Leave **Include Workday Owned Scope** unchecked.
7. Leave **Restricted to IP Ranges** box empty.
8. Click **OK**.


After saving, note the **Client ID** and **Client Secret** on the **Register API Client for Integrations** screen. You will need these when configuring the integration.

## Step 6: Generate a Refresh Token

To access **Related Actions** for an item in Workday, hover the mouse next to it and you should see a small oval with 3 horizontal dots appear next to it. Clicking on this oval will open the related actions menu.

1. In the search bar, type **View API Clients** and select the report.
2. Navigate to the **API Clients for Integrations** tab and locate the client you registered in Step 5.
3. Note the **Token Endpoint** URL displayed on this screen — you will need it when configuring the integration. (e.g. `https://impl-services1.wd12.myworkday.com/ccx/oauth2/acmecorp_dpt1/token`)
4. Click **Related Actions** on the client row, then select **API Client > Manage Refresh Tokens for Integrations**.
5. For **Workday Account**, select the ISU you created in Step 1.
6. Check **Generate New Refresh Token**.
7. Leave **Confirm Delete** unchecked.
8. Click **OK**.


After saving, note down the **Refresh Token**. You will need this when configuring the integration.

If you change the **Scope (Functional Areas)** associated with the API client, you should repeat this step to generate a new refresh token.

## Configure the Integration

Once you have completed the steps above, you should have all the information you need to configure the integration. Provide the values as shown below:

| Integration Parameter | Description |
|  --- | --- |
| Client ID | The **Client ID** from Step 5. |
| Client Secret | The **Client Secret** from Step 5. |
| Refresh Token | The **Refresh Token** generated in Step 6. |
| Token URL | The **Token Endpoint** you noted in step 6. |