Initial draft of identity docs #5133

conceptualshark · 2025-03-03T20:29:47Z

Description

Identity (with basic auth) is now bundled in the Orchestration cluster. However, Web Modeler and Console clusters will still need to run Identity independently, and so the older documentation is still relevant.

This PR aims to:

Provide a proof of concept for separating the new Orchestration vs Web Modeler etc Identity documentation
Create a place for new Identity documentation to live
Scaffold out initial documentation required (landing page, current configuration).

This PR does not address how Identity is used or described elsewhere in the docs, including the Helm chart. I've also moved a bunch of content only in the sidebars, but not yet moved their actual file locations.

Resolves requirements 2 and 3 of https://github.com/camunda/documentation-team/issues/455

Relates to https://github.com/camunda/documentation-team/issues/465

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.

github-actions · 2025-03-03T20:30:13Z

👋 🤖 🤔 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/self-managed/identity/orchestration-identity/configuration.md
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/self-managed/identity/orchestration-identity/configuration.md
docs/self-managed/identity/orchestration-identity/installation.md
docs/self-managed/identity/what-is-identity.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.

Ben-Sheppard · 2025-03-04T10:14:00Z

docs/self-managed/identity/orchestration-identity/configuration.md

+<Tabs>
+  <TabItem value="env" label="Environment variables" default>
+
+| Environment variable                                  | Description                                                                                       | Default value       |


💭 These variables are applicable to all components in the orchestration cluster so I think we need to find a central home for these. As per @megglos suggestion I wonder if we can create a new area for the Core components?

It may be that its more important to just get this in place regardless and then adjust as we go, happy to align off PR.

Followed up on the related issue, but I think ideally we move forward with this iteration, and then make additional Core-related changes in subsequent PRs: https://github.com/camunda/documentation-team/issues/465#issuecomment-2701824081

In favor of having this as a first increment too.

Ben-Sheppard · 2025-03-04T10:15:15Z

sidebars.js

+              ],
+            },
+            {
+              "Identity for Web Modeler and Console": [


💭 How do you feel about positioning this one as Management cluster Identity?

I would love to have a simple name for this, but right now we use "Web Modeler and Console" throughout the docs. For consistency - and to make it easier to update when/if this gets changed - I'd like to have it match for now.

docs/self-managed/identity/orchestration-identity/installation.md

akeller · 2025-03-05T14:04:28Z

Added @FarkasRabai as a reviewer to get the PM perspective on these Identity docs changes.

conceptualshark

I've pushed an update to include/respond to @Ben-Sheppard's suggestions, and to incorporate the ACs asked by @megglos in https://github.com/camunda/documentation-team/issues/465

I am sure some of this is incorrect! 😅 Let me know what needs to be updated.

docs/self-managed/identity/orchestration-identity/installation.md

akeller · 2025-03-05T22:13:01Z

docs/self-managed/identity/orchestration-identity/configuration.md

+[Spring configuration](https://docs.spring.io/spring-boot/reference/features/external-config.html) method.
+:::
+
+The following variables apply globally to all components within the Camunda Orchestration core: Zeebe, Operate, and Tasklist.


Do you know if we need to state anything about Optimize explicitly? In the current 8.8 glossary definition of Orchestration core, we include Optimize but don't mention it here at all.

I think that Glossary needs updating after this decision https://camunda.slack.com/archives/C01H4NG9XDY/p1740070705216559 where from my understanding Optimize is not considered part of the core orchestration cluster but a separate component.

can you confirm @RomanJRW @felix-mueller @romansmirnov ?

Yes, this would be true.

The kick-off for Optimize in a dedicated app happened earlier this week. One of the defined action items was for the DRI (@buccarel) to reach out to the Docs team and specify what docs changes need as a result of this decision. This needs a more holistic approach than just tweaks imo

docs/self-managed/identity/orchestration-identity/configuration.md

docs/self-managed/identity/what-is-identity.md

docs/self-managed/identity/orchestration-identity/installation.md

Ben-Sheppard

I've left some comments but I'm going to approve early because I'm of the opinion that we should keep making progress and refine as we go and you've answered the points I made :D

docs/self-managed/identity/orchestration-identity/configuration.md

Ben-Sheppard · 2025-03-06T15:32:19Z

docs/self-managed/identity/orchestration-identity/installation.md

-For example, to enable basic authentication and create an initial user, the following is required:
+### Configure an initial user
+
+The initial user created by the application will be assigned the `admin` role, and can be used for authentication to the web applications and additional role management.


🔧 I'm not sure if it should be noted here or not but the admin role is assigned to all users who are set in the camunda.security.initialization.users list, long term we'd want to refine that IMO but for now thats the functionality

Ben-Sheppard · 2025-03-06T15:33:22Z

docs/self-managed/identity/orchestration-identity/installation.md

+</Tabs>
+
+:::note
+To enable authorizations, API protection must also be enabled.


👍🏻 this is a great point to note down, in the future we will look to make the application more defensive during start up but its super important to note this otherwise you can get into a broken state :)

Ben-Sheppard · 2025-03-06T15:38:18Z

docs/self-managed/identity/what-is-identity.md

@@ -5,7 +5,7 @@ sidebar_label: "What is Identity?"
 description: "Identity is the component within the Camunda 8 stack responsible for authentication and authorization."
 ---

-Identity is the component within the Camunda 8 stack responsible for authentication and authorization. Identity functions differently in Orchestration clusters and in Console and Web Modeler. 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).
+Identity is responsible for authentication and authorization within the Camunda 8 stack. Identity functions differently in Orchestration clusters and in Console and Web Modeler. 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).


💭 I'm still wondering if this is the right wording but I don't feel strongly enough that we should block the merging. Identity is responsible really for authorization and for managing the assignments to different entities i.e. groups.

The authentication is handled via Spring in the basic setup or via Spring + the provider in cases of OIDC, we do have a new authentication layer/module but its not really exposed.

megglos

Great start on finally documenting the new configuration properties and guidance on relevant config scenarios!

I'm requesting changes mainly for:

clarification of default values - as they depend on the distribution
the installation page being c8run specific while not stating that clearly enough

megglos · 2025-03-06T15:11:56Z

docs/self-managed/identity/orchestration-identity/configuration.md

+import TabItem from '@theme/TabItem';
+
+:::note
+As a Spring Boot application, Identity supports any standard


🔧 effectively Identity is part of the Camunda 8 application, I would thus keep this statement general with regards to Camunda 8 as spring boot application.

Suggested change

As a Spring Boot application, Identity supports any standard

As a Spring Boot application, Camunda 8 supports any standard

megglos · 2025-03-06T15:16:22Z

docs/self-managed/identity/orchestration-identity/configuration.md

+[Spring configuration](https://docs.spring.io/spring-boot/reference/features/external-config.html) method.
+:::
+
+The following variables apply globally to all components within the Camunda Orchestration core: Zeebe, Operate, and Tasklist.


🔧 the config applies also to identity itself too,

Suggested change

The following variables apply globally to all components within the Camunda Orchestration core: Zeebe, Operate, and Tasklist.

The following variables apply globally to all components within the Camunda Orchestration core: Zeebe, Operate, Tasklist and Identity.

megglos · 2025-03-06T15:24:12Z

docs/self-managed/identity/orchestration-identity/installation.md

+2. API authentication disabled
+3. Authorizations disabled


❌ this is only true for c8run, for helm we default to a secured setup and both are enabled, as the into mentions both distributions, let's label this guide as c8run specific?

megglos · 2025-03-06T15:27:05Z

docs/self-managed/identity/orchestration-identity/configuration.md

+The following variables apply globally to all components within the Camunda Orchestration core: Zeebe, Operate, and Tasklist.
+
+<!-- updates must be made to BOTH tables -->
+<Tabs>


❓ what is the default config we want to refer to here? Because this differs by distribution, whether it's c8run or helm, based on the second tab it seems helm? I can then provide the actual defaults next. Some like SPRING_PROFILES_ACTIVE are also not relevant then as the user can't control them.

I see in installation we refer to this as reference from a c8run perspective, I woudl thus suggest to have tabs by distribution c8run and helm. I would omit the ENV variable tab and instead extend the spring boot note by the fact that all properties can be provided as environment variables too, like we do in other places of the docs like here https://docs.camunda.io/docs/next/self-managed/zeebe-deployment/configuration/environment-variables/#environment-variables-for-configuration

Ideally I think this guide should reflect Helm (and other production-ready distributions when ready) and not C8Run at all, as C8Run is unique, not for production, and its configuration requirements are largely handled on its own page. I assume that other production-ready distributions, when available, would reflect the same defaults as Helm?

We've historically had difficulty with users converting from Helm config to environment variables, and the docs team has discussed listing them out separately as we can - @akeller do you have any input here? My thinking was to start having this available for Docker and other distributions down the line, to prevent our docs from being as Helm-biased a they are now.

(Edit: Recognizing that Helm isn't ready for prod, either - but it will be!)

My current understanding is C8Run is for onboarding and non-production use cases to get up and running as quickly as possible (and maybe even, ideally, with no configuration?). Since we prioritize the Java Spring dev during onboarding, leading with the Spring configuration makes sense.

Once we start talking about production distributions, things are a bit unclear to me - what's our happy path or recommendation when it comes to config? Default config feels like a PM decision and I would defer to @FarkasRabai and/or @theburi.

I do think we need to be super explicit about Helm config vs. environment variables vs. properties and not expect our users to do the mapping themselves and add _ or . appropriately. We can't just say "follow this pattern" and document the configuration fully in only one way.

🤞 hope this helps. LMK if there if anything else I can clarify.

megglos · 2025-03-06T15:37:00Z

docs/self-managed/identity/orchestration-identity/installation.md

+4. An initial user with the username/password `demo`/`demo`
+5. An `admin` role with read, create, update, and delete permissions for other roles, which is applied to the initial `demo` user
+
+To make changes to the initial configuration, add the desired values via your `application.yaml` or environment variables according to the available [configuration properties](./configuration.md).


❌ you would need to use the --config flag of c8run to make use of an own config, see https://github.com/camunda/camunda-docs/pull/5145/files#diff-5f8b726fad04379e6db620802a56d8916fd1fb90956429487f4b16d80b88afcfR133

megglos · 2025-03-06T15:37:33Z

docs/self-managed/identity/orchestration-identity/installation.md

+
+## Initial configuration
+
+Following the default installation will result in a cluster with the following:


❓ what is the default installation, reading further it seems c8run?

megglos · 2025-03-06T15:38:28Z

docs/self-managed/identity/orchestration-identity/installation.md

+  </TabItem>
+<TabItem value="env" label="Environment variables" default>
+
+```shell
+CAMUNDA_SECURITY_INITIALIZATION_USERS[0]_USERNAME=<Your chosen username>
+CAMUNDA_SECURITY_INITIALIZATION_USERS[0]_PASSWORD=<Your chosen password>
+CAMUNDA_SECURITY_INITIALIZATION_USERS[0]_NAME=<The name of the first user>
+CAMUNDA_SECURITY_INITIALIZATION_USERS[0]_EMAIL=<The email address of the first user>
+```
+
+  </TabItem>


🔧 similar to the configuration page, I would not duplicate config for env var setups, given this conversion is a spring boot feature we can refer to generally.

megglos · 2025-03-06T15:40:06Z

docs/self-managed/identity/orchestration-identity/installation.md

+  </TabItem>
+</Tabs>
+
+### Enable API authentication and authorizations


🔧 this duplicates pending changes by #5145 shall we link from one to the other instead?

Would this differ at all if we look at this guide from a Helm default perspective? Otherwise the C8Run guide can point here, but that can be updated separately.

megglos · 2025-03-06T15:46:17Z

docs/self-managed/identity/what-is-identity.md

@@ -5,7 +5,17 @@ sidebar_label: "What is Identity?"
 description: "Identity is the component within the Camunda 8 stack responsible for authentication and authorization."
 ---

-Identity is the component within the Camunda 8 stack responsible for authentication and authorization. It allows you to manage:
+Identity is responsible for authentication and authorization within the Camunda 8 stack. Identity functions differently in Orchestration clusters and in Console and Web Modeler. 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).


🔧 we should indicate these are different identity components indeed

Suggested change

Identity is responsible for authentication and authorization within the Camunda 8 stack. Identity functions differently in Orchestration clusters and in Console and Web Modeler. 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).

Identity components are responsible for authentication and authorization within the Camunda 8 stack. There are two different identity components in the stack, one as an integral part of the Orchestration cluster and spanning across orchestration clusters used for Console and Web Modeler access management. 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).

I've tried to clarify this further in the latest update! Once there is a place in the docs for Orchestration cluster docs vs Everything else docs, this page will mostly be able to go away, and I hope this distinction will feel much more separate.

conceptualshark · 2025-03-06T18:29:41Z

@megglos @Ben-Sheppard I've incorporated the last round of feedback, but would like guidance on:

Can this be made Helm specific, or should we leave it as-is until we get PM feedback (and I will note this is cor C8Run)
The different defaults for Helm
How that changes what we document here in support of https://github.com/camunda/documentation-team/issues/465

For the second and third points, I think it means the API is protected and authorizations are enabled by default.

Is there a reason to keep the "Enable API" section, or should it just be swapped to an example for disabling it?

github-actions · 2025-03-06T18:40:39Z

The preview environment relating to the commit 9f6e98a has successfully been deployed. You can access it at https://preview.docs.camunda.cloud/pr-5133/index.html

initial draft of identity docs

80d451d

github-actions bot assigned conceptualshark Mar 3, 2025

conceptualshark added 8.8.0-alpha2 component:docs Documentation improvements, including new or updated content component:self-managed Docs and issues related to Camunda Platform 8 Self-Managed deploy Stand up a temporary docs site with this PR labels Mar 3, 2025

conceptualshark requested a review from Ben-Sheppard March 3, 2025 20:33

github-actions bot temporarily deployed to camunda-docs March 3, 2025 20:39 Destroyed

Ben-Sheppard reviewed Mar 4, 2025

View reviewed changes

docs/self-managed/identity/orchestration-identity/installation.md Show resolved Hide resolved

akeller requested a review from FarkasRabai March 5, 2025 14:04

This was referenced Mar 5, 2025

Add note of temporary Helm chart alpha limitations #5153

Merged

Evaluate SM Components sections for 8.8+/unified architecture #5156

Open

conceptualshark added 2 commits March 5, 2025 14:55

add initial configuration options and basic guide

932e803

Fix brackets

83aa024

conceptualshark requested a review from megglos March 5, 2025 19:59

conceptualshark commented Mar 5, 2025

View reviewed changes

github-actions bot temporarily deployed to camunda-docs March 5, 2025 20:06 Destroyed

akeller reviewed Mar 5, 2025

View reviewed changes

docs/self-managed/identity/orchestration-identity/configuration.md Outdated Show resolved Hide resolved

akeller reviewed Mar 5, 2025

View reviewed changes

docs/self-managed/identity/what-is-identity.md Outdated Show resolved Hide resolved

Ben-Sheppard reviewed Mar 6, 2025

View reviewed changes

docs/self-managed/identity/orchestration-identity/installation.md Outdated Show resolved Hide resolved

update PR feedback

8e5a315

conceptualshark requested review from Ben-Sheppard and akeller March 6, 2025 14:53

conceptualshark marked this pull request as ready for review March 6, 2025 14:54

github-actions bot temporarily deployed to camunda-docs March 6, 2025 15:00 Destroyed

Ben-Sheppard previously approved these changes Mar 6, 2025

View reviewed changes

megglos requested changes Mar 6, 2025

View reviewed changes

add pr feedback

41100be

conceptualshark dismissed Ben-Sheppard’s stale review via 41100be March 6, 2025 18:22

comsole typo that's new

c1ae591

github-actions bot temporarily deployed to camunda-docs March 6, 2025 18:33 Destroyed

conceptualshark requested review from megglos and Ben-Sheppard March 7, 2025 12:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Initial draft of identity docs #5133

Initial draft of identity docs #5133

conceptualshark commented Mar 3, 2025 •

edited

Loading

github-actions bot commented Mar 3, 2025

Ben-Sheppard Mar 4, 2025

conceptualshark Mar 5, 2025

megglos Mar 6, 2025

Ben-Sheppard Mar 4, 2025

conceptualshark Mar 5, 2025

akeller commented Mar 5, 2025

conceptualshark left a comment

akeller Mar 5, 2025

megglos Mar 6, 2025

RomanJRW Mar 6, 2025

Ben-Sheppard left a comment

Ben-Sheppard Mar 6, 2025

Ben-Sheppard Mar 6, 2025

Ben-Sheppard Mar 6, 2025

megglos left a comment

megglos Mar 6, 2025

megglos Mar 6, 2025

megglos Mar 6, 2025

megglos Mar 6, 2025

megglos Mar 6, 2025

conceptualshark Mar 6, 2025 •

edited

Loading

akeller Mar 6, 2025

megglos Mar 6, 2025

megglos Mar 6, 2025

megglos Mar 6, 2025

megglos Mar 6, 2025

conceptualshark Mar 6, 2025

megglos Mar 6, 2025

conceptualshark Mar 6, 2025

conceptualshark commented Mar 6, 2025 •

edited

Loading

github-actions bot commented Mar 6, 2025

	As a Spring Boot application, Identity supports any standard
	As a Spring Boot application, Camunda 8 supports any standard

	The following variables apply globally to all components within the Camunda Orchestration core: Zeebe, Operate, and Tasklist.
	The following variables apply globally to all components within the Camunda Orchestration core: Zeebe, Operate, Tasklist and Identity.


		## Initial configuration

		Following the default installation will result in a cluster with the following:

Initial draft of identity docs #5133

Are you sure you want to change the base?

Initial draft of identity docs #5133

Conversation

conceptualshark commented Mar 3, 2025 • edited Loading

Description

When should this change go live?

PR Checklist

github-actions bot commented Mar 3, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

akeller commented Mar 5, 2025

conceptualshark left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Ben-Sheppard left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

megglos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

conceptualshark Mar 6, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

conceptualshark commented Mar 6, 2025 • edited Loading

github-actions bot commented Mar 6, 2025

conceptualshark commented Mar 3, 2025 •

edited

Loading

conceptualshark Mar 6, 2025 •

edited

Loading

conceptualshark commented Mar 6, 2025 •

edited

Loading