docs: describe authentication as of Core v4.3.0 (#214)

docs/docs/getting-started/03-installation-and-launch.md

@@ -27,7 +27,7 @@ the launcher.
 
 Find the latest release on the AICA GitHub organization under https://github.com/aica-technology/api/releases, and
 search for AICA Launcher (for
-example, [AICA Launcher v1.0.0](https://github.com/aica-technology/api/tree/launcher/v1.0.0)).
+example, [AICA Launcher v1.2.0](https://github.com/aica-technology/api/releases/tag/launcher%2Fv1.2.0)).
 
 Download the prebuilt launcher app based on your operating system and architecture. For example,
 `aica-launcher-linux-amd64.zip` for Linux machines with an AMD processor or `aica-launcher-darwin-arm64.zip` for macOS
@@ -87,7 +87,87 @@ the image has been built, launching the configuration a second time will be much
 
 ![aica-launcher-studio](./assets/aica-launcher-studio.png)
 
+## Authentication
+
+The AICA System License owner launching an AICA System configuration from AICA Launcher is treated as the system
+administrator and has full access to create, manage, control and deploy applications and configurations.
+
+Authentication prevents unauthorized users or software clients from accessing or controlling AICA Studio or the API,
+even if they have access to the IP address and port of the AICA Core server.
+
+This section describes how to manage users with specific access scopes to explicitly authorize access to the running
+AICA System through a web browser or API client.
+
+:::info
+
+User roles and access scopes for authentication in AICA Studio and the API was introduced in AICA Core v4.3.0.
+
+System administration privileges and API authentication are supported by AICA Launcher as of v1.2.0 and the Python API
+Client as of v3.1.0. Upgrade to the latest versions of these tools for full compatibility.
+
+:::
+
+### Users
+
+When using AICA Launcher as the system administrator, AICA Studio is automatically logged in as the privileged
+`super-admin` user.
+
+The system administrator (or a user with the `admin` scope) has access to a settings page within AICA Studio to
+configure cloud service integration and manage or create other users. Users are created using an email address as the
+identifier and can be granted a combination of [scopes](#scopes).
+
+:::note
+
+The email address used to create a new user is only used as an identifier and is unrelated to the email address used for
+[licensing](02-licensing.md). Users are defined locally to a specific AICA System Configuration, and access scopes or
+passwords are not inferred or shared between different configurations, even if the same email address is used.
+
+:::
+
+![aica-studio-create-user](./assets/aica-studio-create-user.png)
+
+A random password is generated for a newly created user and can later be changed by the respective user. If AICA Studio
+is accessed from a browser external to AICA Launcher, or if the user of AICA Launcher logs out of the current session, a
+valid user email and password must be supplied to log back in to AICA Studio.
+
+![aica-studio-user-login](./assets/aica-studio-user-login.png)
+
+The User page in AICA Studio can be used to view the current user with their available scopes, change the password or
+create API keys.
+
+![aica-studio-other-user](./assets/aica-studio-other-user.png)
+
+:::tip
+
+Refer to our [API client documentation](https://pypi.org/project/aica-api/) for more info on API keys.
+
+:::
+
+### Scopes
+
+AICA Studio may have different or limited functionality depending on the scopes granted to the logged-in user.
+Similarly, an API key with appropriate scopes is required to access respective endpoints and functionalities of the API.
+The available levels of scopes are described below. 
+
+#### `status`
+
+Read-only access to high-level information about the AICA System such as the available installed features.
+
+#### `monitor`
+
+Read-only access to specific information about the AICA System such as configuration database entries or the
+state and live telemetry of running application.
+
+#### `control`
+
+Write-level access to configuration databases and control-level access to set, start and manage running applications.
+
+#### `admin`
+
+Administration access to manage and create users and authorize cloud service integrations.
+
 ## Manual installation and launch
 
-For advanced users or users that deal with headless machines, there exists the option to [manually perform the login,
-build and launch steps](../reference/02-manual-installation-launch.md) that the AICA Launcher handles automatically.
+For advanced users or users that deal with headless machines, the login, build and launch steps described here can also
+be performed [manually from the command line](../reference/02-manual-installation-launch.md) instead of using AICA
+Launcher.

docs/docs/reference/02-manual-installation-launch.md

@@ -118,7 +118,6 @@ docker build -f aica-application.toml -t aica-runtime .
 
 The command `docker image ls | grep aica-runtime` should then list the `aica-runtime` image.
 
-
 ## Starting the application container
 
 You can start the AICA application container with the following command.
@@ -208,9 +207,89 @@ To shut down the AICA application container at any time, press CTRL+C in the ori
 to stop the application container from a different terminal window, look up the container name
 with `docker container ps` and then run `docker container stop <container_name>`.
 
+### Persistent user data
+
+AICA applications, URDF hardware and user configurations managed through the API or AICA Studio are stored in a
+database. Because the docker container is isolated from the host filesystem, the local database will be lost when the
+container exits. To persist local data between sessions, create a dedicated directory somewhere on the host. For
+example, use `mkdir ~/.aica-data` to keep the data folder hidden in the home folder. Then execute the normal run command
+with an additional volume mount for the user data.
+
+:::note
+
+Change `/path/to/data` in the command below to a desired location for the data (e.g., `~/.aica-data` or elsewhere)
+
+:::
+
+<Tabs groupId="os">
+<TabItem value="linux" label="Linux">
+
+```bash
+docker run -it --rm \
+  --privileged \
+  --net=host \
+  -v /path/to/license:/license:ro \
+  #highlight-next-line
+  -v /path/to/data:/data:rw \
+  aica-runtime
+```
+
+</TabItem>
+<TabItem value="mac" label="macOS">
+
+```bash
+docker run -it --rm \
+  --privileged \
+  -p 8080:8080 -p 18000-18100:18000-18100/udp \
+  -v /path/to/license:/license:ro \
+  #highlight-next-line
+  -v /path/to/data:/data:rw \
+  aica-runtime
+```
+
+</TabItem>
+</Tabs>
+
+### Setting a super-admin password
+
+AICA Core v4.3.0 and later require authentication for AICA Studio and the API. If no users exist in the mounted user
+database, as is the case for a new configuration or when no data folder is mounted, a system administration password can
+be set through an environment variable which grants full administration rights.
+
+<Tabs groupId="os">
+<TabItem value="linux" label="Linux">
+
+```bash
+docker run -it --rm \
+  --privileged \
+  --net=host \
+  -v /path/to/license:/license:ro \
+  #highlight-next-line
+  -e AICA_SUPER_ADMIN_PASSWORD="${AICA_SUPER_ADMIN_PASSWORD}" \
+  aica-runtime
+```
+
+</TabItem>
+<TabItem value="mac" label="macOS">
+
+```bash
+docker run -it --rm \
+  --privileged \
+  -p 8080:8080 -p 18000-18100:18000-18100/udp \
+  -v /path/to/license:/license:ro \
+  #highlight-next-line
+  -e AICA_SUPER_ADMIN_PASSWORD="${AICA_SUPER_ADMIN_PASSWORD}" \
+  aica-runtime
+```
+
+</TabItem>
+</Tabs>
+
 ## Access the AICA Studio
 
-Visit [localhost:8080](http://localhost:8080) in the browser while the container is running to view AICA Studio.
+Visit [localhost:8080](http://localhost:8080) in the browser while the container is running to view AICA Studio. If the
+`AICA_SUPER_ADMIN_PASSWORD` environment variable was set, use the `super-admin` username and the provided password to
+log in as the system administrator.
 
 ## Access the REST API
 
@@ -273,46 +352,3 @@ docker container exec -it -u ros2 -e DISPLAY="$DISPLAY" -e XAUTHORITY="$XAUTH" C
 ```
 
 You should then be able to run `rviz2` inside the container and see the window appear.
-
-## Persistent user data
-
-AICA applications and URDF hardware can be uploaded to a user database through the API or AICA Studio. Because the
-docker container is isolated from the host filesystem, the local database will be lost when the container exists. To
-persist local data between sessions, create a dedicated directory somewhere on the host. For example, use 
-`mkdir ~/.aica-data` to keep the data folder hidden in the home folder. Then execute the normal run command with an
-additional volume mount for the user data.
-
-:::note
-
-Change `/path/to/data` in the command below to a desired location for the data (e.g., `~/.aica-data` or elsewhere)
-
-:::
-
-<Tabs groupId="os">
-<TabItem value="linux" label="Linux">
-
-```bash
-docker run -it --rm \
-  --privileged \
-  --net=host \
-  -v /path/to/license:/license:ro \
-  #highlight-next-line
-  -v /path/to/data:/data:rw \
-  aica-runtime
-```
-
-</TabItem>
-<TabItem value="mac" label="macOS">
-
-```bash
-docker run -it --rm \
-  --privileged \
-  -p 8080:8080 -p 18000-18100:18000-18100/udp \
-  -v /path/to/license:/license:ro \
-  #highlight-next-line
-  -v /path/to/data:/data:rw \
-  aica-runtime
-```
-
-</TabItem>
-</Tabs>