License Guardian for Confluence

License Guardian finds inactive and never-logged-in Confluence users, applies rule-based deactivation policy, and enforces a governed ignore list so IT, security and compliance teams can answer the hardest question in licence cleanup: why wasn’t this account touched?

A flat skip-list cannot answer it. It has no reason, no owner, no expiry and no review. The temporary exemption someone added for a contractor in 2021 is still silently protecting a seat today, and nobody remembers why.

Every exemption here carries a required reason, a named owner, timestamps, an optional expiry and a recurring review obligation — and every change to it is itself audited.

This is the most important thing to understand before installing. Installing a Forge app grants product scopes. No Confluence product scope exposes when a user last logged in or last touched Confluence. That data lives only in the Atlassian Organization admin API, which authenticates with an organization API key created by an organization admin — a completely separate credential from the app’s Forge scopes.

Without a key the app can enumerate groups and members, read space permission grants, show billable paths, and manage the ignore list, rules, RBAC and audit log. With a key it can additionally measure activity, run scans, and suspend or restore accounts.

The key is written with Forge’s encrypted secret storage (kvs.setSecret), which keeps it at rest inside Atlassian’s own infrastructure. It is never returned to the browser, never logged, and the vendor cannot read it — resolvers only ever expose a boolean hasOrgCredential.

Scale matters here. For 5,000 users the bulk user endpoint costs about 50 requests; the per-user activity endpoint would cost 5,000, which is roughly 25 minutes of wall clock at its 200-requests-per-60-seconds limit. The app therefore always prefers the bulk path and only falls back per-user where activity data is genuinely absent. Its client applies a token-bucket limiter at 80% of the documented budget, so the app never consumes the organization’s entire quota — other tools and vendors share it.

Managed accounts only. The Organization API returns activity only for managed accounts on a verified domain. Unmanaged and external accounts are classified UNKNOWN and are never acted on.

Who this is forConfluence site administrators, plus whoever they grant a role to. Everyone else starts with no access at all — site admins resolve automatically and hold every permission.

Installing the app is not enough to measure anything. An organization admin must also supply an organization API key, because no Confluence product scope exposes when a user last logged in. Without a key the app still maps billable paths and governs the ignore list; it just cannot tell you who is idle.

1. Create the organization API key

   At admin.atlassian.com → Settings → API keys, create a key. Note its expiry — new keys default to one week and can never exceed a year.

2. Store it, and record the expiry

   In Confluence, open Apps → License Guardian → Setup. Paste the key, record the expiry date, click Verify key, choose your organization and directory, then Save key securely.

   The directory is required and validated before the key is stored, so suspend and restore can never target an unknown directory. The key is written with Forge’s encrypted secret storage, is never returned to the browser, is never logged, and the vendor cannot read it.

3. Grant roles so approval is a real second pair of eyes

   Five roles: Viewer (read), Operator (dry-run scans), Approver (execute live), Ignore-List Admin (govern exemptions) and Site Admin (everything).

   Ignore-List Admin deliberately does not imply Approver. A compliance owner can govern exceptions while IT keeps execution rights, so nobody can both write themselves an exemption and run the job that honours it.

4. Populate the ignore list before your first live run

   Three mechanisms, one governed record format: a user pin (matched by account id or email), a group exemption, or a pattern (a regular expression against email or display name, for integration and service accounts).

   Every entry requires a reason of at least ten characters, a named owner, and optionally an expiry. A pattern that exempts everything is a silent opt-out from the whole product, so catch-alls, expressions that do not compile, anything broad enough to match ordinary human addresses, and expressions with catastrophic-backtracking characteristics are all rejected.

5. Run a scan in safe mode

   Safe mode is on by default and is checked server-side: a crafted resolver call asking for live: true is still simulated while safe mode is on.

   Review what came back. Accounts scored as suspected service accounts are marked REVIEW_REQUIRED and excluded from “select all actionable” — they are held, not guessed at. Confirm each one, then give it a real ignore-list entry with a reason and an owner.

6. Execute a live run

   Two independent gates: safe mode must be off and you must type EXECUTE in the confirm dialog.

   The server reloads targets from a completed scan and applies each account’s exact scan outcome, so the selection made in the UI cannot override policy; mismatches are skipped. The ignore list is re-checked at execution time, so an exemption added between the scan and the click is still honoured.

7. Know the rollback path before you need it

   Audit → Action runs → Roll back replays each recorded undo instruction in reverse order: a removed licence re-adds the exact groups it removed by group id, not name, and a deactivation restores the account along with its prior roles and group memberships.

   Rollback is refused for safe-mode runs (nothing changed) and for runs already rolled back. A rollback is itself an access change, so it writes its own audit events.

This is the only external host the app contacts, and the app only reads from it. Requests are authenticated with the organization API key an administrator supplies in-app, not with Forge’s own credentials.

Forge KVS with structured keys was chosen over custom entities to keep the manifest simple and the failure modes obvious. Month bucketing keeps each stored value well under the KVS size ceiling while letting a date-range export read a small, predictable number of keys. If server-side querying of the audit log is ever needed, custom entities with indexes are the migration path.

• An organization API key is required for any activity data. Without it the app can show who holds a seat but not whether they use it. This shapes the install flow: an administrator must do something after installing.
• Managed accounts only. Activity data is unavailable for accounts outside a verified domain. These are reported as UNKNOWN and never acted on — safe, but it means external collaborators are invisible to the rule engine.
• CSV export renders for copy, not download. UI Kit runs sandboxed with no filesystem access. The bytes are identical; for very large exports, call the export resolver directly.
• No email delivery. Forge cannot send arbitrary mail. Grace-period notices are tracked, auditable and exportable, but the app does not deliver them. Wiring this to an existing notification channel is the intended integration point.
• Space-permission scanning is capped at the first 200 spaces per scan to stay within invocation budgets. Larger sites see partial space attribution; group-based billable paths are unaffected.
• Cloud only. Data Center and Server are out of scope.
• Deletion is not implemented. If you genuinely need it, do it through Atlassian admin, deliberately, one account at a time.

Version history for License Guardian for Confluence. The most recent release is listed first.

1. v1.0.0 Current

   Initial release.

   Governance

   • A governed ignore list with three mechanisms — user pin, group, and pattern — sharing one record format that requires a reason, an owner and timestamps.
   • An enforced lifecycle: entries expire, expired entries stop shielding immediately and are retained as evidence, and entries with no expiry surface for recurring re-confirmation on a configurable cadence (default 90 days).
   • Pattern guardrails that reject catch-alls and anything broad enough to match ordinary human addresses.
   • Five RBAC roles with deliberate separation of duties, enforced in the resolver layer with every denial audited.

   Detection

   • Weighted service-account scoring across seven signals, tuned so no single signal can clear the threshold alone. Flagged accounts are excluded from bulk selection and routed into the ignore-list process rather than silently spared.
   • Billable-path breakdown showing how each user became licensed — group membership or space-level permission grant.
   • A resumable scan state machine: PENDING → COLLECTING_GROUPS → COLLECTING_USERS → ENRICHING → EVALUATING → COMPLETED. A timeout costs one chunk of progress, never the whole scan.

   Safety

   • Safe mode on by default and enforced server-side; live execution behind two independent gates.
   • Suspend, never delete. Every batch records undo instructions before it runs, and rollback is available from the Audit tab.
   • Auto-restore and grace-period release run after every completed scan regardless of mode, because both only ever restore access.
   • A conservative default policy: 90-day inactivity threshold, 30-day never-logged-in grace, 14-day notice period, 90-day ignore review cadence, scheduled scans requiring approval.