docs: add authorization and user management user guide

[nicpuppa]

Description

This PR adds a user guide on how to create/delete an authorization and how to create/update/delete user

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support. (add bug or support label)
• This is already available but undocumented and should be released within a week. (add available & undocumented label)
• This is on a specific schedule and the assignee will coordinate a release with the DevEx team. (create draft PR and/or add hold label)
• This is part of a scheduled alpha or minor. (add alpha or minor label)
• There is no urgency with this change (add low prio label)

PR Checklist

• My changes are for an upcoming minor release and:
  • are in the /docs directory (version 8.8).
  • are in the /versioned_docs/version-8.7/ directory (version 8.7).
• My changes are for an already released minor and are in a /versioned_docs directory.

• I added a DRI, team, or delegate as a reviewer for technical accuracy and grammar/style:
  • Engineering team review
  • Technical writer review via @camunda/tech-writers unless working with an embedded writer.

closes #5281

[github-actions]

👋 🤖 🤔 Hello, @conceptualshark! Did you make your changes in all the right places?

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.6/.

• docs/components/identity/authorization.md
• docs/components/identity/identity-introduction.md
• docs/components/identity/img/create-authorization-tab.png
• docs/components/identity/img/create-user-tab.png
• docs/components/identity/img/update-user-tab.png
• docs/components/identity/user.md
• docs/self-managed/identity/orchestration-identity/img/create-authorization-tab.png
• docs/self-managed/identity/orchestration-identity/img/create-user-tab.png
• docs/self-managed/identity/orchestration-identity/img/update-user-tab.png
• docs/self-managed/identity/orchestration-identity/installation.md
• docs/self-managed/identity/what-is-identity.md

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.7/.

• docs/components/identity/authorization.md
• docs/components/identity/identity-introduction.md
• docs/components/identity/img/create-authorization-tab.png
• docs/components/identity/img/create-user-tab.png
• docs/components/identity/img/update-user-tab.png
• docs/components/identity/user.md
• docs/self-managed/identity/orchestration-identity/img/create-authorization-tab.png
• docs/self-managed/identity/orchestration-identity/img/create-user-tab.png
• docs/self-managed/identity/orchestration-identity/img/update-user-tab.png
• docs/self-managed/identity/orchestration-identity/installation.md
• docs/self-managed/identity/what-is-identity.md

These files were changed only in versioned_docs/version-8.7/. You might want to duplicate these changes in docs/.

• versioned_docs/version-8.7/components/modeler/web-modeler/versions.md

These files were changed only in versioned_docs/version-8.7/. You might want to duplicate these changes in versioned_docs/version-8.6/.

• versioned_docs/version-8.7/components/modeler/web-modeler/versions.md

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

[akeller]

@nicpuppa this closes #5281, right? Or are you delivering incrementally?

[nicpuppa]

@nicpuppa this closes #5281, right? Or are you delivering incrementally?

You are right, I plan to add both guide with this PR. I just changed the description adding the link to the issue @akeller

[conceptualshark]

I can do an editing pass over these, but my main question is whether or not this content will also apply in any way to (future) SaaS deployments?

If so we should probably move it out of the SM section and into Components, and make sure any content has this end state in mind.

[nicpuppa]

It's a good point @conceptualshark, from my understanding this will apply also to SaaS. There is nothing related to the new Identity as far as I know in the SaaS documentation section

cc @ThorbenLindhauer

[ThorbenLindhauer]

@nicpuppa we don't need to document user management specifically for SaaS, because we will always use OIDC (=> Auth0) for that. But we need to document how to work with authorizations because they apply in both cases.

[nicpuppa]

What is the best approach here ? Move the authorization section outside the SM specific documentation ? Duplicate it in both ? I'm not sure @conceptualshark @ThorbenLindhauer

[conceptualshark]

In my opinion, once we have Identity-related documentation outside of the Self-Managed section, we're making an implicit agreement that any Identity guides could be found there. In an 8.8 world, I don't think SM users should have to go into the SM docs, which is largely for configuration and deployment, to find a user guide - I think that only works now because Identity doesn't exist in SaaS.

I'd like to see both guides in Components, with a note where one doesn't apply to SaaS (and link to the eventual IdP guide, for example), but that's just a recommendation!

I am also not sure if this means building out a new Identity component section in Components, or if Product has any plans for/input on placement here? @FarkasRabai

[ThorbenLindhauer]

I am also not sure if this means building out a new Identity component section in Components

Sounds meaningful to me. That makes it consistent with the docs structure for the other components and conceptually Identity is a webapp in the Orchestration Cluster like the other ones.

[conceptualshark]

I've pushed a version here that builds a section in the Component docs instead, just to see how it feels. I left the older content so we can just remove whichever we end up not using.

I have a few questions that I don't think are quite relevant to the current state of Identity, but may impact how we want to position these docs overall:

• How does (or will) the Console user guide change now that this will be handled in Identity? I assume Console will no longer handle some of these features, so at some point we'll need to pare down this guide. Where does the line between Identity's management and Console's management happen?

• Similar question for the IdP page, though I know this isn't fully implemented yet. Would this guide need to move to the Identity component section, or is it still tied to Console?

• We also have a Concepts section on access control, which I believe was originally considered for some "Identity and access control" docs to expand on concepts if the Identity section ends up not being needed.

It's not entirely clear for me yet how much SaaS will be aware of Identity, and which component will be handling these UI-based tasks. These likely don't all need addressing in this PR, but as we're addressing some structural docs changes, knowing the answers could help me better suggest an order.

For ease, we could always merge these guides as in the initial proposal, and answer some of these questions separately. 🙂

[nicpuppa]

@conceptualshark I like the new section, I think we can remove the duplicated section under SM.

Related to your questions, I'm not sure if I'm able to answer, so I'll ping @Ben-Sheppard

[Ben-Sheppard]

Hey @conceptualshark and @nicpuppa

How does (or will) the Console user guide change now that this will be handled in Identity? I assume Console will no longer handle some of these features, so at some point we'll need to pare down this guide. Where does the line between Identity's management and Console's management happen?

It will change but honestly its difficult to say by how much (my expectation is greatly though), in SaaS there are three core flows that Management Identity is used for:

1. Web Modeler creating authorizations for a user when a model is deployed
2. Operate reading resource authorizations to filter data
3. Tasklist reading groups of a user

2 and 3 will now be cluster based, 1 will have to change also as authorizations are shifting to the cluster - I don't know what the flow looks like there.

Where does the line between Identity's management and Console's management happen?

If it is anything to do with the cluster (with the exception of client credentials for now) its Identity, if its organizational, its Console.

Similar question for the IdP page, though I know this isn't fully implemented yet. Would this guide need to move to the Identity component section, or is it still tied to Console?

For now, this remains the same, we've had discussions about what this could look like in the future (configuring my cluster to talk to a specific IDP) but it will still be a Console level task IMO.

It's not entirely clear for me yet how much SaaS will be aware of Identity, and which component will be handling these UI-based tasks. These likely don't all need addressing in this PR, but as we're addressing some structural docs changes, knowing the answers could help me better suggest an order.

With 8.8 SaaS will be fully aware of Orchestration Identity, it will be a visible component that will offer the UI to handle the cluster management. As mentioned by @ThorbenLindhauer there I think are limited instances where a concept will only apply to SM and not SaaS (User management being one), but I would really like to remove that divide I think and just use a tag/note to say that User management is Self-managed only :)

@ThorbenLindhauer regarding:

Sounds meaningful to me. That makes it consistent with the docs structure for the other components and conceptually Identity is a webapp in the Orchestration Cluster like the other ones.

I was under the impression that we want to move away from the separated component approach is that not applicable/correct here? (Maybe something for @conceptualshark?)

Does that help? (I'll also review the PR shortly)

[Ben-Sheppard]

Its nice to see more content arriving for Identity! I've added some comments

[Ben-Sheppard]

Just one small comment from my side.

It would be good to also get @conceptualshark to have a pass over the changes to make sure they align with his vision for the docs

[conceptualshark]

I ran through and made a few updates (and took the opportunity to add some Optimize references) - this is in good shape to me! 👍 We can come back and improve things (add SaaS references, etc), as those updates are made available.

[github-actions]

🧹 Preview environment for this PR has been torn down.