diff --git a/content/en/docs/marketplace/platform-supported-content/modules/oidc.md b/content/en/docs/marketplace/platform-supported-content/modules/oidc.md index e96aa921e6f..caed56ab635 100644 --- a/content/en/docs/marketplace/platform-supported-content/modules/oidc.md +++ b/content/en/docs/marketplace/platform-supported-content/modules/oidc.md @@ -405,9 +405,9 @@ Now, you can acquire tokens which can be validated using JWKS URI. For more information about configuring your app for OIDC with Amazon Cognito, see [Amazon Cognito: Configuring the Required Settings in Your Mendix App](/appstore/modules/aws/amazon-cognito/#cognito). -### Deploy-time Configuration of Your IdP at Your App{#deploytime-idp-configuration} +### Deploy-Time Configuration of Your IdP at Your App{#deploytime-idp-configuration} -#### Automated Deploy-time SSO Configuration{#deploy-time} +#### Automated Deploy-Time SSO Configuration{#deploy-time} In version 2.3.0 and above, you can configure the OIDC SSO module using app [constants](/refguide/constants/) rather than using the app administration pages. As the developer of an app using OIDC SSO, you can set default values. These values can be overridden using the app constants. @@ -437,7 +437,7 @@ In this configuration, you have several options to customize the Identity Provid In this non-default configuration method, users have the flexibility to introduce your own constants by creating custom IdP configurations. -##### Deploy-time IdPs for SSO and API Security Configuration +##### Deploy-Time IdP Configuration for SSO and API Security {{% alert color="info" %}} **IdPs for SSO and API security** configuration supports both Authorization code and Client Credential grant type. @@ -516,13 +516,13 @@ Example: `OIDC.Default_SAM_TokenProcessing_CustomATP` When the `IsClientGrantOnly` constant is set to *true*, the OIDC SSO module considers the configuration as Client Credential grant configuration. {{% /alert %}} -## User Provisioning (End-user Onboarding) +## User Provisioning (End-User Onboarding) Initially, your app will not have any end-users. You can onboard end-users into your app using one of the following mechanisms: -1. Manual user creation: an admin user can manually create users in your app. The [Administration](/appstore/modules/administration/) module helps you implement this mechanism. -2. SCIM Protocol: use the SCIM protocol to let your IdP create and/or deactivate end-users. The SCIM module helps you implement the mechanism. For more information, see [SCIM](/appstore/modules/scim/). -3. Just-in-Time (JIT) User Provisioning: in the JIT user provisioning, users will be created when they successfully log in via SSO. Both SAML and OIDC SSO support this mechanism. If you do not want JIT user provisioning, it is possible to disable it as described in the section [Runtime Configuration of End-user Onboarding](#custom-provisioning-rt) below. +1. Manual user creation: An admin user can manually create users in your app. The [Administration](/appstore/modules/administration/) module helps you implement this mechanism. +2. SCIM Protocol: Use the SCIM protocol to let your IdP create and/or deactivate end-users. The SCIM module helps you implement the mechanism. For more information, see [SCIM](/appstore/modules/scim/). +3. Just-in-Time (JIT) User Provisioning: In the JIT user provisioning, users will be created when they successfully log in via SSO. Both SAML and OIDC SSO support this mechanism. If you do not want JIT user provisioning, it is possible to disable it as described in the section [Runtime Configuration of End-user Onboarding](#custom-provisioning-rt) below. 4. Proprietary user provisioning: The Mendix Low-Code platform offers the flexibility to develop a customized user provisioning mechanism. The OIDC SSO module supports two methods for configuration of JIT user provisioning: @@ -536,14 +536,14 @@ From version 3.0.0 of the OIDC SSO module, you can configure user provisioning a By default, end-users are provisioned using the `Administration.Account` entity. To use a custom user entity, you can configure it through JIT onboarding via runtime settings or by defining constants in deploy-time configuration, as described below: -#### Deploy-time Configuration of End-user Onboarding{#custom-provisioning-dep} +#### Deploy-Time Configuration of End-User Onboarding{#custom-provisioning-dep} You can set up custom user provisioning by setting constants when you deploy your app. You do not need a local MxAdmin user to do the necessary configurations. This is an automatable configuration in the CI/CD pipeline. However, the configuration has the following limitations compared to setting up provisioning using a microflow or changing the settings at runtime: -* You need to restart your app to apply changes to the constants -* You cannot set custom mapping of IdP claims to attributes of your custom user entity +* You need to restart your app to apply changes to the constants. +* You cannot set custom mapping of IdP claims to attributes of your custom user entity. -You can set up custom user provisioning by setting the following constants. You can set default values when you build your app but can override these in the app's environment. +You can set up custom user provisioning by setting the following constants. You can set default values when you build your app, but you can override these in the app's environment. | Constant | Use | Notes | Example | | --- | --- | --- | --- | @@ -560,9 +560,9 @@ You can set up custom user provisioning by setting the following constants. You You may have a requirement that users log in to your application only via SSO. However, when you deploy your app on the Mendix Cloud, the platform may still create an MxAdmin user with a local password. From version 2.1.0 of the UserCommons module, if the flag for the `DisableMxAdmin` constant is set to `True`, the MxAdmin user will be deactivated via the startup microflow `ASU_UserCommons_StartUp`. {{% /alert %}} -#### Runtime Configuration of End-user Onboarding{#custom-provisioning-rt} +#### Runtime Configuration of End-User Onboarding{#custom-provisioning-rt} -By default, users are provisioned by [Default User Provisioning Configuration](#default). Optionally, you can customize user provisioning by [Modifying Default Attribute Mapping](#modify-default), [User Provisioning Using Your Custom User Entity](#custom_user_entity), or [User Provisioning Using a Microflow at Runtime](#microflow-at-runtime). +By default, users are provisioned by the [Default User Provisioning Configuration](#default). Optionally, you can customize user provisioning by [Modifying Default Attribute Mapping](#modify-default), [User Provisioning Using Your Custom User Entity](#custom_user_entity), or [User Provisioning Using a Microflow at Runtime](#microflow-at-runtime). You can set up just-in-time user provisioning as follows: @@ -576,29 +576,29 @@ Fields below are available in the **UserProvisioning** tab for the User Provisio * **The attribute where the user principal is stored** – a unique identifier associated with an authenticated user. * **Allow the module to create users** – this enables the module to create users based on configurations of JIT user provisioning and attribute mapping. When disabled, it will still update existing users. However, for new users, it will display an exception message in the log. * By default, the value is set to ***Yes***. -* **User role** (optional) – the role which will be assigned to newly created users. This is optional and will be applied to all IdPs. You can select any user role as a default or keep the field empty. User Provisioning does not allow you to assign user roles dynamically. It can only set a default role. If you need additional user roles, use the Access Token Parsing microflow to assign multiple roles. For more information, see the [Dynamic Assignment of Userroles (Access Token Parsing)](#access-token-parsing) section below. +* **User role** (optional) – the role that will be assigned to newly created users. This is optional and will be applied to all IdPs. You can select any user role as a default or keep the field empty. User Provisioning does not allow you to assign user roles dynamically. It can only set a default role. If you need additional user roles, use the Access Token Parsing microflow to assign multiple roles. For more information, see the [Dynamic Assignment of Userroles (Access Token Parsing)](#access-token-parsing) section below. * By default, the value is set to ***User***. -* **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. +* **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. It is a setting configured per IdP. If two IdPs are connected, one IdP may have the user type set to ***Internal*** while the other may have the user type set to ***External***. * 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. 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 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. -* To facilitate upcoming enhancements to the platform, you need to perform some configuration so that Mendix can correctly identify end users. Correct identification is crucial for ensuring consistent and accurate end user metering and deduplication of end users across multiple applications in your landscape. For this reason, the UserCommons module features the **User Metering Named Identifier** entity in version 2.2.0 and above. If you have a multi-app internal user license or an external user license, you must persist the same value for the same end user across different apps, regardless of which modules you use. In most cases, the end user's email address is a good choice. Currently, Mendix uses the `system.user.name` to identify users, it will use the **User Metering Named Identifier** instead, unless it is not populated. For accurate user metering, you do not need to change what value is persisted in the `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](#guidance-user-identifier). Both `system.user.name` and `userCommons.NamedUserIdentifier.value` have a uniqueness constraint for the named user identifier. This means an app cannot have two users who share the same identifier value. +* To facilitate upcoming enhancements to the platform, you need to perform some configuration so that Mendix can correctly identify end users. Correct identification is crucial for ensuring consistent and accurate end user metering and deduplication of end users across multiple applications in your landscape. For this reason, the UserCommons module features the **User Metering Named Identifier** entity in version 2.2.0 and above. If you have a multi-app internal user license or an external user license, you must persist the same value for the same end user across different apps, regardless of which modules you use. In most cases, the end user's email address is a good choice. Currently, Mendix uses the `system.user.name` to identify users, it will use the **User Metering Named Identifier** instead, unless it is not populated. For accurate user metering, you do not need to change what value is persisted in the `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](#guidance-user-identifier). Both `system.user.name` and `userCommons.NamedUserIdentifier.value` has a uniqueness constraint for the named user identifier. This means an app cannot have two users who share the same identifier value. * If you want to use a user attribute other than email address for the **User Metering Named Identifier**, you can configure it 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. -{{< figure src="/attachments/appstore/platform-supported-content/modules/oidc/default-provisioning.png" >}} +{{< figure src="/attachments/appstore/platform-supported-content/modules/oidc/default-user-provisioning.png" >}} {{% 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. @@ -608,7 +608,7 @@ If you are using module version 3.2.0 and below, you will need to refresh the mo If the standard configuration meets your needs and your application does not have special user management requirements, you can use the default User Provisioning. -In default configuration, the custom user entity is set as `Administration.Account`, the principal attribute is set as `Name`, and the default attribute mapping is provided. +In the default configuration, the custom user entity is set as `Administration.Account`, the principal attribute is set as `Name`, and the default attribute mapping is provided. | IdP Attribute | Configured Entity Attribute | | -------------------- | --------------------------- | @@ -621,7 +621,7 @@ In default configuration, the custom user entity is set as `Administration.Accou You may need a different or custom attribute mapping, for example, if you are configuring OIDC SSO and SCIM together and need a common identifier. For more information, see the [User Identifiers in the OIDC and SCIM Protocols](#user-identifiers-in-the-oidc-and-scim-protocols) section below. In this case, you can modify the default attribute mapping. -To do so, change the default **IdP Attribute** or the **Configured Entity Attribute**, by editing the mapping in the **Attribute Mapping** section within the **UserProvisioning** tab. +To do so, change the default **IdP Attribute** or the **Configured Entity Attribute** by editing the mapping in the **Attribute Mapping** section within the **UserProvisioning** tab. ##### Creating IdP Attribute Manually @@ -636,12 +636,12 @@ Select the required attribute to use it in your mapping. ##### User Provisioning Using Your Custom User Entity{#custom_user_entity} -If you want to use your custom user entity which is a specialization of the `System.User` entity to store user information, select it in the **Custom user Entity (extension of System.User)** field by replacing the `Administration.Account` entity. +If you want to use your custom user entity, which is a specialization of the `System.User` entity to store user information, select it in the **Custom user Entity (extension of System.User)** field by replacing the `Administration.Account` entity. To configure custom JIT user provisioning, set up the fields listed in the [Runtime Configuration of End-user Onboarding](#custom-provisioning-rt) section above and save the configuration. {{% alert color="info" %}} -If you connect multiple IdPs to your Mendix app, you can use separate custom user entities for each IdP, each with its own attribute mapping. +If you connect multiple IdPs to your Mendix app, you can use separate custom user entities for each IdP, each with its own attribute mapping. In addition, each IdP configuration can have its own default user role and its own JIT user provisioning configuration, rather than being applied across all IdPs. {{% /alert %}} ##### User Provisioning Using a Microflow at Runtime{#microflow-at-runtime} @@ -655,7 +655,7 @@ Select it in the **Custom UserProvisioning** field. The custom microflow name mu * **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. * **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. +* The microflow must return a **System.User** object to ensure proper user provisioning and updates. It will be executed after user creation or the update of the 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/). ### Configuring User Provisioning for Version 2.4.0 and Below @@ -682,7 +682,7 @@ Do not change the `UserProvisioning_StandardOIDC` microflow. This may cause prob Since this feature is deprecated from version 3.0.0 of the module, you can do the custom user provisioning at runtime or deploy-time. For more information, see the [Runtime configuration of end-user on-boarding](#custom-provisioning-rt) and [Deploy-time configuration of end-user on-boarding](#custom-provisioning-dep) sections above. {{% /alert %}} -Review the microflow `CUSTOM_UserProvisioning` in the **USE_ME** > **1. Configuration** folder of the OIDC module. This is where you can change the way that end-users are provisioned in your app. The OpenID token is passed to the microflow as a parameter. Use this object to find an existing, or create a new, `System.User` object for the end-user. This is set as the return value of the microflow. You can find examples included in the **USE_ME** > **1. Configuration** > **User Provisioning Examples** folder. +Review the microflow `CUSTOM_UserProvisioning` in the **USE_ME** > **1. Configuration** folder of the OIDC module. This is where you can change the way that end-users are provisioned in your app. The OpenID token is passed to the microflow as a parameter. Use this object to find an existing, or create a new `System.User` object for the end-user. This is set as the return value of the microflow. You can find examples included in the **USE_ME** > **1. Configuration** > **User Provisioning Examples** folder. Make a single call from `CUSTOM_UserProvisioning` to your own module where you implement the provisioning flow you need. This way, it will be easy to install new versions of the OIDC SSO module over time without overwriting your custom provisioning. @@ -723,8 +723,8 @@ Role of user identifiers in OIDC and SCIM protocols: The default behavior for the OIDC SSO module is to persist the value of the `sub` claim in the system.user.name attribute. This is not forward-compatible with the introduction of SCIM. Therefore, for B2E applications connected with Entra ID for SSO, Mendix recommends the following: * 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. -* For existing applications that do not persist user-specific application data (other than system.user or administration.account), modify the user provisioning flow to use the `oid` claim instead of the `sub` claim. Delete all system.user and administration.account records to remove old user data. This will re-provision the users, allowing you to introduce SCIM. -* 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`. +* For existing applications that do not persist user-specific application data (other than system.user or administration.account), modify the user provisioning flow to use the `oid` claim instead of the `sub` claim. Delete all `system.user`, and `administration.account` records to remove old user data. This will re-provision the users, allowing you to introduce SCIM. +* 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`. * For existing applications where you want to introduce SCIM, you need to define a migration strategy for the identifiers. #### Configuring `oid` Claim in the OIDC SSO @@ -733,7 +733,7 @@ By default, the `WellKnownendpoint` (Automatic configuration URL) does not inclu 1. Go to **Attribute Mapping** and click **New**. 2. Select **Search** and click **New**. -3. Create `oid` claim and map it to the Entity Attribute. +3. Create an `oid` claim and map it to the Entity Attribute. ## API Authentication {#api-authentication} diff --git a/static/attachments/appstore/platform-supported-content/modules/oidc/default-provisioning.png b/static/attachments/appstore/platform-supported-content/modules/oidc/default-provisioning.png deleted file mode 100644 index 53145b0ff0a..00000000000 Binary files a/static/attachments/appstore/platform-supported-content/modules/oidc/default-provisioning.png and /dev/null differ diff --git a/static/attachments/appstore/platform-supported-content/modules/oidc/default-user-provisioning.png b/static/attachments/appstore/platform-supported-content/modules/oidc/default-user-provisioning.png new file mode 100644 index 00000000000..fcc8262a9db Binary files /dev/null and b/static/attachments/appstore/platform-supported-content/modules/oidc/default-user-provisioning.png differ