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

# Connect SCIM

> Connect a SCIM 2.0 identity provider so it pushes users and groups to Iru Identity as people join, change, and leave.

### About inbound SCIM

With [Google Workspace](https://docs.iru.com/en/identity/directory/google-workspace.md), [Workday](https://docs.iru.com/en/identity/directory/hris-workday.md), and [BambooHR](https://docs.iru.com/en/identity/directory/hris-bamboohr.md), Iru reads the directory on a schedule. Inbound SCIM works the other way. Your identity provider sends each change to Iru as it happens. Nothing is scheduled, and there is no **Sync now**.

You give the provider two values from Iru: a **SCIM base URL** and an **API key**, sent as a bearer token. Users and groups the provider pushes are applied shortly after they arrive.

> [!NOTE]
>
> This article covers inbound SCIM. For concepts shared across every provider, see [Directory Sync](https://docs.iru.com/en/identity/directory/directory-sync).

### Connect SCIM

**1. Navigate to Directory**

Navigate to **Directory** in the left-hand navigation bar (under **Identity**). Select the **Sync** tab.

**2. Select Connect Source**

Select **Connect Source** in the upper-right.

**3. Select SCIM**

Under the **Inbound SCIM** heading, select **SCIM**.

**4. Name the connection**

Enter a **Name** and, optionally, a **Description**. The name is what appears in the directory sync list. Select **Next**.

> [!NOTE]
>
> Selecting **Next** creates the connection. If you close setup before you finish, the connection stays in the list, turned off.

**5. Map the domain**

Every Iru user needs a domain, and SCIM has no attribute for it. **Domain** starts as the domain of each user's primary email:

```
(emails.primary.split("@") + [""])[1].trim().lowerAscii()
```

To give every user the same domain, replace that expression with one domain in quotes, such as `"acme.com"`. Select **Next**.

Username, email, and name start from the standard SCIM attributes: `userName`, `name.givenName`, `name.familyName`, `name.middleName`, and `emails.primary`. You can change those later on the connection's **Mapping** tab. A custom attribute appears in that list after the provider pushes a user that includes it.

**6. Copy the SCIM base URL and API key**

Copy the **SCIM base URL**. Name the API key for the provider that will use it, then select **Create API key** and copy the key.

> [!WARNING]
>
> Copy the key now. It will not be shown again. If you lose it, create a new key from the connection's page and revoke this one.

**7. Select Finish**

Select **Finish**. This turns the connection on.

**8. Set up your identity provider**

In the provider's SCIM settings, enter the **SCIM base URL** and send the API key as a bearer token. The provider can start pushing users and groups right away.

### Settings

Open the connection and select **Edit**.

**1. Review the SCIM base URL and API keys**

On the **Configuration** tab, **SCIM base URL** is the address you enter in the identity provider, with the API key sent as a bearer token.

**API keys** lists each key's name, a masked key, status (**Active**, **Expired**, or **Revoked**), when it was created, and when it was last used. A connection can have up to five active keys. Select **Create API key** to add one. Select **Revoke** on a row to stop that key from working.

To rotate a key without a gap, create a new key, update the identity provider, then revoke the old key.

> [!WARNING]
>
> If a connection has no active key, the identity provider cannot push to Iru.

**2. Choose whether new users are invited**

Under **Invites**, set **Invites for new users**. **Don't send** creates the user and leaves the invitation for you to send later. **Send** emails an invitation to each user this connection creates. A user marked suspended is not invited, and an update to an existing user does not send an invite. See [Invite new users](https://docs.iru.com/en/identity/directory/directory-sync#invite-new-users).

**3. Choose whether groups sync**

Under **Groups**, set **Group sync**. **Don't sync groups** brings in users only. **Sync groups and membership** also brings in each group and its members. The **Exclude group IQL expression** field is shown when membership sync is on. It can use the group's `name` and `memberCount`. Leave it empty to sync every group. For example, `memberCount < 2 || name.startsWith("test-")` skips groups with fewer than two members and groups whose names start with `test-`. See [Sync groups](https://docs.iru.com/en/identity/directory/group-sync.md).

**4. Review the attribute mapping**

On the **Mapping** tab, each row maps a SCIM attribute to an Iru attribute. Username, email, and name start from the standard SCIM attributes, and the domain row uses the expression you set during setup. **name.firstName**, **name.lastName**, **primaryEmail.email**, and **username** are required. You can edit a row that already has an expression.

A custom attribute, including an enterprise extension attribute such as `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department`, appears in the list after the provider pushes a user that includes it. Attributes left under **Not mapped** are not written to the user. On a mapped row, select **Don't overwrite** when a later push should leave the value already stored in Iru as it is. See [Attribute mapping](https://docs.iru.com/en/identity/directory/attribute-mapping.md#writing-expressions).

### How Iru applies a push

**1. Iru accepts the request, then applies it**

Iru accepts each request right away and applies it to your users soon after. A success response means the request was accepted, not that the user is already updated. If a mapped value is wrong and the user cannot be applied, the provider still received success. The reason shows on the connection in Iru.

If the connection is turned off, Iru keeps what the provider sends and applies it when you turn the connection on.

**2. Inactive and deleted users**

When the provider marks a user inactive, Iru suspends that user. When the provider marks them active again, Iru restores them. A user the provider sends as inactive is created suspended, and does not get an invite.

When the provider deletes a user, Iru deletes that user, including a suspended one. Iru does not remove a user just because a later push left them out. A user is removed only when the provider deletes them.

**3. Groups follow the provider**

This applies when **Group sync** is set to **Sync groups and membership**. Groups the provider pushes then appear in Iru with their members. When the provider deletes a group, Iru deletes it. Members stay in Iru, and they lose the membership and any access that came through that group. **Don't sync groups** brings in users only.

### SCIM API

Iru follows SCIM 2.0 ([RFC 7643](https://www.rfc-editor.org/rfc/rfc7643), [RFC 7644](https://www.rfc-editor.org/rfc/rfc7644)). Paths are relative to the connection's **SCIM base URL**:

```
https://<organization host>/scim/v2/<connection id>
```

Send the API key on every request as `Authorization: Bearer <api key>`. Requests and responses use `application/scim+json`.

**Discovery**

| Method and path | Returns |
| - | - |
| `GET /ServiceProviderConfig` | The features Iru supports. |
| `GET /ResourceTypes` | `User`, with the enterprise and Iru extensions, and `Group`. |
| `GET /Schemas` and `GET /Schemas/{id}` | The User, Enterprise User, and Group schemas, plus the Iru extension for your organization's custom attributes. |

**Users**

| Method and path | What it does |
| - | - |
| `POST /Users` | Creates a user and returns it with its Iru `id`. |
| `GET /Users/{id}` | Returns one user. |
| `GET /Users?filter=…` | Lists users. |
| `PUT /Users/{id}` | Replaces the user. |
| `PATCH /Users/{id}` | Changes part of the user. |
| `DELETE /Users/{id}` | Deletes the user from Iru. |

**Groups**

| Method and path | What it does |
| - | - |
| `POST /Groups` | Creates a group. `displayName` is required. |
| `GET /Groups/{id}` | Returns one group. Add `excludedAttributes=members` to leave out the member list. |
| `GET /Groups?filter=…` | Lists groups. |
| `PUT /Groups/{id}` | Replaces the group, including its full member list. |
| `PATCH /Groups/{id}` | Adds, removes, or replaces members, or renames the group. |
| `DELETE /Groups/{id}` | Deletes the group from Iru. |

Each group member is `{"value": "<id>", "type": "User"}` or `"type": "Group"`. Use the `id` Iru returned for that user or group.

**Filtering, paging, and PATCH**

* **Filtering:** one `eq` comparison. For users, filter on `userName` or `externalId`. For groups, filter on `displayName` or `externalId`. For example, `filter=userName eq "jane@acme.com"`. Any other filter returns `400`.
* **Paging:** `startIndex` starts at 1. `count` sets the page size. A page holds 100 results by default and 200 at most.
* **PATCH:** `add`, `replace`, and `remove`. A path can be an attribute or sub-attribute (`name.givenName`), an extension attribute, or one list entry chosen by a single `eq` filter (`emails[type eq "work"].value`). A PATCH with no path sends an object of attributes.

**Errors**

| Status | When |
| - | - |
| `400` | Invalid JSON, an unsupported filter or PATCH path, or a value of the wrong type. |
| `401` | The API key is missing, wrong, revoked, or expired. |
| `404` | The user, group, or connection does not exist. |
| `409` | `userName` is already used in this connection, or the user changed during the request. Retry the request. |
| `413` | The request is too large. |

### Considerations

> [accordion] What Iru does not support
>
> Iru does not support bulk operations, sorting, ETags, or password changes. Passwords the provider sends are ignored, as are `id`, `meta`, and `groups` on a user. Filters other than one `eq` comparison on the attributes above are rejected.

> [accordion] Request limits
>
> A user request can be up to 1 MB. A group request can be up to 8 MB, about 100,000 members. For a list attribute, Iru keeps the first 10 entries. Lists nested inside other lists or objects are ignored.
>
> Iru does not limit the request rate today. When it does, a request over the limit gets `429 Too Many Requests` and a `Retry-After` header.

> [accordion] userName must be unique
>
> `userName` must be unique within the connection. A duplicate returns `409`. A user created again with the same `userName` gets the old `id` back, and is a new person in Iru. A group created again gets a new `id`.

> [accordion] A user missing a required value is not imported
>
> If the attribute used for username, email, or domain is empty, Iru skips that user and shows why on the connection.

> [accordion] Managers match by Iru id
>
> Send the manager's Iru `id` in the enterprise extension's `manager.value`. An email address or a username does not match. Order does not matter. Iru links a user to their manager once that manager has arrived.

> [accordion] Attribute names and the Iru role
>
> Standard attribute names must use the exact RFC spelling, such as `userName`, not `UserName`. Your own attribute names are case-insensitive.
>
> Put custom attributes in your own extension schema, or at the top level of the user. A top-level attribute with the same name as a standard one is ignored.
>
> The Iru role comes from `roles`. The mapped value must match a role's name or slug, ignoring case. A user whose value matches no role is not imported or updated. A new user gets End User unless a role is mapped. The account owner's role never changes through sync.

### Related Articles

> [card] [Directory Sync](https://docs.iru.com/en/identity/directory/directory-sync)
>
> The shared concepts behind every Directory Sync provider.

> [card] [Sync groups](https://docs.iru.com/en/identity/directory/group-sync.md)
>
> Bring groups and their membership into Iru from Google Workspace or inbound SCIM.

> [card] [Attribute mapping](https://docs.iru.com/en/identity/directory/attribute-mapping.md)
>
> Map SCIM attributes to Iru user fields, and reshape values with IQL.

> [card] [Connect Google Workspace](https://docs.iru.com/en/identity/directory/google-workspace.md)
>
> Read users from Google Workspace on a schedule, instead of receiving a SCIM push.


## Related topics

- [Directory Sync](https://docs.iru.com/en/identity/directory/directory-sync.md)
- [Sync groups](https://docs.iru.com/en/identity/directory/group-sync.md)
- [SCIM Directory Integration](https://docs.iru.com/en/endpoint/integrations/scim/scim-directory-integration.md)
