User Metering

[Karuna-Mendix]

https://mendix.atlassian.net/browse/TW-2769
https://mendix.atlassian.net/wiki/spaces/CloudRnD/pages/4634411009/Doc-draft+User+Metering

[satyammx]

@JaapF @Karuna-Mendix the whole section somehow sounds very apologetic and guessing why you could have done it wrong. Documentation should be more directive IMO.

We ought to be first telling - "you are supposed to do xyz... ". These usecases when a customer might have done it wrong might be best suited for a Q&A or FAQ IMO.

What do you think?

[JaapF]

Good point.

The recommended cross-app user identifier is the enduser's email address and the recommended place to store it is in the UserCommons.namedUserIdentifier.value.

Note that an email address is personal information and the Mendix platform therefore collects hashed values of the user identifier. If you have privacy concerns, please check the data processing agreement you have with Siemens. If you don't want to use email addresses or email addresses arenot available; you have to set a guideline on what user identifier your company will be using for cross-app user identification.

The apps in your portfolio, however, may not yet be consistently storing a cross-app user identifier value.
User metering may not have been considered when your application was originally designed. As a result, different applications may store different identifier values for the same multi-app user in the system.user.name and the UserCommons.namedUserIdentifier.value may not yet be used. Applications in your portfolio may use different user-provisioning logic. Some apps use standard identity modules (Administration, SAML, OIDC SSO, SCIM, or LDAP) while others rely on proprietary modules or app logic to create users. This can lead to inconsistent identifiers. Even when all apps use the same solution, for example, OIDC SSO, the technical identifier value for a multi-app user may still differ, see section [Avoiding pairwise identifiers]

[Karuna-Mendix]

Hi @satyammx @JaapF, I tried asking Siemens GPT to improve the current section for a more directive tone. It showed the following revision to the text. Let me know if you find it useful.

Guidelines for Unique User Identification (Deduplication)
Mendix offers multi-app user licenses, which allow a single user to access multiple applications while being counted only once for metering purposes. This applies to both internal and external users. Accurate user metering and correct multi-app user deduplication depend critically on consistent user identification across all your applications.

To ensure unique multi-app users are correctly identified and metered, you must maintain a consistent user identifier across all relevant applications.

The Mendix metering mechanism uses the UserCommons.namedUserIdentifier.value attribute as the primary user identifier. If this attribute is not available or populated, it falls back to system.user.name. For a detailed overview of relevant entities and attributes, refer to the "Domain Model Entities" section.

Key Requirements for Multi-App User Identification:

Consistent Identifier Value: The same value for a given multi-app user must be stored in the chosen identifier attribute (UserCommons.namedUserIdentifier.value or system.user.name) across all applications that user accesses. Inconsistent values will result in the user being counted as multiple distinct users.

Best Practices for Choosing and Implementing a Cross-App User Identifier:

User identification strategies can vary across application portfolios, especially if applications were developed independently or use different provisioning methods. Consider the following guidelines to establish a robust and consistent identification strategy:

1. Prioritize UserCommons.namedUserIdentifier.value: Always aim to use and populate UserCommons.namedUserIdentifier.value for user identification. This provides a dedicated field for metering purposes and offers flexibility regardless of the system.user.name value.

2. Use a Stable, Globally Unique Identifier: Select an identifier that is stable and consistently unique across your entire user base and application portfolio.

• Recommended: User's Email Address: Mendix strongly recommends storing the user's email address in UserCommons.namedUserIdentifier.value. This is typically a stable and globally unique identifier that users are familiar with.
• Handling Case Sensitivity: If using email addresses or other text-based identifiers, always store these values in lowercase to prevent metering issues due to case sensitivity. The system.user.name attribute is case-sensitive by design. Mendix's standard SAML, OIDC SSO, and SCIM modules already apply this for email claims received from Identity Providers (IdPs).

3. Address Pairwise Identifiers (e.g., OIDC sub claim): Some identity providers (like Microsoft Entra ID's OIDC sub claim) generate "pairwise" identifiers, which are unique per application for the same user. This is designed to prevent correlation across different service providers but will lead to incorrect multi-app metering within your portfolio.
   Solution for Microsoft Entra ID: If using the OIDC SSO module with Microsoft Entra ID, configure your application to store the oid claim (which contains Entra ID's user object ID) in system.user.name. The oid claim provides a consistent identifier for a multi-app user across all applications.

4. Integrating with Existing Application Logic: If your current applications use varying system.user.name values or different provisioning methods, you can implement UserCommons.namedUserIdentifier.value without altering existing logic.
   Strategy: Continue using your existing application logic for system.user.name if necessary, but additionally implement logic to populate UserCommons.namedUserIdentifier.value with your chosen consistent cross-app identifier (e.g., email address or oid claim). This ensures the metering mechanism has a reliable, consistent identifier to use.

For more information on user types and definitions, refer to the "User Types and Definitions" section.

[JaapF]

Hi @Karuna-Mendix , yes I like the overall flow of the SiemensGPT text.
However one nuance got lost: the 'pair wise identifier' remark does not always apply.
Improved version:

"3. Address Pairwise Identifiers (e.g., OIDC sub claim): Some identity providers (like Microsoft Entra ID) generate "pairwise" identifiers (Entra ID's "sub" claim) , which are unique per application for the same user. This is designed to prevent correlation across different service providers but will lead to incorrect multi-app metering within your portfolio if you're using this technical identifier as the global unique identifier.
If using the OIDC SSO module with Microsoft Entra ID, you can use the oid claim (which contains Entra ID's user object ID) instead of "sub" as global unique identifier. The oid claim provides a consistent identifier for a multi-app user across all applications.
If you follow the above recommendation to use the user's email address as global unique identifier for user metering, pair-wise identifiers don't matter."

[satyammx]

Mendix offers multi-app user licenses
@Karuna-Mendix
Mendix offers two variants of multi-app user licenses namely Internal multi-app and External multi-app user licenses... ...

[satyammx]

@JaapF Since we do not support UserCommons.Nam.... yet from a User Metering perspective, is it wise to call this out OR should we skip?

[JaapF]

@JaapF Since we do not support UserCommons.Nam.... yet from a User Metering perspective, is it wise to call this out?

We've discussed this a couple of times and agreed that it's important to call this out to ensure the accuracy of the data.

[JaapF]

Let's add:

"Userrole-based user classification is the recommended approach. It encourages and leverages application design with distinct userrole definitions for external and internal users."

[JaapF]

Given satyam's comment about first clearly stating guidance and after that explain in more detail I think we need to start this section with clear guidance, rather than "If your apps..."

"The recommended entity attribute to store cross-app user identifiers is the UserCommons.namedUserIdentifier.value. This allows you keep the existing application logic as it is, and in addition, store the selected user identifier value for a multi-app user in this attribute. If your applications are already consistently storing the same identifier for a multi-app user in system.user.name, you don't have to use the UserCommons.namedUserIdentifier.value."

I thin k this is more positive wording.

[JaapF]

Hi @Karuna-Mendix , yes I like the overall flow of the SiemensGPT text.
However one nuance got lost: the 'pair wise identifier' remark does not always apply.
Improved version:

"3. Address Pairwise Identifiers (e.g., OIDC sub claim): Some identity providers (like Microsoft Entra ID) generate "pairwise" identifiers (Entra ID's "sub" claim) , which are unique per application for the same user. This is designed to prevent correlation across different service providers but will lead to incorrect multi-app metering within your portfolio if you're using this technical identifier as the global unique identifier.
If using the OIDC SSO module with Microsoft Entra ID, you can use the oid claim (which contains Entra ID's user object ID) instead of "sub" as global unique identifier. The oid claim provides a consistent identifier for a multi-app user across all applications.
If you follow the above recommendation to use the user's email address as global unique identifier for user metering, pair-wise identifiers don't matter."

[satyammx]

All running app environments transmist usage data to Mendix Platform at regular intervals.

[satyammx]

Anonymous users are not reported and hence not even counted ....