Overhaul identity docs

docs/self-managed/concepts/access-control/apis.md

@@ -9,3 +9,5 @@ access via permissions.
 
 In [Identity](/self-managed/identity/what-is-identity.md), we use APIs to attach [Permissions](/self-managed/concepts/access-control/resource-authorizations.md). Once they have been created, the
 components in the Camunda 8 stack are able to allow or deny users certain functionality.
+
+<!-- Do we have a more concrete example of what an API is? -->

docs/self-managed/concepts/access-control/applications.md

@@ -19,9 +19,13 @@ See our documentation on [adding an application](/self-managed/identity/user-gui
 There are three types of applications in Identity:
 
 - Confidential
-- Machine-to-machine
+- Machine-to-machine (M2M)
 - Public
 
+Public and confidential applications are applications where a user can log in, like a custom Tasklist.
+
+An M2M application is an application that does not have a UI, like a service worker.
+
 A type is selected when [creating the application](/self-managed/identity/user-guide/additional-features/incorporate-applications.md) based on
 its ability to securely store and use secrets, as well as the mode of authentication it uses.
 

docs/self-managed/identity/getting-started/install-identity.md

@@ -1,18 +1,20 @@
 ---
 id: install-identity
-title: "Installation and first steps"
-sidebar_label: "Installation and first steps"
-description: "Learn more about installing Identity, accessing the UI, default users, the home screen, and more."
+title: "First steps"
+sidebar_label: "First steps"
+description: "Learn more about accessing the Identity UI, default users, the home screen, and more."
 ---
 
-To use Identity, install it locally via Docker or Kubernetes.
+Before you can work with Identity, you need to install it along with other Camunda 8 components.
 
 Follow the [installation guide](/self-managed/platform-deployment/overview.md) for more details on this process.
 
 ## Accessing the UI
 
 As soon as Identity is started, you can access the login page and log in to the Identity application.
 
+<!-- Let's move away from recommending localhost first. What port or URL would they find Identity if they used Helm Kubernetes? -->
+
 Navigate to [localhost:8080](http://localhost:8080) to see the UI exposed by Identity.
 
 ![identity-login-page](./img/identity-login-page.png)
@@ -21,6 +23,9 @@ Navigate to [localhost:8080](http://localhost:8080) to see the UI exposed by Ide
 
 The configuration in this guide creates an example user during installation; use this account to log in:
 
+<!-- Is this true for any setup? -->
+<!-- For setting up production systems, we should nudge users to remove this configuration prior to launching. -->
+
 ```text
 Username: demo
 Password: demo
@@ -35,4 +40,8 @@ Creating a user in Identity is not currently supported. To create a user, see
 
 You are directed to the home page once logged in successfully.
 
+<!-- What should they expect to see on this page? A list of all their applications, including the Identity application? -->
+
+<!-- This should be the name associated with demo demo or aligned with other screenshot users. -->
+
 ![identity-landing-page](./img/identity-landing-page.png)

docs/self-managed/identity/user-guide/additional-features/incorporate-applications.md

@@ -5,11 +5,7 @@ sidebar_label: "Incorporate applications"
 description: "Use Identity to create an application and assign a permission to an application."
 ---
 
-In this guide we will show you how to use Identity to create an application and assign a permission to an application.
-
-:::tip Want to learn more about applications?
-Head over to our documentation on [applications](/self-managed/concepts/access-control/applications.md) to find out more.
-:::
+In this guide we will show you how to use Identity to create an [applications](/self-managed/concepts/access-control/applications.md) and assign a permission to an application.
 
 :::caution Write access needed
 To add an application and assign a permission to an application, you need to have write access to Identity.

docs/self-managed/identity/user-guide/authorizations/managing-resource-authorizations.md

@@ -15,11 +15,15 @@ In this guide you will learn about the methods to control resource access within
 Resource authorizations can be configured for an individual user or a group. Below we show you how to create authorizations
 for both:
 
+<!-- Why would I choose configuring for an individual user vs. a group? Do we have a recommendation to use groups for larger organizations? Let's offer some opinionated recommendations here. -->
+
 <Tabs groupId="entityType" defaultValue="groups" values={[{label: 'Groups', value: 'groups', }, {label: 'Users', value: 'users', },]} >
 <TabItem value="groups">
 
 1. Log in to the Identity UI and navigate to the **Groups** tab. Select the group you would like to create an authorization for from the table, and click on the **Authorizations** tab:
 
+<!-- This needs to be a business-oriented example. Can we name this group something like "business analysts"? What kind of role would have read + delete process definition access? -->
+
 ![create-authorization-for-group-tab](../img/create-authorization-for-group-tab.png)
 
 2. Click **Create resource authorization** and a modal will open. Select the type of resource you are creating an authorization for, and click **Next**:
@@ -47,6 +51,8 @@ On confirmation, the modal closes, the table updates, and your authorization is
 </TabItem>
 <TabItem value="users">
 
+<!-- This is unclear to me based on the screenshots. Where do I select the user? Where do users come from? -->
+
 1. Log in to the Identity UI and navigate to the **Users** tab. Select the user you would like to create an authorization for from the table, and click on the **Authorizations** tab:
 
 ![create-authorization-for-user-tab](../img/create-authorization-for-user-tab.png)

docs/self-managed/identity/user-guide/configuration/configure-external-identity-provider.md

@@ -12,7 +12,10 @@ identity provider directly in Keycloak Administrator Console.
 
 To configure an external identity provider like OpenID Connect, SAML, LDAP, or Active Directory, take the following steps:
 
+<!-- We could consider using tabs here if we want to document both the Docker Compose and Helm Kubernetes experiences. Having them both in line is a bit confusing. Let's prioritize Helm Kubernetes and show that path first or preferentially. -->
+
 1. Log in to the Keycloak Administrator Console. Open the URL you have configured for Keycloak in your browser.
+   <!-- Where would you find Keycloak in a Helm Kubernetes setup? -->
    :::tip
    When using the example
    [Docker Compose](/self-managed/platform-deployment/docker.md#docker-compose) setup, Keycloak

docs/self-managed/identity/user-guide/configuration/configure-logging.md

@@ -8,6 +8,8 @@ description: "Learn how to configure logging in Identity."
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
+<!-- Why would anyone want to enable logging? What level should be configured for dev/test/prod systems? Do we have any recommendations? -->
+
 ## Configuring logging
 
 The Identity component uses the [Log4j2](https://logging.apache.org/log4j/2.x/) framework to control

docs/self-managed/identity/user-guide/configuration/making-identity-production-ready.md

@@ -7,6 +7,9 @@ description: "Consider the following topics when moving Identity into a producti
 
 We recommend considering the following topics when moving Identity into a production environment.
 
+<!-- Any recommendations about logging? -->
+<!-- Remove demo demo user? -->
+
 ## Keycloak dependency
 
 As Keycloak is an external-based dependency of Identity, we recommend looking at

docs/self-managed/identity/user-guide/tenants/managing-tenants.md

@@ -8,7 +8,7 @@ description: "Manage tenants within Identity to support the logical separation o
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-In this guide you will learn how to manage tenants in Identity and how to control the members who have access to them.
+In this guide you will learn how to manage [tenants](/self-managed/concepts/multi-tenancy.md) in Identity and how to control the members who have access to them.
 
 ## Managing tenants
 

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

@@ -5,16 +5,14 @@ sidebar_label: "What is Identity?"
 description: "Identity is the component within the Camunda 8 stack responsible for authentication and authorization."
 ---
 
-:::note Looking for IAM documentation?
-From version 8.0.0+ the IAM component has been replaced with the Identity component.
-:::
-
 Identity is the component within the Camunda 8 stack responsible for authentication and authorization. It allows you to manage:
 
-- Applications
-- APIs
-- Permissions
-- Roles
+- [Applications](/self-managed/concepts/access-control/applications.md)
+- [APIs](/self-managed/concepts/access-control/apis.md)
+- [Roles](/self-managed/identity/user-guide/roles/add-assign-role.md)
+- [Permissions](/self-managed/identity/user-guide/roles/add-assign-permission.md)
+
+<!-- Let's intro some of the other sections within the Identity docs here -->
 
 ### Next steps