Apply comments

site/content/en/docs/enterprise/social-accounts-configuration.md

@@ -106,60 +106,71 @@ There are 2 basic steps to enable GitHub account authentication.
 > but don't forget to add required permissions.
 > <br>In the **Permission** > **Account permissions** > **Email addresses** must be set to **read-only**.
 
-## Enable Authentication with Amazon Cognito
-
-To enable authentication with Amazon Cognito for your CVAT instance, you need to complete two main steps:
-
-1. **Create and configure an [Amazon Cognito user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html)**.
-   Follow these detailed steps to set up the user pool:
-   - Create a user pool. For example, you might use settings like those shown in the image below:
-     ![](/images/cognito_pool_1.png)
-
-   - Configure a new app on the step `Integrate your app`:
-     - Select the `Confidential client` type, as CVAT securely stores
-     client secrets on the server side.
-       (_Note_: the `Public client` type is also supported.)
-     - Enter a name for your app client.
-     - Choose the `Generate a client secret` option.
-       ![](/images/cognito_pool_2.png)
-
-   - Once your pool is configured, go to the `App integration` tab
-   on the pool details page and then to the `Domain` section.
-     Create either a custom domain or Cognito domain (e.g., `https://cvat.auth.us-east-1.amazoncognito.com`).
-     Copy this domain as you'll need it later when configuring the `auth_config.yml` file for CVAT.
-
-   - Scroll down to the `App client list` section, find the app you created, and open its settings.
-     Edit the `Hosted UI` settings:
-     - `Allowed callback URLs`: add a callback URL (`<http|https>://<cvat_domain>/api/auth/social/amazon-cognito/login/callback/`)
-     - `Identity providers`: select `Cognito user pool`
-     - `OAuth 2.0 grant types`: select `Authorization code grant`
-     - `OpenID Connect scopes`: select the following scopes: `OpenID`, `Profile`, `Email`
-       ![](/images/cognito_pool_3.png)
-
-2. **Configure social authentication in CVAT**:
-   - Create the `auth_config.yml` file in CVAT with the following content:
-
-   ```yaml
-   ---
-   social_account:
-     enabled: true
-     amazon_cognito:
-       client_id: <client_id>
-       client_secret: <client_secret>
-       domain: <custom-domain> or
-         https://<custom-cognito-prefix>.auth.us-east-1.amazoncognito.com
-   ```
-   The client_id and client_secret can be found on the app details page,
-   while the domain value can be found on the pool details page.
-
-   - Set the required environment variables:
-
-   ```bash
-   export AUTH_CONFIG_PATH="<path_to_auth_config>"
-   export CVAT_HOST="<cvat_host>"
-   # schema: http|https, CVAT_PORT is optional
-   export CVAT_BASE_URL="<SCHEMA>://${CVAT_HOST}:<CVAT_PORT>"
-   ```
+## Enable authentication with Amazon Cognito
+
+To enable authentication with Amazon Cognito for your CVAT instance, follow these steps:
+
+1. Create an **[Amazon Cognito pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html)**
+   (*Optional*)
+1. Set up a new app client
+1. Configure social authentication in CVAT
+
+Now, let’s dive deeper into how to accomplish these steps.
+
+### Amazon Cognito pool creation
+
+This step is optional and should only be performed if a `user pool` has not already been created.
+To create a user pool, follow these instructions:
+1. Go to the [Amazon console](https://console.aws.amazon.com/console/home)
+1. Locate `Cognito` in the list of services
+1. Click `Create user pool`
+1. Fill in the required fields
+
+### App client creation
+
+To create a new `app client`, follow these steps:
+1. Go to the details page of the created user pool
+1. Find the `App clients` item in the menu on the left
+1. Click `Create app client`
+1. Fill out the form as shown bellow:
+    ![](/images/cognito_pool_1.png)
+    - `Application type`: `Traditional web application`
+    - `Application name`: Specify a desired name, or leave the autogenerated one
+    - `Return URL` (*optional*): Specify CVAT redirect URL.
+      (`<http|https>://<cvat_domain>/api/auth/social/amazon-cognito/login/callback/`).
+      This setting can also be updated or specified later after the app client is created.
+1. Navigate to the `Login pages` tab of the created app client
+1. Check the parameters in the `Managed login pages configuration` section and edit them if needed:
+    ![](/images/cognito_pool_2.png)
+    - `Allowed callback URLs`: Must be set to CVAT redirect URL
+    - `Identity providers`: Must be specified
+    - `OAuth grant types`: The `Authorization code grant` must be selected
+    - `OpenID Connect scopes`: `OpenID`, `Profile`, `Email` scopes must be selected
+
+### Setting up social authentication in CVAT
+
+To configure social authentication in CVAT, create a configuration file
+(`auth_config.yml`) with the following content:
+  ```yaml
+  ---
+  social_account:
+    enabled: true
+    amazon_cognito:
+      client_id: <client_id>
+      client_secret: <client_secret>
+      domain: <custom-domain> or
+        https://<custom-cognito-prefix>.auth.us-east-1.amazoncognito.com
+  ```
+To find `client_id` and `client_secret` values, navigate to the created app client page
+and check `App client information` section. To find `domain`, find `Domain` item in the list on the left.
+
+Once configuration file is updated, several environment variables must be exported before running CVAT:
+  ```bash
+  export AUTH_CONFIG_PATH="<path_to_auth_config>"
+  export CVAT_HOST="<cvat_host>"
+  # cvat_port is optional
+  export CVAT_BASE_URL="<http|https>://${CVAT_HOST}:<cvat_port>"
+  ```
 
 Start the CVAT enterprise instance as usual.
 That's it! On the CVAT login page, you should now see the option `Continue with Amazon Cognito`.