User Provisioning via SCIM

There are several ways to bring users from external sources into Txture. One way is to configure a user importer that "pulls" user information into Txture. In some cases it is more desirable to let external applications send that information to Txture in a "push"-based fashion. Txture allows for push-based user and role provisioning by implementing the SCIM Standard, an open IETF standard for user data interchange.

From the SCIM perspective, Txture acts as the SCIM Provider that accepts and serves SCIM requests. It is important to note that in terms of identity authority, the SCIM Client controls the SCIM Provider, not the other way around. User and group information is provisioned by the client (e.g. Microsoft Entra ID) to the provider (Txture).

Provisioning Users and Roles via Microsoft Entra ID

API Token Setup

In order to provision users via Microsoft Entra ID, you first need to create an API Token within Txture. This token will be used by Microsoft Entra ID to authorize the provisioning requests. Since the Txture SCIM provisioning endpoints require admin permissions, please assign the "admin" role to it.

Save the token, and copy the token into your clipboard.

Make sure your Txture Server URL is set up correctly

It is always good practice to ensure that the Txture Server URL is configured correctly. However, it is of particular importance when working with SCIM, as SCIM responses contain full resource URLs, which include the Txture Server URL.

You can check this by going to the Txture Admin area / System Info and checking the Server URL there. If it doesn't match the actual URL, please configure it in your txture.properties file and restart the server.

Microsoft Entra ID Setup

After we have configured the External Application token in Txture, we need to let Microsoft Entra ID know that Txture exists and that it needs to be provisioned with users and groups.

SCIM support in Microsoft Entra ID

The SCIM support in Microsoft Entra ID is only available in Microsoft Entra ID. On-premise installations of Microsoft Microsoft Entra ID do not support SCIM at the time of writing this document.

In Microsoft Entra ID, navigate to Enterprise Applications / All Applications (1). Add your Txture instance as an Enterprise Application (2). In the sidebar, name your application and use the Integrate any other application that you don't find in the gallery option.

Proceed to the Provisioning section of your newly created Enterprise Application. Microsoft Entra ID requires the URL as well as an access token. Paste your access token (copied during the Txture API Token setup) from the clipboard into the appropriate field in the Admin Credentials section. For the URL, please enter the Txture server URL with the additional suffix /api/scim/v2/.

Important: Do not add any users or groups to this Enterprise Application yet.

Next, we need to configure the Attribute Mapping that decides which Microsoft Entra ID attributes are mapped to which SCIM standard attribues.

Unfold the "Mappings" category and click on "Provision Microsoft Entra ID Users". In the attribute mappings, ensure that the "Microsoft Entra ID Attribute" objectId maps to the "customappsso Attribute" externalId. If it does not, delete this particular mapping entry and add a new one that maps objectId to externalId. Repeat the same process for the Mapping "Provision Microsoft Entra ID Groups".

Do not change the 'externalId' mapping after provisioning users or groups

Microsoft Entra ID internally stores the externalId per user/group and application. Changing this mapping breaks this implicit relationship, causing errors during the provisioning. We strongly recommend to configure this mapping for this particular property once (before provisioning any users and/or groups) and to leave it untouched afterwards.

The next step is to select the Enterprise Application we've just created (3) and decide which groups and users in Microsoft Entra ID should be provisioned to Txture. All users and groups that belong to the Enterprise Application that represents Txture will be provisioned to your Txture instance.

In the "Users and Groups" section (1) you can add or remove users and roles from Txture (2). All changes performed in this panel will be synchronized to your Txture instance. By default, Microsoft Entra ID performs the synchronization process once every 40 minutes. You can provision individual users and groups manually via the "Provisioning" tab (3).

Azure AD groups are mapped and synchronized to Roles in Txture. Access control can then be managed in Txuture by assigning Permissions to the user roles.

OAuth with Microsoft Entra ID Provisioning

A common use case for user provisioning via SCIM is to use it in conjunction with OAuth. This allows the identity provider (e.g. Microsoft Entra ID) to fully manage access to the application. The setup for OAuth via SCIM-managed user accounts is similar to the regular SCIM setup, but involves a bit more configuration. For general information on the Txture OAuth mechanism, please refer to the respective documentation page.

In order to configure Txture to work with OAuth and SCIM via Microsoft Entra ID, please ensure that the OAuth authentication mechanism is set up in your Txture server. In your txture.properties file, configure the following:

txture.security.auth.enabled=oauth2
txture.security.auth.oauth2.clientId={CLIENT ID}
txture.security.auth.oauth2.clientSecret={CLIENT SECRET}
txture.security.auth.oauth2.uri.accessToken=https://login.microsoftonline.com/{TENANT ID}/oauth2/v2.0/token
txture.security.auth.oauth2.uri.authorization=https://login.microsoftonline.com/{TENANT ID}/oauth2/v2.0/authorize
txture.security.auth.oauth2.uri.userInfo=https://graph.microsoft.com/oidc/userinfo
txture.security.auth.oauth2.scope=openid email profile
# we strongly recommend using the OID as the corporate ID in txture, because (unlike the 'sub' claim) it doesn't change.
txture.security.auth.oauth2.corporateIdClaims=oid
# we recommend using the email claim as username to ensure uniqueness.
txture.security.auth.oauth2.usernameClaims=email
# If you want to disable on-the-fly user creation via OAuth, set this to false.
# This way, only users which were provisioned via SCIM first will be able to log in.
txture.security.auth.oauth2.createUser.enabled=false

Replace the placeholders for {CLIENT ID}, {CLIENT SECRET} and {TENANT_ID} accordingly, as described in our OAuth documentation page.

After changing those values in txture.properties, restart your Txture Server. If you have already configured the SCIM integration, it should work after the first provisioning cycle has been completed. If you did not configure the SCIM integration yet, log into Txture as administrator and follow the steps described in the SCIM setup section.

Txture SCIM Mapping

The SCIM Core Schema contains two main resources: Users and Groups. Many SCIM-compatible tools, such as Microsoft Entra ID, provide meaningful defaults for SCIM property values. However, in case that you do need to manually adapt the property mapping on the identity authority side, this section explains in detail how Txture processes the individual SCIM fields.

Txture SCIM User Mapping

A SCIM User is mapped to a Txture User Account.

SCIM User Property	Txture User Property	Constraints	Remarks
id	id	Unique, Read-Only	Txture-internal ID for this user.
externalId	corporateId	Unique, Immutable	Must be present in the create (POST) request, cannot be updated.
userName	userName	Unique
name.givenName	firstName
name.familyName	lastName
active	isActive		Deactivated users cannot log into Txture.
emails	email		See section on email mapping below.
phoneNumbers	phone / mobile		See section on phone mapping below.
preferredLanguage	settings.locale		See section on locale mapping below.
locale	settings.locale		See section on locale mapping below.
photos	profileImage		See section on profile image mapping below.

All SCIM attributes which are not listed in the table above are either unsupported or read-only (i.e. the SCIM client can query them but not modify them).

Please note that the built-in Admin account can not be modified via SCIM.

Mapping Email Addresses

The User.emails property in SCIM is multi-valued and consists of four sub-fields: display, value, primary and type. Txture only supports a single "email" property per user, which is the address that will receive all notification emails sent out by Txture. When a SCIM create or update request is received, Txture will try to find an address that meets a filter, falling back to a more general filter if no match is found. The filters are (in order):

1. The primary work email address (SCIM Path: emails[(primary eq true) and (type eq "work")])
2. The primary address, regardless of type (SCIM Path: emails[primary eq true])
3. Any work address (SCIM Path: emails[type eq "work"]). If there are multiple, the lexicographic smallest one is used.
4. Any address (SCIM Path: emails). If there are multiple, the lexicographic smallest one is used.

Txture will always use the contents value field; the display field is ignored during updates. When the email property is queried via SCIM, Txture will always report the (single) email address as primary and of type "work". Both display and value will be set to the actual email address string.

Mapping Phone Numbers

The User.phoneNumbers property in SCIM is multi-valued and consists of four fields: display, value, primary and type. Txture only supports a single "phone" property and a single "mobile" property per user. When a SCIM create or update request is received, Txture will try to find an appropriate value for both internal properties by applying a filter, and falling back to a more general filter if no match is found.

The filters for the internal "phone" property are:

1. The primary work phone number (SCIM Path: phoneNumbers[(primary eq true) and (type eq "work")])
2. The primary phone number (SCIM Path: phoneNumbers[primary eq true])
3. Any work phone number (SCIM Path: phoneNumbers[type eq "work"]). If there are multiple, the lexicographic smallest one is used.
4. Any phone number (SCIM Path: phoneNumbers). If there are multiple, the lexicographic smallest one is used.

The filters for the internal "mobile" property are:

1. The primary mobile phone number (SCIM Path: phoneNumbers[(primary eq true) and (type eq "mobile")])
2. Any mobile phone number (SCIM Path: phoneNumbers[type eq "mobile"]). If there are multiple, the lexicographic smallest one is used.

Txture will always use the contents value field; the display field is ignored during updates. When the phoneNumbers property is queried via SCIM, Txture will always report the (single) "phone" property as primary and of type "work", with both display and value set to the actual phone number string. If there is a "mobile" property, it will be reported to be of type "mobile". If there's only a mobile phone number, but no regular one, the mobile number will be reported as primary.

Mapping User Locale

The user locale decides which language is used on the Txture User Interface for that particular user (as of Txture 22, only English and German are supported). In SCIM, there are two different properties which can hold locale information: preferredLanguage and locale. Txture will attempt to find a language identifier first in preferredLanuage and then fall back to trying the same in the locale property. If no known language is found, the fallback is always English. The following table shows the language identifiers we're looking for (case-insensitive) after splitting the input value by punctuation (.,-_/) and whitespace:

Language	Identifiers	Example input values which are recognized	2-Letter-Code
German	de, deutsch, german	DE-AT, DE/AT, DE, Deutsch, Deutsch (Österreich), German, German (Austria)	de
English	en, english	EN-US, EN/US, EN, English, English (United States)	en

When queried, the preferredLanguage and locale fields will both reflect the selected language, as the 2-letter-code indicated in the table above.

Mapping Profile Images

SCIM defines the property photos for Users. photos is multi-valued and contains four sub-fields: value, display, type and primary, with the value containing a URI that hosts the image. Txture supports a single profile image per user. When an incoming call attempts to update the photos property, Txture will attempt to fetch the image from the value URI. There are several conditions that must be met in order for this process to work:

• The value field of the photo contains a valid URI that points to an existing location that hosts the image.
• The URI is public and can be acccessed without any authorization.
• Downloading the URI directly returns the bytes of the image.
• The image is of type PNG or JPEG/JPG.

If all of the conditions above are met, Txture can fetch the image and attach it to the user account as profile image. Since SCIM allows for multiple photos, Txture needs to choose one. It will attempt to download all images from their respective URIs and take the first one which delivers a valid result. The photo URIs will be checked in the following order:

1. The primary thumbnail image (SCIM Path: photos[(primary eq true) and (type eq "thumbnail")])
2. The primary image (SCIM Path: photos[primary eq true])
3. Any thumbnail (SCIM Path: photos[type eq "thumbnail"]). If there are multiple, the lexicographically smallest URI is tried first.
4. Any image (SCIM Path: photos). If there are multiple, the lexicographically smallest URI is tried first.

When queried, the photos field will either have no value or a single value. In the latter case, primary is set to true and the URI is a valid download URI that is hosted by the Txture server. Note, however, that this URI requires Txture authentication.

Txture SCIM Group Mapping

A SCIM Group (e.g. a group in Azure AD) is mapped to a Role in Txture. Even though SCIM defines the concept of a Role, it is intended for the role within a company (e.g. CEO, Sales Manager etc.) and not for access permissions. Txture Roles are used for permission management, therefore we map SCIM Groups to Txture Roles. SCIM Roles are not supported and will be ignored.

SCIM Group Property	Txture Role Property	Constraints	Remarks
id	id	Unique, Read-Only	Txture-internal ID for this role. Read-only .
externalId	corporateId	Unique, Immutable	Must be present in the create (POST) request, cannot be updated.
displayName	name
members	(managed in TxtureUser.roles)

All SCIM attributes which are not listed in the table above are either unsupported or read-only (i.e. the SCIM client can query them but not modify them).

The three built-in groups (All Users, Admin and External Applications) can not be modified via SCIM.