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 offboarding 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 integration docid\ mquniqc1hs6aks15roipx azure scim integration docid\ zw6aynxm yzpyacpfuwkr jumpcloud scim integration docid\ sjvsy89msbvqma91aid5k ping identity scim integration docid\ ytoezir1nbw xkyr qg6n 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 /#prerequisites for configuring scim base url and pat authentication authentication /#authentication scim rest api reference rest api endpoints for scim /#rest api endpoints for scim attribute mapping field mapping with swimlane /#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 /#field mapping with swimlane ) roles assigned in swimlane turbine are not overwritten by scim assign roles to synced groups manually after provisioning 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 by default, items per page should be 100 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" " test user\@okta local mailto\ test user\@okta local ", "name" { "givenname" "test", "familyname" "user" }, "emails" \[{ "primary" true, "value" " test user\@okta local mailto\ test user\@okta local ", "type" "work" }], "displayname" "test user", "locale" "en us", "externalid" "00ujl29u0le5t6aj10h7", "active" true, "groups" \[], "meta" { "resourcetype" "user" } } ] } 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" " test user\@okta local mailto\ test user\@okta local ", "name" { "givenname" "test", "middlename" "", "familyname" "user" }, "active" true, "emails" \[{ "primary" true, "value" " test user\@okta local mailto\ test user\@okta local ", "type" "work", "display" " test user\@okta local mailto\ test user\@okta local " }], "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" " test user\@okta local mailto\ test user\@okta local ", "name" { "givenname" "test", "familyname" "user" }, "emails" \[{ "primary" true, "value" " test user\@okta local mailto\ test user\@okta local ", "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" " test user\@okta local mailto\ test user\@okta local ", "name" { "givenname" "test", "familyname" "user" }, "emails" \[{ "primary" true, "value" " test user\@okta local mailto\ test user\@okta local ", "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 } 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" " test user\@okta local mailto\ test user\@okta local ", "name" { "givenname" "another", "middlename" "excited", "familyname" "user" }, "emails" \[{ "primary" true, "value" " test user\@okta local mailto\ test user\@okta local ", "type" "work", "display" " test user\@okta local mailto\ test user\@okta local " }], "active" true, "groups" \[], "meta" { "resourcetype" "user" } } response should return the updated user patch β patch /users/{userid} to activate, deactivate, or update user attributes, patch is used example request schema for { "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 put or 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 by default items perpage should be 100 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" " aashmi chaudhary+okta\@swimlane com mailto\ aashmi chaudhary+okta\@swimlane com " } ] } { "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" " test user\@okta local mailto\ test user\@okta local " }] } 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" " test user\@okta local mailto\ test user\@okta local " }] }] } 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