Peer review: OIDC Provider #9085
Conversation
| @@ -26,7 +27,7 @@ There are below versions of the OIDC Provider module, compatible with Mendix ver | |||
|
|
|||
| ### Typical Usage Scenarios | |||
|
|
|||
| The following are usage scenarios that would be achievable with the OIDC Provider module. | |||
There was a problem hiding this comment.
Eliminated "would", a conditional adverb.
SG entry on conditional adverbs: https://mendix.atlassian.net/wiki/spaces/RNDHB/pages/2520678744/Grammar+Formatting#Conditional-Adverbs
|
|
||
| For successful implementation of the OIDC Provider module, [Advanced](https://academy.mendix.com/link/certifications/6/advanced) or [Expert](https://academy.mendix.com/link/certifications/24/expert) Mendix certification is recommended. Customers with limited low-code experience may consider partnering with a Mendix Implementation Partner. |
There was a problem hiding this comment.
Changed "Mendix certification is recommended" to "We recommend you attain X or Y Mendix certifications" so it goes from passive voice to active voice.
SG entry on passive voice: https://mendix.atlassian.net/wiki/spaces/RNDHB/pages/2520678744/Grammar+Formatting#Active-and-Passive-Voice
|
|
||
| #### SSO Brokering for Rapid Innovation{#brokering} | ||
|
|
||
| {{< figure src="/attachments/appstore/platform-supported-content/services/oidc-provider/brokering.png" class="no-border" >}} | ||
|
|
||
| The Mendix marketplace offers Single Sign-On (SSO) module, enabling your Mendix application to delegate end-user login to your Identity Providers (IdPs) such as Entra ID and Okta. However, for some organizations, implementing SSO for each Mendix application can cost more or slow down innovation. In such cases, an SSO broker between your IdP and your expanding portfolio of Mendix applications can offer an effective solution. |
There was a problem hiding this comment.
Mendix Marketplace is a branded term. These often surprise me, so if you're ever on the fence, give the PNG a quick check.
|
|
||
| You can build a Mendix application that acts as a SSO Broker by using the OIDC SSO and the OIDC Provider modules. The OIDC SSO module authenticates end-users at your central IdP, while the OIDC Provider module enables your new app to act as an IdP (OpenID Provider) for your other Mendix applications. This means it is working as an SSO broker, catering for authentication and, optionally, for authorization. | ||
|
|
||
| For more information on the concepts behind authorization, see the [About Authorization](#about-authorization) section below. | ||
|
|
||
| Your deployment pipeline (deployment agent) would be responsible for registering additional Mendix apps with the SSO broker. This process can be automated using client registration API provided by the OIDC Provider module. | ||
| Your deployment pipeline (deployment agent) will be responsible for registering additional Mendix apps with the SSO broker. This process can be automated using client registration API provided by the OIDC Provider module. | ||
|
|
||
| #### SSO Within Multi-app Mendix Solution |
There was a problem hiding this comment.
In this section you use a "proper name" term Mendix Solution Vendors (MSVs). We do not have an entry in our PNG for this, so I suggest you add it here so that other tech writers can know this is a term they can use as well https://mendix.atlassian.net/wiki/spaces/RNDHB/pages/2109145362/Other+Mendix+Terms
We do not put items in single quotes. I put the term in bold where it is first mentioned, as bold is the way we refer to what customers can see as they use a component. I think this paragraph would be even better if it had a sentence explaining where a user clicks in order to build their first Central Portal App. Also, I lowercased CIAM because when things are turned into acronyms, that does not retroactively get the noun capitalized. The noun form is only capitalized if it is a proper noun. Customer identity and access management is a general concept, so not a proper noun.
|
|
||
| Instead of using local credentials in the Central Portal App, you may want to integrate your solution with an IdP. As an MSV, you probably also want to hide the internal multi-application structure from this IdP and have a single integration point. The Central Portal App can then act as an SSO broker, similar to the usage scenario described in the [SSO Brokering for rapid innovation](#brokering) section above. | ||
|
|
||
| #### Non-user Specific API Consumption | ||
|
|
||
| {{< figure src="/attachments/appstore/platform-supported-content/services/oidc-provider/API_consumption.png" class="no-border" >}} | ||
|
|
||
| For API security, it is a best practice to use OAuth-tokens rather than API-keys. OAuth tokens are also known as bearer tokens, access tokens or simply JWTs. You have below two options for using OAuth tokens: |
There was a problem hiding this comment.
JWTs are mentioned in a handful of other places. Sometimes they are erroneously written as "JWT tokens", which is wrong for the reason "ATM machine" is wrong: automatic teller machine machine, JSON web token token.
As a small side-task, perhaps you can edit the handful of JWT mentions around the docs to make them as clear/accurate as possible.
It's a third party concept, so if we can give a safe link that looks like it won't change often, we should.
| @@ -168,7 +169,7 @@ To configure the app security, do the following: | |||
|
|
|||
| ### Configure App Modules | |||
|
|
|||
| Every end-user that is known in Admin module also needs to be known in the OIDC Provider service. Access has to be given to allow an OIDCProvider.AccountDetail record to be created for every Administration.Account record when the end-user signs in. This can be achieved by the following steps: | |||
There was a problem hiding this comment.
Verify if it's Admin or Administration module and then bold it (when you uppercase, it implies you're referring to the one the customer should look at, not a general concept. If you want to just write about the general concept of an admin module, lowercase it).
Colons that end in colons usually need to have a list (bulleted or numbered) after them. This sentence previously ended in a colon with nothing after it -- seemingly previewing the header of the section below it.
All words in a compound hyphenate are individual words linked by hyphens, not one big word. Thus, they all get capitalized.
No description provided.