Skip to main content

About inbound SCIM

With Google Workspace, Workday, and BambooHR, 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.
This article covers inbound SCIM. For concepts shared across every provider, see 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.
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:
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.
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.
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.
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.
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.

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, RFC 7644). Paths are relative to the connection’s SCIM base URL:
Send the API key on every request as Authorization: Bearer <api key>. Requests and responses use application/scim+json. Discovery Users Groups 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

Considerations

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.
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.
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.
If the attribute used for username, email, or domain is empty, Iru skips that user and shows why on the connection.
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.
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.

Directory Sync

The shared concepts behind every Directory Sync provider.

Sync groups

Bring groups and their membership into Iru from Google Workspace or inbound SCIM.

Attribute mapping

Map SCIM attributes to Iru user fields, and reshape values with IQL.

Connect Google Workspace

Read users from Google Workspace on a schedule, instead of receiving a SCIM push.