Skip to content

User Metering Named Identifier for SCIM, OIDC SSO, and SAML #10070

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 12 commits into from
Closed

User Metering Named Identifier for SCIM, OIDC SSO, and SAML #10070

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
167f04c
OIDC changes
Karuna-Mendix Sep 8, 2025
15eb609
User Identifier in the OIDC SSO module
Karuna-Mendix Sep 9, 2025
16dee4b
User Identifier in the SCIM module
Karuna-Mendix Sep 9, 2025
a2e2513
User Identifier in the SAML module
Karuna-Mendix Sep 9, 2025
15ae6ff
Image updated
Karuna-Mendix Sep 9, 2025
f44c29e
SAML feedback
Karuna-Mendix Oct 14, 2025
4fc5ea3
OIDC feedback
Karuna-Mendix Oct 14, 2025
f31853f
SCIM feedback
Karuna-Mendix Oct 14, 2025
2be3619
SAML changes as per Jaap's comments
Karuna-Mendix Oct 31, 2025
eb051b4
SCIM changes as per Jaap's comment
Karuna-Mendix Oct 31, 2025
af46310
OIDC changes
Karuna-Mendix Oct 31, 2025
4d62ba4
Merge branch 'development' into kv-usercommons
Karuna-Mendix Oct 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion content/en/docs/marketplace/platform-supported-content/modules/SAML/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -470,7 +470,12 @@ You can set up custom user provisioning by selecting the **IdP Configuration** t

The microflow must return a **System.User** object to ensure proper user provisioning and updates. It will be executed after user creation or update of user. However, starting from version 2.0.0 of the UserCommons module, this is no longer mandatory. If you have added a new microflow, you will need to refresh the module containing your microflow as described in the [Mx Model Reflection](/appstore/modules/model-reflection/). This selection can be blank if you do not want to add custom logic.

4. Click **Save** to save the configuration.
4. To improve licensing and metering accuracy, a configuration requires the use of a mandatory **User Metering Named Identifier**, for example, `email` or `sub`, etc.
Copy link

@JaapF JaapF Oct 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to explain better:

"To facilitate future improvements in the Mendix platform's user metering capabilities, you can configure which cliam you want to map to the User Metering Named Identifier. This is specifically relevant if a multi-app user license is allocated to your application; you need to make sure that a multi-app user gets the same value for the User Metering Named Identifier in each of the apps for that user. In most cases the end user's email address is the best choice, so we've made that a default.
The platform's current user metering mechanism is using the system.user.name to count users. It is often used for technical user identifiers, e.g. the "oid" value when using OIDC SSO module. See https://docs.mendix.com/appstore/modules/oidc/#guidance-user-identifier "

Copy link

@JaapF JaapF Oct 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@karuna, I will confirm this messaging on monday after meeting with Job/Satyam. As i said before.

Copy link

@JaapF JaapF Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would want the "guidance-user-identifier" section to be updated as well.
I think it needs to include the info about the new User Metering Named Identifier as well.

Copy link
Collaborator Author

@Karuna-Mendix Karuna-Mendix Oct 14, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would want the "guidance-user-identifier" section to be updated as well.
I think it needs to include the info about the new User Metering Named Identifier as well.

Hi @JaapF, based on your comment above, do you mean to update the below?

  1. For any new application, use the oid claim as a user identifier by modifying the user provisioning flow. This will allow you to introduce SCIM.
  • so, if we are using oid as an identifier then we should choose "oid" as usernamedidentifier???
  1. For existing applications that do not need to use SCIM, you can continue to use the default sub claim value or any other claim such as preferred_username.
  • so, if we are using oid as an identifier then we should choose "sub" as usernamedidentifier???

Please refer Guidance on User Identifier for the original section.

Copy link

@JaapF JaapF Oct 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for trying, but it's actually more nuanced.
I'll work on something to explain better and after that you can iterate - as always


* In the **UserProvisioning** tab, select the identifier in the **User Metering Named Identifier** field to be used for metering (default value is `email`).
* This configuration prioritizes the selected identifier over the default `system.user.name` for accurate user tracking.

5. Click **Save** to save the configuration.

### Custom Behavior

Expand Down
20 changes: 12 additions & 8 deletions content/en/docs/marketplace/platform-supported-content/modules/oidc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -580,18 +580,22 @@ Fields below are available in the **UserProvisioning** tab for the User Provisio
* **User Type** – this allows you to configure end-users of your application as internal or external. It is created upon the creation of the user and updated each time the user logs in.
* By default, the value is set to ***Internal***.

Under **Attribute Mapping**, for each piece of information you want to add to your custom user entity, select an **IdP Attribute** (claim) and specify the **Configured Entity Attribute** where you want to store the information.
* Under **Attribute Mapping**, for each piece of information you want to add to your custom user entity, select an **IdP Attribute** (claim) and specify the **Configured Entity Attribute** where you want to store the information.

Note the following:
Note the following:

* You cannot use the IdP claim which is the primary attribute identifying the user and you cannot use the attribute you set in **The attribute where the user principal is stored**.
* You can map only one IdP claim to a Custom user Entity attribute.
* The **IdP Attribute** is one of the fixed claims supported by the OIDC SSO module.
* IdP Attributes(Claims) cannot be of type enum, autonumber, or an association.
* You cannot use the IdP claim which is the primary attribute identifying the user and you cannot use the attribute you set in **The attribute where the user principal is stored**.
* You can map only one IdP claim to a Custom user Entity attribute.
* The **IdP Attribute** is one of the fixed claims supported by the OIDC SSO module.
* IdP Attributes(Claims) cannot be of type enum, autonumber, or an association.

Optionally, you can select the microflow in the **Custom UserProvisioning** field to use custom logic for user provisioning. For more information, see the [User Provisioning Using a Microflow at Runtime](#microflow-at-runtime) section below.
* Optionally, you can select the microflow in the **Custom UserProvisioning** field to use custom logic for user provisioning. For more information, see the [User Provisioning Using a Microflow at Runtime](#microflow-at-runtime) section below.
* To improve licensing and metering accuracy, a configuration requires the use of a mandatory **User Metering Named Identifier**, for example, `email` or `sub`, etc.

{{< figure src="/attachments/appstore/platform-supported-content/modules/oidc/default_provisioning.png" >}}
* In the **UserProvisioning** tab, select the identifier in the **User Metering Named Identifier** field to be used for metering (default value is `email`).
Copy link

@JaapF JaapF Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same text as with SAML.
My same comment applies.

* This configuration prioritizes the selected identifier over the default `system.user.name` for accurate user tracking.

{{< figure src="/attachments/appstore/platform-supported-content/modules/oidc/default-provisioning.png" >}}
Copy link

@JaapF JaapF Oct 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To facilitate upcoming enhancements in the platform, you need to do some configuration so Mendix can correctly identify endusers. Correct identification is crucial for ensuring consistent and accurate end-user metering and deduplication of endusers across multiple applications in your landscape.

For this reason the UserCommons module features the User Metering Named Identifier entity in version x.y.z and higher. If you have a 'multi-app internal user' license or an 'external user' license, it's important that you persist the same value for the same enduser across different apps, regardless of which modules you use. In most cases, the end-user's email address is a good choice.

Whereas currently Mendix currently uses the system.user.name to identify users, it will use the User Metering Named Identifier instead, unless it's not populated. For accurate user metering you don't need to change what value is persisted in "system.user.name"; you can continue to persist whatever value you are using there today. The system.user.name is often used for technical user identifiers, for example, the oid value when using the OIDC SSO module. For more information, see Guidance on User Identifier.

If you want to use a user attribute other than email address for the User Metering Named Identifier you can configure this on the UserProvisioning tab:

select the identifier in the User Metering Named Identifier field to be used for metering
Click Save to save the configuration.


{{% alert color="info" %}}
If you are using module version 3.2.0 and below, you will need to refresh the module containing your microflow as described in the [Installing Mx Model Reflection](/appstore/modules/oidc/#mxmodelreflection) and select the microflow in the **Custom UserProvisioning** field.
Expand Down
29 changes: 17 additions & 12 deletions content/en/docs/marketplace/platform-supported-content/modules/scim.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -257,24 +257,29 @@ In the **Provisioning** tab of the SCIM server configuration, you need to config
* By default, the value is set to ***Internal***.
* **Attribute Mapping**: under **Attribute Mapping**, select an **IdP Attribute** (claim) for each piece of information you want to add to your custom user entity. Specify the **Configured Entity Attribute** where you want to store the information.

Note the following:
Note the following:
Copy link

@JaapF JaapF Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The whole section is rather cryptic to me.
It hasn;t really changed so we can either:

  • pragmatic: leave it 'as is' and improve later
  • use this opportunity to improve.

I'm in favor of the latter. But i would need someone to explain to me what we're trying to say in the next bullets.


* You cannot use the IdP claim which is the primary attribute identifying the user and you cannot use the attribute you set in **The attribute where the user principal is stored**.
* You can map only one IdP claim to a **Custom user Entity** attribute.
* The **IdP Attribute** is one of the fixed claims supported by the SCIM module.
* **IdP attribute** (Claim) cannot be of type enum, autonumber, or an association.
* Use custom logic in the **User Provisioning** (Optional) – In **Custom UserProvisioning**, select a microflow you want to run for custom user provisioning.
* You cannot use the IdP claim which is the primary attribute identifying the user and you cannot use the attribute you set in **The attribute where the user principal is stored**.
* You can map only one IdP claim to a **Custom user Entity** attribute.
* The **IdP Attribute** is one of the fixed claims supported by the SCIM module.
* **IdP attribute** (Claim) cannot be of type enum, autonumber, or an association.
* Use custom logic in the **User Provisioning** (Optional) – In **Custom UserProvisioning**, select a microflow you want to run for custom user provisioning.

The custom microflow name must begin with the string `UC_CustomProvisioning` and requires the following parameters:
* The custom microflow name must begin with the string `UC_CustomProvisioning` and requires the following parameters:

1. **UserInfoParameter(UserCommons.UserInfoParam)**: A Mendix object containing user claims information through its associated objects. You can use this parameter to retrieve user provisioning configuration information.
2. **User(System.User)**: A Mendix object representing the user to be provisioned. Ensure that the selected microflow matches this parameter signature.
1. **UserInfoParameter(UserCommons.UserInfoParam)**: A Mendix object containing user claims information through its associated objects. You can use this parameter to retrieve user provisioning configuration information.
2. **User(System.User)**: A Mendix object representing the user to be provisioned. Ensure that the selected microflow matches this parameter signature.

The microflow must return a **System.User** object to ensure proper user provisioning and updates. It will be executed after user creation or update of user. However, starting from version 2.0.0 of the UserCommons module, this is no longer mandatory. If you have added a new microflow, you need to refresh the module containing your microflow as described in the [Mx Model Reflection](/appstore/modules/model-reflection/).
The microflow must return a `System.User` object to ensure proper user provisioning and updates. It will be executed after user creation or update of user. However, starting from version 2.0.0 of the UserCommons module, this is no longer mandatory. If you have added a new microflow, you need to refresh the module containing your microflow as described in the [Mx Model Reflection](/appstore/modules/model-reflection/). The selection can be blank if you do not want to add custom logic.

{{< figure src="/attachments/appstore/platform-supported-content/modules/scim/user_commons.png" class="no-border" >}}
* To improve licensing and metering accuracy, a configuration requires the use of a mandatory **User Metering Named Identifier**, for example, `email` or `sub`, etc.
Copy link

@JaapF JaapF Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same text as with SAML.
My same comment applies.


This selection can be blank if you do not want to add custom logic. Save this configuration. Double-click on the **Alias** name and you will be able to copy the generated **API Key**.
* In the **UserProvisioning** tab, select the identifier in the **User Metering Named Identifier** field to be used for metering (default value is `email`).
* This configuration prioritizes the selected identifier over the default `system.user.name` for accurate user tracking.

{{< figure src="/attachments/appstore/platform-supported-content/modules/scim/user-commons.png" >}}

Save this configuration. Double-click on the **Alias** name and you will be able to copy the generated **API Key**.
Copy link

@JaapF JaapF Oct 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same suggested text as with SAML.


### Deploy-time Configuration {#deploy-time}

Expand Down
Binary file added ...ments/appstore/platform-supported-content/modules/oidc/default-provisioning.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed ...ments/appstore/platform-supported-content/modules/oidc/default_provisioning.png
View file
Open in desktop
Binary file not shown.
Binary file added ...c/attachments/appstore/platform-supported-content/modules/scim/user-commons.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed ...c/attachments/appstore/platform-supported-content/modules/scim/user_commons.png
View file
Open in desktop
Binary file not shown.