From db978e1bc57f8b0e7d4522b3977fd8a2ccc4eab2 Mon Sep 17 00:00:00 2001 From: christinaausley <84338309+christinaausley@users.noreply.github.com> Date: Fri, 19 Jan 2024 14:59:07 -0500 Subject: [PATCH] identity and modeler sm review (#3136) * identity and modeler sm review * remove comment * adjust note * remove comments --- .../deployment/configuration-variables.md | 12 ++++++------ .../deployment/starting-configuration.md | 8 ++++---- .../authorizations/generating-m2m-tokens.md | 4 ++-- .../managing-resource-authorizations.md | 2 +- .../connect-to-an-existing-keycloak.md | 10 +++++++--- docs/self-managed/identity/what-is-identity.md | 16 ++++++++++++---- .../deployment/configuration-variables.md | 8 ++++---- .../deployment/starting-configuration.md | 8 ++++---- .../authorizations/generating-m2m-tokens.md | 4 ++-- .../managing-resource-authorizations.md | 2 +- .../connect-to-an-existing-keycloak.md | 6 +++--- 11 files changed, 46 insertions(+), 34 deletions(-) diff --git a/docs/self-managed/identity/deployment/configuration-variables.md b/docs/self-managed/identity/deployment/configuration-variables.md index 70e9fa4b342..d5ff8969656 100644 --- a/docs/self-managed/identity/deployment/configuration-variables.md +++ b/docs/self-managed/identity/deployment/configuration-variables.md @@ -9,7 +9,7 @@ As Identity is a Spring Boot application, you may use the standard Spring [configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config) methods. -### Core configuration +## Core configuration | Environment variable | Description | Default value | | ------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -28,7 +28,7 @@ methods. | `KEYCLOAK_SETUP_CLIENT_ID` | The client to use for authentication during setup of the provided Keycloak. | admin-cli | | `KEYCLOAK_URL` | The URL of the Keycloak instance to use. | http://localhost:18080/auth | -### Component configuration +## Component configuration Identity supports component configuration using preset values. To configure a component for use within Identity, set two variables: @@ -48,7 +48,7 @@ For the `WEBMODELER` value, only the `KEYCLOAK_INIT__ROOT_URL` variab For the `KEYCLOAK_INIT__CLIENT_ID` value, the default is the component name in lowercase except for `WEBMODELER`, which is`web-modeler`. ::: -### Database configuration +## Database configuration Identity requires a database to store information about [resource authorization](/self-managed/concepts/access-control/resource-authorizations.md) and [multi-tenancy](/self-managed/concepts/multi-tenancy.md). @@ -66,7 +66,7 @@ There are no default values for the variables above. See supported databases. ::: -#### Running Identity on Amazon Aurora PostgreSQL +### Running Identity on Amazon Aurora PostgreSQL Identity supports running on Amazon Aurora PostgreSQL. To connect Identity with your Amazon Aurora PostgreSQL instance, make the following configuration adjustments: @@ -76,7 +76,7 @@ To connect Identity with your Amazon Aurora PostgreSQL instance, make the follow For a full list of available driver parameters visit the [AWS JDBC Driver documentation](https://github.com/awslabs/aws-advanced-jdbc-wrapper/wiki/UsingTheJdbcDriver#aws-advanced-jdbc-driver-parameters). -##### AWS IAM authentication +#### AWS IAM authentication To use AWS Identity and Access Management (IAM) database authentication with your Amazon Aurora PostgreSQL instance, in addition to the adjustments described [above](#running-identity-on-amazon-aurora-postgresql), follow these steps: @@ -85,7 +85,7 @@ instance, in addition to the adjustments described [above](#running-identity-on- 2. Modify the `SPRING_DATASOURCE_USERNAME` environment variable to match the database user you configured for AWS IAM authentication as described in the [Amazon Aurora documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html#UsingWithRDS.IAMDBAuth.DBAccounts.PostgreSQL). 3. Remove the `SPRING_DATASOURCE_PASSWORD` environment variable. -### Feature flags +## Feature flags Identity uses feature flag environment variables to enable and disable features; the supported flags are: diff --git a/docs/self-managed/identity/deployment/starting-configuration.md b/docs/self-managed/identity/deployment/starting-configuration.md index d6b8649eb13..84a565c00c0 100644 --- a/docs/self-managed/identity/deployment/starting-configuration.md +++ b/docs/self-managed/identity/deployment/starting-configuration.md @@ -8,7 +8,7 @@ description: "Understand the set of base configurations to operate Identity corr Identity requires a set of base configurations to operate correctly. When Identity is started, it will create or update the following entities in Keycloak: -### Clients +## Clients | Name | Client ID | Service accounts | Created/updated with component | | -------------------------------- | -------------------------------- | ---------------- | ------------------------------ | @@ -23,7 +23,7 @@ create or update the following entities in Keycloak: | Web Modeler | web-modeler | disabled | Web Modeler | | Web Modeler API | web-modeler-api | enabled | Web Modeler | -### Roles +## Roles | Name | Created/updated with component | | ----------- | ------------------------------ | @@ -33,13 +33,13 @@ create or update the following entities in Keycloak: | Tasklist | Tasklist | | Web Modeler | Web Modeler | -### Client scopes +## Client scopes | Name | Protocol | Description | | ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | camunda-identity | openid-connect | A default client scope that contains mappers to augment the token generated with information required by the components of Camunda. Contains the mappers described in the [mappers](#mappers) section. | -### Mappers +## Mappers | Name | Protocol Mapper | Description | | ---------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- | diff --git a/docs/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md b/docs/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md index 69ddf2b67ae..0aaf83e0b77 100644 --- a/docs/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md +++ b/docs/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md @@ -13,7 +13,7 @@ the need for user intervention. In this guide, we'll show you how to generate your own **machine-to-machine (M2M)** tokens. -### Prerequisites +## Prerequisites - A running [Identity](/self-managed/identity/what-is-identity.md) service - An [application](/self-managed/concepts/access-control/applications.md) for your service @@ -21,7 +21,7 @@ In this guide, we'll show you how to generate your own **machine-to-machine (M2M - The client secret of your application - A REST client of your choice -### Generate token +## Generate token In our example, the Keycloak instance that supports Identity can be found via `http://localhost:18080`. This may be different for you, so adjust the host name (and port if required) as appropriate. diff --git a/docs/self-managed/identity/user-guide/authorizations/managing-resource-authorizations.md b/docs/self-managed/identity/user-guide/authorizations/managing-resource-authorizations.md index d1260e8a6fa..abd35a4738c 100644 --- a/docs/self-managed/identity/user-guide/authorizations/managing-resource-authorizations.md +++ b/docs/self-managed/identity/user-guide/authorizations/managing-resource-authorizations.md @@ -10,7 +10,7 @@ import TabItem from "@theme/TabItem"; In this guide you will learn about the methods to control resource access within the Identity application. -### Creating resource authorizations +## Creating resource authorizations Resource authorizations can be configured for an individual user or a group. Below we show you how to create authorizations for both: diff --git a/docs/self-managed/identity/user-guide/configuration/connect-to-an-existing-keycloak.md b/docs/self-managed/identity/user-guide/configuration/connect-to-an-existing-keycloak.md index dbe8c95860f..a42b24bad01 100644 --- a/docs/self-managed/identity/user-guide/configuration/connect-to-an-existing-keycloak.md +++ b/docs/self-managed/identity/user-guide/configuration/connect-to-an-existing-keycloak.md @@ -7,12 +7,16 @@ description: "Learn how to connect Identity to your existing Keycloak instance." In this guide, we'll demonstrate how to connect Identity to your existing Keycloak instance. -### Prerequisites +## Prerequisites - Access to your [Keycloak Admin Console](https://www.keycloak.org/docs/22.0.1/server_admin/#using-the-admin-console) - A basic understanding of [administering realms and clients](https://www.keycloak.org/docs/22.0.1/server_admin/#assembly-managing-clients_server_administration_guide) in Keycloak. -### Steps +:::note +Clients in Camunda 8 SaaS and applications in Camunda 8 Self-Managed provide a similar purpose. One key difference is that for Camunda 8 SaaS, you can set up specific [client connection credentials](/docs/guides/setup-client-connection-credentials.md), whereas in Identity, an application is created with credentials automatically assigned. +::: + +## Steps To connect Identity to an existing Keycloak instance, take the following steps: @@ -50,7 +54,7 @@ To connect Identity to an existing Keycloak instance, take the following steps: Identity creates a base set of configurations required to function successfully. To understand more about what is created and why, see [the starting configuration](/docs/self-managed/identity/deployment/starting-configuration.md). ::: -### Considerations +## Considerations When connecting Identity to a shared realm, accurately determining what clients should and should not be displayed in the Identity UI is not possible. Therefore, the clients in the realm you connect Identity to will be shown in the Identity UI and can have their secrets viewed and updated. Users with access to Identity should be considered as having administrator-level access to the system. diff --git a/docs/self-managed/identity/what-is-identity.md b/docs/self-managed/identity/what-is-identity.md index f6a6730afbc..4c844ca9c8e 100644 --- a/docs/self-managed/identity/what-is-identity.md +++ b/docs/self-managed/identity/what-is-identity.md @@ -12,11 +12,19 @@ Identity is the component within the Camunda 8 stack responsible for authenticat - Permissions - Roles -You can use Identity for authentication with Keycloak. The following guidance can be used during platform installation and deployment: +For example, using Identity you can: -- [Use existing Keycloak](/self-managed/platform-deployment/helm-kubernetes/guides/using-existing-keycloak.md) -- [Connect to an OIDC provider](/self-managed/platform-deployment/helm-kubernetes/guides/connect-to-an-oidc-provider.md) +- [Add and assign a role to a user](/self-managed/identity/user-guide/roles/add-assign-role.md), which is a way to group sets of permissions which can be assigned to users using the Identity UI. +- [Add and assign a permission to a role](/self-managed/identity/user-guide/roles/add-assign-permission.md) to control the level of access a user or an application has to a particular component. +- [Create a group](/self-managed/identity/user-guide/groups/create-group.md) to apply a set of roles and authorizations to users. +- [Manage resource authorizations](/self-managed/identity/user-guide/authorizations/managing-resource-authorizations.md) to control resource access within the Identity application. +- [Utilize configuration variables](/self-managed/identity/deployment/configuration-variables.md). -### Next steps +## Next steps If you're new to Identity, we suggest reviewing our [getting started guide](./getting-started/install-identity.md). + +You can use Identity for authentication with Keycloak. The following guidance can be used during platform installation and deployment: + +- [Use existing Keycloak](/self-managed/platform-deployment/helm-kubernetes/guides/using-existing-keycloak.md) +- [Connect to an OIDC provider](/self-managed/platform-deployment/helm-kubernetes/guides/connect-to-an-oidc-provider.md) diff --git a/versioned_docs/version-8.3/self-managed/identity/deployment/configuration-variables.md b/versioned_docs/version-8.3/self-managed/identity/deployment/configuration-variables.md index 27577a38a99..85015e58765 100644 --- a/versioned_docs/version-8.3/self-managed/identity/deployment/configuration-variables.md +++ b/versioned_docs/version-8.3/self-managed/identity/deployment/configuration-variables.md @@ -9,7 +9,7 @@ As Identity is a Spring Boot application, you may use the standard Spring [configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config) methods. -### Core configuration +## Core configuration | Environment variable | Description | Default value | | ------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -28,7 +28,7 @@ methods. | `KEYCLOAK_SETUP_CLIENT_ID` | The client to use for authentication during setup of the provided Keycloak. | admin-cli | | `KEYCLOAK_URL` | The URL of the Keycloak instance to use. | http://localhost:18080/auth | -### Component configuration +## Component configuration Identity supports component configuration using preset values. To configure a component for use within Identity, set two variables: @@ -45,7 +45,7 @@ and `WEBMODELER`. For the `WEBMODELER` value, only the `KEYCLOAK_INIT__ROOT_URL` variable is required to be set. ::: -### Database configuration +## Database configuration Identity requires a database to store information about [resource authorization](/self-managed/concepts/access-control/resource-authorizations.md) and [multi-tenancy](/self-managed/concepts/multi-tenancy.md). @@ -63,7 +63,7 @@ There are no default values for the variables above. See supported databases. ::: -### Feature flags +## Feature flags Identity uses feature flag environment variables to enable and disable features; the supported flags are: diff --git a/versioned_docs/version-8.3/self-managed/identity/deployment/starting-configuration.md b/versioned_docs/version-8.3/self-managed/identity/deployment/starting-configuration.md index d6b8649eb13..84a565c00c0 100644 --- a/versioned_docs/version-8.3/self-managed/identity/deployment/starting-configuration.md +++ b/versioned_docs/version-8.3/self-managed/identity/deployment/starting-configuration.md @@ -8,7 +8,7 @@ description: "Understand the set of base configurations to operate Identity corr Identity requires a set of base configurations to operate correctly. When Identity is started, it will create or update the following entities in Keycloak: -### Clients +## Clients | Name | Client ID | Service accounts | Created/updated with component | | -------------------------------- | -------------------------------- | ---------------- | ------------------------------ | @@ -23,7 +23,7 @@ create or update the following entities in Keycloak: | Web Modeler | web-modeler | disabled | Web Modeler | | Web Modeler API | web-modeler-api | enabled | Web Modeler | -### Roles +## Roles | Name | Created/updated with component | | ----------- | ------------------------------ | @@ -33,13 +33,13 @@ create or update the following entities in Keycloak: | Tasklist | Tasklist | | Web Modeler | Web Modeler | -### Client scopes +## Client scopes | Name | Protocol | Description | | ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | camunda-identity | openid-connect | A default client scope that contains mappers to augment the token generated with information required by the components of Camunda. Contains the mappers described in the [mappers](#mappers) section. | -### Mappers +## Mappers | Name | Protocol Mapper | Description | | ---------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- | diff --git a/versioned_docs/version-8.3/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md b/versioned_docs/version-8.3/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md index 69ddf2b67ae..0aaf83e0b77 100644 --- a/versioned_docs/version-8.3/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md +++ b/versioned_docs/version-8.3/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md @@ -13,7 +13,7 @@ the need for user intervention. In this guide, we'll show you how to generate your own **machine-to-machine (M2M)** tokens. -### Prerequisites +## Prerequisites - A running [Identity](/self-managed/identity/what-is-identity.md) service - An [application](/self-managed/concepts/access-control/applications.md) for your service @@ -21,7 +21,7 @@ In this guide, we'll show you how to generate your own **machine-to-machine (M2M - The client secret of your application - A REST client of your choice -### Generate token +## Generate token In our example, the Keycloak instance that supports Identity can be found via `http://localhost:18080`. This may be different for you, so adjust the host name (and port if required) as appropriate. diff --git a/versioned_docs/version-8.3/self-managed/identity/user-guide/authorizations/managing-resource-authorizations.md b/versioned_docs/version-8.3/self-managed/identity/user-guide/authorizations/managing-resource-authorizations.md index 8f7dbd9e365..bd68900ec11 100644 --- a/versioned_docs/version-8.3/self-managed/identity/user-guide/authorizations/managing-resource-authorizations.md +++ b/versioned_docs/version-8.3/self-managed/identity/user-guide/authorizations/managing-resource-authorizations.md @@ -10,7 +10,7 @@ import TabItem from "@theme/TabItem"; In this guide you will learn about the methods to control resource access within the Identity application. -### Creating resource authorizations +## Creating resource authorizations Resource authorizations can be configured for an individual user or a group. Below we show you how to create authorizations for both: diff --git a/versioned_docs/version-8.3/self-managed/identity/user-guide/configuration/connect-to-an-existing-keycloak.md b/versioned_docs/version-8.3/self-managed/identity/user-guide/configuration/connect-to-an-existing-keycloak.md index dbe8c95860f..a7ea08ab9fb 100644 --- a/versioned_docs/version-8.3/self-managed/identity/user-guide/configuration/connect-to-an-existing-keycloak.md +++ b/versioned_docs/version-8.3/self-managed/identity/user-guide/configuration/connect-to-an-existing-keycloak.md @@ -7,12 +7,12 @@ description: "Learn how to connect Identity to your existing Keycloak instance." In this guide, we'll demonstrate how to connect Identity to your existing Keycloak instance. -### Prerequisites +## Prerequisites - Access to your [Keycloak Admin Console](https://www.keycloak.org/docs/22.0.1/server_admin/#using-the-admin-console) - A basic understanding of [administering realms and clients](https://www.keycloak.org/docs/22.0.1/server_admin/#assembly-managing-clients_server_administration_guide) in Keycloak. -### Steps +## Steps To connect Identity to an existing Keycloak instance, take the following steps: @@ -50,7 +50,7 @@ To connect Identity to an existing Keycloak instance, take the following steps: Identity creates a base set of configurations required to function successfully. To understand more about what is created and why, see [the starting configuration](/docs/self-managed/identity/deployment/starting-configuration.md). ::: -### Considerations +## Considerations When connecting Identity to a shared realm, accurately determining what clients should and should not be displayed in the Identity UI is not possible. Therefore, the clients in the realm you connect Identity to will be shown in the Identity UI and can have their secrets viewed and updated. Users with access to Identity should be considered as having administrator-level access to the system.