From fe14f648dc22e549c4e8002f7d78492e6fecaa8c Mon Sep 17 00:00:00 2001
From: Chaoran Chen <mail@chaoran-chen.de>
Date: Fri, 12 Apr 2024 14:14:57 +0200
Subject: [PATCH] docs(authentication): document user administration

---
 docs/astro.config.mjs                         |  1 +
 .../docs/guides/user-administration.md        | 24 +++++++++++++++++++
 2 files changed, 25 insertions(+)
 create mode 100644 docs/src/content/docs/guides/user-administration.md

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index b2367ae746..b951c65239 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -20,6 +20,7 @@ export default defineConfig({
           items: [
             // Each item here is one entry in the navigation menu.
             { label: "Getting started", link: "/guides/getting-started/" },
+            { label: "User administration", link: "/guides/user-administration/" },
           ],
         },
         {
diff --git a/docs/src/content/docs/guides/user-administration.md b/docs/src/content/docs/guides/user-administration.md
new file mode 100644
index 0000000000..604b72edc4
--- /dev/null
+++ b/docs/src/content/docs/guides/user-administration.md
@@ -0,0 +1,24 @@
+---
+title: User administration
+description: How to manage (technical and non-technical) users
+---
+
+User accounts are managed by [Keycloak](https://www.keycloak.org/) which offers a web interface for managing users. It can be used to manage both technical and non-technical users.
+
+## Accessing the Keycloak admin console
+
+TODO: Describe how to find the admin console.
+
+TODO: How to get the initial admin credentials.
+
+The Loculus-specific users are stored in the `loculus` realm which can be selected in the selection box in the left navigation bar.
+
+## Superusers/curators
+
+Superusers have the privilege to submit, revise, revoke and approve sequences on behalf of other groups. This role is envisioned to be assigned to curators.
+
+To grant superuser privileges to a user, click on "Users" in the left navigation bar, select the user, click on "Role Mappings" and assign the `super_user` role.
+
+## Processing pipeline
+
+The processing pipeline requires a technical user to authenticate with the Loculus API. To create a new technical user, you can use the usual user registration form on the website. Afterwards, go to the Keycloak admin console, click on "Users" in the left navigation bar, select the user, click on "Role Mappings" and assign the `preprocessing_pipeline` role.