Provisioning with SCIM Integration

swimlane turbine supports integration with system for cross domain identity management (scim) 2 0 this helps to 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 both okta scim/sso application configuration and azure scim integration (microsoft entra) with scim integration you can create a new user with group create a new user without any group retrieve a user by id create a new user without any group that exists in swimlane turbine delete a user disable user delete the user in turbine and not let them login to the application activating a user in an idp activates the user in turbine update user profile information to update in swimlane turbine create a group with users create a group without users update a group delete a group 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 obtain necessary credentials (for example, oauth tokens, api keys) for secure communication 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) user endpoints post /tenant/api/account/{account id}/scim/v2/users get /tenant/api/account/{account id}/scim/v2/users/{userid} delete /tenant/api/account/{account id}//scim/v2/users/{userid} patch /tenant/api/account/{account id}/scim/v2/users/{userid} put /tenant/api/account/{account id}//scim/v2/users/{userid} groups endpoints 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} delete /tenant/api/account/{account id}/scim/v2/groups/{groupid} patch /tenant/api/account/{account id}/scim/v2/groups/{groupid} user endpoint examples get accepts startindex and count query param by default items perpage should be 100 accepts a filter query string like filter=username eq "${email}" returns the list of users or empty array 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", "name" { "givenname" "test", "familyname" "user" }, "emails" \[{ "primary" true, "value" "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", "name" { "givenname" "test", "middlename" "", "familyname" "user" }, "active" true, "emails" \[{ "primary" true, "value" "test user\@okta local", "type" "work", "display" "test user\@okta local" }], "groups" \[], "meta" { "resourcetype" "user" } } 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", "name" { "givenname" "test", "familyname" "user" }, "emails" \[{ "primary" true, "value" "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", "name" { "givenname" "test", "familyname" "user" }, "emails" \[{ "primary" true, "value" "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 } update 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", "name" { "givenname" "another", "middlename" "excited", "familyname" "user" }, "emails" \[{ "primary" true, "value" "test user\@okta local", "type" "work", "display" "test user\@okta local" }], "active" true, "groups" \[], "meta" { "resourcetype" "user" } } response should return the updated user patch patch /users/$userid to activate/deactivate/password sync the user, 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 delete is not directly supported from okta patch is used for deprovisioning or deactivating the user group endpoint examples get /groups accepts startindex and count query param by default items perpage should be 100 get should accept query string filter = displayname eq "${groupname}" sample request /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 a specific group /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" } ] } { "schemas" \["urn\ ietf\ params\ scim\ schemas\ core 2 0\ group"], "displayname" "test scimv2", "members" \[] } put patch /groups/$groupid patch is used to update the group object like name 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" }] }] } response should the updated group or 204 delete /groups/$groupid should return 204 authentication the scim endpoint uses user pat token defined for the user at an account level the base url will include {accountid} in the following format and will be used as identifier of the account for which users and groups are created /tenant/api/account/{account id}/scim/v2/ 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 use case okta scim/sso application configuration provisioning scim application in okta log in to okta as an administrator on the left panel, select applications > applications , and click browse app catalog search for scim 2 0 app in the search field click on add integration > integrate the app click on provisioning tab and configure api integration enter the base url {baseurl}/tenant/api/scim/v2 in base url and pat in api token and click save assigning users to provision okta users in swimlane turbine, create users in okta, assign the users to a group, and then assign the provisioning app to the group create users in okta in okta, on the left panel, select directory > people , and click add person in the add person dialog box, enter the user details click save or click save and add another to add another user from the assignments tab, click assign from the pop up menu, click assign to people assign any user and verify that the assigned user is added in swimlane account note that swimlane turbine displays only few fields from the user fields for example, see field mapping editing or removing users from the assignments tab, click on assign click edit symbol next to the user update any user detail such as mapped fields givenname, familyname, display name, and so on and click save to delete a user, click delete icon next to the user and click save verify that user info is updated in swimlane assigning groups if you do not already have your user groups set up in you idp, you will need to create them these will be the groups that you will later assign role and account access to in swimlane to learn how to create groups, see your idp documentation assigning users is done using two different tabs in the app we recommend having your users selected on the assignments tab and their associated groups selected on the push groups tab in the app, click on the assignments tab from the assignments form, click on assign from the pop up menu, click on assign to groups from the assign to groups form, click on assign for the group you wish to assign to the application click on save and go back repeat the steps to add a group until all desired groups have been assigned to the application click done pushing groups in the app, click on the push groups tab from the push groups form, click on push groups from the pop up menu, click on find groups by name from the push groups by name form, in the search field enter the first few characters of the name of the group you want to send to swimlane leave the push group memberships immediately checkbox checked click on your group in the pop up search results list if this is the last group you wish to send to swimlane, click on save otherwise, if you have more groups to configure, click on save & add another and repeat the steps to add a group without pushing the group, the group will not sync in turbine once that is done that group will be syncing until it is deactivated in okta verify the group, group members, and user group association is added to turbine use case azure scim integration (microsoft entra) swimlane turbine supports scim 2 0 integration with azure active directory (microsoft entra) this integration enables administrators to automatically provision users and groups to swimlane using the scim standard high level configuration steps in the azure portal, create an enterprise application and enable scim provisioning under the provisioning tab set the provisioning mode to automatic enter your swimlane tenant url and secret token to create a secret token, see get a microsoft entra token https //learn microsoft com/en us/rest/api/eventhub/get azure active directory token use provision on demand to manually sync a user or group if needed assign users and groups under the users and groups tab in the azure application user provisioning provisioning users from microsoft entra id to swimlane turbine takes approximately 40 minutes this interval is controlled by microsoft and applies to all user related operations, such as updating user details or removing user assignments these changes are synced to swimlane at the end of the next 40 minute cycle group provisioning provisioning groups, with or without users, typically takes 20 minutes to sync with swimlane this applies to changes such as adding or removing users from a group updating group details deleting groups or removing group assignments from the scim application understanding provisioning cycles in the overview tab of your azure scim configuration, you can view provisioning cycle timestamps the most relevant fields are last cycle start time and last cycle completed time any user or group related changes made after the last cycle start time will be processed in the next provisioning run—approximately 40 minutes later for users and 20 minutes later for groups immediate provisioning (provision on demand) to sync a user or group immediately, use the provision on demand feature available in the left navigation pane of the azure scim configuration this triggers an instant provisioning attempt for the selected user or group keep the following in mind provision on demand only supports provisioning; it does not support updates, deletions, or group membership changes when provisioning groups, you can select individual users rather than syncing the entire group attribute handling azure requires only the userprincipalname and displayname attributes swimlane expects additional attributes, including firstname , lastname , email , and displayname if any required attribute is missing, swimlane uses the userprincipalname value as a fallback for more information, see how scim provisioning works in azure ad https //learn microsoft com/en us/azure/active directory/app provisioning/how provisioning works on microsoft learn