Provisioning with SCIM Integration

Swimlane Turbine supports integration with System for Cross-domain Identity Management (SCIM) 2.0. This helps streamline user management by automating onboarding and off boarding of users. Managing groups and the association of users to groups can be handled efficiently without manual intervention.

Swimlane Turbine supports SCIM 2.0 integration with:

Okta SCIM IntegrationOkta SCIM Integration

Azure SCIM IntegrationAzure SCIM Integration

JumpCloud SCIM IntegrationJumpCloud SCIM Integration

Ping Identity SCIM IntegrationPing Identity SCIM Integration

Choose Your Path

Goal	Go to
Configure SCIM in your IdP	IdP links in the info callout above
Prerequisites and network	Prerequisites for Configuring SCIM
Base URL and PAT authentication	Authentication
SCIM REST API reference	REST API Endpoints for SCIM
Attribute mapping	Field Mapping with Swimlane

With SCIM integration you can:

Create, retrieve, update, and deactivate users

Delete users in Swimlane Turbine (Turbine 26.0.0 and later)

Create, retrieve, update, and delete groups

Manage group membership through SCIM PUT or PATCH operations

Sync user profile fields from your IdP (see Field Mapping with Swimlane)

Roles assigned in Swimlane Turbine are not overwritten by SCIM. Assign roles to synced groups manually after provisioning.

Common User Lifecycle Behavior

User deprovisioning actions received through SCIM do not always result in user deletion. Depending on the provisioning event, users may be disabled in Swimlane Turbine rather than removed.

Examples include user suspension or removal from all SCIM-managed groups. Explicit SCIM DELETE operations continue to delete users when supported by the identity provider and Turbine version.

Prerequisites for Configuring SCIM

Supported IdP: Verify that your Identity Provider (IdP) supports SCIM integration.

SCIM-Compatible Configuration: Ensure Swimlane is configured to support SCIM integration and provides the required SCIM endpoints.

Network Configuration: Confirm that network settings allow communication between your IdP and Swimlane over HTTPS.

Authentication Credentials: Create a Swimlane Personal Access Token (PAT) for a user with Account Admin privileges at the account level.

Configuring SCIM

Provisioning a SCIM (System for Cross-domain Identity Management) application in an Identity Provider (IdP) involves configuring the IdP to communicate with the Service Provider (SP) using the SCIM protocol, ensuring efficient user identity management and automation.

See your IdP documentation for more information on provisioning SCIM in your IdP.

If you already have SAML and LDAP, you can still enable SCIM.

REST API Endpoints for SCIM

Following are the endpoints as part of the implementation on the tenant service (swimlane-tenant).

In the paths below, substitute ACCOUNT_ID with your Swimlane account UUID. For operations on a single resource, substitute userId or groupId with the SCIM resource id.

User endpoints

Method	Path
GET	/tenant/api/account/ACCOUNT_ID/scim/v2/Users
POST	/tenant/api/account/ACCOUNT_ID/scim/v2/Users
GET	/tenant/api/account/ACCOUNT_ID/scim/v2/Users/userId
PUT	/tenant/api/account/ACCOUNT_ID/scim/v2/Users/userId
PATCH	/tenant/api/account/ACCOUNT_ID/scim/v2/Users/userId
DELETE	/tenant/api/account/ACCOUNT_ID/scim/v2/Users/userId

DELETE /tenant/api/account/ACCOUNT_ID/scim/v2/Users/userId is supported in Turbine 26.0.0 and later. In earlier versions, user deprovisioning must be handled by updating the user status with PUT or PATCH and setting active to false.

Groups endpoints

Method	Path
GET	/tenant/api/account/ACCOUNT_ID/scim/v2/Groups
POST	/tenant/api/account/ACCOUNT_ID/scim/v2/Groups
GET	/tenant/api/account/ACCOUNT_ID/scim/v2/Groups/groupId
PUT	/tenant/api/account/ACCOUNT_ID/scim/v2/Groups/groupId
PATCH	/tenant/api/account/ACCOUNT_ID/scim/v2/Groups/groupId
DELETE	/tenant/api/account/ACCOUNT_ID/scim/v2/Groups/groupId

User Endpoint Examples

GET — Accepts startIndex and count query parameters. Accepts a filter query string such as filter=userName eq "${email}".

Returns the list of users that match the supplied filter criteria.

An empty or unsupported filter returns an empty result set by design. User lookups currently support filtering by userName.

Responses returned from userName-based filtering do not include group membership information. To retrieve complete group membership details, use GET /Users/{userId}.

Schema for empty Response:

{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "totalResults": 0, "startIndex": 1, "itemsPerPage": 0, "Resources": [] }

Schema for Response with Users:

{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "totalResults": 0, "startIndex": 1, "itemsPerPage": 0, "Resources": [ { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "23a35c27-23d3-4c03-b4c5-6443c09e7173", "userName": "[email protected]", "name": { "givenName": "Test", "familyName": "User" }, "emails": [{ "primary": true, "value": "[email protected]", "type": "work" }], "displayName": "Test User", "locale": "en-US", "externalId": "00ujl29u0le5T6Aj10h7", "active": true, "groups": [], "meta": { "resourceType": "User" } } ] }

Schema for Response with User Group Membership:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 100,
    "Resources": [
        {
            "userName": "[email protected]",
            "name": {
                "givenName": "Jane",
                "familyName": "Doe"
            },
            "emails": [
                {
                    "primary": true,
                    "value": "[email protected]",
                    "type": "work"
                }
            ],
            "displayName": "Jane Doe",
            "groups": [
                {
                    "value": "019f12cb-5197-7647-abc6-11c8e31fd0b0",
                    "display": "Engineering",
                    "type": "direct"
                }
            ],
            "active": true,
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "id": "019f1375-8d45-7077-ad89-a8026805f545"
        }
    ]
}

Get a Specific User - GET Users/userId

Response Schema for getting a user:

{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "23a35c27-23d3-4c03-b4c5-6443c09e7173", "userName": "[email protected]", "name": { "givenName": "Test", "middleName": "", "familyName": "User" }, "active": true, "emails": [{ "primary": true, "value": "[email protected]", "type": "work", "display": "[email protected]" }], "groups": [], "meta": { "resourceType": "User" } }

Beginning with Turbine 26.2, GET /Users/{userId} returns the user's group memberships when group associations exist in Swimlane Turbine.

Create - Post

It accepts the user details from SCIM and returns the user with additional fields added by Swimlane.

Request Schema:

{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "[email protected]", "name": { "givenName": "Test", "familyName": "User" }, "emails": [{ "primary": true, "value": "[email protected]", "type": "work" }], "displayName": "Test User", "locale": "en-US", "externalId": "00ujl29u0le5T6Aj10h7", "groups": [], "active": true }

Response Schema:

{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "23a35c27-23d3-4c03-b4c5-6443c09e7173", "userName": "[email protected]", "name": { "givenName": "Test", "familyName": "User" }, "emails": [{ "primary": true, "value": "[email protected]", "type": "work" }], "displayName": "Test User", "locale": "en-US", "externalId": "00ujl29u0le5T6Aj10h7", "active": true, "groups": [], "meta": { "resourceType": "User" } }

If the user already exists then response should be returned in following schema:

{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "detail": "User already exists in the database.", "status": 409 }

Example: Create a User and Assign to an Existing Group

Request

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "[email protected]",
    "displayName": "Jane Doe",
    "active": true,
    "groups": [
        {
            "value": "019f12cb-5197-7647-abc6-11c8e31fd0b0"
        }
    ]
}

Response

{
    "userName": "[email protected]",
    "displayName": "Jane Doe",
    "groups": [
        {
            "value": "019f12cb-5197-7647-abc6-11c8e31fd0b0",
            "display": "Engineering",
            "type": "direct"
        }
    ],
    "active": true,
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "019f1375-8d45-7077-ad89-a8026805f545"
}

If the specified group exists in the same Swimlane account, the user is created and associated with that group. If the group ID is invalid or belongs to a different account, the user is created successfully and the groups attribute in the response is returned as an empty array.

PUT — PUT /Users/{userId}

Request schema to update the user:

{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "23a35c27-23d3-4c03-b4c5-6443c09e7173", "userName": "[email protected]", "name": { "givenName": "Another", "middleName": "Excited", "familyName": "User" }, "emails": [{ "primary": true, "value": "[email protected]", "type": "work", "display": "[email protected]" }], "active": true, "groups": [], "meta": { "resourceType": "User" } }

Response should return the updated user.

Example: Add a User to an Existing Group

Request

{
    "groups": [
        {
            "value": "019f12cb-5197-7647-abc6-11c8e31fd0b0"
        }
    ]
}

Response

{
    "userName": "[email protected]",
    "displayName": "Jane Doe",
    "groups": [
        {
            "value": "019f12cb-5197-7647-abc6-11c8e31fd0b0",
            "display": "Engineering",
            "type": "direct"
        }
    ],
    "active": true
}

When groups is included in a PUT request, the specified groups are added to the user's existing group memberships. Existing group memberships are retained. If a referenced group does not exist or belongs to another account, the user is updated successfully and the groups attribute in the response is returned as an empty array.

PATCH — PATCH /Users/{userId}

To disable, enable, or update user attributes, PATCH is used.

Example request schema for disabling the users:

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

Response for patch should be updated user or 204.

DELETE /Users/{userId} deletes the user in Swimlane Turbine. This endpoint is supported in Turbine 26.0.0 and later. In earlier versions, use PATCH with active set to false to disable the user and revoke access.

Group Endpoint Examples

GET — /Groups — Accepts startIndex and count query parameters.

Group queries currently support filtering by displayName only. Example: filter=displayName eq "Group Name" An empty filter returns an empty result set.

GET should accept query string filter = displayName eq "$"

Sample Request:

/tenant/api/account/ACCOUNT_ID/scim/v2/Groups?filter=displayName%20eq%20%22Test%20SCIMv2%22&startIndex=1&count=100

Response Schema if group exists:

{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 1, "startIndex": 1, "itemsPerPage": 1, "Resources": [ { "id": "e7d09e9b3faa4888b65cf9e9316cba1c", "meta": { "created": "2024-05-15T09:21:23", "lastModified": "2024-05-15T09:21:23", "version": "v1.0" }, "displayName": "Test SCIMv1" }, ] }

Response schema if no group exists:

{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "totalResults": 0, "startIndex": 1, "itemsPerPage": 0, "Resources": [] }

GET — GET /Groups/{groupId}

Response schema:

{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b", "displayName": "Test SCIMv2", "members": [{ "value": "b1c794f24f4c49f4b5d503a4cb2686ea", "display": "SCIM 2 Group A" }], "meta": { "resourceType": "Group" } }

POST - Request schema, Response should be group object same as Get.

Example:

{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "TestGroup", "members": [ { "value": "584a1e86-5de0-4634-80a6-f357156de9f3", "display": "[email protected]" } ] }

{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "displayName": "Test SCIMv2", "members": [] }

PUT — PUT /Groups/{groupId}

Use PUT to send a full SCIM Group resource. Swimlane creates the group if it does not exist (matched by display name or SCIM external ID), updates group details when applicable, and adds members listed in the request body.

Many IdPs (for example, Azure and Okta) use PATCH for group rename and membership changes instead of PUT. See the PATCH examples below.

Request schema:

{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b", "displayName": "Test SCIMv2", "members": [{ "value": "23a35c27-23d3-4c03-b4c5-6443c09e7173", "display": "[email protected]" }] }

Response should return the updated group object (HTTP 200), with the same shape as GET group by ID.

PATCH — PATCH /Groups/{groupId}

PATCH is used to update the group display name or group membership (add or remove members).

Request schema for PATCH to update group name:

{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "replace", "value": { "id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b", "displayName": "Test SCIMv2" } }] }

Response for patch could be the updated group object or 204.

Users can be added by PATCH for OIN app.

Request schema :

{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "remove", "path": "members[value eq \"89bb1940-b905-4575-9e7f-6f887cfb368e\"]" }, { "op": "add", "path": "members", "value": [{ "value": "23a35c27-23d3-4c03-b4c5-6443c09e7173", "display": "[email protected]" }] }] }

The response should be the updated group or 204.

DELETE — DELETE /Groups/{groupId} — Returns 204 when the group is deleted.

Authentication

The SCIM endpoint uses User PAT Token defined for the user at an account level.

The SCIM base URL includes your Swimlane hostname and account UUID. Use this format when configuring your IdP (Tenant URL or Base URL):

https://your-swimlane-host/tenant/api/account/ACCOUNT_ID/scim/v2

Replace your-swimlane-host with your Swimlane Turbine hostname and ACCOUNT_ID with your account UUID. IdPs append resource paths such as /Users and /Groups. See the IdP-specific guides linked at the top of this page.

Authorization

User with Account Admin privilege should be able to access the endpoints

Cross-account access is restricted

All the roles assigned in Turbine for the users and groups will not be overwritten by the SCIM API Endpoint call

Field Mapping with Swimlane

SCIM	Swimlane
userName	Email
name.givenName	firstname
name.familyName	lastname
displayName	DisplayName
groups	Groups
active	disabled

When provisioning from Azure, only userPrincipalName and displayName are required. If firstname, lastname, or email are not provided by Azure, Swimlane will automatically substitute them using the value from userPrincipalName.