Automatic provisioning#

Automatic provisioning refers to creating user identities, roles and their membership in an organization in Skalio ID by an external identity provider. In addition to creating user identities, automatic provisioning includes the maintenance and removal of user identities as status or roles change.

Skalio ID supports automatic provisioning according to the SCIM 2.0 standard.

Concept#

A customer typically manages their users and privileges in a central location. To help automatic provisioning of these users within Skalio ID, a set of API endpoints are exposed that allow the creation, modification and removal of user accounts by the customer. The API endpoints implement parts of the System for Cross-domain Identity Management (SCIM) 2.0. An SCIM-compliant provisioning agent can make use of these endpoints to manage the organization's data.

An introduction to SCIM can be found here: https://aka.ms/scimoverview

Scope#

The SCIM provisioning interface operates always within the context of a Skalio ID organization. The organization must exist beforehand and be mapped to the external identity provider.

Skalio ID supports the following functionality:

• Create a new user within your organization
• List, search for users of your organization
• Update properties of a user:
  • name
  • email address: update, make primary, add/remove additional addresses
  • preferred language, timezone
  • external username: not used by Skalio ID, it exists only as a link to the external identity provider
  • roles/privileges
• Activate or deactivate a user
• Delete a user and all their data

The following external identity providers are supported:

• Microsoft Entra ID

Additional identity providers can be requested via support@teambeam.de.

Limitations#

• Authentication of users cannot be managed. Since SCIM-provisioned users must be authenticated by their external identity provider, they cannot authenticate locally (using passwords or MFA).
• No support for /Groups. The concept is not used by Skalio ID.
• No support for /Bulk operations.
• Members of the organization that are not mapped to an external identity provider ("local users") cannot be managed.
• Email addresses must be unique across the complete system and all organizations. Attempting to set an email address that is not unique fails the request.
• Only named external identity providers are supported.

Licensing#

This feature is included in all commercial licenses.

Sufficient staff-licenses are required in order to create or activate users. A deactivated user does not require a staff-license.

Service URL#

The SCIM 2.0 service is available at the following URL: /api/id/v3/scim. Please use the appropriate hostname. SCIM requires a connection using TLS v1.2.

These endpoints exist:

• https://id.teambeam.de/api/id/v3/scim/ServiceProviderConfig
• https://id.teambeam.de/api/id/v3/scim/Schemas
• https://id.teambeam.de/api/id/v3/scim/ResourceTypes
• https://id.teambeam.de/api/id/v3/scim/Users

Microsoft Entra ID#

To address some issues with protocol compliance in Microsoft's implementation of SCIM, the URL must contain "query parameter" aadOptscim062020.

Without this parameter present, Microsoft Entra ID will not send correct requests when updating role-assignments.

Authentication#

Requests to the /Users SCIM endpoint must be authenticated using a bearer token. The token identifies the tenant / organization the request belongs to. The organization must exist already in Skalio ID.

Microsoft Entra ID#

Microsoft Entra ID auto-creates a bearer token, if the Secret Token field of the configuration is left blank. Microsoft Entra ID issues the token itself and includes it in every request. Skalio ID verifies the token against its signature, validity timeframe and issuer. The following issuers are supported:

• https://sts.windows.net/{tenantId}/
• https://login.microsoftonline.com/{tenantId}/2.0

The Microsoft Entra tenant ID is encoded in the tid claim and must match the externalUid of the Skalio ID organization.

Schema mapping#

SCIM standardizes the schema used in the information exchange between SCIM client (the external identity provider) and SCIM server (Skalio ID).

An administrator must configure the schema mapping when integrating the external identity provider with Skalio ID.

Microsoft Entra ID#

The configuration of the schema mapping requires TeamBeam as a Microsoft Entra Enterprise application.

Required	Microsoft Entra attribute	SCIM attribute	Skalio ID attribute
yes	userPrincipalName	userName	externalUserName
yes	objectId	externalId	externalUid
yes	Expression: Switch([IsSoftDeleted], , "False", "True", "True", "False")	active	active
one or more	mail	emails[type eq "work"].value emails[type eq "work"].primary	email[].address email[].primary
no	Expression: Join(" ", [givenName], [surname])	name.formatted	name
no	preferredLanguage	preferredLanguage	locale
no	n/a	timezone	timezone
no	Expression: AssertiveAppRoleAssignmentsComplex([appRoleAssignments])	roles[]	membership.roles[]

Note:

• If preferredLanguage or timezone are not set, the values of the organization are used.
• "App-Role assignments" are mapped to roles
• Before the mapping for the roles attribute can be configured, the attribute must be added to the mappings:
  • Name: roles
  • Type: string
  • Multi-value: yes
  • Required: no
• Multiple email addresses can be transferred, but only one can be marked as primary.

Configuration#

Skalio ID#

The customer's organization must exist. Typically, it is created during the purchasing flow of subscription management.

The organization must have sufficient staff-account licenses to accommodate the total number of active users that are to be provisioned.

The external identity provider's tenant ID must be configured for the organization. Typically, this step is done by Skalio operations staff in coordination with the customer.

Microsoft Entra ID: gallery app#

Microsoft Entra ID: non-gallery app#

For customers who want to integrate TeamBeam and Skalio ID into their Entra tenant independent of the published gallery app should follow this section. Doing so requires the customer to manage both the Entra enterprise application and the application registration, which is usually managed by Skalio. Reasons for doing so may be that the customer wants full control over the app registration, or to integrate an on-premises system.

A member of the customer's organization with access to Microsoft Entra ID must perform the integration of TeamBeam as an Enterprise application. The person must be assigned one of the following roles: Application Administrator, Cloud Application Administrator, or Global Administrator.

Create application#

Open Applications > Enterprise applications and click on New application. Click + Create your own application, enter a descriptive name and select Integrate any other application you don't find in the gallery (Non-gallery). Click on Create. This creates a new enterprise application and the matching application registration.

App registration#

Switch to Applications > App registrations and find the newly created app, possibly under All applications. Under Branding & properties you can configure several attributes regarding the appearance of the application for your users.

Authentication#

Switch to Authentication and click + Add a platform. Select Web and enter a redirect URI. Typically, it looks like this: https://customer.teambeam.pro/api/id/v3/oidc/auth/form, with the hostname likely requiring adjusting. Click on Configure. Add a Front-channel logout URL: https://customer.teambeam.pro/api/id/v3/oidc/auth/logout. Ensure ID tokens is activated. Select the Supported account types. Click Save.

Token configuration#

Switch to Authentication and click + Add optional claim, select token type ID. Activate sid, verified_primary_email, xms_pl and xms_tpl, click Add.

App roles#

Switch to App roles and click + Create app role. Fill in the details:

Repeat this for all roles described here.

Delete the User role (open it, set a value, disable it, save, then re-open and delete it).

Client ID#

Switch to Overview and select the value for Application (client) ID. Inform Skalio support of the value, together with your tenant ID.

Before you can continue, these values must be configured in Skalio ID by Skalio support.

Enterprise application#

Switch to Application > Enterprise applications and find the newly created app.

Provisioning#

Click on Provisioning, then Get Started. Select Provisioning Mode: Automatic. Enter the tenant URL: https://id.teambeam.de/api/id/v3/scim?aadOptscim062020. Possibly the hostname may need to be adapted. Leave the Secret Token blank and click on Test Connection. When the test is successful, click on Save.

Under Manage provisioning click on Edit attribute mappings. Open Mappings and click on Provision Microsoft Entra ID Users. Activate Show advanced options and click on Edit attribute list for customappsso. Scroll to the bottom and enter roles, type String, check Multi-Value?, click on Save.

Remove unnecessary attribute mappings until only the following are left:

• userName
• active
• emails[type eq "work"].value
• preferredLanguage
• name.formatted
• externalId

Edit externalId, change Source attribute to objectId. Click on Ok.

Click on Add mapping. Select Mapping type: Expression and use this value: AssertiveAppRoleAssignmentsComplex([appRoleAssignments]). Select the previously created Target attribute roles and click on Ok.

Click on Save and close the view.

Assign users#

Switch to the enterprise application and open Users and groups. Click + add user/group. Select users or groups and assign the appropriate app role to them.

Test & start provisioning#

Switch back to the Provisioning view and click on Provision on demand. Search for a user that has been assigned before and click on Provision. Observe the output.

If provisioning was successful, close the view and activate Start provisioning. Once started, it will run at regular intervals, typically once within 40 minutes. Entra collects logs of provisioning sessions.