OIDC SSO improvements #8761
OIDC SSO improvements #8761
Conversation
…OIDCSSO-improvements # Conflicts: # content/en/docs/appstore/use-content/platform-supported-content/modules/oidc sso/_index.md
|
|
||
| ## Introduction | ||
|
|
||
| Initially, your app will not have any end-users. The OIDC module provides Just-In-Time (JIT) user provisioning. This means an end-user will be created in your app when they log in for the first time. If you do not want JIT user provisioning, it is possible to disable it as described in the section [Custom User Provisioning at Runtime](#custom-provisioning-rt). |
There was a problem hiding this comment.
This is good opportunity to add some additional 'how to' information about user provisioning.
Myabe you can improve and merge the following suggestion into the introduction section for this page.
Suggestion:
_Initially, your app will not have any end-users. You can on-board endusers into your app using one of the following mechanisms:
- An admin user can manually create users in your app. The Administration helps you to implement this. See
- Use the SCIM protocol to let your IdP create and/or deactivate endusers. The SCIM module helps you implement this, see
- Just-in-time user provisioning: users are created when they succesfully login via SSO. Both SAML and OIDC SSO support this mechanism. This documentation page explains the JIT approach.
- Proprietary user provisisioning. The flexibility of the Mendix Low-code platform is that you can also build your own bespoke user provisioning mechanism._
This may help us to get more awarness and adoption of the SCIM module.
| @@ -0,0 +1,183 @@ | |||
| --- | |||
| title: "OIDC SSO User Provisioning" | |||
| url: /appstore/modules/oidc/oidc-user-provisioning | |||
There was a problem hiding this comment.
Maybe terminology "end-user onboarding" is more clear to low-code developers.
I suggest we use onboarding in title and in the text use both terminologies. This will make Maia understand they're both words for the same thing.
|
|
||
| * **Custom user Entity (extension of System.User)** – the Mendix entity where you will store and look up the user account. If you are using the [Administration module](https://marketplace.mendix.com/link/component/23513), this would be `Administration.Account`. | ||
| * **The attribute where the user principal is stored** – unique identifier associated with an authenticated user. | ||
| * **Allow the module to create users** – this enables the module to create users based on configurations of user provisioning and attribute mapping. When disabled, it will still update existing users. However, for new users, it will display an exception message stating that the login action was successful but no user has been configured. |
There was a problem hiding this comment.
Let's repeat the Just-in-time userprovisioning term here again. So the reader gets cvonfirmed we are talking about the same thing.
| * **The attribute where the user principal is stored** – unique identifier associated with an authenticated user. | ||
| * **Allow the module to create users** – this enables the module to create users based on configurations of user provisioning and attribute mapping. When disabled, it will still update existing users. However, for new users, it will display an exception message stating that the login action was successful but no user has been configured. | ||
| * By default, the value is set to ***Yes***. | ||
| * **User role** – the role which will be assigned to newly created users. You can select one default user role. If you need additional user roles, use Access Token Parsing microflow to assign multiple roles. |
There was a problem hiding this comment.
can you make more clear this is optional.
Customers may choose to not apply a default userrole.
| * By default, the value is set to ***Yes***. | ||
| * **User role** – the role which will be assigned to newly created users. You can select one default user role. If you need additional user roles, use Access Token Parsing microflow to assign multiple roles. | ||
| * **User Type** – this allows you to configure end-users of your application as internal or external. | ||
| * By default, the value is set to ***Internal***. |
There was a problem hiding this comment.
I think this is a setting per IdP.
So if 2 IdPs are connected, one IdP may have "User Type=inetrnal" and the other may have "user trype = external".
|
|
||
| * 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 multiple **IdP Attribute** (claims) to a **Configured Entity Attribute** but you cannot map a new **IdP Attribute** to a **Configured Entity Attribute** if it is already mapped. | ||
| * The **IdP Attribute** is one of the fixed claims supported by the OIDC SSO module. |
There was a problem hiding this comment.
I don't understand what this means. We need to improve.
| * 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. | ||
|
|
||
| 6. Optionally, you can select the microflow in the **Custom UserProvisioning** field to use custom logic for user provisioning. For more information, see the [Customizing User Provisioning Using a Microflow at Runtime](#microflow-at-runtime) section below. |
There was a problem hiding this comment.
We should also say something about the default of developer chooses not to do this.
Add explanation about the default user provisioning flow
There was a problem hiding this comment.
Also, if developer chooses to use the default user provisioning flow, I think step 5 (attribute mappings) becomes obsolete, right?
|
|
||
| 7. Click **Save** to save the configuration. | ||
|
|
||
| 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). |
There was a problem hiding this comment.
We should start with explaining the defaults.
These were designed to provide develkopers with easy developer experince.
Currently the flow of this page is:
- look you can do a lot of difefrent things
- and - by the way - you can also use defaults.
I prefer:
- look we've got all kinds of smart defaults to make it easy. The minium you have to do is: ....
- if you need to deviate from defaults, you may choose to do .....
There was a problem hiding this comment.
In the current documentation we do this already
6.1 default user provisioning
6.2 Custom user provisioning
| 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). | ||
|
|
||
| {{% 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. |
There was a problem hiding this comment.
This remark makes me think about something I didn't think about before:
- the default role is not per IdP but applies to all IdPs?
- the "Allow JIT-provisioning" is also not per IdP and applies to all IdPs?
Maybe at a remark about that as well. What do you think?
|
|
||
| The custom microflow will be executed after the user is created or updated. | ||
|
|
||
| ### User Provisioning at Deploy-time{#custom-provisioning-dep} |
There was a problem hiding this comment.
This heading is confusing.
I would suggest:
"Deploy-time configuration of enduser on-boarding"
The word deploytime refers to the configuration activity, not to the user provisioning itself.
|
|
||
| ## Configuring User Provisioning for Version 3.0.0 and Above | ||
|
|
||
| ### User Provisioning at Runtime{#custom-provisioning-rt} |
There was a problem hiding this comment.
This heading is confusing.
I would suggest:
"Runtime configuration of enduser on-boarding"
The word runtime refers to the configuration activity, not to the user provisioning itself.
|
|
||
| By default, end-users are provisioned using the `Account` object in the Administration module. If you need to use a custom user entity you can do this via [User Provisioning at Runtime](#custom-provisioning-rt) or [User Provisioning at Deploy-time](#custom-provisioning-dep). | ||
|
|
||
| ## Configuring User Provisioning for Version 3.0.0 and Above |
There was a problem hiding this comment.
I suggest to add a little introduction.
Something like:
The OIDC SSO module supports two methods for configuration of user provisioning:
- deploytime configuration. This approach allows for fully automated configurations in your CICD pipeline. Mendix recommend this approach for customers with an ever growing portfolio of Mendx applications.
- runtime configuration. This approach may be the preferred way of doing configuration if you're not yet familiar with getting the various settings right. Also this method is needed when you're connecting multiple IdPs to a single app.
Maybe this introduction should be in the main document (as well).
There was a problem hiding this comment.
I'd like the deploytime option to be explained first.
|
|
||
| ### User Provisioning at Deploy-time{#custom-provisioning-dep} | ||
|
|
||
| You can also set up custom user provisioning by setting constants when you deploy your app. This has the following limitations compared to setting up provisioning using a microflow or changing the settings at runtime: |
There was a problem hiding this comment.
Let's first mention the benefits:
"Automatable configuration in CICD pipeline.
No local MxAdmin user is needed to do the necessary configurations. etc."
See also old release blog: https://www.mendix.com/blog/mendix-release-10-11-power-up-your-development/#governance
|
|
||
| The section below shows the methods to configure user provisioning when using OIDC module version 2.4.0 or below. | ||
|
|
||
| ### Default User Provisioning |
There was a problem hiding this comment.
I think these are also the defaults for newer versions.
Current documentation confirms this.
| ### User Provisioning Using a Microflow{#custom-provisioning-mf} | ||
|
|
||
| {{% alert color="warning" %}} | ||
| 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 [User Provisioning at Runtime](#custom-provisioning-rt) and [User Provisioning at Deploy-time](#custom-provisioning-dep) sections above. |
There was a problem hiding this comment.
Repeating my previous remark:
user provisioning is the process of creating users. That always happens at runtime.
For the configuration of user provisioning we have options: runtime/deploytime.
| @@ -76,7 +74,24 @@ The OIDC SSO module supports the following features: | |||
|
|
|||
| * Built primarily in standard Mendix components (minimal Java) to allow for easy customization and ongoing development. | |||
|
|
|||
| #### OIDC Protocol Adherence | |||
There was a problem hiding this comment.
In this PR, the content of the adherence section is gone / in strikethrough-font.
In the pdf you sent me on slack it's still there.
We want to keep it!
There was a problem hiding this comment.
The PR shows a lot of changes in this document.
I think what you did was;
- change the order of section "limitations" and "adherence". I agree with that and I like that. Because in the PR this looks as a lot of changes, I did not check word for word. I trust you didn't change the content.
- you seem to have done various smaller chnages to the IdP-configuration. I'm not sure why?
- ....
Given the number of remarks from me on this big PR, i feel it will take a couple of iterations before we are alligned.
Can I suggest to create a sequence of smaller PRs?
We can review/merge each PR seperately. If each PR has it's own purpose, the cognitive load for me per PR will be more manageable.
| 2. Navigate to the `OIDC.OIDC_Client_Overview` page set up in the app navigation. | ||
| 3. Select the **Provisioning** tab. | ||
| 4. Set up the following information: | ||
| ### IdP Configuration for Microsoft Entra ID and Amazon Cognito |
There was a problem hiding this comment.
I don't like that this is now a seperate section.
These are the specifics of "Configure Your app at your IdP".
The current structure where he specifics for Entra are a subsection to 5.1 feels more logical to me as a reader.
|
|
||
| In this configuration, you have several options to customize the Identity Provider (IdP) settings. Firstly, you can configure the IdP using constants. Additionally, the OIDC module supports further customization of the IdP configuration through the implementation of a custom microflow called `Custom_CreateIdPConfiguration`. This microflow returns a list of configured IdPs, which the OIDC module then uses to generate the necessary SSO configurations for multiple IdPs. | ||
|
|
||
| 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 IdPs for SSO and API Security Configuration |
There was a problem hiding this comment.
This heading is very cryptic. When - as a reader, I would read the ToC, I would be very confused what this is about.
Replacing #8577