identity and modeler sm review (#3136)

* identity and modeler sm review

* remove comment

* adjust note

* remove comments

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_<COMPONENT>_ROOT_URL` variab
 For the `KEYCLOAK_INIT_<COMPONENT>_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:
 

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                                                                                               |
 | ---------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- |

docs/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md

@@ -13,15 +13,15 @@ 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
 - The client ID of your application
 - 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.

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:

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.

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)

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_<COMPONENT>_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:
 

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                                                                                               |
 | ---------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- |

versioned_docs/version-8.3/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md

@@ -13,15 +13,15 @@ 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
 - The client ID of your application
 - 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.

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:

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.