QRun-IO/qbit-authentik
3
0 Fork 0
Code Issues Pull Requests 6 Actions Packages Projects Releases 8 Wiki Activity

docs: add 'Adopting in another app' README section; neutralize kof22 examples #3

New Issue
Closed
opened 2026-10-12 10:28:11 +00:00 by KofTwentyTwo · 1 comment
KofTwentyTwo commented 2026-10-12 10:28:11 +00:00 (Migrated from github.com)
Copy link
Copy source

From the 2026-10-12 repo audit. The README needs an ## Adopting in another app section (stable anchor #adopting-in-another-app). PR #2 edits README.md, so the audit did not touch it; add this after #1 and #2 merge.

Proposed section

## Adopting in another app

| Item | What to do |
|---|---|
| Coordinates | `com.kingsrook.qbits:qbit-authentik`. Nothing is published yet: the repo is private and has no CircleCI project, so there are no snapshots or RCs on Maven Central. Build from source until `0.1.0` ships. |
| QQQ version | QQQ 4.1 (see `pom.xml` for the exact RC). Java 21. |
| Infrastructure | Authentik, contract-tested against 2026.8.3. The API must be reachable from the app at `baseUrl` (`/api/v3` is appended). |
| Authentik setup | A dedicated service account (default username `qqq-<appKey>-idadmin`) whose role holds only the read permissions the qbit needs, created by a bootstrap blueprint in the host's GitOps repo. `src/test/resources/blueprints/kof22-identity-bootstrap.yaml` is a worked example, not something to apply as is. |
| Registration | `new AuthentikQBitProducer().withQBitConfig(config).produce(qInstance)`. Produces the `authentikApi` API backend, read-only tables (`authentikUser`, `authentikGroup`, `authentikGroupMember`, `authentikSession`, `authentikEvent`), the drift report widget, and the `authentikAdmin` ("Identity") app, which the host may nest. |
| Required config | `baseUrl`, `apiToken`, `appKey` (lower-case letters, digits, dashes; chooses the service-account name), `applicationsInScope` (Authentik application slugs). Optional: `userScopePathStartsWith`, `groupScopeNamePrefix`, `mirrorBackendName` (phase 1 MIRROR), `throttleRequestsPerSecond` (default 10). |
| Secrets / env | `apiToken` as a `${env.X}` reference (README example: `AUTHENTIK_API_TOKEN`). Keep it in the host's secret store; never in config files. |
| Permissions | `identity.users.read` (Identity app and tables), `identity.audit.read` (sensitive fields and tables); full `identity.*` set in docs/DESIGN.md section 5.2. Granted through the Authentik group attribute `qqq.io/permissions`, read by `AuthentikGroupPermissionMapper`. |
| Storage | None for the read-only line, except mirror tables when `MIRROR` is enabled on `mirrorBackendName` (document the DDL when that lands). |
| Known limitations | Read-only: every write is refused by `AuthentikGuard` until phases 2-3. `RBAC`, `WEBHOOK`, `SNAPSHOT_EXPORT` are refused by config validation. |
| Upgrading | First release line; nothing to migrate. |

Host-specific coupling found

src/main has no kof22 defaults, only kof22 examples in Javadoc (AuthentikQBitConfig validation message e.g. kof22-admin, AuthentikAppMetaDataProducer, AuthentikGroupPermissionMapper, TokenBucketThrottle) and kof22-shaped contract-test blueprints. Suggested cleanup: make the Javadoc and README examples neutral (my-app-admin, my-app-prod) and say the test blueprints are an example of one host.

Filed with AI assistance (Claude Code).

From the 2026-10-12 repo audit. The README needs an `## Adopting in another app` section (stable anchor `#adopting-in-another-app`). PR #2 edits `README.md`, so the audit did not touch it; add this after #1 and #2 merge. ## Proposed section ```markdown ## Adopting in another app | Item | What to do | |---|---| | Coordinates | `com.kingsrook.qbits:qbit-authentik`. Nothing is published yet: the repo is private and has no CircleCI project, so there are no snapshots or RCs on Maven Central. Build from source until `0.1.0` ships. | | QQQ version | QQQ 4.1 (see `pom.xml` for the exact RC). Java 21. | | Infrastructure | Authentik, contract-tested against 2026.8.3. The API must be reachable from the app at `baseUrl` (`/api/v3` is appended). | | Authentik setup | A dedicated service account (default username `qqq-<appKey>-idadmin`) whose role holds only the read permissions the qbit needs, created by a bootstrap blueprint in the host's GitOps repo. `src/test/resources/blueprints/kof22-identity-bootstrap.yaml` is a worked example, not something to apply as is. | | Registration | `new AuthentikQBitProducer().withQBitConfig(config).produce(qInstance)`. Produces the `authentikApi` API backend, read-only tables (`authentikUser`, `authentikGroup`, `authentikGroupMember`, `authentikSession`, `authentikEvent`), the drift report widget, and the `authentikAdmin` ("Identity") app, which the host may nest. | | Required config | `baseUrl`, `apiToken`, `appKey` (lower-case letters, digits, dashes; chooses the service-account name), `applicationsInScope` (Authentik application slugs). Optional: `userScopePathStartsWith`, `groupScopeNamePrefix`, `mirrorBackendName` (phase 1 MIRROR), `throttleRequestsPerSecond` (default 10). | | Secrets / env | `apiToken` as a `${env.X}` reference (README example: `AUTHENTIK_API_TOKEN`). Keep it in the host's secret store; never in config files. | | Permissions | `identity.users.read` (Identity app and tables), `identity.audit.read` (sensitive fields and tables); full `identity.*` set in docs/DESIGN.md section 5.2. Granted through the Authentik group attribute `qqq.io/permissions`, read by `AuthentikGroupPermissionMapper`. | | Storage | None for the read-only line, except mirror tables when `MIRROR` is enabled on `mirrorBackendName` (document the DDL when that lands). | | Known limitations | Read-only: every write is refused by `AuthentikGuard` until phases 2-3. `RBAC`, `WEBHOOK`, `SNAPSHOT_EXPORT` are refused by config validation. | | Upgrading | First release line; nothing to migrate. | ``` ## Host-specific coupling found `src/main` has no kof22 defaults, only kof22 examples in Javadoc (`AuthentikQBitConfig` validation message `e.g. kof22-admin`, `AuthentikAppMetaDataProducer`, `AuthentikGroupPermissionMapper`, `TokenBucketThrottle`) and kof22-shaped contract-test blueprints. Suggested cleanup: make the Javadoc and README examples neutral (`my-app-admin`, `my-app-prod`) and say the test blueprints are an example of one host. Filed with AI assistance (Claude Code).
KofTwentyTwo commented 2026-10-12 10:47:31 +00:00 (Migrated from github.com)
Copy link
Copy source

When the adoption section from this issue lands in the README, also link the QQQ adoption checklist: https://github.com/QRun-IO/qqq/blob/develop/docs/migration/adoption-checklist.adoc (QRun-IO/qqq#1071, section 5 covers this QBit).

When the adoption section from this issue lands in the README, also link the QQQ adoption checklist: https://github.com/QRun-IO/qqq/blob/develop/docs/migration/adoption-checklist.adoc (QRun-IO/qqq#1071, section 5 covers this QBit).
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
architecture
Architecture review: coupling, cohesion, UI API
 bug
Something isn't working
 dependencies
documentation
Improvements or additions to documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 github_actions
Pull requests that update GitHub Actions code
 good first issue
Good for newcomers
 help wanted
Extra attention is needed
 invalid
This doesn't seem right
 java
Pull requests that update java code
 question
Further information is requested
 release:rc
Merging this develop PR cuts the next release candidate
 secuurity
wontfix
This will not be worked on
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
forge-recovery (Forge Recovery) james.maes (James Maes)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: QRun-IO/qbit-authentik#3