Initial draft of identity docs #5133
+221
−58
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,9 +1,12 @@ | ||
| --- | ||
| id: installation | ||
conceptualshark marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| title: Initial setup | ||
| description: "Learn how Identity is bundled with your default Orchestration cluster." | ||
| --- | ||
|
|
||
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; | ||
|
|
||
| Identity is included by default with the deployment of any [Orchestration cluster](/self-managed/reference-architecture/reference-architecture.md#orchestration-cluster). Within an Orchestration cluster, Identity provides unified, cluster-level identity management and authorizations. | ||
|
|
||
| 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). | ||
|
|
@@ -16,33 +19,74 @@ Following the default installation will result in a cluster with the following: | |
| 2. API authentication disabled | ||
| 3. Authorizations disabled | ||
| 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). | ||
|
There was a problem hiding this comment. ❌ you would need to use the |
||
|
|
||
| ### 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. | ||
|
There was a problem hiding this comment. 🔧 I'm not sure if it should be noted here or not but the |
||
|
|
||
| To create a unique initial user, the following is required in your `application.yaml` or environment variables: | ||
|
|
||
| <Tabs> | ||
| <TabItem value="helm" label="Helm properties" default> | ||
|
|
||
| ```yaml | ||
| camunda: | ||
| security: | ||
| initialization: | ||
| users: | ||
| - username: <Your chosen username> | ||
| password: <Your chosen password> | ||
| name: <The name of the first user> | ||
| email: <The email address of the first user> | ||
| ``` | ||
|
|
||
| </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> | ||
| </Tabs> | ||
|
|
||
| ### Enable API authentication and authorizations | ||
|
There was a problem hiding this comment. 🔧 this duplicates pending changes by #5145 shall we link from one to the other instead? There was a problem hiding this comment. 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. |
||
|
|
||
| By default, 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: | ||
|
|
||
| <Tabs> | ||
| <TabItem value="helm" label="Helm properties" default> | ||
|
|
||
| ```yaml | ||
| camunda: | ||
| security: | ||
| authentication: | ||
| unprotected-api: false | ||
| authorizations: | ||
| enabled: true | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="env" label="Environment variables" default> | ||
|
|
||
| ```shell | ||
| CAMUNDA_SECURITY_AUTHENTICATION_UNPROTECTED-API=false | ||
| CAMUNDA_SECURITY_AUTHORIZATIONS_ENABLED=true | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| :::note | ||
| To enable authorizations, API protection must also be enabled. | ||
|
There was a problem hiding this comment. 👍🏻 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 :) |
||
| ::: | ||
|
|
||
| Basic authentication credentials are then required when making API requests, as in the following: | ||
|
|
||
| ```shell | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
❓ 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_ACTIVEare also not relevant then as the user can't control them.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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!)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.