> ## 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 Microsoft Entra ID

> Turn on automatic provisioning for the Windmill app in Microsoft Entra ID, add the Windmill extension attributes to the attribute list, map the manager, and assign users and groups.

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

## Before you begin

You'll need:

* A **Windmill enterprise application in Entra ID** 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).
* **Application Administrator** or **Cloud Application Administrator** access in Entra ID.

<Note>
  The Windmill token's setup window is 24 hours. Complete the **Turn on provisioning** section within that time. Entra ID's **Test Connection** 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 the Microsoft Entra admin center, go to **Enterprise applications** and open your Windmill app.
  </Step>

  <Step title="Start automatic provisioning">
    Select **Provisioning** in the left menu, then **Get started** (or **Edit provisioning** if provisioning already exists). Set **Provisioning Mode** to **Automatic**.
  </Step>

  <Step title="Enter the Windmill credentials">
    Under **Admin Credentials**, enter the **Tenant URL** and the **Secret Token** from Windmill. Select **Test Connection**. When the test succeeds, select **Save**.
  </Step>
</Steps>

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

## Review the standard attribute mappings

Under **Mappings**, open **Provision Microsoft Entra ID Users**. The default mappings already cover most of the fields Windmill supports. Confirm these rows are present.

| Windmill field | Entra ID source attribute      | Target attribute                                                     |
| -------------- | ------------------------------ | -------------------------------------------------------------------- |
| Work email     | `userPrincipalName`            | `userName`                                                           |
| Access         | `Switch([IsSoftDeleted], ...)` | `active`                                                             |
| External ID    | `mailNickname` or `objectId`   | `externalId`                                                         |
| First name     | `givenName`                    | `name.givenName`                                                     |
| Last name      | `surname`                      | `name.familyName`                                                    |
| Display name   | `displayName`                  | `displayName`                                                        |
| Job title      | `jobTitle`                     | `title`                                                              |
| Work phone     | `telephoneNumber`              | `phoneNumbers[type eq "work"].value`                                 |
| Manager        | `manager`                      | `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager` |

<Tip>
  If your users sign in with an email that differs from their user principal name, map `mail` to `userName` instead. Windmill uses the work email to identify each member.
</Tip>

Windmill ignores attributes it doesn't support, such as address or department, so you can leave the other default mappings in place.

## Add the Windmill extension attributes

Job level, start date, pronouns, and gender live in the Windmill extension schema. Add them to the app's attribute list, then map a source attribute to each one.

<Steps>
  <Step title="Open the attribute list">
    In **Provision Microsoft Entra ID Users**, select **Show advanced options** at the bottom of the page, then **Edit attribute list for customappsso**.
  </Step>

  <Step title="Add the attributes">
    Add a row for each attribute. Use the full namespaced name. Set the type to **String**.

    | Attribute  | Name                                                                   | Type   |
    | ---------- | ---------------------------------------------------------------------- | ------ |
    | Job level  | `urn:ietf:params:scim:schemas:extension:gowindmill:2.0:User:jobLevel`  | String |
    | Start date | `urn:ietf:params:scim:schemas:extension:gowindmill:2.0:User:startDate` | String |
    | Pronouns   | `urn:ietf:params:scim:schemas:extension:gowindmill:2.0:User:pronouns`  | String |
    | Gender     | `urn:ietf:params:scim:schemas:extension:gowindmill:2.0:User:gender`    | String |

    Select **Save**.
  </Step>

  <Step title="Map a source attribute to each one">
    Back on the mappings page, select **Add New Mapping**. Set **Mapping type** to **Direct**, choose the **Source attribute** that holds the value, for example `extensionAttribute1` or a custom directory extension, and choose the new **Target attribute**. Set **Apply this mapping** to **Always**, then select **Ok**.

    Repeat for each attribute, then select **Save** on the mappings page.
  </Step>
</Steps>

<Info>
  Entra ID doesn't have built-in attributes for job level, start date, or pronouns. Use one of the `extensionAttribute1` to `extensionAttribute15` fields, or a directory extension synced from your HR system. For start date, use the `YYYY-MM-DD` format. Windmill skips dates in other formats.
</Info>

<Warning>
  The attribute name must include the full namespace, exactly as shown in the table. An attribute named only `jobLevel` is sent as a core attribute and Windmill ignores it.
</Warning>

## Map the manager

Keep the default `manager` mapping. Entra ID resolves it to the manager's SCIM ID in Windmill automatically, as long as both the manager and the report are in the app's provisioning scope. If the manager isn't provisioned yet, Windmill keeps the reference and applies it once the manager exists.

See [Manager references](/security/scim-attributes#manager-references) for how Windmill resolves the value.

## Assign users and groups

Entra ID provisions the people and groups in the app's scope.

<Steps>
  <Step title="Set the scope">
    Under **Provisioning > Settings**, set **Scope** to **Sync only assigned users and groups**. This is the recommended option so you control exactly who gets access.
  </Step>

  <Step title="Assign users and groups">
    Open **Users and groups** in the app's left menu and select **Add user/group**. Assigning a group provisions each of its members. To sync the group itself into Windmill Groups, see [Sync groups from your identity provider](/security/scim-group-sync).
  </Step>

  <Step title="Turn provisioning on">
    On the **Provisioning** page, set **Provisioning Status** to **On** and select **Save**. Entra ID runs an initial cycle, then checks for changes about every 40 minutes.
  </Step>
</Steps>

<Tip>
  To test a single person right away, use **Provision on demand** on the Provisioning page. The person appears in Windmill within a few seconds.
</Tip>

When you remove someone from the app, Entra ID deactivates them in Windmill. Windmill archives the member and signs them out. Assigning them again restores their access.

## Set the field sources in Windmill

Windmill stores every value Entra ID 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 Entra ID 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 Entra ID 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 a provisioned employee in [**Settings > Org Chart**](https://app.gowindmill.com/COMPANY/config/org-chart). The **Sources** tab shows **SCIM** for the fields Entra ID manages, and the **Info** tab shows the values.
* In Entra ID, **Provisioning > Provisioning logs** shows each user and group operation and any errors.

## FAQs

<AccordionGroup>
  <Accordion title="Test Connection fails.">
    Check that the Tenant URL is the full URL from Windmill and the Secret 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="The provisioning log shows 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). Entra ID retries on its next cycle, or you can use **Restart provisioning**.
  </Accordion>

  <Accordion title="Job level, start date, pronouns, or gender aren't reaching Windmill.">
    Confirm the target attribute name includes the full namespace `urn:ietf:params:scim:schemas:extension:gowindmill:2.0:User:` and that the mapping is saved with **Apply this mapping** set to **Always**. Then check the field's source in Windmill under [**Settings > Org Chart**](https://app.gowindmill.com/COMPANY/config/org-chart). If another system owns the field, switch it to SCIM.
  </Accordion>

  <Accordion title="The manager isn't set in Windmill.">
    Both the manager and the report must be assigned to the Windmill app. Entra ID sends the manager only after the manager has been provisioned. Check the provisioning log for the report. 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="How long do changes take to reach Windmill?">
    Entra ID runs an incremental cycle about every 40 minutes. Use **Provision on demand** to push one person immediately. Once a request reaches Windmill, the change is applied within seconds.
  </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>