add bootstrap password generation to release note

also changes environment variables to reflect KC_BOOTSTRAP values for
temporary bootstrap admin user

.drone.yml

@@ -3,10 +3,12 @@ kind: pipeline
 name: deploy to swarm-test.autonomic.zone
 steps:
   - name: deployment
-    image: decentral1se/stack-ssh-deploy:latest
+    image: git.coopcloud.tech/coop-cloud/stack-ssh-deploy:latest
     settings:
       host: swarm-test.autonomic.zone
       stack: keycloak
+      networks:
+       - proxy
       generate_secrets: true
       purge: true
       deploy_key:
@@ -23,11 +25,17 @@ trigger:
     - master
 ---
 kind: pipeline
-name: recipe release
+name: generate recipe catalogue
 steps:
   - name: release a new version
-    image: thecoopcloud/drone-abra:latest
+    image: plugins/downstream
     settings:
-      command: recipe keycloak release
-      deploy_key:
-        from_secret: abra_bot_deploy_key
+      server: https://build.coopcloud.tech
+      token:
+        from_secret: drone_abra-bot_token
+      fork: true
+      repositories:
+        - toolshed/auto-recipes-catalogue-json
+
+trigger:
+  event: tag

.env.sample

@@ -5,8 +5,17 @@ DOMAIN=keycloak.example.com
 #EXTRA_DOMAINS=', `www.keycloak.example.com`'
 LETS_ENCRYPT_ENV=production
 
+# ADMIN_USERNAME and _EMAIL are for permanent admin user
 ADMIN_USERNAME=admin
+ADMIN_EMAIL=
+WELCOME_THEME=keycloak
+
+COMPOSE_FILE="compose.yml"
 
 SECRET_DB_ROOT_PASSWORD_VERSION=v1
 SECRET_DB_PASSWORD_VERSION=v1
 SECRET_ADMIN_PASSWORD_VERSION=v1
+SECRET_BOOTSTRAP_PASSWORD_VERSION=v1
+
+# Enable persistent theme volume, if you want to apply a custom theme
+#COMPOSE_FILE="$COMPOSE_FILE:compose.theme.yml"

README.md

@@ -20,10 +20,29 @@
 1. Set up Docker Swarm and [`abra`][abra]
 2. Deploy [`coop-cloud/traefik`][cc-traefik]
 3. `abra app new keycloak --secrets` (optionally with `--pass` if you'd like
-   to save secrets in `pass`)
-4. `abra app YOURAPPDOMAIN config` - be sure to change `$DOMAIN` to something that resolves to
+   to save secrets in `pass`). Make sure to note the `admin_password`
+4. `abra app config YOURAPPDOMAIN` - be sure to change `$DOMAIN` to something that resolves to
    your Docker swarm box
-5. `abra app YOURAPPDOMAIN deploy`
+5. `abra app deploy YOURAPPDOMAIN`
+6. Proceed with replacing the temporary admin user
+
+## Replacing the temporary admin user
+
+The inital user created by Keycloak, is a bootstrap user whose password is stored in plain text on the server. This recipe assigns that user the name "admin_bootstrap" and the password $BOOTSTRAP_PASSWORD set by `abra app config YOURAPDOMAIN`
+
+Running `abra app command YOURAPPDOMAIN app init_kc` replaces this bootstrap admin with a permanent admin user whose username is $ADMIN_USERNAME and whose password is the secret generated in step 3 above. This will also delete the temporary admin user.
+
+It is recommended to also set up MFA for this account from the web admin panel. Log in to the account, select manage account, select account security/signing in, and enable two factor authentication.
+
+## Running Commands in Keycloak's Admin CLI
+
+To authenticate a session to Keycloak's admin API run:
+`abra app command YOURAPPDOMAIN app login_kcadm`
+
+After this you can run any Admin CLI command via the run_kcadm command. An example, which creates a "sandbox" realm:
+`abra app command YOURAPPDOMAIN app run_kcadm "'create realms -s realm=sandbox -s displayName=sandbox -s enabled=true'"`
+
+[Keycloak Admin CLI documentation](https://www.keycloak.org/docs/latest/server_admin/index.html#admin-cli) has more info on running kcadm commands
 
 ## How do I setup a custom theme?
 
@@ -35,12 +54,22 @@ Check [this approach](https://git.autonomic.zone/ruangrupa/login.lumbung.space).
 - Create the user and set a temporary password
 - Under the `Role Mappings` tab, move `admin` from `Available Roles` into `Assigned Roles`
 
+## What do I do if I lost my admin account credentials?
+
+You can create a new admin account like this:
+
+```
+abra app run <domain> app -- bash -c '/opt/keycloak/bin/kc.sh bootstrap-admin user --db-password $(cat /run/secrets/db_password)'
+```
+
+Make sure to delete the temp-admin user after you finish recovering.
+
 ## How do I configure Keycloak login for..
 
 - [Nextcloud][nextcloud]
 - [Peertube][peertube]
 
-[nextcloud]: https://git.coopcloud.tech/coop-cloud/nextcloud
-[peertube]: https://git.coopcloud.tech/coop-cloud/peertube
+[nextcloud]: https://git.coopcloud.tech/coop-cloud/nextcloud#how-do-i-integrate-with-keycloak-sso
+[peertube]: https://git.coopcloud.tech/coop-cloud/peertube#plugins
 [abra]: https://git.autonomic.zone/autonomic-cooperative/abra
 [cc-traefik]: https://git.autonomic.zone/coop-cloud/traefik

abra.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+run_kcadm() {
+    bin/sh -c "/opt/keycloak/bin/kcadm.sh $@"
+}
+
+login_kcadm() {
+    export KC_CLI_PASSWORD=$(cat /run/secrets/admin_password)
+    run_kcadm "config credentials --server http://localhost:8080 --realm master --user ${ADMIN_USERNAME}"
+}
+
+init_kc() {
+    BOOTSTRAP_PW=$(cat /run/secrets/bootstrap_password)
+    run_kcadm "config credentials --server http://localhost:8080 --realm master --user admin_bootstrap --password ${BOOTSTRAP_PW}"
+    # CREATE NEW ADMIN USER
+    ADMIN_PW=$(cat /run/secrets/admin_password)
+    run_kcadm "create users -r master -s username=${ADMIN_USERNAME} -s email='${ADMIN_EMAIL}' -s emailVerified=true -s enabled=true"
+    run_kcadm "set-password -r master --username ${ADMIN_USERNAME} --new-password ${ADMIN_PW}"
+    run_kcadm "add-roles --uusername ${ADMIN_USERNAME} --rolename admin --rolename default-roles-master"
+
+    export KC_CLI_PASSWORD="$ADMIN_PW"
+    # AUTHENTICATE WITH NEW ADMIN USER
+    run_kcadm "config credentials --server http://localhost:8080 --realm master --user ${ADMIN_USERNAME}"
+    # DEMOTE BOOTSTRAP ADMIN IN CASE WE CAN'T DELETE
+    run_kcadm "remove-roles -r master --uusername admin_bootstrap --rolename admin --rolename default-roles-master"
+    # JSON MUNGING
+    BOOTSTRAP_ID=$(run_kcadm "get users -q username=admin_bootstrap --limit 1 --fields id | grep id | cut -d : -f2 | tr -d [:space:]")
+    run_kcadm "delete -r master users/${BOOTSTRAP_ID}"
+}

compose.theme.yml

@@ -0,0 +1,7 @@
+services:
+  app:
+    volumes:
+      - "themes:/opt/keycloak/themes"
+
+volumes:
+  themes:

compose.yml

@@ -1,32 +1,37 @@
----
-version: "3.8"
-
 services:
   app:
-    image: "jboss/keycloak:16.1.1"
+    image: "keycloak/keycloak:26.5.4"
+    entrypoint: >
+      bash -c "KC_BOOTSTRAP_ADMIN_PASSWORD=\"$$(cat run/secrets/bootstrap_password)\" KC_DB_PASSWORD=\"$$(cat /run/secrets/db_password)\" /opt/keycloak/bin/kc.sh start"
     networks:
       - proxy
       - internal
     secrets:
       - admin_password
+      - bootstrap_password
       - db_password
     environment:
-      - DB_ADDR=db
-      - DB_DATABASE=keycloak
-      - DB_PASSWORD_FILE=/run/secrets/db_password
-      - DB_USER=keycloak
-      - DB_VENDOR=mariadb
-      - KEYCLOAK_PASSWORD_FILE=/run/secrets/admin_password
-      - KEYCLOAK_USER=${ADMIN_USERNAME}
-      - PROXY_ADDRESS_FORWARDING=true
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8080"]
-      interval: 30s
-      timeout: 10s
-      retries: 10
-      start_period: 1m
+      - KC_DB=mariadb
+      - KC_DB_URL_DATABASE=keycloak
+      - KC_DB_URL_HOST=db
+      - KC_HOSTNAME=https://${DOMAIN}
+      - KC_PROXY=edge
+      - KC_SPI_CONNECTIONS_JPA_LEGACY_MIGRATION_STRATEGY=update
+      # admin_bootstrap will be superceded by $ADMIN_USERNAME on init_kc
+      - KC_BOOTSTRAP_ADMIN_USERNAME=admin_bootstrap
+      - KEYCLOAK_WELCOME_THEME=${WELCOME_THEME}
+      - KC_PROXY_HEADERS=xforwarded
+      - KC_HTTP_ENABLED=true
+    # NOTE(3wc): disabled due to missing curl binary, see
+    #   https://git.coopcloud.tech/coop-cloud/keycloak/issues/15
+    # healthcheck:
+    #   test: ["CMD", "curl", "-f", "http://localhost:8080"]
+    #   interval: 30s
+    #   timeout: 10s
+    #   retries: 10
+    #   start_period: 1m
     volumes:
-      - "themes:/opt/jboss/keycloak/themes"
+      - "providers:/opt/keycloak/providers"
     depends_on:
       - mariadb
     deploy:
@@ -40,12 +45,15 @@ services:
         - "traefik.http.routers.${STACK_NAME}.entrypoints=web-secure"
         - "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"
         - "traefik.http.routers.${STACK_NAME}.middlewares=${STACK_NAME}-redirect"
-        - "traefik.http.middlewares.${STACK_NAME}-redirect.headers.SSLForceHost=true"
-        - "traefik.http.middlewares.${STACK_NAME}-redirect.headers.SSLHost=${DOMAIN}"
-        - "coop-cloud.${STACK_NAME}.version=4.0.1+16.1.1"
+        - "traefik.http.middlewares.${STACK_NAME}-redirect.redirectscheme.scheme=https"
+        - "traefik.http.middlewares.${STACK_NAME}-redirect.redirectscheme.permanent=true"
+        - "caddy=${DOMAIN}"
+        - "caddy.reverse_proxy={{upstreams 8080}}"
+        - "caddy.tls.on_demand="
+        - "coop-cloud.${STACK_NAME}.version=10.6.1+26.5.4"
 
   db:
-    image: "mariadb:10.6"
+    image: "mariadb:12.2"
     environment:
       - MYSQL_DATABASE=keycloak
       - MYSQL_USER=keycloak
@@ -58,6 +66,13 @@ services:
       - "mariadb:/var/lib/mysql"
     networks:
       - internal
+    deploy:
+      labels:
+        backupbot.backup: "true"
+        backupbot.backup.volumes.mariadb.path: "dump.sql.gz"
+        backupbot.backup.pre-hook: "sh -c 'mariadb-dump -u root -p\"$$(cat /run/secrets/db_root_password)\" keycloak | gzip > /var/lib/mysql/dump.sql.gz'"
+        backupbot.backup.post-hook: "rm -f /var/lib/mysql/dump.sql.gz"
+        backupbot.restore.post-hook: "sh -c 'gzip -d /var/lib/mysql/dump.sql.gz && mariadb -u root -p\"$$(cat /run/secrets/db_root_password)\" keycloak < /var/lib/mysql/dump.sql && rm -f /var/lib/mysql/dump.sql'"
 
 networks:
   internal:
@@ -68,6 +83,9 @@ secrets:
   admin_password:
     name: ${STACK_NAME}_admin_password_${SECRET_ADMIN_PASSWORD_VERSION}
     external: true
+  bootstrap_password:
+    name: ${STACK_NAME}_bootstrap_password_${SECRET_BOOTSTRAP_PASSWORD_VERSION}
+    external: true
   db_password:
     name: ${STACK_NAME}_db_password_${SECRET_DB_PASSWORD_VERSION}
     external: true
@@ -77,4 +95,4 @@ secrets:
 
 volumes:
   mariadb:
-  themes:
+  providers:

release/10.5.0+26.4.0

@@ -0,0 +1 @@
+See here for possible breaking changes: https://www.keycloak.org/docs/latest/upgrading/#migrating-to-26-4-0

release/5.0.0+20.0.1

@@ -0,0 +1,9 @@
+You'll need to remove `/auth/` from your app SSO URLs, e.g.
+
+    https://foo.example.com/auth/realms/foo/protocol/openid-connect/auth
+
+Would become:
+
+    https://foo.example.com/realms/foo/protocol/openid-connect/auth
+
+-- decentral1se @ Autonomic

release/6.0.0+21.0.2

@@ -0,0 +1,2 @@
+Healthchecks are disabled, see
+https://git.coopcloud.tech/coop-cloud/keycloak/issues/15

release/7.2.0+22.0.5

@@ -0,0 +1,5 @@
+A persistent volume for themes is now optional, and not enabled by default.
+
+If you are using a custom theme, consult the recipe `.env.sample` to see the new
+variables you need to add. You can use `abra app check ...` to verify that
+they've been added correctly.

release/next

@@ -0,0 +1,25 @@
+This release introduces admin cli commands to "abra app command"
+
+If you are updating from a previous release, please note that the meaning
+of the "admin_password" secret is changed to reflect the permanent admin
+user's password. To enable "login_kcadm" and "run_kcadm" commands, you
+will need to add your permanent admin password to the secret store.
+
+To increment the secret version:
+"abra app config $APP"
+change this line in the config file:
+SECRET_ADMIN_PASSWORD_VERSION=NEW_VERSION
+
+To insert your permanent admin password:
+"abra app secret insert $APP SECRET_ADMIN_PASSWORD_VERSION \
+  $NEW_VERSION $ADMIN_PASSWORD"
+
+You will also need to generate a bootstrap password (this will not be used)
+"abra app secret generate $APP bootstrap_password v1
+
+See here for more on rotating secrets:
+https://docs.coopcloud.tech/operators/handbook/#rotating-a-secret
+
+After redeploying, ensure that you are able to authenticate the admin
+CLI by running:
+"abra app command $APP app login_kcadm"