Repository: camunda/camunda-docs
Pull request #5282: docs: add authorization and user management user guide
Author: login: nicpuppa
Labels: name: component:identity
description: Issues related with Identity project
name: component:docs
description: Documentation improvements, including new or updated content
name: component:self-managed
description: Docs and issues related to Camunda Platform 8 Self-Managed
name: deploy
description: Stand up a temporary docs site with this PR
Created: 2025-03-18T11:43:16Z | Merged: 2025-03-21T07:38:55Z

## Description

<!-- Provide an overview of what to expect in the PR. -->
<!-- Relate or link the associated epic or task. -->
<!-- Add `@camunda/tech-writers` as reviewer to pull in a tech writer, or add your embedded tech writer. -->

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?

<!-- PRs merged go to stage.docs.camunda.io first and must be manually released to docs.camunda.io. -->

- [ ] 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)
- [x] 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

<!-- Camunda maintains 18 months of minor versions. Backporting your change to multiple versions is common. -->

- [ ] My changes are for **an upcoming minor release** and:
  - [x] 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.

<!-- UNCOMMENT THIS SECTION IF APPLICABLE. Adding or removing pages requires extra steps.
- [ ] I included my new page in the sidebar file(s).
- [ ] I added a redirect for a renamed or deleted page to the .htaccess file.
-->

- [ ] I added a DRI, team, or delegate as a reviewer for technical accuracy and grammar/style:
  - [ ] [Engineering team review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process)
  - [ ] [Technical writer review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process) via `@camunda/tech-writers` unless working with an embedded writer.

<!-- UNCOMMENT THIS SECTION IF APPLICABLE. Changes to **docs infra**, including updates to workflows and adding new npm packages, must be first discussed via issue or #ask-c8-documentation and linked for context.
- [ ] My changes require a [docs infrastructure review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process). (add `dx` label) -->

closes #5281 


Linked issue #5281: Authorization and User Management User Guide
Add docs pages in the `Orchestration Cluster Identity` section on how to create/delete an authorization and how to create/delete/update user

Diff:
diff --git a/docs/components/identity/authorization.md b/docs/components/identity/authorization.md
new file mode 100644
index 00000000000..f0cfb5234b8
--- /dev/null
+++ b/docs/components/identity/authorization.md
@@ -0,0 +1,58 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Authorizations are managed through permissions that can be assigned to [users](user.md), groups, roles, and mappings.
+
+## Authorization overview
+
+Camunda 8 Self-Managed [Orchestration clusters](/self-managed/reference-architecture/reference-architecture.md#orchestration-cluster) use resource-based authorization control, which grants permissions to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources, such as process instances.
+
+A user is not granted authorizations by default, and must be explicitly granted permission to access applications or perform actions on resources. Authorizations can be enabled or disabled in Self-Managed deployments via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations).
+
+## Authorization concepts
+
+### Permissions
+
+Permissions are the building blocks of authorizations. They define the actions that can be performed on resources. Permissions are granted to entities (like users) to perform specific actions on specified resources.
+
+Permissions are defined by a combination of a resource type, resource ID, and action. For example, a permission might grant a user the ability to read (the action) a specific process instance (the resource type).
+
+### Resources
+
+Resources are the objects on which actions can be performed. Resources can be entities like process instances, tasks, or users. Resources are identified by a resource ID and type.
+
+### Owners
+
+Owners are the entities to which permissions are granted. Owners can be [users](user.md), groups, roles, or mappings. Owners are identified by an owner ID and type.
+
+## Create an authorization
+
+To create a new authorization:
+
+1. Log in to Identity in your cluster, and click on the **Authorizations** tab.
+2. Select the resource type on the left side of the screen, and click **Create authorization**.
+3. Provide the following information for your authorization:
+   - **Owner type:** The entity (user, group, role, or mapping) to which you want to assign permissions.
+   - **Owner ID:** The ID of the owner to which you want to assign permissions.
+   - **Resource type:** A dropdown pre-populated with the selected resource type.
+   - **Resource ID**: The ID of the resource to which the owner's permissions apply.
+4. Select the permissions this authorization will grant.
+5. Click on the **Create authorization** button to finish.
+
+The authorization is then created, and the user, group, role, or mapping is granted the permission to perform the action on the specified resource.
+
+![identity-create-authorization-tab](./img/create-authorization-tab.png)
+
+## Delete an authorization
+
+To delete an authorization:
+
+1. Log in to Identity in your cluster, and click on the **Authorizations** tab.
+2. Select the resource type of the authorization you want to delete.
+3. Click on the **Delete** button next to the authorization you want to delete.
+4. Confirm the deletion by clicking **Delete** button in the confirmation dialog.
+
+The authorization is deleted, and the user, group, role, or mapping no longer has permission to perform the action on the specified resource.
diff --git a/docs/components/identity/identity-introduction.md b/docs/components/identity/identity-introduction.md
new file mode 100644
index 00000000000..e736f9975a6
--- /dev/null
+++ b/docs/components/identity/identity-introduction.md
@@ -0,0 +1,9 @@
+---
+id: identity-introduction
+title: Introduction
+description: "Identity provides unified identity management and authorizations in the Camunda 8 stack."
+---
+
+Identity is responsible for managing authentication, authorization, and entities within Camunda 8.
+
+For documentation on deploying Identity as part of Camunda 8 Self-Managed, refer to the [configuration guides](/self-managed/identity/what-is-identity.md).
diff --git a/docs/components/identity/img/create-authorization-tab.png b/docs/components/identity/img/create-authorization-tab.png
new file mode 100644
index 00000000000..5b6aca18781
Binary files /dev/null and b/docs/components/identity/img/create-authorization-tab.png differ
diff --git a/docs/components/identity/img/create-user-tab.png b/docs/components/identity/img/create-user-tab.png
new file mode 100644
index 00000000000..c67edf864e0
Binary files /dev/null and b/docs/components/identity/img/create-user-tab.png differ
diff --git a/docs/components/identity/img/update-user-tab.png b/docs/components/identity/img/update-user-tab.png
new file mode 100644
index 00000000000..354d50e818c
Binary files /dev/null and b/docs/components/identity/img/update-user-tab.png differ
diff --git a/docs/components/identity/user.md b/docs/components/identity/user.md
new file mode 100644
index 00000000000..2c7dc702327
--- /dev/null
+++ b/docs/components/identity/user.md
@@ -0,0 +1,59 @@
+---
+id: user
+title: User management
+description: "Learn how to manage users in your Self-Managed Orchestration cluster."
+---
+
+:::note
+User management in Identity is only supported by Self-Managed deployments. For SaaS, see how to [connect your identity provider](http://localhost:3000/docs/next/components/console/manage-organization/external-sso/).
+:::
+
+User management is the process of creating, updating, and deleting users in your Orchestration cluster. Users can be assigned roles and permissions to access applications and perform actions on resources.
+
+### Create a user
+
+To create a user:
+
+1. Log in to Identity in your cluster, and click on the **Users** tab.
+2. Click on the `Create user` button, and provide the following the user details:
+   - **Username**: The username for the user.
+   - **Name**: The name of the user.
+   - **Email**: The email address of the user.
+   - **Password**: The password for the user.
+3. Click on the **Create user** button to finish.
+
+The user is created, and can now log in to the Camunda 8 web application.
+
+![identity-create-user-tab](./img/create-user-tab.png)
+
+### Update a user
+
+1. Log in to Identity in your cluster, and click on the **Users** tab.
+2. Click on the **pencil icon** next to the user you want to update.
+   :::note
+   You can also select the user, and click the three vertical dots > **Update**.
+   :::
+3. Update the user details:
+   - **Name**: The name of the user.
+   - **Email**: The email address of the user.
+   - **Password**: The password for the user.
+4. Click on the **Save** button to finish.
+
+The user details are updated, and the user can now use these credentials to log in.
+
+![identity-update-user-tab](./img/update-user-tab.png)
+
+### Delete a user
+
+1. Log in to Identity in your cluster, and click on the **Users** tab.
+2. Click on the **Delete** button next to the user you want to delete.
+   :::note
+   You can also select the user, and click the three vertical dots > **Delete**.
+   :::
+3. Confirm the deletion by clicking on the **Delete** button in the confirmation dialog.
+
+The user is deleted, and can no longer log in to the Camunda 8 web application.
+
+### Assign authorizations to a user
+
+See the [authorization](./authorization.md) section to learn how to create authorizations for users.
diff --git a/docs/self-managed/identity/orchestration-identity/img/create-authorization-tab.png b/docs/self-managed/identity/orchestration-identity/img/create-authorization-tab.png
new file mode 100644
index 00000000000..5b6aca18781
Binary files /dev/null and b/docs/self-managed/identity/orchestration-identity/img/create-authorization-tab.png differ
diff --git a/docs/self-managed/identity/orchestration-identity/img/create-user-tab.png b/docs/self-managed/identity/orchestration-identity/img/create-user-tab.png
new file mode 100644
index 00000000000..c67edf864e0
Binary files /dev/null and b/docs/self-managed/identity/orchestration-identity/img/create-user-tab.png differ
diff --git a/docs/self-managed/identity/orchestration-identity/img/update-user-tab.png b/docs/self-managed/identity/orchestration-identity/img/update-user-tab.png
new file mode 100644
index 00000000000..354d50e818c
Binary files /dev/null and b/docs/self-managed/identity/orchestration-identity/img/update-user-tab.png differ
diff --git a/docs/self-managed/identity/orchestration-identity/installation.md b/docs/self-managed/identity/orchestration-identity/installation.md
index c7e45dce645..177df7f96db 100644
--- a/docs/self-managed/identity/orchestration-identity/installation.md
+++ b/docs/self-managed/identity/orchestration-identity/installation.md
@@ -11,6 +11,12 @@ Identity is included by default with the deployment of any [Orchestration cluste
 
 Identity for Orchestration clusters is available via [Helm install](/self-managed/setup/install.md), and for local development via [Camunda 8 Run](/self-managed/setup/deploy/local/c8run.md).
 
+:::note
+
+The following guides are on Identity configuration in Self-Managed environments. For information on Identity use and management, see the [user guides](/components/identity/identity-introduction.md).
+
+:::
+
 ## Initial configuration
 
 Following the default installation for [Camunda 8 Run](/self-managed/setup/deploy/local/c8run.md) will result in a cluster with the following:
@@ -66,7 +72,7 @@ Any other users included in the initialization `user` list will also be granted
 
 ### Enable API authentication and authorizations
 
-In Camunda 8 Run installations, basic authentication is enabled on the Camunda web applications, but the API is unprotected, and authorizations are disabled. API protection and authorizations can both be enabled by modifying your `application.yaml` or environment variables:
+In Camunda 8 Run installations, basic authentication is enabled on the Camunda web applications, but the API is unprotected, and [authorizations](/components/identity/authorization.md) are disabled. API protection and authorizations can both be enabled by modifying your `application.yaml` or environment variables:
 
 <Tabs>
   <TabItem value="helm" label="Helm properties">
diff --git a/docs/self-managed/identity/what-is-identity.md b/docs/self-managed/identity/what-is-identity.md
index 8a0d4b3e057..f1d4e2e7de1 100644
--- a/docs/self-managed/identity/what-is-identity.md
+++ b/docs/self-managed/identity/what-is-identity.md
@@ -5,19 +5,25 @@ sidebar_label: "What is Identity?"
 description: "Identity is the component within the Camunda 8 stack responsible for authentication and authorization."
 ---
 
-Identity in the Camunda 8 stack is handled by two distinct components: Identity for [Orchestration clusters](#identity-for-orchestration-clusters), and Identity for [Web Modeler and Console](#identity-for-web-modeler-and-console). In both cases, Identity is responsible for managing authentication and authorization within the Camunda 8 stack, but each implementation requires different configurations. In the case of Web Modeler and Console, Identity must be set up independently.
+Identity in the Camunda 8 stack is handled by two distinct components: Identity for [Orchestration clusters](#identity-for-orchestration-clusters), and Identity for [Web Modeler, Console, and Optimize](#identity-for-web-modeler-and-console). In both cases, Identity is responsible for managing authentication and authorization within the Camunda 8 stack, but each implementation requires different configurations. In the case of Web Modeler, Console, and Optimize, Identity must be set up independently.
 
 For more information on these differences, see the Self-Managed [reference architecture](/self-managed/reference-architecture/reference-architecture.md#orchestration-cluster-vs-web-modeler-and-console).
 
+:::note
+
+The following guides are on Identity configuration in Self-Managed environments. For information on Identity use and management, see the [user guides](/components/identity/identity-introduction.md).
+
+:::
+
 ## Identity for Orchestration clusters
 
 Identity is included by default in the [Orchestration cluster](/self-managed//reference-architecture/reference-architecture.md#orchestration-cluster), and does not require any external dependencies. For more information, see the Identity [configuration options](/self-managed/identity/orchestration-identity/configuration.md).
 
-## Identity for Web Modeler and Console
+## Identity for Web Modeler, Console, and Optimize
 
-For [Web Modeler and Console deployments](/self-managed/reference-architecture/reference-architecture.md#), Identity runs as a separate and dedicated component. For more information, see the guides on using an [existing Keycloak](/self-managed/setup/guides/using-existing-keycloak.md) instance, and connecting to an [OIDC provider](/self-managed/setup/guides/connect-to-an-oidc-provider.md).
+For [Web Modeler, Console, and Optimize deployments](/self-managed/reference-architecture/reference-architecture.md#), Identity runs as a separate and dedicated component. For more information, see the guides on using an [existing Keycloak](/self-managed/setup/guides/using-existing-keycloak.md) instance, and connecting to an [OIDC provider](/self-managed/setup/guides/connect-to-an-oidc-provider.md).
 
-Once deployed, Identity manages the following in Web Modeler and Console:
+Once deployed, Identity manages the following in Web Modeler, Console, and Optimize:
 
 - Applications
 - APIs
diff --git a/sidebars.js b/sidebars.js
index dc838975c40..031135019bd 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -675,6 +675,21 @@ module.exports = {
           ],
         },
       ],
+    },
+    {
+      type: "category",
+      label: "Identity",
+      link: {
+        type: "doc",
+        id: "components/identity/identity-introduction",
+      },
+      items: [
+        "components/identity/identity-introduction",
+        "components/identity/authorization",
+        "components/identity/user",
+      ],
+    },
+    {
       "Best Practices": [
         "components/best-practices/best-practices-overview",
         {
@@ -1399,13 +1414,13 @@ module.exports = {
           Identity: [
             "self-managed/identity/what-is-identity",
             {
-              "Orchestration Cluster Identity": [
+              "Identity for Orchestration clusters": [
                 "self-managed/identity/orchestration-identity/installation",
                 "self-managed/identity/orchestration-identity/configuration",
               ],
             },
             {
-              "Identity for Web Modeler and Console": [
+              "Identity for Web Modeler, Console, and Optimize": [
                 "self-managed/identity/getting-started/install-identity",
                 {
                   "User guide": [
diff --git a/versioned_docs/version-8.7/components/modeler/web-modeler/versions.md b/versioned_docs/version-8.7/components/modeler/web-modeler/versions.md
index b02098f326d..a07dc92fba3 100644
--- a/versioned_docs/version-8.7/components/modeler/web-modeler/versions.md
+++ b/versioned_docs/version-8.7/components/modeler/web-modeler/versions.md
@@ -115,7 +115,7 @@ The diagram reverts to the restored version. A new version is created with "(res
 You can create a new diagram by copying a specific version.
 
 1. In the sidebar **Versions** list, hover over the diagram version you want to copy.
-1. Select the three vertical dots to open the actions menu.
+1. Select the three to open the actions menu.
 1. Select **Copy to...**.
 1. Choose a project/folder and select **Copy here** to create the new diagram in the chosen folder.
 


Reviews:
user: login: conceptualshark
body: 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.
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-18T14:13:29Z
user: login: Ben-Sheppard
body: Its nice to see more content arriving for Identity! I've added some comments
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-19T17:18:40Z
user: login: nicpuppa
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T08:33:40Z
user: login: Ben-Sheppard
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T08:47:20Z
user: login: nicpuppa
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T08:50:11Z
user: login: Ben-Sheppard
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T08:51:21Z
user: login: nicpuppa
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T09:00:09Z
user: login: nicpuppa
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T09:09:41Z
user: login: nicpuppa
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T09:14:00Z
user: login: Ben-Sheppard
body: 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 
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T11:05:14Z
user: login: conceptualshark
body: 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.
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T18:20:00Z

Review comments:
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
path: docs/components/identity/authorization.md
user: login: Ben-Sheppard
body: I'm not sure the definition of Identity at the start of this paragraph makes sense on this page given the subject is about managing authorizations.

```suggestion
Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
```
created_at: 2025-03-19T16:50:04Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+
+## Authorization overview
+
+Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
path: docs/components/identity/authorization.md
user: login: Ben-Sheppard
body: 💭 I think this sentence can be removed, we explain underneath that C8 uses resource based authorizations and what that means (permissions, actions, access)
created_at: 2025-03-19T16:54:29Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+
+## Authorization overview
+
+Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
+
+Camunda 8 cluster uses resource-based authorization control, which means that permissions are granted to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources like process instances.
+
+Authorizations can be enabled or disabled for each Camunda 8 cluster via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations). By default, authorizations are disabled. When they are enabled, a user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources.
path: docs/components/identity/authorization.md
user: login: Ben-Sheppard
body: 🔧 This is true only for C8run, in helm they are enabled, we should make that clear here
created_at: 2025-03-19T16:57:23Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+
+## Authorization overview
+
+Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
+
+Camunda 8 cluster uses resource-based authorization control, which means that permissions are granted to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources like process instances.
+
+Authorizations can be enabled or disabled for each Camunda 8 cluster via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations). By default, authorizations are disabled. When they are enabled, a user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources.
+
+## Authorization concepts
path: docs/components/identity/authorization.md
user: login: Ben-Sheppard
body: ❓ Are we describing this in a general sense or a C8 sense? I think here I would opt (its its about C8) to be more descriptive with an example, in C8 an authorization has 3 core parts, the first is an owner, the second are resources and the third is the permissions allowed on those resources. This is how I create the authorization in the UI.

In the future I think we can be quite visual here and create a graphic of an owner (person) a BPMN (resource id) and permission. As a text example:

Owner: {Type: User, ID: foo@Bar} has permissions: ["Read process definition", "Update process definition"] for resources: ["my-bpmn-process", "my-other-bpmn"]

This can then be extended to show groups and how we handle inheritance 
created_at: 2025-03-19T17:05:02Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+
+## Authorization overview
+
+Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
+
+Camunda 8 cluster uses resource-based authorization control, which means that permissions are granted to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources like process instances.
+
+Authorizations can be enabled or disabled for each Camunda 8 cluster via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations). By default, authorizations are disabled. When they are enabled, a user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources.
+
+## Authorization concepts
+
+### Permissions
+
+Permissions are the building blocks of authorizations. They define the actions that can be performed on resources. Permissions are granted to entities (like users) to perform specific actions on specified resources.
+
+Permissions are defined by a combination of a resource type, resource ID, and action. For example, a permission might grant a user the ability to read a specific process instance.
+
+### Resources
+
+Resources are the objects on which actions can be performed. Resources can be entities like process instances, tasks, or users. Resources are identified by a resource ID and type.
+
+## Create an authorization
+
+1. Log in to the Camunda 8 web application.
path: docs/components/identity/authorization.md
user: login: Ben-Sheppard
body: ```suggestion
1. Log in to Identity in your cluster.
```
created_at: 2025-03-19T17:06:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+
+## Authorization overview
+
+Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
+
+Camunda 8 cluster uses resource-based authorization control, which means that permissions are granted to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources like process instances.
+
+Authorizations can be enabled or disabled for each Camunda 8 cluster via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations). By default, authorizations are disabled. When they are enabled, a user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources.
+
+## Authorization concepts
+
+### Permissions
+
+Permissions are the building blocks of authorizations. They define the actions that can be performed on resources. Permissions are granted to entities (like users) to perform specific actions on specified resources.
+
+Permissions are defined by a combination of a resource type, resource ID, and action. For example, a permission might grant a user the ability to read a specific process instance.
+
+### Resources
+
+Resources are the objects on which actions can be performed. Resources can be entities like process instances, tasks, or users. Resources are identified by a resource ID and type.
+
+## Create an authorization
+
+1. Log in to the Camunda 8 web application.
+2. Click on the `Authorizations` tab.
+3. Select the resource type on the left side of the screen.
+4. Click on the `Create authorization` button, this will create an authorization for the previously selected resource type.
+5. Select the owner type (user, group, role, or mapping) to which you want to assign permissions.
+6. Add the owner ID to which you want to assign permissions.
path: docs/components/identity/authorization.md
user: login: Ben-Sheppard
body: ❓ In a later iteration I think it would be good to explain what/where the owner ID comes from, as an example in the users its the username, in groups its the group ID etc
created_at: 2025-03-19T17:08:03Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+
+## Authorization overview
+
+Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
+
+Camunda 8 cluster uses resource-based authorization control, which means that permissions are granted to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources like process instances.
+
+Authorizations can be enabled or disabled for each Camunda 8 cluster via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations). By default, authorizations are disabled. When they are enabled, a user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources.
+
+## Authorization concepts
+
+### Permissions
+
+Permissions are the building blocks of authorizations. They define the actions that can be performed on resources. Permissions are granted to entities (like users) to perform specific actions on specified resources.
+
+Permissions are defined by a combination of a resource type, resource ID, and action. For example, a permission might grant a user the ability to read a specific process instance.
+
+### Resources
+
+Resources are the objects on which actions can be performed. Resources can be entities like process instances, tasks, or users. Resources are identified by a resource ID and type.
+
+## Create an authorization
+
+1. Log in to the Camunda 8 web application.
+2. Click on the `Authorizations` tab.
+3. Select the resource type on the left side of the screen.
+4. Click on the `Create authorization` button, this will create an authorization for the previously selected resource type.
+5. Select the owner type (user, group, role, or mapping) to which you want to assign permissions.
+6. Add the owner ID to which you want to assign permissions.
+7. Add the resource ID.
+8. Select the permissions you want to permit.
+9. Click on the `Create authorization` button.
+10. The authorization is created and the user, group, role, or mapping is granted the permission to perform the action on the specified resource.
+
+![identity-create-authorization-tab](./img/create-authorization-tab.png)
+
+## Delete an authorization
+
+1. Log in to the Camunda 8 web application.
path: docs/components/identity/authorization.md
user: login: Ben-Sheppard
body: ```suggestion
1. Log in to Identity in your cluster.
```
created_at: 2025-03-19T17:08:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,9 @@
+---
+id: identity-introduction
+title: Introduction
+description: "Identity provides unified identity management and authorizations in the Camunda 8 stack."
+---
+
+Identity is responsible for managing authentication and authorization within Camunda 8.
path: docs/components/identity/identity-introduction.md
user: login: Ben-Sheppard
body: 🔧 Identity also manages the entities in the system such as groups, roles etc. 
created_at: 2025-03-19T17:10:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,58 @@
+---
+id: user
+title: User management
+description: "Learn how to manage users in your Self-Managed Orchestration cluster."
+---
+
+:::note
+User management in Identity is only needed by Self-Managed deployments. For SaaS, see how to [connect your identity provider](http://localhost:3000/docs/next/components/console/manage-organization/external-sso/).
path: docs/components/identity/user.md
user: login: Ben-Sheppard
body: ```suggestion
User management in Identity is only supported in Self-Managed deployments. For SaaS, see how to [connect your identity provider](http://localhost:3000/docs/next/components/console/manage-organization/external-sso/).
```
created_at: 2025-03-19T17:11:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,58 @@
+---
+id: user
+title: User management
+description: "Learn how to manage users in your Self-Managed Orchestration cluster."
+---
+
+:::note
+User management in Identity is only needed by Self-Managed deployments. For SaaS, see how to [connect your identity provider](http://localhost:3000/docs/next/components/console/manage-organization/external-sso/).
+:::
+
+Identity provides unified, cluster-level identity management and authorizations. User management is a key part of identity management, and allows you to create, update, and delete users in your Orchestration cluster.
path: docs/components/identity/user.md
user: login: Ben-Sheppard
body: ```suggestion
User management is a key part of identity management, and allows you to create, update, and delete users in your Orchestration cluster.
```

I think here I'd also remove the Identity definition at the start, this page is about user management which the sentence after captures well
created_at: 2025-03-19T17:13:15Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,58 @@
+---
+id: user
+title: User management
+description: "Learn how to manage users in your Self-Managed Orchestration cluster."
+---
+
+:::note
+User management in Identity is only needed by Self-Managed deployments. For SaaS, see how to [connect your identity provider](http://localhost:3000/docs/next/components/console/manage-organization/external-sso/).
+:::
+
+Identity provides unified, cluster-level identity management and authorizations. User management is a key part of identity management, and allows you to create, update, and delete users in your Orchestration cluster.
path: docs/components/identity/user.md
user: login: Ben-Sheppard
body: Though looking at this and the next section `User management overview`, are they both needed?
created_at: 2025-03-19T17:13:46Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,58 @@
+---
+id: user
+title: User management
+description: "Learn how to manage users in your Self-Managed Orchestration cluster."
+---
+
+:::note
+User management in Identity is only needed by Self-Managed deployments. For SaaS, see how to [connect your identity provider](http://localhost:3000/docs/next/components/console/manage-organization/external-sso/).
+:::
+
+Identity provides unified, cluster-level identity management and authorizations. User management is a key part of identity management, and allows you to create, update, and delete users in your Orchestration cluster.
+
+## User management overview
+
+User management is the process of creating, updating, and deleting users in your Orchestration cluster. Users can be assigned roles and permissions to access applications and perform actions on resources.
+
+### Create a user
+
+1. Log in to the Camunda 8 web application.
path: docs/components/identity/user.md
user: login: Ben-Sheppard
body: Same comment here as before that I think for now it should say Identity
created_at: 2025-03-19T17:15:51Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,58 @@
+---
+id: user
+title: User management
+description: "Learn how to manage users in your Self-Managed Orchestration cluster."
+---
+
+:::note
+User management in Identity is only needed by Self-Managed deployments. For SaaS, see how to [connect your identity provider](http://localhost:3000/docs/next/components/console/manage-organization/external-sso/).
+:::
+
+Identity provides unified, cluster-level identity management and authorizations. User management is a key part of identity management, and allows you to create, update, and delete users in your Orchestration cluster.
+
+## User management overview
+
+User management is the process of creating, updating, and deleting users in your Orchestration cluster. Users can be assigned roles and permissions to access applications and perform actions on resources.
+
+### Create a user
+
+1. Log in to the Camunda 8 web application.
+2. Click on the `Users` tab.
+3. Click on the `Create user` button.
+4. Enter the user details:
+   - **Username**: The username for the user.
+   - **Name**: The name of the user.
+   - **Email**: The email address of the user.
+   - **Password**: The password for the user.
+5. Click on the `Create user` button.
+6. The user is created and can now log in to the Camunda 8 web application.
+
+![identity-create-user-tab](./img/create-user-tab.png)
+
+### Update a user
+
+1. Log in to the Camunda 8 web application.
+2. Click on the `Users` tab.
+3. Select the user you want to update.
+4. Click on the `Edit` button next to the user.
+5. Update the user details:
+   - **Name**: The name of the user.
+   - **Email**: The email address of the user.
+   - **Password**: The password for the user.
+6. Click on the `Save` button.
+7. The user details are updated.
+
+![identity-update-user-tab](./img/update-user-tab.png)
+
+### Delete a user
+
+1. Log in to the Camunda 8 web application.
+2. Click on the `Users` tab.
+3. Select the user you want to delete.
+4. Click on the `Delete` button next to the user.
+5. Confirm the deletion by clicking on the `Delete` button in the confirmation dialog.
+6. The user is deleted and can no longer log in to the Camunda 8 web application.
+
+### Assign authorizations to a user
+
+Please refer to the [authorization](./authorization.md) section to learn how to assign permissions to users.
path: docs/components/identity/user.md
user: login: Ben-Sheppard
body: An alternative here:
```suggestion
Please refer to the [authorization](./authorization.md) section to learn how to create authorizations for users.
```
created_at: 2025-03-19T17:16:57Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+
+## Authorization overview
+
+Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
+
+Camunda 8 cluster uses resource-based authorization control, which means that permissions are granted to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources like process instances.
+
+Authorizations can be enabled or disabled for each Camunda 8 cluster via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations). By default, authorizations are disabled. When they are enabled, a user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources.
path: docs/components/identity/authorization.md
user: login: nicpuppa
body: Should I completely remove the sentence `By default, authorizations are disabled` ?  I think say something like: _in C8Run authorization is  disabled by default but in Helm authorization is enabled_ doesn't bring any value here. I'll rephrase
created_at: 2025-03-20T08:33:40Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+
+## Authorization overview
+
+Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
+
+Camunda 8 cluster uses resource-based authorization control, which means that permissions are granted to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources like process instances.
+
+Authorizations can be enabled or disabled for each Camunda 8 cluster via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations). By default, authorizations are disabled. When they are enabled, a user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources.
path: docs/components/identity/authorization.md
user: login: Ben-Sheppard
body: In other places we've taken the approach that the page is written from the view of C8Run, and if we need to clarify a difference with helm its added in a `:::note` section. I'm fine with either but @conceptualshark may have a preference here
created_at: 2025-03-20T08:47:20Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+
+## Authorization overview
+
+Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
+
+Camunda 8 cluster uses resource-based authorization control, which means that permissions are granted to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources like process instances.
+
+Authorizations can be enabled or disabled for each Camunda 8 cluster via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations). By default, authorizations are disabled. When they are enabled, a user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources.
path: docs/components/identity/authorization.md
user: login: nicpuppa
body: Those section (authorization and user management) are not under the SM documentations, so I think here doesn't make sense to use the C8Run point of view, we should use a general approach
created_at: 2025-03-20T08:50:10Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+
+## Authorization overview
+
+Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
+
+Camunda 8 cluster uses resource-based authorization control, which means that permissions are granted to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources like process instances.
+
+Authorizations can be enabled or disabled for each Camunda 8 cluster via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations). By default, authorizations are disabled. When they are enabled, a user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources.
path: docs/components/identity/authorization.md
user: login: Ben-Sheppard
body: Ah thats a good point, lets go with the general approach 
created_at: 2025-03-20T08:51:21Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+
+## Authorization overview
+
+Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
+
+Camunda 8 cluster uses resource-based authorization control, which means that permissions are granted to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources like process instances.
+
+Authorizations can be enabled or disabled for each Camunda 8 cluster via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations). By default, authorizations are disabled. When they are enabled, a user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources.
+
+## Authorization concepts
path: docs/components/identity/authorization.md
user: login: nicpuppa
body: I can add an owner section and explain what does it mean in C8
created_at: 2025-03-20T09:00:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,51 @@
+---
+id: authorization
+title: Authorization
+description: "Learn how to manage authorizations in your Orchestration cluster."
+---
+
+Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+
+## Authorization overview
+
+Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
+
+Camunda 8 cluster uses resource-based authorization control, which means that permissions are granted to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources like process instances.
+
+Authorizations can be enabled or disabled for each Camunda 8 cluster via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations). By default, authorizations are disabled. When they are enabled, a user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources.
+
+## Authorization concepts
+
+### Permissions
+
+Permissions are the building blocks of authorizations. They define the actions that can be performed on resources. Permissions are granted to entities (like users) to perform specific actions on specified resources.
+
+Permissions are defined by a combination of a resource type, resource ID, and action. For example, a permission might grant a user the ability to read a specific process instance.
+
+### Resources
+
+Resources are the objects on which actions can be performed. Resources can be entities like process instances, tasks, or users. Resources are identified by a resource ID and type.
+
+## Create an authorization
+
+1. Log in to the Camunda 8 web application.
+2. Click on the `Authorizations` tab.
+3. Select the resource type on the left side of the screen.
+4. Click on the `Create authorization` button, this will create an authorization for the previously selected resource type.
+5. Select the owner type (user, group, role, or mapping) to which you want to assign permissions.
+6. Add the owner ID to which you want to assign permissions.
path: docs/components/identity/authorization.md
user: login: nicpuppa
body: I think it make sense to add this section once we have documented all the entities
created_at: 2025-03-20T09:09:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,58 @@
+---
+id: user
+title: User management
+description: "Learn how to manage users in your Self-Managed Orchestration cluster."
+---
+
+:::note
+User management in Identity is only needed by Self-Managed deployments. For SaaS, see how to [connect your identity provider](http://localhost:3000/docs/next/components/console/manage-organization/external-sso/).
+:::
+
+Identity provides unified, cluster-level identity management and authorizations. User management is a key part of identity management, and allows you to create, update, and delete users in your Orchestration cluster.
path: docs/components/identity/user.md
user: login: nicpuppa
body: They are similar, I'll merge the sections
created_at: 2025-03-20T09:13:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -4,15 +4,13 @@ title: Authorization
 description: "Learn how to manage authorizations in your Orchestration cluster."
 ---
 
-Identity provides unified, cluster-level identity management and authorizations. Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
+Authorizations are managed through permissions that can be assigned to [users](user.md), group, role and mapping.
 
 ## Authorization overview
 
-Authorization is a mechanism that controls access to resources and actions based on permissions assigned to an entity.
-
 Camunda 8 cluster uses resource-based authorization control, which means that permissions are granted to entities (like users) to perform specific actions on specified resources. For example, permissions can be set for actions such as reading, updating, creating, or deleting resources like process instances.
 
-Authorizations can be enabled or disabled for each Camunda 8 cluster via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations). By default, authorizations are disabled. When they are enabled, a user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources.
+A user is not granted access to anything by default and must be explicitly granted permission to access applications or perform actions on resources. Authorizations can be enabled or disabled in Self-Managed deployments via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations).
path: docs/components/identity/authorization.md
user: login: Ben-Sheppard
body: ```suggestion
A user is not granted authorizations by default and must be explicitly granted permission to access applications or perform actions on resources. Authorizations can be enabled or disabled in Self-Managed deployments via [configuration settings](/self-managed/identity/orchestration-identity/installation.md#enable-api-authentication-and-authorizations).
```
created_at: 2025-03-20T11:02:45Z
author_association: CONTRIBUTOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-03-18T11:43:42Z
body: :wave: :robot: :thinking: 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/*.<br/><ul> <li>docs/components/identity/authorization.md</li> <li>docs/components/identity/identity-introduction.md</li> <li>docs/components/identity/img/create-authorization-tab.png</li> <li>docs/components/identity/img/create-user-tab.png</li> <li>docs/components/identity/img/update-user-tab.png</li> <li>docs/components/identity/user.md</li> <li>docs/self-managed/identity/orchestration-identity/img/create-authorization-tab.png</li> <li>docs/self-managed/identity/orchestration-identity/img/create-user-tab.png</li> <li>docs/self-managed/identity/orchestration-identity/img/update-user-tab.png</li> <li>docs/self-managed/identity/orchestration-identity/installation.md</li> <li>docs/self-managed/identity/what-is-identity.md</li> </ul> These files were changed only in *docs/*. You might want to duplicate these changes in *versioned_docs/version-8.7/*.<br/><ul> <li>docs/components/identity/authorization.md</li> <li>docs/components/identity/identity-introduction.md</li> <li>docs/components/identity/img/create-authorization-tab.png</li> <li>docs/components/identity/img/create-user-tab.png</li> <li>docs/components/identity/img/update-user-tab.png</li> <li>docs/components/identity/user.md</li> <li>docs/self-managed/identity/orchestration-identity/img/create-authorization-tab.png</li> <li>docs/self-managed/identity/orchestration-identity/img/create-user-tab.png</li> <li>docs/self-managed/identity/orchestration-identity/img/update-user-tab.png</li> <li>docs/self-managed/identity/orchestration-identity/installation.md</li> <li>docs/self-managed/identity/what-is-identity.md</li> </ul> These files were changed only in *versioned_docs/version-8.7/*. You might want to duplicate these changes in *docs/*.<br/><ul> <li>versioned_docs/version-8.7/components/modeler/web-modeler/versions.md</li> </ul> These files were changed only in *versioned_docs/version-8.7/*. You might want to duplicate these changes in *versioned_docs/version-8.6/*.<br/><ul> <li>versioned_docs/version-8.7/components/modeler/web-modeler/versions.md</li> </ul>

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](https://github.com/camunda/camunda-docs/blob/c666b7e5e35bfe31468ce4ac679ea7b62ab86d73/howtos/documentation-guidelines.md#versions).
<!-- thollander/actions-comment-pull-request "check-versions" -->
author_association: CONTRIBUTOR
user: login: akeller
created_at: 2025-03-18T13:22:35Z
body: @nicpuppa this closes https://github.com/camunda/camunda-docs/issues/5281, right? Or are you delivering incrementally? 
author_association: CONTRIBUTOR
user: login: nicpuppa
created_at: 2025-03-18T13:25:13Z
body: > @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 

author_association: CONTRIBUTOR
user: login: nicpuppa
created_at: 2025-03-18T14:18:22Z
body: 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 
author_association: CONTRIBUTOR
user: login: ThorbenLindhauer
created_at: 2025-03-18T15:04:17Z
body: @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.
author_association: MEMBER
user: login: nicpuppa
created_at: 2025-03-18T15:15:46Z
body: 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 
author_association: CONTRIBUTOR
user: login: conceptualshark
created_at: 2025-03-18T15:21:57Z
body: 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 
author_association: CONTRIBUTOR
user: login: ThorbenLindhauer
created_at: 2025-03-18T16:37:11Z
body: > 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.
author_association: MEMBER
user: login: conceptualshark
created_at: 2025-03-18T20:49:02Z
body: 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](https://docs.camunda.io/docs/next/components/console/manage-organization/manage-users/) 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](https://docs.camunda.io/docs/next/components/console/manage-organization/external-sso/), 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](https://docs.camunda.io/docs/next/components/concepts/access-control/user-groups/), 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. 🙂 
author_association: CONTRIBUTOR
user: login: nicpuppa
created_at: 2025-03-19T07:08:08Z
body: @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
author_association: CONTRIBUTOR
user: login: Ben-Sheppard
created_at: 2025-03-19T16:12:17Z
body: Hey @conceptualshark and @nicpuppa 

> How does (or will) the Console [user guide](https://docs.camunda.io/docs/next/components/console/manage-organization/manage-users/) 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](https://docs.camunda.io/docs/next/components/console/manage-organization/external-sso/), 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)
author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-03-21T07:43:13Z
body: <!-- add-pr-comment:add-pr-comment -->

:broom: Preview environment for this PR has been torn down.
author_association: CONTRIBUTOR