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.

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, and Authentication 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 from Settings → SCIM Configuration instead of creating an OAuth application. Send all SCIM requests to your Oleria API URL with the /scim/v2 path appended (for example, https://devx.YOUR_TENANT.oleria.io/scim/v2). Your API URL is shown alongside your credentials 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. Roles can be assigned in two ways:

Directly to a user through the roles attribute on the user.
Indirectly through group membership. Each group maps to exactly one role, and all members of the group inherit that role’s permissions.

A user with both direct and inherited roles receives the combined permissions of all assigned roles. The recommended pattern is to create one group per role and assign users to groups accordingly. Reserve direct role assignment for one-off exceptions, such as temporary admin escalation. 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.

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). Note these Oleria-specific behaviors:

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.
`roles`	Roles assigned directly to the user. Additive with any roles inherited from group membership.

Create a user

Send a POST to /scim/v2/Users:

{
  "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"
    }
  ],
  "roles": [
    {
      "value": "admin"
    }
  ]
}

Returns 201 Created:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "ol_8675309a-bc57-41d4-a716-446655440000",
  "userName": "jane@example.com",
  "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,
  "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"
        }
      ],
      "meta": {
        "resourceType": "User",
        "location": "Users/ol_8675309a-bc57-41d4-a716-446655440000"
      },
      "roles": [
        {
          "value": "analyst"
        }
      ]
    }
  ]
}

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"
    }
  ],
  "meta": {
    "resourceType": "User",
    "location": "Users/ol_8675309a-bc57-41d4-a716-446655440000"
  },
  "roles": [
    {
      "value": "analyst"
    }
  ]
}

Replace a user

Send a PUT to /scim/v2/Users/{id} to replace all of a user’s attributes with those in the request.

As with a create request, all attributes must be included. Any attribute you omit is cleared.

{
  "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"
    }
  ],
  "roles": [
    {
      "value": "analyst"
    }
  ]
}

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"
    }
  ],
  "meta": {
    "resourceType": "User",
    "location": "Users/ol_8675309a-bc57-41d4-a716-446655440000"
  },
  "roles": [
    {
      "value": "analyst"
    }
  ]
}

Update a user

Oleria has only partial support for PATCH on users and makes no guarantees about future support. Use Replace a user (PUT) instead.

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"
    }
  ]
}

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 update some of a group’s attributes using the add, remove, and replace operations. Change the group’s role:

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

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.

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

​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

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