🔀 Merge pull request #2206 from lissy93/docs/authentication-guides

Clearer authentication docs

Author: lissy93

.github/workflows/docker.yml

@@ -18,7 +18,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Existing git tag to build. Empty = build current ref as :latest.'
+        description: 'Tag to build (empty = build current ref as :latest. tag must exist in git)'
         required: false
         default: ''
   push:
@@ -139,9 +139,9 @@ jobs:
           output: 'trivy-${{ matrix.arch }}.sarif'
           timeout: '10m'
 
-      # SARIF isn't human-readable, so on a gating failure re-print the CVEs as a table
+      # If CVEs found, print them in human readable table so i can read and address them
       - name: 📋 List blocking CVEs (on scan failure)
-        if: steps.scan.outcome == 'failure'
+        if: always() && steps.scan.outcome == 'failure'
         uses: aquasecurity/trivy-action@v0.36.0
         env:
           TRIVY_DB_REPOSITORY: ghcr.io/aquasecurity/trivy-db:2

.github/workflows/tag.yml

@@ -179,6 +179,7 @@ jobs:
             git commit -m "🔖 Bump version to $NEW_VERSION"
             git push
             echo "bumped=true" >> "$GITHUB_OUTPUT"
+            echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
           fi
 
       - name: 🏷️ Create and push tag
@@ -285,9 +286,9 @@ jobs:
                     `this has now been implemented${byLine} in #${prNumber},`,
                     `and will be released shortly in ${version} 😇`,
                   ];
-                  if (isOld) parts.push(`\n\nWe're sorry this one took so long 😔`);
+                  if (isOld) parts.push(`\nWe're sorry this one took so long 😔`);
                   if (isNew) {
-                    parts.push(`\n\nIf you're enjoying Dashy, consider ` +
+                    parts.push(`\nIf you're enjoying Dashy, consider ` +
                       `[sponsoring us](https://github.com/sponsors/lissy93) on GitHub to help with development 💖`);
                   }
                   parts.push(`<!-- ${marker} -->`);
@@ -329,11 +330,13 @@ jobs:
         env:
           PR_NUMBER: ${{ github.event.pull_request.number || '' }}
           PR_TITLE: ${{ github.event.pull_request.title || '' }}
+          PR_AUTHOR: ${{ github.event.pull_request.user.login || github.actor }}
           REPO_URL: ${{ github.server_url }}/${{ github.repository }}
           NEEDS_BUMP: ${{ steps.check_pr.outputs.needs_bump }}
           NEEDS_TAG: ${{ steps.check_pr.outputs.needs_tag }}
           ISSUES: ${{ steps.issues.outputs.numbers }}
           BUMPED: ${{ steps.bump.outputs.bumped }}
+          BUMP_SHA: ${{ steps.bump.outputs.sha }}
           TAG_OUTCOME: ${{ steps.tag.outcome }}
           TAG_RESULT: ${{ steps.tag.outputs.result }}
           TAG_VERSION: ${{ steps.tag.outputs.version }}
@@ -352,11 +355,18 @@ jobs:
             if [ "$IS_MANUAL" = "true" ]; then
               echo "| Trigger | Manual dispatch |"
             elif [ -n "$PR_NUMBER" ]; then
-              echo "| PR | [#${PR_NUMBER}](${REPO_URL}/pull/${PR_NUMBER}) — ${PR_TITLE} |"
+              echo "| PR | [#${PR_NUMBER}](${REPO_URL}/pull/${PR_NUMBER}): ${PR_TITLE} |"
+            fi
+            if [ -n "$PR_AUTHOR" ]; then
+              echo "| Author | [@${PR_AUTHOR}](${REPO_URL%/*/*}/${PR_AUTHOR}) |"
+            fi
+
+            if [ "$NEEDS_TAG" = "false" ]; then
+              echo "| Result | ⏭️ No code changes, nothing to do |"
             fi
 
             if [ "$BUMPED" = "true" ]; then
-              echo "| Version bump | ✅ \`${VERSION}\` |"
+              echo "| Version bump | ✅ \`${VERSION}\` ([\`${BUMP_SHA:0:7}\`](${REPO_URL}/commit/${BUMP_SHA})) |"
             else
               echo "| Version bump | ⏭️ Skipped |"
             fi

Dockerfile

@@ -45,7 +45,8 @@ RUN apk upgrade --no-cache \
  && apk add --no-cache tzdata tini iputils-ping \
  && apk add --no-cache --virtual .setcap libcap-setcap \
  && setcap cap_net_raw+ep "$(readlink -f "$(command -v ping)")" \
- && apk del .setcap
+ && apk del .setcap \
+ && rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx
 
 COPY --chown=node:node --from=deps  /app/node_modules ./node_modules
 COPY --chown=node:node --from=build /app/dist ./dist

docs/authentication.md

@@ -13,6 +13,7 @@ Dashy supports using [Authelia](https://www.authelia.com/) as its OIDC provider.
   - [Main configuration](#main-configuration)
 - [3. Enabling Authelia in Dashy](#3-enabling-authelia-in-dashy)
 - [4. Groups and Visibility](#4-groups-and-visibility)
+- [5. Silent token renewal (optional)](#5-silent-token-renewal-optional)
 - [Troubleshooting](#troubleshooting-common-authelia-issues)
 - [How it Works](#how-it-works)
   - [Client side](#client-side)
@@ -241,37 +242,6 @@ If Authelia uses a self-signed cert, Dashy's server has to trust it before it ca
 Everything should now be fully configured and working 🎉
 When you load Dashy, you'll be redirected to Authelia's login page. After signing in, you'll land back on Dashy's homepage with full access, and all of Dashy's client, server and asset endpoints will be locked behind authentication.
 
-### Silent token renewal (optional)
-
-By default, when your token expires Dashy sends you back through Authelia's login to get a new one. Set `enableSilentRenew: true` to have Dashy refresh the session quietly in the background instead, using a refresh token:
-
-```yaml
-    oidc:
-      clientId: dashy
-      endpoint: https://authelia.lvh.me:9091
-      adminGroup: admins
-      scope: openid profile email groups
-      enableSilentRenew: true
-```
-
-Dashy adds the `offline_access` scope to its request automatically, but Authelia only issues a refresh token if the client is allowed to. Add `offline_access` to the client's `scopes` and `refresh_token` to its `grant_types`:
-
-```yaml
-    clients:
-      - client_id: dashy
-        scopes:
-          - openid
-          - profile
-          - email
-          - groups
-          - offline_access
-        grant_types:
-          - authorization_code
-          - refresh_token
-```
-
-It's off by default, and if a refresh ever fails Dashy falls back to the normal sign-in. See [silent token renewal](../authentication.md#silent-token-renewal) for the full notes and caveats.
-
 ---
 
 ## 4. Groups and Visibility
@@ -304,6 +274,41 @@ sections:
             groups: ['interns']
 ```
 
+---
+
+
+## 5. Silent token renewal (optional)
+
+By default, when your token expires Dashy sends you back through Authelia's login to get a new one. Set `enableSilentRenew: true` to have Dashy refresh the session quietly in the background instead, using a refresh token:
+
+```yaml
+    oidc:
+      clientId: dashy
+      endpoint: https://authelia.lvh.me:9091
+      adminGroup: admins
+      scope: openid profile email groups
+      enableSilentRenew: true
+```
+
+Dashy adds the `offline_access` scope to its request automatically, but Authelia only issues a refresh token if the client is allowed to. Add `offline_access` to the client's `scopes` and `refresh_token` to its `grant_types`:
+
+```yaml
+    clients:
+      - client_id: dashy
+        scopes:
+          - openid
+          - profile
+          - email
+          - groups
+          - offline_access
+        grant_types:
+          - authorization_code
+          - refresh_token
+```
+
+It's off by default, and if a refresh ever fails Dashy falls back to the normal sign-in. See [silent token renewal](./oidc.md#silent-token-renewal) for the full notes and caveats.
+
+
 ---
 
 ## Troubleshooting common Authelia Issues
@@ -395,7 +400,7 @@ Boot starts in [`src/main.js`](https://github.com/lissy93/dashy/blob/4.1.5/src/m
 - `loadOidcSettings()` reads `auth.oidc` (or `auth.keycloak`) at boot and returns a normalised `{ issuer, clientId, adminGroup, adminRole }`. For generic OIDC providers the `issuer` is whatever you set as `endpoint` in `conf.yml`, verbatim
 - `createOidcMiddleware()` returns a Connect middleware. Permissive on no-token requests so the SPA can bootstrap; otherwise it verifies the Bearer token against the issuer's JWKS using [`jose`](https://github.com/panva/jose). Checks cover signature, issuer (against the canonical value from the discovery doc), audience (must equal `clientId`), and expiry, with a 30-second clock-skew tolerance. Sets `req.auth = { user, isAdmin, claims }` on success, `401` on failure
 - `getIssuerContext()` lazily fetches `.well-known/openid-configuration` on first use and wraps `jwks_uri` in `createRemoteJWKSet`, which handles JWKS caching and on-demand key rotation. The result is memoised per-issuer for the life of the process
-- `deriveIsAdmin()` checks the token's `groups` claim against `adminGroup`, and the `realm_access.roles` / `resource_access.<clientId>.roles` arrays against `adminRole`. Authelia only emits `groups`, so the group path is what's used in practice
+- `deriveIsAdmin()` checks the token's `groups` claim against `adminGroup`, and the top-level `roles` claim against `adminRole` (for Keycloak it also folds in the nested `realm_access.roles` / `resource_access.<clientId>.roles` arrays). Authelia only emits `groups`, so the group path is what's used in practice
 - `maybeBootstrapConfig()` is the stripped-response helper. When auth is configured, guest access is off, and an unauthenticated request hits the root `/conf.yml`, it returns a minimal copy with only `appConfig.auth`, `appConfig.enableServiceWorker`, and a `pageInfo.title` of `Login | <your title>`. Sections, items, hostnames and any other secrets never leave the server
 
 [`services/app.js`](https://github.com/lissy93/dashy/blob/4.1.5/services/app.js) wires it all together. The middleware mounts as `protectConfig` in front of every YAML route and config-mutating route. The `/*.yml` handler sets `Cache-Control: private, no-store` and `Vary: Authorization` whenever auth is configured (so intermediate caches can never mix auth states), then calls `maybeBootstrapConfig`; a stripped result is sent as-is, otherwise `res.sendFile` serves the full file. `POST /config-manager/save` is additionally guarded by `requireAdmin`, which returns `401` if `req.auth` is unset and `403` if `req.auth.isAdmin` is false.

docs/authentication/authelia-oidc.md

@@ -13,8 +13,10 @@ Dashy supports using [Authentik](https://goauthentik.io/) as its OIDC provider.
   - [Create the application](#create-the-application)
   - [Create the admin group](#create-the-admin-group)
   - [Create test users](#create-test-users)
+  - [Restrict who can access Dashy (optional)](#restrict-who-can-access-dashy-optional)
 - [3. Enabling Authentik in Dashy](#3-enabling-authentik-in-dashy)
 - [4. Groups and Visibility](#4-groups-and-visibility)
+- [5. Silent token renewal (optional)](#5-silent-token-renewal-optional)
 - [Troubleshooting](#troubleshooting-common-authentik-issues)
 - [How it Works](#how-it-works)
   - [Client side](#client-side)
@@ -181,6 +183,24 @@ If you want separate accounts beyond `akadmin`:
 3. On the new user's page, click **Set password**, set a password, click **Update**
 4. Add the user to `dashy-admins` for admin access, or leave them out for a non-admin
 
+### Restrict who can access Dashy (optional)
+
+By default any Authentik user can sign in to Dashy. To limit access to one or more groups, bind a group policy to the `Dashy` application; Authentik then denies sign-in to anyone outside those groups. This is separate from `adminGroup`, which only controls who gets admin rights inside Dashy, not who can access it at all.
+
+1. Go to **Applications > Applications** and open the `Dashy` application
+
+![Open the Dashy application](https://github.com/user-attachments/assets/613fafe7-881f-4664-a903-945854ac65e2)
+
+2. Open the **Policy / Group / User Bindings** tab and click **Bind existing policy**
+
+![Open the bindings tab](https://github.com/user-attachments/assets/10fca15b-e77d-4624-ae03-0ece3910904c)
+
+3. Switch to the **Group** tab, choose the group that should have access, make sure **Enabled** is on, and click **Create**
+
+![Bind a group to the application](https://github.com/user-attachments/assets/ebf680ab-696f-4c08-ae89-d73fe92b398f)
+
+Access is now limited to members of the bound group. Add another binding for each additional group that should be allowed in.
+
 ### Summary
 
 Authentik should now be configured, and ready to go!
@@ -219,21 +239,6 @@ If Authentik runs on a different host or behind a reverse proxy, make sure `endp
 Everything should now be fully configured and working 🎉
 When you load Dashy, you'll be redirected to Authentik's login page. After signing in you will land back on Dashy's homepage with full access, and all of Dashy's client, server and asset endpoints will be locked behind authentication.
 
-### Silent token renewal (optional)
-
-By default, when your token expires Dashy sends you back through Authentik's login to get a new one. Set `enableSilentRenew: true` to have Dashy refresh the session quietly in the background instead, using a refresh token:
-
-```yaml
-    oidc:
-      clientId: dashy
-      endpoint: https://auth.example.com/application/o/dashy/
-      adminGroup: dashy-admins
-      scope: openid profile email groups
-      enableSilentRenew: true
-```
-
-Dashy adds the `offline_access` scope to its request automatically. Authentik ships an `offline_access` scope mapping by default, so just make sure it's listed under the provider's **Advanced protocol settings > Selected Scopes**. It's off by default, and if a refresh ever fails Dashy falls back to the normal sign-in. See [silent token renewal](../authentication.md#silent-token-renewal) for the full notes and caveats.
-
 ---
 
 ## 4. Groups and Visibility
@@ -266,6 +271,22 @@ sections:
             groups: ['interns']
 ```
 
+
+## 5. Silent token renewal (optional)
+
+By default, when your token expires Dashy sends you back through Authentik's login to get a new one. Set `enableSilentRenew: true` to have Dashy refresh the session quietly in the background instead, using a refresh token:
+
+```yaml
+    oidc:
+      clientId: dashy
+      endpoint: https://auth.example.com/application/o/dashy/
+      adminGroup: dashy-admins
+      scope: openid profile email groups
+      enableSilentRenew: true
+```
+
+Dashy adds the `offline_access` scope to its request automatically. Authentik ships an `offline_access` scope mapping by default, so just make sure it's listed under the provider's **Advanced protocol settings > Selected Scopes**. It's off by default, and if a refresh ever fails Dashy falls back to the normal sign-in. See [silent token renewal](./oidc.md#silent-token-renewal) for the full notes and caveats.
+
 ---
 
 ## Troubleshooting common Authentik Issues
@@ -349,7 +370,7 @@ Boot starts in [`src/main.js`](https://github.com/lissy93/dashy/blob/4.1.5/src/m
 - `loadOidcSettings()` reads `auth.oidc` (or `auth.keycloak`) at boot and returns a normalised `{ issuer, clientId, adminGroup, adminRole }`. For generic OIDC providers the `issuer` is whatever you set as `endpoint` in `conf.yml`, verbatim
 - `createOidcMiddleware()` returns a Connect middleware. Permissive on no-token requests so the SPA can bootstrap; otherwise it verifies the Bearer token against the issuer's JWKS using [`jose`](https://github.com/panva/jose). Checks cover signature, issuer (against the canonical value from the discovery doc), audience (must equal `clientId`), and expiry, with a 30-second clock-skew tolerance. Sets `req.auth = { user, isAdmin, claims }` on success, `401` on failure
 - `getIssuerContext()` lazily fetches `.well-known/openid-configuration` on first use and wraps `jwks_uri` in `createRemoteJWKSet`, which handles JWKS caching and on-demand key rotation. The result is memoised per-issuer for the life of the process
-- `deriveIsAdmin()` checks the token's `groups` claim against `adminGroup`, and the `realm_access.roles` / `resource_access.<clientId>.roles` arrays against `adminRole`. Authentik only emits `groups`, so the group path is what's used in practice
+- `deriveIsAdmin()` checks the token's `groups` claim against `adminGroup`, and the top-level `roles` claim against `adminRole` (for Keycloak it also folds in the nested `realm_access.roles` / `resource_access.<clientId>.roles` arrays). Authentik only emits `groups`, so the group path is what's used in practice
 - `maybeBootstrapConfig()` is the stripped-response helper. When auth is configured, guest access is off, and an unauthenticated request hits the root `/conf.yml`, it returns a minimal copy with only `appConfig.auth`, `appConfig.enableServiceWorker`, and a `pageInfo.title` of `Login | <your title>`. Sections, items, hostnames and any other secrets never leave the server
 
 [`services/app.js`](https://github.com/lissy93/dashy/blob/4.1.5/services/app.js) wires it all together. The middleware mounts as `protectConfig` in front of every YAML route and config-mutating route. The `/*.yml` handler sets `Cache-Control: private, no-store` and `Vary: Authorization` whenever auth is configured (so intermediate caches can never mix auth states), then calls `maybeBootstrapConfig`; a stripped result is sent as-is, otherwise `res.sendFile` serves the full file. `POST /config-manager/save` is additionally guarded by `requireAdmin`, which returns `401` if `req.auth` is unset and `403` if `req.auth.isAdmin` is false.