SCIM user provisioning - Oleria Identity Security

Provision and deprovision Oleria workspace users and groups automatically from your identity provider (IdP) or any System for Cross-domain Identity Management (SCIM) 2.0 client, instead of managing each user by hand in Manage Users. Oleria exposes a SCIM 2.0 API so your IdP can create users, assign roles, manage group membership, and remove access as your directory changes. This page covers how to authenticate to the SCIM API, how Oleria maps SCIM users and groups to its role-based access control (RBAC) model, and the supported user, group, and service provider endpoints.

This page covers how to provision workspace users. To provision reviewers for access review campaigns and access requests, use the separate governance endpoint documented in SCIM reviewer provisioning.

Prerequisites

Administrator access to your Oleria workspace.
The SCIM client credentials for your workspace, found in Settings → SCIM Configuration.
A SCIM 2.0 client, such as your IdP’s outbound provisioning feature, that can send a bearer token on every request.

Authenticate to the SCIM API

The SCIM API uses the same OAuth 2.0 Client Credentials flow as the rest of the Oleria API. Oleria pre-creates a dedicated set of SCIM client credentials for your workspace, so you do not need to create an OAuth application. Find your Client ID, Client Secret, OAuth Token URL, and SCIM Base URL in Settings → SCIM Configuration. Exchange these credentials for a short-lived bearer token, then send that token on every SCIM request. See Generate an API Token for the token request and response, token lifetime, and reuse guidance - the flow is identical, except you use the SCIM credentials in Settings → SCIM Configuration instead of creating an OAuth application. Send all SCIM requests to your SCIM Base URL, shown in Settings → SCIM Configuration. The examples below show paths relative to this base URL.

Every SCIM request must include an Authorization header carrying the bearer token you minted with your SCIM client credentials: Authorization: Bearer YOUR_ACCESS_TOKEN.

How Oleria maps roles and groups

Oleria manages user access through RBAC roles. Each role carries a predefined set of permissions that are granted to any user assigned that role. Via SCIM, users receive roles only through group membership. Each group maps to exactly one role, and every member of that group inherits the role’s permissions. A user who belongs to more than one group receives the combined permissions of all their groups’ roles. The roles attribute on a user is read-only over SCIM. It reflects the roles a user has inherited from their groups; you cannot set or change it directly on the user. To change a user’s access, change their group membership or the role a group maps to. Sending roles in a user create, replace, or patch request returns 400 Bad Request. Oleria supports these predefined role values:

Role value	Grants
`admin`	Full administrator access to all features and settings.
`operator`	Operator access to Adaptive Security and connected integrations.
`analyst`	View-only analyst access.
`governance-operator`	Access to all Governance features, including access reviews, identity lifecycle, and access requests. Can view but not modify connected integrations.
`identity-lifecycle-operator`	Access to identity lifecycle, access bundles, and access requests. Cannot run access reviews. Can view but not modify connected integrations.

See Default user roles for a description of each role.

Provision a user with a role

Because roles are granted through groups, giving a user a role is a sequence of steps: create a group, map it to the role, create the user, then add the user to the group. Creating the group and mapping it to a role happen in a single request, and that setup is one-time per role. After that, you only create users and manage their group membership.

Create a group and map it to a role

Send a POST to /scim/v2/Groups with a displayName and the role the group maps to. See Create a group.

{
  "displayName": "Admins",
  "role": "admin"
}

The response includes the group’s id (for example, olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b). You use this id to add members.

Create the user

Send a POST to /scim/v2/Users with the user’s userName, name, and emails. Do not send roles - the user’s roles come from their groups. See Create a user.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jane@example.com",
  "name": { "formatted": "Jane Doe" },
  "emails": [{ "primary": true, "value": "jane@example.com" }]
}

The response includes the user’s id (for example, ol_8675309a-bc57-41d4-a716-446655440000).

Add the user to the group

Send a PATCH to /scim/v2/Groups/{id} that adds the user to the group’s members. The user immediately inherits the group’s role. See Update a group.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [{ "value": "ol_8675309a-bc57-41d4-a716-446655440000" }]
    }
  ]
}

You can combine the last two steps by including groups in the create request. See Create a user.

Users

A user’s attributes follow the SCIM core schema. The full list of supported attributes is in the SCIM core schema (RFC 7643 §4.1).

Attribute	Notes
`userName`	The user’s primary identifier. Must be their email address.
`name`	Provide either `formatted` or the name components (for example, `givenName` and `familyName`).
`emails`	Email addresses in SCIM format. At least one is required. Oleria associates only one email with the user: the `primary` email if one is marked, otherwise the first email in the list.
`active`	Whether the user is active. Defaults to `true`. Set to `false` to deactivate the user without deleting them.
`externalId`	Optional. An immutable identifier set by your provisioning client. You can set it on create; it cannot be changed afterward.
`groups`	The groups the user belongs to, which determine the user’s roles. Read-write: include it on create, replace, or patch to manage the user’s group membership.
`roles`	Read-only. Reflects the roles the user has inherited from their groups. Cannot be set or changed through the SCIM API.

Create a user

Send a POST to /scim/v2/Users. Include groups to add the user to one or more groups on creation, which grants them the groups’ roles. Omit groups to create a user with no group membership, then add them to groups later:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jane@example.com",
  "name": {
    "formatted": "Jane Doe"
  },
  "emails": [
    {
      "primary": true,
      "value": "jane@example.com"
    }
  ],
  "groups": [
    {
      "value": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
    }
  ]
}

Returns 201 Created. The roles in the response are read-only and reflect the user’s resulting membership and inherited roles:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "ol_8675309a-bc57-41d4-a716-446655440000",
  "userName": "jane@example.com",
  "name": {
    "formatted": "Jane Doe"
  },
  "emails": [
    {
      "primary": true,
      "value": "jane@example.com"
    }
  ],
  "active": true,
  "groups": [
    {
      "$ref": "https://api.YOUR_TENANT.oleria.io/scim/v2/Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
      "display": "Admins",
      "type": "direct",
      "value": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
    }
  ],
  "roles": [
    {
      "value": "admin"
    }
  ],
  "meta": {
    "resourceType": "User",
    "location": "Users/ol_8675309a-bc57-41d4-a716-446655440000"
  }
}

List users

Send a GET to /scim/v2/Users. Omit filter to return all users, or filter on an attribute such as userName:

GET /scim/v2/Users?filter=userName eq "jane@example.com"

Returns 200 OK with a list response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "startIndex": 1,
  "itemsPerPage": 100,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "ol_8675309a-bc57-41d4-a716-446655440000",
      "userName": "jane@example.com",
      "name": {
        "formatted": "Jane Doe"
      },
      "emails": [
        {
          "primary": true,
          "value": "jane@example.com"
        }
      ],
      "active": true,
      "groups": [
        {
          "$ref": "https://api.YOUR_TENANT.oleria.io/scim/v2/Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
          "display": "Admins",
          "type": "direct",
          "value": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
        }
      ],
      "meta": {
        "resourceType": "User",
        "location": "Users/ol_8675309a-bc57-41d4-a716-446655440000"
      },
      "roles": [
        {
          "value": "admin"
        }
      ]
    }
  ]
}

The list endpoints are paginated. Use the startIndex (1-based) and count query parameters to page through results, for example GET /scim/v2/Users?startIndex=1&count=50. Oleria returns at most 100 results per page. Keep requesting pages until you have retrieved totalResults records.

Get a user

Send a GET to /scim/v2/Users/{id}:

GET /scim/v2/Users/ol_8675309a-bc57-41d4-a716-446655440000

Returns 200 OK:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "ol_8675309a-bc57-41d4-a716-446655440000",
  "userName": "jane@example.com",
  "name": {
    "formatted": "Jane Doe"
  },
  "emails": [
    {
      "primary": true,
      "value": "jane@example.com"
    }
  ],
  "active": true,
  "groups": [
    {
      "$ref": "https://api.YOUR_TENANT.oleria.io/scim/v2/Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
      "display": "Admins",
      "type": "direct",
      "value": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
    }
  ],
  "meta": {
    "resourceType": "User",
    "location": "Users/ol_8675309a-bc57-41d4-a716-446655440000"
  },
  "roles": [
    {
      "value": "admin"
    }
  ]
}

Replace a user

Send a PUT to /scim/v2/Users/{id} to replace a user’s attributes with those in the request. This example moves the user to a different group, which changes their inherited role:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jane@example.com",
  "name": {
    "formatted": "Jane Doe"
  },
  "emails": [
    {
      "primary": true,
      "value": "jane@example.com"
    }
  ],
  "groups": [
    {
      "value": "olg_9f8e7d6c-5b4a-4c3d-9e2f-1a0b2c3d4e5f"
    }
  ]
}

A PUT replaces the user’s writable attributes with the values you send, so include every attribute you want to keep. Two exceptions: roles is read-only, so sending it returns 400 Bad Request; and omitting groups leaves the user’s current group membership unchanged rather than clearing it. To remove the user from all groups, send an empty groups array.

Returns 200 OK:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "ol_8675309a-bc57-41d4-a716-446655440000",
  "userName": "jane@example.com",
  "name": {
    "formatted": "Jane Doe"
  },
  "emails": [
    {
      "primary": true,
      "value": "jane@example.com"
    }
  ],
  "active": true,
  "groups": [
    {
      "$ref": "https://api.YOUR_TENANT.oleria.io/scim/v2/Groups/olg_9f8e7d6c-5b4a-4c3d-9e2f-1a0b2c3d4e5f",
      "display": "Operators",
      "type": "direct",
      "value": "olg_9f8e7d6c-5b4a-4c3d-9e2f-1a0b2c3d4e5f"
    }
  ],
  "meta": {
    "resourceType": "User",
    "location": "Users/ol_8675309a-bc57-41d4-a716-446655440000"
  },
  "roles": [
    {
      "value": "operator"
    }
  ]
}

Update a user

Send a PATCH to /scim/v2/Users/{id} to change specific attributes without replacing the whole user. The request body is a SCIM PatchOp with one or more operations. Oleria supports these operations on users:

Attribute (`path`)	Operations	Notes
`groups`	`add`, `remove`, `replace`	Manage the user’s group membership, which determines their roles.
`active`	`replace`	Set to `false` to deactivate the user or `true` to reactivate them.
`name`	`replace`	Replace the user’s name. Provide `formatted` or the name components (for example, `givenName` and `familyName`).

Any other path, or an unsupported operation on a supported path, returns 400 Bad Request. The roles attribute is read-only and cannot be patched. Add the user to a group:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "groups",
      "value": [
        {
          "value": "olg_9f8e7d6c-5b4a-4c3d-9e2f-1a0b2c3d4e5f"
        }
      ]
    }
  ]
}

Remove the user from a group:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "groups",
      "value": [
        {
          "value": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
        }
      ]
    }
  ]
}

Replace the user’s entire group membership with a new set:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "groups",
      "value": [
        {
          "value": "olg_9f8e7d6c-5b4a-4c3d-9e2f-1a0b2c3d4e5f"
        }
      ]
    }
  ]
}

To remove the user from all groups at once, send a remove operation on groups with no value:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "groups"
    }
  ]
}

Deactivate a user:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": false
    }
  ]
}

Change a user’s name:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "name",
      "value": {
        "formatted": "Jane M. Doe"
      }
    }
  ]
}

Each request returns 200 OK with the updated user resource, or 204 No Content if the operations produced no change.

Delete a user

Send a DELETE to /scim/v2/Users/{id}:

DELETE /scim/v2/Users/ol_8675309a-bc57-41d4-a716-446655440000

Returns 204 No Content with no response body.

Groups

A group’s attributes follow the SCIM core schema. The full list of supported attributes is in the SCIM core schema (RFC 7643 §4.2). In addition to the standard displayName and members, Oleria adds a role attribute that records which role the group maps to. All members of the group inherit that role.

Create a group

Send a POST to /scim/v2/Groups:

{
  "displayName": "Admins",
  "members": [
    {
      "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
    }
  ],
  "role": "admin"
}

Returns 201 Created:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
  "displayName": "Admins",
  "members": [
    {
      "$ref": "urn:ietf:params:scim:schemas:core:2.0:User",
      "display": "user@example.com",
      "type": "User",
      "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "location": "Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
  },
  "role": "admin"
}

List groups

Send a GET to /scim/v2/Groups:

GET /scim/v2/Groups

Returns 200 OK with a list response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "startIndex": 1,
  "itemsPerPage": 100,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "id": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
      "displayName": "Admins",
      "members": [
        {
          "$ref": "urn:ietf:params:scim:schemas:core:2.0:User",
          "display": "user@example.com",
          "type": "User",
          "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
        }
      ],
      "meta": {
        "resourceType": "Group",
        "location": "Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
      },
      "role": "admin"
    }
  ]
}

As with List users, the response is paginated with startIndex and count, returning at most 100 results per page.

Get a group

Send a GET to /scim/v2/Groups/{id}:

GET /scim/v2/Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b

Returns 200 OK:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
  "displayName": "Admins",
  "members": [
    {
      "$ref": "urn:ietf:params:scim:schemas:core:2.0:User",
      "display": "user@example.com",
      "type": "User",
      "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "location": "Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
  },
  "role": "admin"
}

Replace a group

Send a PUT to /scim/v2/Groups/{id} to replace all of a group’s attributes with those in the request. As with a create request, all attributes must be included. This example changes the group’s role:

{
  "displayName": "Admins",
  "members": [
    {
      "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
    }
  ],
  "role": "operator"
}

Returns 200 OK:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
  "displayName": "Admins",
  "members": [
    {
      "$ref": "urn:ietf:params:scim:schemas:core:2.0:User",
      "display": "user@example.com",
      "type": "User",
      "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "location": "Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
  },
  "role": "operator"
}

Update a group

Send a PATCH to /scim/v2/Groups/{id} to change specific attributes without replacing the whole group. The request body is a SCIM PatchOp with one or more operations. Oleria supports these operations on groups:

Attribute (`path`)	Operations	Notes
`members`	`add`, `remove`, `replace`	Manage the group’s membership. `replace` sets the full member list.
`role`	`replace`	Change the role the group maps to. All members inherit the new role.
`displayName`	`replace`	Rename the group.

Any other path, or an unsupported operation on a supported path, returns 400 Bad Request. Change the group’s role:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "role",
      "value": "operator"
    }
  ]
}

Rename the group:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "Platform Admins"
    }
  ]
}

Add a member to the group:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "ol_4b18b2d4-0751-4fea-afd7-27ae7c1785c0"
        }
      ]
    }
  ]
}

Remove a member from the group:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "members",
      "value": [
        {
          "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
        }
      ]
    }
  ]
}

Each request returns 200 OK with the updated group resource, or 204 No Content if the operations produced no change.

Delete a group

Send a DELETE to /scim/v2/Groups/{id}:

DELETE /scim/v2/Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b

Returns 204 No Content with no response body.

Service provider configuration endpoints

Oleria supports the standard SCIM discovery endpoints so clients can inspect the service provider’s capabilities. See the SCIM protocol, service provider configuration (RFC 7644 §4) for details.

Endpoint	Purpose
`GET /scim/v2/ResourceTypes`	Discover the resource types Oleria supports: Users and Groups.
`GET /scim/v2/Schemas`	Retrieve the resource schemas Oleria supports.
`GET /scim/v2/ServiceProviderConfig`	Describe the SCIM features available on the service provider.

SCIM specification reference

Contact us

For questions about SCIM provisioning, contact us at support@oleria.com.

​Prerequisites

​Authenticate to the SCIM API

​How Oleria maps roles and groups

​Provision a user with a role

​Users

​Create a user

​List users

​Get a user

​Replace a user

​Update a user

​Delete a user

​Groups

​Create a group

​List groups

​Get a group

​Replace a group

​Update a group

​Delete a group

​Service provider configuration endpoints

​SCIM specification reference

​Contact us

Prerequisites

Authenticate to the SCIM API

How Oleria maps roles and groups

Provision a user with a role

Users

Create a user

List users

Get a user

Replace a user

Update a user

Delete a user

Groups

Create a group

List groups

Get a group

Replace a group

Update a group

Delete a group

Service provider configuration endpoints

SCIM specification reference

Contact us