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

# Set Up SCIM with Okta

> Turn on SCIM provisioning for the Windmill app in Okta, map the standard profile attributes, add the Windmill extension attributes in the Profile Editor, and push groups.

This guide walks through the Okta side of SCIM (System for Cross-domain Identity Management) provisioning. When you're done, Okta creates Windmill members, keeps their profiles and managers current, archives people you unassign, and pushes groups into Windmill.

## Before you begin

You'll need:

* A **Windmill SAML app in Okta** with SSO active in Windmill. See [Set up SAML SSO](/security/sso-and-scim#set-up-saml-sso).
* The **Tenant URL** and **Secret token** from Windmill. In [**Settings > Security**](https://app.gowindmill.com/COMPANY/config/security), select **Set up SCIM**, then **Generate token**. See [Set up SCIM provisioning](/security/sso-and-scim#set-up-scim-provisioning).
* **Super Admin or Application Admin** access in Okta.

<Note>
  The Windmill token's setup window is 24 hours. Complete the **Turn on provisioning** section within that time. Okta's connector test counts as the first connection, so Windmill turns provisioning on as soon as the test succeeds.
</Note>

## Turn on provisioning

<Steps>
  <Step title="Open the Windmill app in Okta">
    In the Okta Admin Console, go to **Applications > Applications** and open your Windmill app.
  </Step>

  <Step title="Enable SCIM on the app">
    On the **General** tab, select **Edit** under App Settings. Under **Provisioning**, select **SCIM**, then **Save**. A **Provisioning** tab appears.

    If you created the app from an Okta SCIM template, this option is already on.
  </Step>

  <Step title="Connect Okta to Windmill">
    Open the **Provisioning** tab, select **Integration**, then **Edit**. Enter these values:

    | Setting                           | Value                                                         |
    | --------------------------------- | ------------------------------------------------------------- |
    | SCIM connector base URL           | The **Tenant URL** from Windmill                              |
    | Unique identifier field for users | `userName`                                                    |
    | Supported provisioning actions    | **Push New Users**, **Push Profile Updates**, **Push Groups** |
    | Authentication Mode               | **HTTP Header**                                               |
    | Authorization (Bearer)            | The **Secret token** from Windmill                            |

    Select **Test Connector Configuration**. When the test succeeds, select **Save**.

    <Tip>
      **Import Users** is optional. Turn it on if you want Okta to match people who already have access to Windmill to their Okta accounts.
    </Tip>
  </Step>

  <Step title="Turn on the provisioning actions">
    Under **Provisioning > To App**, select **Edit**. Turn on **Create Users**, **Update User Attributes**, and **Deactivate Users**, then **Save**.

    **Update User Attributes** must be on. Without it, Okta creates members but never sends profile changes.
  </Step>
</Steps>

Back in Windmill, the SCIM card in **Settings > Security** now shows **Active**.

## Map the standard attributes

The **To App** section of the **Provisioning** tab lists the attribute mappings Okta sends to Windmill. Okta's SCIM template includes most of the fields Windmill supports. Confirm these mappings and remove any you don't want to send.

| Windmill field | Okta app attribute | External name                        | Suggested Okta value                    |
| -------------- | ------------------ | ------------------------------------ | --------------------------------------- |
| Work email     | Username           | `userName`                           | `user.email`                            |
| First name     | Given name         | `name.givenName`                     | `user.firstName`                        |
| Last name      | Family name        | `name.familyName`                    | `user.lastName`                         |
| Display name   | Display name       | `displayName`                        | `user.displayName`                      |
| Job title      | Title              | `title`                              | `user.title`                            |
| Work phone     | Primary phone      | `phoneNumbers.^[type=='work'].value` | `user.primaryPhone`                     |
| Manager        | Manager value      | `manager.value`                      | See [Map the manager](#map-the-manager) |

Make sure each mapping applies on **Create and update**. Windmill ignores attributes it doesn't support, such as address or department, so extra mappings are harmless.

## Add the Windmill extension attributes

Job level, start date, pronouns, and gender live in the Windmill extension schema. Okta doesn't include them by default. Add each one to the app's user profile in the Profile Editor, then map an Okta attribute to it.

<Steps>
  <Step title="Open the app's profile in the Profile Editor">
    Go to **Directory > Profile Editor**. Filter by **Apps**, find your Windmill app, and select **User** to open its profile.
  </Step>

  <Step title="Add an attribute">
    Select **Add Attribute** and fill in the fields below. Use the exact external name and external namespace. They're case-sensitive.

    | Attribute  | Data type | Display name | Variable name | External name | External namespace                                           |
    | ---------- | --------- | ------------ | ------------- | ------------- | ------------------------------------------------------------ |
    | Job level  | string    | Job level    | `jobLevel`    | `jobLevel`    | `urn:ietf:params:scim:schemas:extension:gowindmill:2.0:User` |
    | Start date | string    | Start date   | `startDate`   | `startDate`   | `urn:ietf:params:scim:schemas:extension:gowindmill:2.0:User` |
    | Pronouns   | string    | Pronouns     | `pronouns`    | `pronouns`    | `urn:ietf:params:scim:schemas:extension:gowindmill:2.0:User` |
    | Gender     | string    | Gender       | `gender`      | `gender`      | `urn:ietf:params:scim:schemas:extension:gowindmill:2.0:User` |

    Leave **Scope** unchecked so the attribute is a user-level attribute. Select **Save**, or **Save and Add Another** to continue with the next one.
  </Step>

  <Step title="Map an Okta attribute to each new attribute">
    Back in the app's profile, select **Mappings**, then the **Okta User to \[Windmill app]** tab. For each new attribute, choose the Okta attribute that holds the value, for example `user.jobLevel` or `user.startDate`. Set the mapping to apply on **Create and update**.

    Select **Save Mappings**, then **Apply updates now** to push the values to existing assigned users.
  </Step>
</Steps>

<Info>
  Okta's default user profile doesn't include job level, start date, or pronouns. If you don't already have these attributes, add them to the Okta user profile first: in **Profile Editor**, open **Okta User (default)**, select **Add Attribute**, and create a string attribute such as `jobLevel`. Then populate it from your HR system or by hand. For start date, use the `YYYY-MM-DD` format.
</Info>

<Warning>
  If you set the external name without the external namespace, Okta sends the attribute as a core attribute and Windmill ignores it. Both values are required.
</Warning>

## Map the manager

Windmill reads the manager from the enterprise extension attribute `manager.value`. In most Okta SCIM apps this is the **Manager value** attribute (variable name `managerValue`). If your app doesn't have it, add it in the Profile Editor with external name `manager.value` and external namespace `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`.

Map it to an Okta attribute that identifies the manager by work email or Okta login, for example `user.managerId` when your directory stores the manager's login there. Windmill resolves the manager by SCIM ID, external ID, username, or work email. See [Manager references](/security/scim-attributes#manager-references).

Both the manager and the report must be assigned to the Windmill app. If the manager hasn't been provisioned yet, Windmill keeps the reference and applies it once the manager exists.

## Assign people

Okta provisions a person when you assign the Windmill app to them.

<Steps>
  <Step title="Open the Assignments tab">
    In the Windmill app, open **Assignments**.
  </Step>

  <Step title="Assign people or groups">
    Select **Assign**, then **Assign to People** or **Assign to Groups**. Assigning a group provisions everyone in it.
  </Step>

  <Step title="Check Windmill">
    New members appear in [**Settings > Members**](https://app.gowindmill.com/COMPANY/config/members) within a few seconds. They get the **Team Member** role. Change roles in Windmill as needed.
  </Step>
</Steps>

When you unassign someone, Okta deactivates them in Windmill. Windmill archives the member and signs them out. Assigning them again restores their access.

## Push groups

To bring Okta groups into Windmill Groups, use the **Push Groups** tab in the Windmill app. Windmill creates a group with the same name and keeps its membership in sync. See [Sync groups from your identity provider](/security/scim-group-sync) for the steps and how synced groups behave in Windmill.

## Set the field sources in Windmill

Windmill stores every value Okta sends. It writes a value to an employee's profile only when SCIM is the source for that field. Fields with no source are claimed by SCIM automatically. Fields owned by another system, like job level from your HRIS (Human Resources Information System), keep the other system's value until you switch the source.

To have Okta manage a field, open [**Settings > Org Chart**](https://app.gowindmill.com/COMPANY/config/org-chart), open **Company defaults**, and set the field's source to **SCIM**. Windmill applies the latest values Okta sent within a few minutes. See [How SCIM works with field sources](/security/scim-attributes#how-scim-works-with-field-sources).

## Verify the setup

* In Windmill, the SCIM card in [**Settings > Security**](https://app.gowindmill.com/COMPANY/config/security) shows **Active** and a recent **Last sync** time.
* Open an assigned employee in [**Settings > Org Chart**](https://app.gowindmill.com/COMPANY/config/org-chart). The **Sources** tab shows **SCIM** for the fields Okta manages, and the **Info** tab shows the values.
* In Okta, **Reports > System Log** shows the push events. Filter by your Windmill app to see any errors.

## FAQs

<AccordionGroup>
  <Accordion title="Test Connector Configuration fails.">
    Check that the SCIM connector base URL is the full **Tenant URL** from Windmill, the Authentication Mode is **HTTP Header**, and the token was pasted without extra spaces. If more than 24 hours have passed since you generated the token, regenerate it in Windmill and try again.
  </Accordion>

  <Accordion title="Okta reports an error that says SCIM provisioning is paused.">
    Provisioning was turned off in Windmill. Turn the **Provisioning is on** toggle back on in [**Settings > Security**](https://app.gowindmill.com/COMPANY/config/security), then retry the task in Okta.
  </Accordion>

  <Accordion title="Job level, start date, pronouns, or gender aren't reaching Windmill.">
    Check three things in Okta. The attribute's **External namespace** must be `urn:ietf:params:scim:schemas:extension:gowindmill:2.0:User`. The attribute must be mapped in **Okta User to \[app]** mappings and applied on **Create and update**. And **Update User Attributes** must be on under **Provisioning > To App**. Then check the field's source in Windmill under [**Settings > Org Chart**](https://app.gowindmill.com/COMPANY/config/org-chart).
  </Accordion>

  <Accordion title="The manager isn't set in Windmill.">
    Confirm the manager is assigned to the Windmill app and has been provisioned. Confirm the **Manager value** attribute maps to a value Windmill can resolve, such as the manager's work email. Then check that the manager field's source is SCIM in [**Settings > Org Chart**](https://app.gowindmill.com/COMPANY/config/org-chart).
  </Accordion>

  <Accordion title="Okta shows a 409 conflict for a user.">
    The person's employee record in Windmill is already linked to a different member. Contact [support@gowindmill.com](mailto:support@gowindmill.com) with the person's email so we can reconcile the records.
  </Accordion>

  <Accordion title="Do assigned people get an invite email or Slack message?">
    Not by default. Turn on [onboarding notifications](/security/sending-invites-with-automatic-provisioning) in **Settings > Security** to notify them automatically.
  </Accordion>
</AccordionGroup>