ci: align canonical shared orb workers

Co-Authored-By: Codex <noreply@openai.com>

.circleci/config.yml

@@ -1,60 +1,14 @@
 version: 2.1
-
+setup: true
 orbs:
-   qqq-orb: kingsrook/qqq-orb@0.6.9
-
-commands:
-   configure-package-install:
-      steps:
-         - run:
-              name: Keep package installation unattended
-              command: |
-                 # These build machines are discarded after the job.
-                 sudo install -d /etc/needrestart/conf.d
-                 printf '%s\n' '$nrconf{restart} = "l";' | sudo tee /etc/needrestart/conf.d/99-qqq-ci.conf >/dev/null
-
+  qqq-orb: kingsrook/qqq-orb@0.7.11
 workflows:
-   test_only:
-      jobs:
-         - qqq-orb/mvn_test_only:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              filters:
-                 branches:
-                    ignore: /(develop|release\/.*)/
-
-   publish_snapshot:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: snapshot
-              filters:
-                 branches:
-                    only: [develop]
-
-   publish_release_candidate:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: release_candidate
-              filters:
-                 branches:
-                    only: [/release\/.*/]
-
-   publish_release:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: release
-              filters:
-                 branches:
-                    ignore: /.*/
-                 tags:
-                    only: [/^v\d+\.\d+\.\d+$/]
+  setup:
+    jobs:
+    - qqq-orb/generate_pipeline:
+        orb_version: 0.7.11
+        filters:
+          branches:
+            ignore: automation/qbit-rc-pending
+          tags:
+            only: /^v\d+\.\d+\.\d+$/

.github/workflows/release-rc.yml

@@ -21,5 +21,6 @@ jobs:
   release-rc:
     if: github.event_name == 'workflow_dispatch' || (github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release:rc'))
     uses: QRun-IO/.github/.github/workflows/qbit-release-rc.yml@main
+    secrets: inherit
     with:
       dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}

.github/workflows/schema-drift.yml

@@ -1,42 +1,16 @@
-# Weekly: does the newest Authentik release still have every operation and
-# query parameter qbit-authentik uses? Downloads the release's schema.yml from
-# goauthentik/authentik and runs SchemaDriftTest against it (no Docker, no
-# credentials). A failure means: review the release notes before upgrading.
 name: authentik-schema-drift
-
-on:
+'on':
   schedule:
-    - cron: "17 6 * * 1"
+  - cron: 17 6 * * 1
   workflow_dispatch:
     inputs:
       version:
-        description: "Authentik version (e.g. 2026.10.0); empty = latest release"
+        description: Authentik version (e.g. 2026.10.0); empty = latest release
         required: false
-
 permissions:
   contents: read
-
 jobs:
   drift:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-java@v4
-        with:
-          distribution: temurin
-          java-version: "21"
-          cache: maven
-      - name: Resolve version and fetch its schema
-        env:
-          GH_TOKEN: ${{ github.token }}
-          INPUT_VERSION: ${{ inputs.version }}
-        run: |
-          version="${INPUT_VERSION}"
-          if [ -z "$version" ]; then
-            version=$(gh release view --repo goauthentik/authentik --json tagName -q .tagName | sed 's#^version/##')
-          fi
-          echo "Authentik $version"
-          curl -fsSL "https://raw.githubusercontent.com/goauthentik/authentik/version/${version}/schema.yml" -o "$RUNNER_TEMP/schema.yml"
-          echo "SCHEMA=$RUNNER_TEMP/schema.yml" >> "$GITHUB_ENV"
-      - name: Drift test
-        run: ./mvnw -B -q test -Dtest=SchemaDriftTest -Dsurefire.failIfNoSpecifiedTests=false -Dauthentik.schema.file="$SCHEMA"
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-schema-drift.yml@0f33ddadf88b9a1b940b8883782fe2000ee1d2bd
+    with:
+      version: ${{ inputs.version || '' }}

.qqq-ci.yml

@@ -0,0 +1,16 @@
+profile: qbit
+orb_version: 0.7.11
+default_branch: develop
+java_version: '21'
+browsers: true
+api_checks: false
+docs_only: false
+release_on_main: false
+release_tag_policy: stable
+test_branch_policy: non-release
+publish:
+  snapshot: true
+  release_candidate: true
+  release: true
+  asciidoc: false
+release_completion: false

CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to this project are documented here. Format: [Keep a Changel
 
 ## [Unreleased]
 
+- **Breaking (security):** `AuthentikMaintenance.applyPolicy` runs as the host's maintenance service principal (QQQ service identities, qqq `docs/SERVICE-IDENTITY.md`; config `maintenancePrincipal`, default `maintenance`). The self-made `MaintenanceSession`, which granted itself `policies.manage` and the document's grants, is gone; under OAuth2 it was rejected anyway (its audit insert failed). The principal's Authentik service account must hold `policies.manage` and every grant it applies, and the subset rule still holds. The audit operator is `service:{principal}`; the job name (`run-once:`/`maintenance:`) prefixes the reason. Hosts declare the principal: `ServiceIdentitiesMetaData.declare(qInstance, new QServicePrincipalMetaData().withName("maintenance"))`. Needs the QQQ release with service identities (qqq#1255).
+- Fix: a degraded `authentik.mapper` health check now says what to fix. The message and details (`flaggedGroups`, `summary`) name each flagged group with a safe reason: `grants nothing: <permission>`, `malformed <attribute>` or `superuser group carries qqq.io/permissions`. It used to say only "Mapper drift detected". Typed attribute values and service-account activity subjects (people) stay out of the outcome. A group with no `qqq.io/*` attributes is not drift and never was.
+- Fix: the `token_broker` health check probes with the grant the broker uses (token exchange) and sends no subject token, so nothing is issued. `invalid_request` (credentials passed) is UP, `invalid_client` is DOWN (bad secret), and `invalid_grant` is DOWN (provider does not allow token exchange). It used to probe `client_credentials`, which the broker provider does not allow, so Authentik logged a 400 every 5 minutes ("Invalid grant_type for provider").
 - Replace expired token-delivery and credential-scope reflection bridges with the RC.7 APIs; retain conservative permission narrowing and explicit unavailable-delivery tests.
 - Ship the expanded, host-neutral QBIT help bundle using QQQ 4.1.0-RC.7 registration and validation, with coverage for optional features and live references. Preserve inline app/table help for hosts without help storage; document HOST bundle overrides.
 

pom.xml

@@ -249,7 +249,7 @@
             <activeByDefault>true</activeByDefault>
          </activation>
          <properties>
-            <qqq.snapshot.version>4.1.0-RC.8</qqq.snapshot.version>
+            <qqq.snapshot.version>4.1.0-RC.19</qqq.snapshot.version>
          </properties>
          <dependencyManagement>
             <dependencies>

src/main/java/com/kingsrook/qbits/authentik/AuthentikQBitConfig.java

@@ -66,6 +66,7 @@ public class AuthentikQBitConfig implements QBitConfig
    private String tokenBrokerClientId = "${env.AUTHENTIK_TOKEN_BROKER_CLIENT_ID}";
    private String tokenBrokerClientSecret = "${env.AUTHENTIK_TOKEN_BROKER_CLIENT_SECRET}";
    private String tokenEndpointUrl = null;
+   private String maintenancePrincipal = "maintenance";
    private String appPublicUrl = null;
    private String authentikPublicUrl = null;
    private String appClientId = null;
@@ -1737,6 +1738,29 @@ public class AuthentikQBitConfig implements QBitConfig
 
 
 
+   /*******************************************************************************
+    ** Getter for maintenancePrincipal: the service principal (declared by the
+    ** host, docs/SERVICE-IDENTITY.md in qqq) that AuthentikMaintenance runs as.
+    ** Its Authentik policy must hold policies.manage and every grant it applies.
+    *******************************************************************************/
+   public String getMaintenancePrincipal()
+   {
+      return (this.maintenancePrincipal);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for maintenancePrincipal (default maintenance).
+    *******************************************************************************/
+   public AuthentikQBitConfig withMaintenancePrincipal(String maintenancePrincipal)
+   {
+      this.maintenancePrincipal = maintenancePrincipal;
+      return (this);
+   }
+
+
+
    /*******************************************************************************
     ** Getter for appPublicUrl.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/authentik/admin/AuthentikAdmin.java

@@ -63,6 +63,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.serviceidentity.ServiceIdentities;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 import org.json.JSONArray;
 import org.json.JSONObject;
@@ -329,8 +330,8 @@ public class AuthentikAdmin
    /*******************************************************************************
     ** The operator, resolved once per instance from live Authentik data. When
     ** the operator is not an Authentik user (static or development sessions),
-    ** the session's own permissions stand in. Maintenance sessions are local job
-    ** identities and never resolved as Authentik users. bootstrapOperatorSubjects additionally
+    ** the session's own permissions stand in. Service principal sessions
+    ** (maintenance) are never resolved as Authentik users by email. bootstrapOperatorSubjects additionally
     ** hold every authentik.* permission.
     *******************************************************************************/
    public Operator operator() throws QException
@@ -341,7 +342,7 @@ public class AuthentikAdmin
       }
 
       String      email       = guard.operatorEmail();
-      boolean     maintenance = AuthentikMaintenance.isMaintenanceSession(QContext.getQSession());
+      boolean     maintenance = ServiceIdentities.isMintedServiceSession(QContext.getQSession());
       boolean     bootstrap   = !maintenance && email != null && com.kingsrook.qbits.authentik.security.BootstrapOperators.matchesUniqueUser(config.getResolvedBootstrapSubjects(), util, email);
       Integer     pk          = null;
       Set<String> permissions = new TreeSet<>();

src/main/java/com/kingsrook/qbits/authentik/admin/AuthentikMaintenance.java

@@ -21,20 +21,17 @@ import java.net.URLEncoder;
 import java.nio.charset.StandardCharsets;
 import java.util.List;
 import java.util.Set;
-import java.util.TreeSet;
 import com.kingsrook.qbits.authentik.AuthentikQBitConfig;
 import com.kingsrook.qbits.authentik.AuthentikRuntime;
 import com.kingsrook.qbits.authentik.policy.PolicyGenerator;
 import com.kingsrook.qbits.authentik.policy.PolicyParseException;
 import com.kingsrook.qbits.authentik.policy.PolicyParser;
 import com.kingsrook.qbits.authentik.policy.PolicyPermissions;
-import com.kingsrook.qbits.authentik.security.IdentityPermission;
 import com.kingsrook.qqq.backend.core.context.CapturedContext;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
-import com.kingsrook.qqq.backend.core.model.session.QSession;
-import com.kingsrook.qqq.backend.core.model.session.QUser;
+import com.kingsrook.qqq.backend.core.serviceidentity.ServiceIdentities;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 import org.json.JSONObject;
 
@@ -60,13 +57,18 @@ public final class AuthentikMaintenance
     ** plan and execute path. Requires an initialized QContext with the host's
     ** QInstance. The caller's context is restored on success, refusal or failure.
     **
-    ** The operator must start with maintenance: or run-once: and have a nonblank
-    ** suffix. Its name and the required reason are recorded verbatim. A dedicated
-    ** non-system session holds policies.manage and the document's current grants.
-    ** Existing scope, protection, readOnly, feature and stale checks still apply.
-    ** Equivalent policies return NO_CHANGE without a write or an audit row.
-    ** With policyTwoPersonApproval enabled, a change queues an approval instead
-    ** of writing to Authentik; this API never bypasses second-person approval.
+    ** Runs as the host's maintenance service principal (config
+    ** maintenancePrincipal, default "maintenance"; docs/SERVICE-IDENTITY.md in
+    ** qqq): under OAuth2 a real token for its Authentik service account, so its
+    ** authority is exactly what the owner granted that account (policies.manage
+    ** and every grant the document applies - the subset rule still holds). No
+    ** authority is created here. The audit operator is service:{principal};
+    ** the job name (maintenance: or run-once:, nonblank suffix) prefixes the
+    ** required reason. Existing scope, protection, readOnly, feature and stale
+    ** checks still apply. Equivalent policies return NO_CHANGE without a write
+    ** or an audit row. With policyTwoPersonApproval enabled, a change queues an
+    ** approval instead of writing to Authentik; this API never bypasses
+    ** second-person approval.
     *******************************************************************************/
    public static AuthentikAdmin.AdminResult applyPolicy(String apiBackendName, String groupName, String policyJson, String operatorName, String reason) throws QException
    {
@@ -87,18 +89,16 @@ public final class AuthentikMaintenance
       CapturedContext caller = QContext.capture();
       try
       {
-         MaintenanceSession session = new MaintenanceSession();
-         session.setUser(new QUser().withIdReference(operatorName).withFullName("Maintenance (" + operatorName + ")"));
-         session.setPermissions(new TreeSet<>(Set.of(IdentityPermission.POLICIES_MANAGE.getSessionPermission())));
-         QContext.init(caller.qInstance(), session);
+         String principal = AuthentikRuntime.forBackend(apiBackendName).getConfig().getMaintenancePrincipal();
+         QContext.init(caller.qInstance(), ServiceIdentities.session(caller.qInstance(), principal));
 
          AuthentikAdmin admin = AuthentikAdmin.forBackend(apiBackendName);
          AuthentikRuntime runtime = admin.getUtil().getRuntime();
          runtime.getGuard().authorize(AdminAction.SAVE_POLICY);
-         Set<String> grants = StringUtils.hasContent(policyJson)
-            ? PolicyParser.parseStrict(policyJson, runtime.getConfig().getPolicyFormat(), runtime.getPolicyCatalog()).permissions() : Set.of();
-         session.getPermissions().addAll(grants.contains(PolicyPermissions.FULL_ACCESS)
-            ? PolicyPermissions.allPermissions(caller.qInstance(), runtime.getPermissionCatalog()) : grants);
+         if(StringUtils.hasContent(policyJson))
+         {
+            PolicyParser.parseStrict(policyJson, runtime.getConfig().getPolicyFormat(), runtime.getPolicyCatalog());
+         }
 
          runtime.invalidateCache();
          List<JSONObject> groups = admin.getUtil().getAllPages("/core/groups/?name=" + URLEncoder.encode(groupName, StandardCharsets.UTF_8)
@@ -108,7 +108,15 @@ public final class AuthentikMaintenance
             throw (new QUserFacingException("Expected exactly one Authentik group named " + groupName + "."));
          }
          JSONObject group = groups.get(0);
-         AdminRequest request = AdminRequest.of(AdminAction.SAVE_POLICY, group.getString("pk"), reason)
+         if(isServicePrincipalGroup(group))
+         {
+            ////////////////////////////////////////////////////////////////////
+            // a principal never changes a service principal's grants (its own //
+            // or another's): only the owner does, in Identity                 //
+            ////////////////////////////////////////////////////////////////////
+            throw (new QUserFacingException("Service principal groups are changed only by the owner in Identity."));
+         }
+         AdminRequest request = AdminRequest.of(AdminAction.SAVE_POLICY, group.getString("pk"), operatorName + ": " + reason)
             .with(AuthentikAdmin.POLICY_DOCUMENT, policyJson)
             .with("expectedFingerprint", AuthentikSafety.groupFingerprint(group));
          return (admin.execute(request));
@@ -125,6 +133,29 @@ public final class AuthentikMaintenance
 
 
 
+   /*******************************************************************************
+    ** A service principal role group: named service:..., or a child of
+    ** qqq-service-accounts.
+    *******************************************************************************/
+   static boolean isServicePrincipalGroup(JSONObject group)
+   {
+      if(group.optString("name", "").startsWith("service:"))
+      {
+         return (true);
+      }
+      org.json.JSONArray parents = group.optJSONArray("parents_obj");
+      for(int i = 0; parents != null && i < parents.length(); i++)
+      {
+         if("qqq-service-accounts".equals(parents.optJSONObject(i) == null ? null : parents.getJSONObject(i).optString("name")))
+         {
+            return (true);
+         }
+      }
+      return (false);
+   }
+
+
+
    /*******************************************************************************
     ** Canonical compact full-access document using the host's spec and version.
     *******************************************************************************/
@@ -139,23 +170,4 @@ public final class AuthentikMaintenance
          throw (new QException("Could not generate the full-access policy.", e));
       }
    }
-
-
-
-   /*******************************************************************************
-    ** Recognize only sessions created here, never an ordinary user's name prefix.
-    *******************************************************************************/
-   static boolean isMaintenanceSession(QSession session)
-   {
-      return (session instanceof MaintenanceSession);
-   }
-
-
-
-   /*******************************************************************************
-    ** A local job identity, never an Authentik user or a QSystemUserSession.
-    *******************************************************************************/
-   private static final class MaintenanceSession extends QSession
-   {
-   }
 }

src/main/java/com/kingsrook/qbits/authentik/client/AuthentikActionUtil.java

@@ -1563,7 +1563,7 @@ public class AuthentikActionUtil extends BaseAPIActionUtil
             {
                // Never echo an untrusted broker error body.
             }
-            throw (new QUserFacingException("Authentik refused to act as you (" + error + ")"));
+            throw (new BrokerRefusedException(error));
          }
          throw (mapError(request, path, status, response.getContent(), token));
       }

src/main/java/com/kingsrook/qbits/authentik/client/AuthentikTokenBroker.java

@@ -62,20 +62,40 @@ public class AuthentikTokenBroker
 
 
    /*******************************************************************************
-    ** Request client credentials for health, then discard the bearer immediately.
+    ** Prove the broker's client credentials with the grant it actually uses
+    ** (token exchange), without a subject token, so nothing is issued and no
+    ** user data is sent. Authentik checks the grant type, then the client
+    ** secret, then the subject: invalid_request (missing subject) means both
+    ** passed; invalid_client means a bad secret; invalid_grant means the
+    ** provider does not allow token exchange.
     *******************************************************************************/
-   public void probeClientCredentials(AuthentikActionUtil util) throws QException
+   public void probeCredentials(AuthentikActionUtil util) throws QException
    {
       AuthentikQBitConfig config = util.getRuntime().getConfig();
       HttpPost request = new HttpPost(config.getTokenEndpointUrl());
       request.setEntity(new UrlEncodedFormEntity(List.of(
-         new BasicNameValuePair("grant_type", "client_credentials"),
+         new BasicNameValuePair("grant_type", "urn:ietf:params:oauth:grant-type:token-exchange"),
          new BasicNameValuePair("client_id", config.getTokenBrokerClientId()),
-         new BasicNameValuePair("client_secret", config.getTokenBrokerClientSecret()),
-         new BasicNameValuePair("scope", "goauthentik.io/api")), StandardCharsets.UTF_8));
-      if(util.requestBrokerCredentials(request).optString("access_token", "").isBlank())
+         new BasicNameValuePair("client_secret", config.getTokenBrokerClientSecret())), StandardCharsets.UTF_8));
+      String code;
+      try
       {
-         throw (new QUserFacingException("Authentik broker returned no access token"));
+         util.requestBrokerCredentials(request);
+         code = "issued";
+      }
+      catch(BrokerRefusedException e)
+      {
+         code = e.getErrorCode();
+      }
+      switch(code)
+      {
+         case "invalid_request" ->
+         {
+            return;
+         }
+         case "invalid_client" -> throw (new QUserFacingException("Authentik rejected the token broker's client credentials"));
+         case "invalid_grant", "unsupported_grant_type" -> throw (new QUserFacingException("The token broker's Authentik provider does not allow token exchange"));
+         default -> throw (new QUserFacingException("Authentik answered the token broker probe unexpectedly (" + code + ")"));
       }
    }
 }

src/main/java/com/kingsrook/qbits/authentik/client/BrokerRefusedException.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.authentik.client;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
+
+
+/*******************************************************************************
+ ** Authentik's token endpoint refused a broker request. Carries only the
+ ** standard OAuth2 error code (never the untrusted response body).
+ *******************************************************************************/
+public class BrokerRefusedException extends QUserFacingException
+{
+   private final String errorCode;
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    *******************************************************************************/
+   public BrokerRefusedException(String errorCode)
+   {
+      super("Authentik refused to act as you (" + errorCode + ")");
+      this.errorCode = errorCode;
+   }
+
+
+
+   /*******************************************************************************
+    ** The OAuth2 error code, or exchange_failed when it was not a standard one.
+    *******************************************************************************/
+   public String getErrorCode()
+   {
+      return (errorCode);
+   }
+}

src/main/java/com/kingsrook/qbits/authentik/drift/AuthentikDriftReport.java

@@ -22,6 +22,7 @@ import java.util.Comparator;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
+import java.util.regex.Pattern;
 import com.kingsrook.qbits.authentik.AuthentikQBitConfig;
 import com.kingsrook.qbits.authentik.client.AuthentikActionUtil;
 import com.kingsrook.qbits.authentik.client.AuthentikJson;
@@ -61,6 +62,9 @@ public class AuthentikDriftReport
 {
    private static final QLogger LOG = QLogger.getLogger(AuthentikDriftReport.class);
 
+   private static final Pattern SAFE_PERMISSION = Pattern.compile("[A-Za-z0-9_.*-]{1,120}");
+   private static final Pattern SAFE_ATTRIBUTE  = Pattern.compile("[A-Za-z0-9_./-]{1,60}");
+
    private final AuthentikActionUtil client;
    private final AuthentikQBitConfig config;
    private final AuthentikGuard      guard;
@@ -373,6 +377,19 @@ public class AuthentikDriftReport
 
 
 
+   /*******************************************************************************
+    ** The attribute name of a GroupGraph malformed entry ("key: detail"), never
+    ** the detail, which can echo whatever a person typed.
+    *******************************************************************************/
+   static String attributeOf(String malformedEntry)
+   {
+      int    colon = malformedEntry == null ? -1 : malformedEntry.indexOf(": ");
+      String key   = colon < 0 ? "" : malformedEntry.substring(0, colon);
+      return (SAFE_ATTRIBUTE.matcher(key).matches() ? key : "attribute");
+   }
+
+
+
    /*******************************************************************************
     ** 6
     *******************************************************************************/
@@ -388,14 +405,16 @@ public class AuthentikDriftReport
          for(String bad : node.malformed())
          {
             issues++;
-            findings.add(DriftFinding.warning("group attributes", node.name(), "Malformed entry ignored (" + bad + "); qqq.io/permissions and qqq.io/app-access must be lists of strings."));
+            findings.add(DriftFinding.warning("group attributes", node.name(), "Malformed entry ignored (" + bad + "); qqq.io/permissions and qqq.io/app-access must be lists of strings.")
+               .withReason("malformed " + attributeOf(bad)));
          }
          for(String permission : node.permissions())
          {
             if(resolver.expand(permission).isEmpty())
             {
                issues++;
-               findings.add(DriftFinding.warning("group attributes", node.name(), "qqq.io/permissions entry \"" + permission + "\" grants nothing in this app (unknown permission or empty wildcard)."));
+               findings.add(DriftFinding.warning("group attributes", node.name(), "qqq.io/permissions entry \"" + permission + "\" grants nothing in this app (unknown permission or empty wildcard; a name the app checks only in code, not in its metadata, is not in the catalog).")
+                  .withReason("grants nothing: " + (SAFE_PERMISSION.matcher(permission).matches() ? permission : "(unprintable name)")));
             }
          }
          for(String app : node.appAccess())
@@ -409,7 +428,8 @@ public class AuthentikDriftReport
          if(graph.isSuperuserInherited(node.pk()) && !node.permissions().isEmpty())
          {
             issues++;
-            findings.add(DriftFinding.warning("group attributes", node.name(), "Superuser group (or under one) carries qqq.io/permissions. QQQ cannot manage it; keep QQQ grants on ordinary groups."));
+            findings.add(DriftFinding.warning("group attributes", node.name(), "Superuser group (or under one) carries qqq.io/permissions. QQQ cannot manage it; keep QQQ grants on ordinary groups.")
+               .withReason("superuser group carries qqq.io/permissions"));
          }
       }
       if(issues == 0)

src/main/java/com/kingsrook/qbits/authentik/drift/DriftFinding.java

@@ -25,10 +25,33 @@ package com.kingsrook.qbits.authentik.drift;
  ** @param check    the check's short name, e.g. "blueprints"
  ** @param subject  what the finding is about, e.g. a group name
  ** @param message  plain-language explanation and what to do
+ ** @param reason   a short, safe summary for health outcomes (no attribute
+ **                 values a person typed beyond validated permission names);
+ **                 null when the finding has none
  *******************************************************************************/
-public record DriftFinding(Severity severity, String check, String subject, String message)
+public record DriftFinding(Severity severity, String check, String subject, String message, String reason)
 {
 
+   /*******************************************************************************
+    ** A finding without a health reason.
+    *******************************************************************************/
+   public DriftFinding(Severity severity, String check, String subject, String message)
+   {
+      this(severity, check, subject, message, null);
+   }
+
+
+
+   /*******************************************************************************
+    ** This finding with a short, safe reason for health outcomes.
+    *******************************************************************************/
+   public DriftFinding withReason(String reason)
+   {
+      return (new DriftFinding(severity, check, subject, message, reason));
+   }
+
+
+
    /*******************************************************************************
     ** Severity, most severe first.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/authentik/health/AuthentikHealthChecks.java

@@ -19,7 +19,10 @@ package com.kingsrook.qbits.authentik.health;
 
 import java.time.Instant;
 import java.time.temporal.ChronoUnit;
+import java.util.ArrayList;
 import java.util.List;
+import java.util.Locale;
+import java.util.TreeMap;
 import java.util.TreeSet;
 import com.kingsrook.qbits.authentik.AuthentikQBitConfig;
 import com.kingsrook.qbits.authentik.client.AuthentikActionUtil;
@@ -45,6 +48,8 @@ import org.json.JSONObject;
  *******************************************************************************/
 public final class AuthentikHealthChecks
 {
+   private static final String GROUP_ATTRIBUTES = "group attributes";
+
    /*******************************************************************************
     ** Utility class.
     *******************************************************************************/
@@ -151,30 +156,91 @@ public final class AuthentikHealthChecks
 
 
    /*******************************************************************************
-    ** Findings carry fixed codes only, never subjects or diagnostic messages.
+    ** Findings carry fixed codes, plus the flagged group names and each group
+    ** finding's safe reason (DriftFinding.reason), so a degraded mapper says
+    ** what to fix. Service-account activity subjects (people) stay private.
     *******************************************************************************/
-   private static HealthCheckOutcome mapper(AuthentikActionUtil util, AuthentikQBitConfig config)
+   static HealthCheckOutcome mapper(AuthentikActionUtil util, AuthentikQBitConfig config)
    {
-      HealthStatus status = HealthStatus.UP;
-      TreeSet<String> codes = new TreeSet<>();
-      for(DriftFinding finding : new AuthentikDriftReport(util, config).runMapperChecks())
+      return (mapperOutcome(new AuthentikDriftReport(util, config).runMapperChecks()));
+   }
+
+
+
+   /*******************************************************************************
+    ** The mapper outcome for a set of drift findings.
+    *******************************************************************************/
+   static HealthCheckOutcome mapperOutcome(List<DriftFinding> findings)
+   {
+      HealthStatus                                      status  = HealthStatus.UP;
+      TreeSet<String>                                   codes   = new TreeSet<>();
+      TreeMap<String, TreeMap<String, TreeSet<String>>> byGroup = new TreeMap<>();
+      TreeSet<String>                                   other   = new TreeSet<>();
+      for(DriftFinding finding : findings)
       {
-         if(finding.severity() == DriftFinding.Severity.ERROR || finding.severity() == DriftFinding.Severity.WARNING)
+         if(finding.severity() != DriftFinding.Severity.ERROR && finding.severity() != DriftFinding.Severity.WARNING)
          {
-            String code = "group attributes".equals(finding.check()) ? "group_attributes" : "service_account_activity";
-            codes.add(code + "." + finding.severity().name().toLowerCase(java.util.Locale.ROOT));
-            if(finding.severity() == DriftFinding.Severity.ERROR)
+            continue;
+         }
+         boolean groupCheck = GROUP_ATTRIBUTES.equals(finding.check());
+         codes.add((groupCheck ? "group_attributes" : "service_account_activity") + "." + finding.severity().name().toLowerCase(Locale.ROOT));
+         status = finding.severity() == DriftFinding.Severity.ERROR || status == HealthStatus.DOWN ? HealthStatus.DOWN : HealthStatus.DEGRADED;
+         if(groupCheck && finding.reason() != null)
+         {
+            String reason = finding.reason();
+            int    colon  = reason.indexOf(": ");
+            TreeSet<String> values = byGroup.computeIfAbsent(safeName(finding.subject()), k -> new TreeMap<>())
+               .computeIfAbsent(colon < 0 ? reason : reason.substring(0, colon), k -> new TreeSet<>());
+            if(colon >= 0)
             {
-               status = HealthStatus.DOWN;
-            }
-            else if(status != HealthStatus.DOWN)
-            {
-               status = HealthStatus.DEGRADED;
+               values.add(reason.substring(colon + 2));
             }
          }
+         else
+         {
+            other.add(groupCheck ? "group attributes check could not run" : "service-account activity (see the identity drift report)");
+         }
       }
-      return (new HealthCheckOutcome().withStatus(status).withMessage(status == HealthStatus.UP ? "Mapper checks passed" : "Mapper drift detected")
-         .withDetails(new HealthDetails().withValue("findingCodes", String.join(",", codes))));
+      if(status == HealthStatus.UP)
+      {
+         return (HealthCheckOutcome.up("Mapper checks passed").withDetails(new HealthDetails().withValue("findingCodes", "")));
+      }
+
+      List<String> parts = new ArrayList<>();
+      byGroup.forEach((group, reasons) ->
+      {
+         List<String> texts = new ArrayList<>();
+         reasons.forEach((label, values) -> texts.add(values.isEmpty() ? label : label + ": " + String.join(", ", values)));
+         parts.add(group + " (" + String.join("; ", texts) + ")");
+      });
+      parts.addAll(other);
+      String summary = String.join("; ", parts);
+      return (new HealthCheckOutcome().withStatus(status).withMessage(truncate("Mapper drift: " + summary, 500))
+         .withDetails(new HealthDetails()
+            .withValue("findingCodes", String.join(",", codes))
+            .withValue("flaggedGroups", truncate(String.join(", ", byGroup.keySet()), 500))
+            .withValue("summary", truncate(summary, 500))));
+   }
+
+
+
+   /*******************************************************************************
+    ** A group name fit for a health message: printable and bounded.
+    *******************************************************************************/
+   private static String safeName(String name)
+   {
+      String printable = name == null ? "" : name.replaceAll("\\p{Cntrl}", "").trim();
+      return (printable.isEmpty() ? "(unnamed group)" : truncate(printable, 100));
+   }
+
+
+
+   /*******************************************************************************
+    ** Cut a text to a length, marking the cut.
+    *******************************************************************************/
+   private static String truncate(String text, int max)
+   {
+      return (text.length() <= max ? text : text.substring(0, max - 3) + "...");
    }
 
 
@@ -188,7 +254,7 @@ public final class AuthentikHealthChecks
       {
          return (HealthCheckOutcome.unknown("not configured"));
       }
-      new AuthentikTokenBroker().probeClientCredentials(util);
+      new AuthentikTokenBroker().probeCredentials(util);
       return (HealthCheckOutcome.up("Token broker authenticated"));
    }
 }

src/test/java/com/kingsrook/qbits/authentik/admin/AuthentikMaintenanceTest.java

@@ -33,6 +33,9 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.session.QSession;
 import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession;
+import com.kingsrook.qqq.backend.core.serviceidentity.QServicePrincipalMetaData;
+import com.kingsrook.qqq.backend.core.serviceidentity.ServiceIdentities;
+import com.kingsrook.qqq.backend.core.serviceidentity.ServiceIdentitiesMetaData;
 import org.json.JSONObject;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
@@ -41,13 +44,16 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 
 /*******************************************************************************
- ** Host maintenance uses the audited Save Policy path with a local job identity.
+ ** Host maintenance uses the audited Save Policy path as the maintenance service
+ ** principal (a local principal here: the test instance uses MOCK auth).
  *******************************************************************************/
 class AuthentikMaintenanceTest
 {
    private static final String GROUP = "kof-website-analysts";
    private static final String OPERATOR = "run-once:KOF22_RUN_ONCE";
    private static final String REASON = "  owner request 2026-10-14: full-access policy for kof22-admins  ";
+   private static final String PRINCIPAL_ID = "service:maintenance";
+   private static final String AUDIT_REASON = OPERATOR + ": " + REASON;
 
    private AdminTestSupport t;
    private String fullAccess;
@@ -62,13 +68,17 @@ class AuthentikMaintenanceTest
    {
       t = AdminTestSupport.create(EnumSet.of(AuthentikFeature.READ, AuthentikFeature.GROUPS, AuthentikFeature.POLICIES));
       fullAccess = AuthentikMaintenance.fullAccessDocument(t.config);
+      Set<String> all = new java.util.TreeSet<>(PolicyPermissions.allPermissions(t.qInstance, t.admin().getUtil().getRuntime().getPermissionCatalog()));
+      all.add(IdentityPermission.POLICIES_MANAGE.getSessionPermission());
+      ServiceIdentitiesMetaData.declare(t.qInstance, new QServicePrincipalMetaData().withName("maintenance").withLocalPermissions(all.toArray(new String[0])));
    }
 
 
 
    /*******************************************************************************
-    ** A system job gets a dedicated, fully expanded session. The audit precedes
-    ** PATCH, the event identifies the job, and an equivalent document is a no-op.
+    ** A system job runs as the maintenance principal (its own grants, nothing
+    ** minted here). The audit precedes PATCH, the operator is the principal,
+    ** the reason names the job, and an equivalent document is a no-op.
     *******************************************************************************/
    @Test
    void appliesFullAccessAuditedAndIdempotently() throws Exception
@@ -84,8 +94,8 @@ class AuthentikMaintenanceTest
       {
          QSession session = QContext.getQSession();
          assertThat(session).isNotInstanceOf(QSystemUserSession.class);
-         assertThat(session.getUser().getIdReference()).isEqualTo(OPERATOR);
-         assertThat(session.getUser().getFullName()).isEqualTo("Maintenance (" + OPERATOR + ")");
+         assertThat(ServiceIdentities.isMintedServiceSession(session)).isTrue();
+         assertThat(session.getUser().getIdReference()).isEqualTo(PRINCIPAL_ID);
          assertThat(session.getPermissions()).containsAll(all).doesNotContain(PolicyPermissions.FULL_ACCESS);
          assertThat(QContext.getActionStack()).isNotSameAs(caller.actionStack());
          assertThat(QContext.getAuthorizedActionScopeDepth()).isZero();
@@ -112,15 +122,15 @@ class AuthentikMaintenanceTest
       assertThat(t.authentik.groupByName(GROUP).getJSONObject("attributes").getString(t.config.getPolicyAttribute())).isEqualTo(fullAccess);
       assertThat(rows(AuthentikLocalTables.ADMIN_ACTION)).singleElement().satisfies(row ->
       {
-         assertThat(row.getValueString("operator")).isEqualTo(OPERATOR);
-         assertThat(row.getValueString("reason")).isEqualTo(REASON);
+         assertThat(row.getValueString("operator")).isEqualTo(PRINCIPAL_ID);
+         assertThat(row.getValueString("reason")).isEqualTo(AUDIT_REASON);
          assertThat(row.getValueString("status")).isEqualTo("SUCCEEDED");
       });
       assertThat(t.authentik.events).singleElement().satisfies(event ->
       {
          assertThat(event.getString("action")).isEqualTo("custom_qqq_admin_action");
-         assertThat(event.getJSONObject("context").getString("operator")).isEqualTo(OPERATOR);
-         assertThat(event.getJSONObject("context").getString("reason")).isEqualTo(REASON);
+         assertThat(event.getJSONObject("context").getString("operator")).isEqualTo(PRINCIPAL_ID);
+         assertThat(event.getJSONObject("context").getString("reason")).isEqualTo(AUDIT_REASON);
       });
       assertThat(result.eventPk()).isNotBlank();
       int writes = t.writes().size();
@@ -134,12 +144,16 @@ class AuthentikMaintenanceTest
 
 
    /*******************************************************************************
-    ** Ordinary policies need only their grants and policies.manage, and honor
+    ** Ordinary policies need only their grants and policies.manage (held by the
+    ** principal, not added here), and honor
     ** the configured spec/version. The maintenance: prefix is accepted too.
     *******************************************************************************/
    @Test
    void appliesNamedPolicyWithLimitedSession() throws Exception
    {
+      ServiceIdentitiesMetaData.declare(t.qInstance, new QServicePrincipalMetaData().withName("policy-maintenance")
+         .withLocalPermissions("cms_page.read", IdentityPermission.POLICIES_MANAGE.getSessionPermission()));
+      t.config.withMaintenancePrincipal("policy-maintenance");
       t.config.withPolicySpec("host-iam");
       String document = AuthentikMaintenance.fullAccessDocument(t.config).replace("\"Action\":[\"*\"]", "\"Action\":[\"read\"]")
          .replace("\"Resource\":[\"*\"]", "\"Resource\":[\"cms_page\"]");
@@ -245,8 +259,8 @@ class AuthentikMaintenanceTest
          assertThat(row.getValueString("status")).isEqualTo("PENDING_APPROVAL"));
       assertThat(rows(AuthentikLocalTables.APPROVAL_REQUEST)).singleElement().satisfies(row ->
       {
-         assertThat(row.getValueString("requester")).isEqualTo(OPERATOR);
-         assertThat(row.getValueString("reason")).isEqualTo(REASON);
+         assertThat(row.getValueString("requester")).isEqualTo(PRINCIPAL_ID);
+         assertThat(row.getValueString("reason")).isEqualTo(AUDIT_REASON);
       });
       assertThat(QContext.capture()).isEqualTo(caller);
    }
@@ -314,6 +328,52 @@ class AuthentikMaintenanceTest
 
 
 
+   /*******************************************************************************
+    ** Without a declared principal, or with one that lacks the grants, nothing
+    ** is written: maintenance never creates authority.
+    *******************************************************************************/
+   @Test
+   void needsAPrincipalHoldingTheGrants() throws Exception
+   {
+      CapturedContext caller = QContext.capture();
+      t.config.withMaintenancePrincipal("undeclared");
+      assertThatThrownBy(() -> apply(GROUP, fullAccess)).hasMessageContaining("not declared");
+      assertThat(QContext.capture()).isEqualTo(caller);
+
+      ServiceIdentitiesMetaData.declare(t.qInstance, new QServicePrincipalMetaData().withName("weak")
+         .withLocalPermissions(IdentityPermission.POLICIES_MANAGE.getSessionPermission()));
+      t.config.withMaintenancePrincipal("weak");
+      AuthentikAdmin.AdminResult result;
+      try
+      {
+         result = apply(GROUP, fullAccess);
+         assertThat(result.ok()).isFalse();
+      }
+      catch(QException e)
+      {
+         assertThat(e).isNotNull();
+      }
+      assertThat(t.writes()).isEmpty();
+      assertThat(QContext.capture()).isEqualTo(caller);
+   }
+
+
+
+   /*******************************************************************************
+    ** Maintenance never changes a service principal's role group.
+    *******************************************************************************/
+   @Test
+   void refusesServicePrincipalGroups() throws Exception
+   {
+      t.authentik.group("service:kof22-scheduler", false, List.of(), List.of());
+      assertThatThrownBy(() -> apply("service:kof22-scheduler", fullAccess)).hasMessageContaining("Service principal groups");
+      assertThat(AuthentikMaintenance.isServicePrincipalGroup(new JSONObject().put("name", "x")
+         .put("parents_obj", new org.json.JSONArray().put(new JSONObject().put("name", "qqq-service-accounts"))))).isTrue();
+      assertThat(t.writes()).isEmpty();
+   }
+
+
+
    /*******************************************************************************
     ** Apply using the production public API.
     *******************************************************************************/

src/test/java/com/kingsrook/qbits/authentik/drift/AuthentikDriftReportTest.java

@@ -186,4 +186,20 @@ class AuthentikDriftReportTest
       assertThatThrownBy(() -> new AuthentikDriftReportWidgetRenderer().render(input)).isInstanceOf(QPermissionDeniedException.class);
    }
 
+
+
+
+   /*******************************************************************************
+    ** A malformed entry's health reason keeps the attribute name, never the
+    ** value a person typed.
+    *******************************************************************************/
+   @Test
+   void malformedReasonKeepsOnlyTheAttribute()
+   {
+      assertThat(AuthentikDriftReport.attributeOf("qqq.io/permissions: {\"x\":\"typed value\"}")).isEqualTo("qqq.io/permissions");
+      assertThat(AuthentikDriftReport.attributeOf("qqq.io/policy: line 1: bad")).isEqualTo("qqq.io/policy");
+      assertThat(AuthentikDriftReport.attributeOf("no separator")).isEqualTo("attribute");
+      assertThat(AuthentikDriftReport.attributeOf("bad key with spaces: x")).isEqualTo("attribute");
+      assertThat(AuthentikDriftReport.attributeOf(null)).isEqualTo("attribute");
+   }
 }

src/test/java/com/kingsrook/qbits/authentik/health/AuthentikHealthChecksTest.java

@@ -26,6 +26,7 @@ import com.kingsrook.qbits.authentik.AuthentikTestSupport;
 import com.kingsrook.qbits.authentik.client.AuthentikActionUtil;
 import com.kingsrook.qbits.authentik.client.FixtureActionUtil;
 import com.kingsrook.qbits.authentik.client.TokenBucketThrottle;
+import com.kingsrook.qbits.authentik.drift.DriftFinding;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.health.HealthCategory;
@@ -176,22 +177,49 @@ class AuthentikHealthChecksTest
 
 
    /*******************************************************************************
-    ** Only the two relevant drift checks run; their subjects stay private.
+    ** Only the two relevant drift checks run. Group findings name the group and
+    ** a safe reason; typed attribute values and people (service-account
+    ** activity subjects) stay private.
     *******************************************************************************/
    @Test
    void mapperStates() throws QException
    {
       assertThat(run("mapper").getStatus()).isEqualTo(HealthStatus.UP);
-      JSONObject group = new JSONObject().put("pk", "g1").put("name", SECRET)
-         .put("attributes", new JSONObject().put("qqq.io/permissions", new JSONArray().put(SECRET)));
-      FixtureActionUtil.groupGraphBody = new JSONObject(FixtureActionUtil.EMPTY_PAGE).put("results", new JSONArray().put(group)).toString();
+
+      //////////////////////////////////////////////////////////////////////////////
+      // a group with no qqq.io/* attributes (kof22-admins on its static floor) is //
+      // not drift                                                                 //
+      //////////////////////////////////////////////////////////////////////////////
+      JSONObject floorOnly = new JSONObject().put("pk", "g0").put("name", "kof22-admins").put("attributes", new JSONObject());
+      groups(floorOnly);
       var outcome = run("mapper");
+      assertThat(outcome.getStatus()).isEqualTo(HealthStatus.UP);
+      assertThat(outcome.getMessage()).isEqualTo("Mapper checks passed");
+
+      JSONObject unknown = new JSONObject().put("pk", "g1").put("name", "file-gateway-admins")
+         .put("attributes", new JSONObject().put("qqq.io/permissions", new JSONArray().put("file_gateway.view").put("file_gateway.admin")));
+      JSONObject malformed = new JSONObject().put("pk", "g2").put("name", "editors")
+         .put("attributes", new JSONObject().put("qqq.io/permissions", new JSONArray().put(new JSONObject().put("x", SECRET))));
+      JSONObject superuser = new JSONObject().put("pk", "g3").put("name", "authentik Admins").put("is_superuser", true)
+         .put("attributes", new JSONObject().put("qqq.io/permissions", new JSONArray().put("authentik.users.read")));
+      groups(floorOnly, unknown, malformed, superuser);
+      outcome = run("mapper");
       assertThat(outcome.getStatus()).isEqualTo(HealthStatus.DEGRADED);
-      assertThat(outcome.getDetails().getValues()).containsEntry("findingCodes", "group_attributes.warning");
+      assertThat(outcome.getMessage()).isEqualTo("Mapper drift: authentik Admins (superuser group carries qqq.io/permissions); "
+         + "editors (malformed qqq.io/permissions); file-gateway-admins (grants nothing: file_gateway.admin, file_gateway.view)");
+      assertThat(outcome.getDetails().getValues())
+         .containsEntry("findingCodes", "group_attributes.warning")
+         .containsEntry("flaggedGroups", "authentik Admins, editors, file-gateway-admins")
+         .containsEntry("summary", outcome.getMessage().substring("Mapper drift: ".length()));
+      assertClean(outcome);
+
+      groups(unknown);
       page(new JSONObject().put("action", "model_deleted").put("context", new JSONObject()
          .put("model", new JSONObject().put("model_name", "user").put("pk", "1").put("name", SECRET))));
       outcome = run("mapper");
       assertThat(outcome.getStatus()).isEqualTo(HealthStatus.DOWN);
+      assertThat(outcome.getMessage()).isEqualTo("Mapper drift: file-gateway-admins (grants nothing: file_gateway.admin, file_gateway.view); "
+         + "service-account activity (see the identity drift report)");
       assertClean(outcome);
       assertThat(FixtureActionUtil.REQUESTS).allSatisfy(request -> assertThat(request.getURI().getPath())
          .doesNotContain("/admin/version/", "/core/tokens/", "/managed/blueprints/"));
@@ -200,19 +228,74 @@ class AuthentikHealthChecksTest
 
 
    /*******************************************************************************
-    ** A broker check exercises the grant without exposing the returned bearer.
+    ** A group check that cannot run, unprintable names and long summaries stay
+    ** readable and within the health limits.
+    *******************************************************************************/
+   @Test
+   void mapperOutcomeEdges()
+   {
+      var outcome = AuthentikHealthChecks.mapperOutcome(List.of(
+         DriftFinding.error("group attributes", "-", "Check could not run: " + SECRET),
+         DriftFinding.info("group attributes", "x", "info only").withReason("ignored"),
+         DriftFinding.warning("group attributes", "bad\u0007name", "m").withReason("grants nothing: (unprintable name)"),
+         DriftFinding.warning("group attributes", "", "m").withReason("malformed attribute")));
+      assertThat(outcome.getStatus()).isEqualTo(HealthStatus.DOWN);
+      assertThat(outcome.getMessage()).isEqualTo("Mapper drift: (unnamed group) (malformed attribute); badname (grants nothing: (unprintable name)); "
+         + "group attributes check could not run");
+      assertThat(outcome.getDetails().getValues()).containsEntry("findingCodes", "group_attributes.error,group_attributes.warning");
+      assertClean(outcome);
+
+      List<DriftFinding> many = new java.util.ArrayList<>();
+      for(int i = 0; i < 60; i++)
+      {
+         many.add(DriftFinding.warning("group attributes", "group-number-" + i, "m").withReason("grants nothing: some.long.permission.name." + i));
+      }
+      outcome = AuthentikHealthChecks.mapperOutcome(many);
+      assertThat(outcome.getMessage()).hasSize(500).endsWith("...");
+      assertThat(outcome.getDetails().toJson().getBytes(java.nio.charset.StandardCharsets.UTF_8).length).isLessThanOrEqualTo(4096);
+      assertThat(outcome.getDetails().getValues()).containsKeys("findingCodes", "flaggedGroups", "summary");
+   }
+
+
+
+   /*******************************************************************************
+    ** Serve these groups as the group graph.
+    *******************************************************************************/
+   private static void groups(JSONObject... groups)
+   {
+      JSONArray results = new JSONArray();
+      for(JSONObject group : groups)
+      {
+         results.put(group);
+      }
+      FixtureActionUtil.groupGraphBody = new JSONObject(FixtureActionUtil.EMPTY_PAGE).put("results", results).toString();
+   }
+
+
+
+   /*******************************************************************************
+    ** The broker check uses the grant the broker uses (token exchange) with no
+    ** subject: invalid_request proves the credentials; nothing is ever issued.
     *******************************************************************************/
    @Test
    void brokerStates() throws Exception
    {
-      respond(new JSONObject().put("access_token", SECRET));
+      refuse("invalid_request");
       assertThat(run("token_broker").getStatus()).isEqualTo(HealthStatus.UP);
       HttpPost request = (HttpPost) FixtureActionUtil.REQUESTS.getLast();
-      assertThat(EntityUtils.toString(request.getEntity())).contains("grant_type=client_credentials", "client_id=", "client_secret=");
+      String body = EntityUtils.toString(request.getEntity());
+      assertThat(body).contains("grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange", "client_id=", "client_secret=");
+      assertThat(body).doesNotContain("client_credentials", "subject_token");
       assertThat(request.getFirstHeader("Authorization")).isNull();
       assertThat(request.getURI().toString()).isEqualTo(config.getTokenEndpointUrl());
-      respond(new JSONObject());
+
+      refuse("invalid_client");
       assertThat(run("token_broker").getStatus()).isEqualTo(HealthStatus.DOWN);
+      refuse("invalid_grant");
+      assertThat(run("token_broker").getStatus()).isEqualTo(HealthStatus.DOWN);
+      respond(new JSONObject().put("access_token", SECRET));
+      assertThat(run("token_broker").getStatus()).isEqualTo(HealthStatus.DOWN);
+
       config.withTokenBrokerClientSecret(null);
       FixtureActionUtil.REQUESTS.clear();
       var outcome = run("token_broker");
@@ -223,6 +306,16 @@ class AuthentikHealthChecksTest
 
 
 
+   /*******************************************************************************
+    ** Serve a token-endpoint refusal with a standard OAuth2 error code.
+    *******************************************************************************/
+   private void refuse(String errorCode)
+   {
+      FixtureActionUtil.handler = request -> FixtureActionUtil.response(400, new JSONObject().put("error", errorCode).toString());
+   }
+
+
+
    /*******************************************************************************
     ** Both response bodies and thrown errors may echo every configured secret.
     *******************************************************************************/