SCIM Integration for Users & Groups

microsoft entra id (previously azure active directory) scim support can be used to provision and modify users and groups in servicely automatically based on changes to the identity provider in microsoft entra id the provisioning is one way from entra id into servicely configuration in servicely servicely administrator role is required to perform all servicely configuration outlined on this documentation two records need to be configured in servicely to support integration with entra id a scimconfiguration record and a systemapitoken record scimconfiguration navigate to scim configurations page using the following navigation menu 2\ on the resulting page, click “new” to create a new configuration please ensure the scim configuration record is set to the below to active = yes and default = no field value active yes default yes if required, you may also create related attribute mapping record using the ones related to the sample scim configuration record (screenshot below), as examples if you do create related attribute mapping record(s), please ensure that they are active systemapitoken navigate to system api tokens page using the following navigation menu on the resulting page, click “new” to create a new configuration you can give it a name, e g “entra id scim” please then ensure that it is set to active = yes per the screenshot below 3\ then, a new bearer token needs to be generated which will need to be copied and placed in the entra id scim configuration click on generate token and copy the token value, so that it can be entered in the entra id scim configuration in the later steps below configuration in microsoft entra id (previously) azure active directory choose / set up entra id enterprise application sign into the entra id portal if you have an enterprise application that is used for sso to the servicely environment, you may use that otherwise, if you have to create a new enterprise application, please do that go to list of enterprise applications on entra id and click on “new application” on the following page, click on “create your own application” select “integrate any other application you don’t find in the gallery (non gallery)” option on the resulting “create your own application” pop up configuring entra id enterprise application select provisioning from the left hand menu and click get started if necessary select automatic from the provisioning mode menu enter the url for the scim endpoint and the system api token record’s “token” (recorded previously) for the servicely environment that is to be provisioned typical values look like tenant url https //\<instancename> servicely ai/scim/v2?aadoptscim062020 token (not shared secret) o1p2brkhlyox1 jkjljmx1uso5buweh4cohxylveaw2h7v please note that if you need to support multiple scim providers, you will need to have a different tenant url for each for more information, please see "support for multiple scim tenants" section click the test connection button to see if entra id can connect to the servicely scim endpoint successfully if there is no error message then the connection test was successful click the save button the save the configuration in entra id attribute mappings for users and groups need to be defined servicely currently only supports a fixed set of mappings note that the mappings are from the entra id schema to the scim schema and not to the servicely schema within servicely we have another set of mappings from scim to servicely tables and fields still on the provisioning screen, under the mappings section, click on provision azure active directory users to set the mappings for users the default unmodified set of mappings looks like this it is matching users by username we alter it to be suitable for mapping to servicely by changing or deleting mappings to change a mapping click on the mapping to bring up the edit attribute dialog make required changes click ok to delete a mapping click on the delete button changes change the mapping for externalid from mailnickname to objectid deletions delete the mappings for servicely is setting user's display field, based on the user's first and last name there is no need for entra id to dictate how servicely generates display name of users displayname name formatted you may also want to delete the below mappings if you are not mapping them to servicely there are no equivalent out of box fields in servicely's user table for the below entra id fields i e location field is a single reference field in servicely, while there is no field for fax however, if you want to map them, you can create custom scim configuration mapping to handle the incoming data refer to the "custom mappings" section addresses\[type eq "work"] formatted addresses\[type eq "work"] streetaddress addresses\[type eq "work"] locality addresses\[type eq "work"] region addresses\[type eq "work"] postalcode addresses\[type eq "work"] country phonenumbers\[type eq "fax"] value other you might also want to disable the delete action to ensure that servicely user accounts are never deleted in entra id you can set the account enabled property to false which will set the active property in servicely to false the typical end result looks like this click on provision azure active directory groups to set the mappings for groups the default unmodified set of mappings looks like below it is matching groups by displayname the default mapping for externalid is already objectid you might also want to disable the delete action to ensure that servicely groups are never deleted before turning on provisioning it is important to also set the user and group scope click on overview and then click on add scoping filters and make sure the scope is sync only assigned users and groups accidental deletion prevention and a notification email can also be set at this point to test provisioning immediately without having to wait for the provision cycle (40 minutes usually) you can use the provision on demand feature click on the provision on demand link and enter up to five users or a group and some users, then click on the provision button an attempt will be made to provision the named users and groups and the results will be displayed assigning users, groups if you are creating a new entra id enterprise application solely for user provisioning, you will need to assign users and groups into the enterprise application the assigned users and groups will then be synchronised across to servicely activate provisioning when ready , change provisioning status to on and click save provisioning will start automatically errors can be seen in the provisioning logs configuration in servicely (part 2) servicely mappings services has a set of default mappings from scim attributes to servicely properties and the ability to override these default mappings with custom mappings default mappings the default mappings provide the minimum required to make servicely integrate with azure ad scim user attribute servicely user field id externalkey externalid externalkey name givenname firstname name familyname lastname username username title title preferredlanguage preferredlanguage timezone timezone emails\[type == “work”] email phonenumbers\[type == “work”] deskphone phonenumbers\[type == “mobile”] mobile enterpriseuser employeenumber employeenumber enterpriseuser manager manager scim group attribute servicely group field id externalkey externalid externalkey displayname name custom mappings servicely supports custom mappings that override the default mappings and can also be used for mappings where there is no default mapping to add a new mapping click the new button on the attribute mappings related list of a scim configuration a mapping consists of a scim schema (user or group) and a scim top level attribute (such as username or emails) note that mappings for attributes that have a complex structure, such as emails, are handled in one mapping there are two scripts in a mapping inbound and outbound the inbound script is used to map from scim to servicely, while the outbound script is used to map from servicely to scim here is an example mapping for country, which maps the country part of an scim ‘work’ address attribute to a country field on the user record the outbound mapping creates a scim addresses response of type work that only contains the country subattribute note that the inbound and outbound scripts have to be inverses as entra id uses the results from servicely (and hence the result of the outbound script) to know if it should be setting the servicely field or not the inbound script is handling when entra id pushes data into servicely (in other words, map from scim to servicely), while, the outbound script is handling when entra id is querying servicely to find out the current servicely value for a particular mapping for a user/group record (in other words, map from servicely to scim) below is an example mapping for country, which maps the country part of an scim ‘work’ address attribute to a country field on the user record the outbound mapping creates a scim addresses response of type work that only contains the country subattribute here is an example mapping that uses two fields of the enterpriseuser attribute to set department and company on the user record departments and companies are created if they don’t exist inbound script example below // department (string) > urn\ ietf\ params\ scim\ schemas\ extension\ enterprise 2 0\ user\ department \[lookup by department name] > user department // companyname (string) > urn\ ietf\ params\ scim\ schemas\ extension\ enterprise 2 0\ user\ organization \[lookup by company name] > user company // attributedata will be something like // // { // "employeenumber" "5554433", // "organization" "foo", // "department" "bar", // "manager" { // "value" "4028818a3a2f75cc013a311ffad60000", // "displayname" "chris jones", // "$ref" "http //localhost 8080/#/user/4028818a3a2f75cc013a311ffad60000" // } // } // // we need to find the department and companyname attributes and look up and set on the user record // create new ones if they are missing if (attributedata) { let departmentname = attributedata department; let companyname = attributedata organization; if (departmentname) { let department = table("department", equal("name", departmentname)); if (!department) { department = table("department") newrecord() name(departmentname) create(); } current department(department id()); } if (companyname) { let company = table("company", equal("name", companyname)); if (!company) { company = table("company") newrecord() name(companyname) create(); } current company(company id()); } } outbound script example below // user department name > urn\ ietf\ params\ scim\ schemas\ extension\ enterprise 2 0\ user\ department > department // user company name > urn\ ietf\ params\ scim\ schemas\ extension\ enterprise 2 0\ user\ organization > companyname // attribute data might be null, if so we need to send at least // // { // "organization" "foo", // "department" "bar" // } let departmentname = null; let companyname = null; let department = current department(); if (department) { departmentname = department name(); } let company = current company(); if (company) { companyname = company name(); } if (departmentname || companyname) { attributedata = attributedata || {}; if (departmentname) { attributedata department = departmentname; } if (companyname) { attributedata organization = companyname; } } answer = attributedata; support for custom attribute you can add another attribute or more, to the entra id user/group provisioning's mapping as long as you are mapping to the available "customappsso " attributes example group email mapping entra id configuration go to group mapping screen, click on the show advanced options checkbox and then click on the edit attribute list for customappsso link 2\ on the edit attribute page, add new attribute named urn\ ietf\ params\ scim\ schemas\ extension\ servicely 2 0\ group\ extensionattribute1 and click “save” 3\ then, back on the group mapping screen, edit the mapping by clicking on “edit” 4\ on the “edit attribute” screen, set the “source attribute” to be mail 5\ then, the list of group mappings should look like the below servicely configuration go to the active scim configuration record for your entra id to servicely data synch and add a new related scim attribute mapping record the mapping should look like the below servicely field value name group email mapping active yes schema group attribute urn\ ietf\ params\ scim\ schemas\ extension\ servicely 2 0\ group inbound script servicely does not have an out of box field for email for group records, so, the below assumes you create a custom field called c email as needed, replace c email with your custom field’s name if (attributedata? extensionattribute1) { current c email(attributedata extensionattribute1); } outbound script servicely does not have an out of box field for email for group records, so, the below assumes you create a custom field called c email as needed, replace c email with your custom field’s name let email = current c email(); if (email) { attributedata = attributedata || {}; attributedata extensionattribute1 = email; } answer = attributedata; support for multiple scim tenants in situations where you need to support multiple scim tenants (or pushing user/group data from multiple entra id tenants), you will need a servicely scim configuration record for each tenant to change the tenant url and set the “key” field in servicely if you do not have the key, it will simply use one without the key tenant url https //\<instancename> servicely ai/scim/\<servicelykey>/v2?aadoptscim062020 an example of this is as per below tenant url https //\<instancename> servicely ai/scim/secondaryscimprovider/v2?aadoptscim062020 for each servicely scim configuration record, you will still need to configure the relevant related attribute mappings