identity-aiops

Identity AIops

Disclaimer: Community-maintained open-source project, not affiliated with, endorsed by, or sponsored by the Keycloak project, Red Hat, Authentik Security Inc., or the authentik project. Keycloak and authentik are trademarks of their respective owners. Source at github.com/AIops-tools/Identity-AIops under the MIT license.

Governed identity operations — 29 MCP tools across Keycloak (admin REST /admin/realms/{realm}/...) and authentik (API v3 /api/v3/...), every one wrapped with the bundled @governed_tool harness: a local unified audit log under ~/.identity-aiops/, policy engine, token/runaway budget guard, undo-token recording, and risk-tier labelling on the audit row. A per-target platform field selects the API shape, so the same tools work on both IdPs and one config can span a mixed estate. The Keycloak client secret / authentik API token is stored encrypted (~/.identity-aiops/secrets.enc, Fernet + scrypt) — never plaintext on disk.

Standalone: the governance harness is bundled in the package (identity_aiops.governance) — no external skill-family dependency. Both platforms are free/self-hostable, so a self-hosted lab is the cheapest live check; verification status and the checklist are in docs/VERIFICATION.md.

What This Skill Does

The four flagship analyses are transparent heuristics that report their numbers, never a black-box verdict: login_failure_rca windows the failed-auth feed by user/IP/client and separates password spray, targeted brute-force, a stale stored credential, a misconfigured client, an expired-credential storm, and a lockout storm; stale_access_audit flags dormant and never-used accounts, interactive service accounts, and orphaned sessions; client_misconfig_audit ranks clients by OAuth-BCP risk (wildcard/http redirects, secrets in public clients, implicit flow, missing PKCE, password grant); mfa_coverage_analysis reports second-factor coverage overall and per group.

Quick Install

uv tool install identity-aiops
identity-aiops init       # wizard: pick platform (keycloak/authentik) + encrypted secret
identity-aiops doctor

When to Use This Skill

• Get a one-shot snapshot (overview / realm_info / user_count)
• Triage a login-failure or lockout storm (login_failure_rca) → cause + action
• Run an access re-certification (stale_access_audit: idle users, never-logged-in accounts, service-account misuse, orphaned sessions)
• Audit OAuth clients (client_misconfig_audit: redirect URIs, PKCE, implicit flow, password grant) and fix them (update_client_redirect_uris)
• Measure and close the MFA gap (mfa_coverage_analysis, user_credentials)
• Contain a compromised account (disable_user + revoke_user_sessions + require_password_reset, all governed; re-enable is tagged high risk)
• Rotate a leaked client secret (rotate_client_secret, high risk, masked)

Do NOT use when the target is not a Keycloak/authentik IdP — route hypervisor, storage, backup, cluster, network/firewall, database, endpoint, or OT/industrial work to the appropriate other AIops-tools skill. Cloud IdPs (Okta, Entra ID, Auth0) are out of scope.

Related Skills — Skill Routing

Common Workflows

Each recipe starts from a read or one of the four RCAs and ends in a governed write. The RCAs are MCP tools (login_failure_rca, stale_access_audit, client_misconfig_audit, mfa_coverage_analysis) — call them through the MCP server; the CLI covers the reads and the writes. Every CLI write accepts --dry-run and otherwise double-confirms.

1. "We're being brute-forced — contain it"

1. identity-aiops overview → how big is the failed-login feed right now, and is this one account or the whole realm?
2. MCP login_failure_rca → findings ranked with numbers, separating password spray from one IP, targeted brute-force on one account, a client failing with credential errors (a rotated secret not deployed), an expired-credential storm, and a lockout storm.
3. identity-aiops events --type LOGIN_ERROR --user -n 200 → the raw failures behind the finding (authentik: --type login_failed).
4. identity-aiops users show and identity-aiops users sessions → is the account already compromised, i.e. did any attempt actually succeed?
5. Contain: identity-aiops users disable --dry-run, then for real (reversible — the fetched before-state is captured and an enable_user inverse recorded).
6. identity-aiops users revoke-sessions → kill live sessions. Irreversible (priorState only) — disabling alone does not end sessions already issued, so this step is what actually stops the attacker.
7. identity-aiops undo list → confirm the disable is reversible before you hand off.

Failure branch: if the RCA classifies it as a misconfigured client rather than an attack (mass credential errors from one client id), do not disable users — you would lock out legitimate people while the real fault is a rotated secret that was never deployed. Go to recipe 3. If you disabled the wrong account, identity-aiops users enable is high risk and needs IDENTITY_AUDIT_APPROVED_BY + IDENTITY_AUDIT_RATIONALE, deliberately — re-enabling reverses containment.

2. "Quarterly access re-certification"

1. MCP stale_access_audit (e.g. stale_days=90) → dormant users with day counts, never-logged-in accounts, service accounts being used interactively, and orphaned sessions.
2. identity-aiops users list --search / identity-aiops users show → confirm each candidate is genuinely the account you think.
3. identity-aiops users sessions → check for a live session before you touch a "dormant" account.
4. Confirm with the account owner or its manager. Then, per account: identity-aiops users disable (reversible, undo-recorded).
5. identity-aiops users revoke-sessions for the orphaned sessions the audit found (irreversible).
6. Re-run stale_access_audit to confirm the list shrank as expected.

Failure branch: an interactive service account finding is not a disable candidate — disabling it takes down whatever integration depends on it. Trace the client first (identity-aiops clients show , identity-aiops clients list) and fix the integration to stop using interactive login. If a disable breaks something unexpectedly, identity-aiops undo apply replays the captured prior state.

3. "Harden the OAuth clients before the audit"

1. MCP client_misconfig_audit → per-client riskScore with the evidence behind it: wildcard or plain-http redirect URIs, a public client holding a secret, implicit flow enabled, missing PKCE, password grant allowed.
2. identity-aiops clients show → the full current client configuration, so you replace the right values.
3. identity-aiops clients set-redirect-uris --uri https://app.example.com/callback --dry-run → note that --uri is repeated and supplies the FULL new list, replacing what is there.
4. Re-run without --dry-run: high risk, double confirm, requires IDENTITY_AUDIT_APPROVED_BY + IDENTITY_AUDIT_RATIONALE. The prior URI list is captured, so undo replays it exactly.
5. If a secret leaked: identity-aiops clients rotate-secret (high risk, irreversible, masked priorState) — then deploy the new secret everywhere that client is used.
6. Re-run client_misconfig_audit to confirm the score dropped.

Failure branch: rotating a secret before the deployments are ready is how you cause recipe 1's "misconfigured client" storm — every service using the old secret starts failing authentication immediately, and rotation cannot be undone. Stage the deployment first. If a redirect-URI replacement breaks a login flow, identity-aiops undo apply restores the exact prior list; this is why the URI change is reversible and the rotation is not.

4. "Show me who still has no second factor"

1. MCP mfa_coverage_analysis → coverage percentage, the worst groups first, and the per-user gap list.
2. identity-aiops users credentials → what a specific user actually has configured, so you distinguish "no MFA" from "an enrolled factor the analysis could not see".
3. identity-aiops overview and realm settings → confirm the realm's brute-force protection and OTP policy actually require what you think they require.
4. Where a forced re-enrolment is part of the rollout: identity-aiops users require-reset --dry-run, then for real (reversible — undo clears the pending requirement).
5. identity-aiops undo list → confirm each reset flag can be cleared if the rollout stalls.

Failure branch: if a user is blocked out by the reset requirement (no working recovery path, or they cannot complete enrolment), identity-aiops users require-reset --clear removes the pending requirement, and identity-aiops undo apply does the same from the recorded token. Do not chase a 100% coverage number by forcing resets on service accounts — they have no interactive user to complete the flow, and the stale_access_audit in recipe 2 is the right tool for those.

Governance & Safety

The skill delivers reads and writes and records them; it does not decide whether a write is permitted. That is your agent's judgement, or the permission of the account you connect it with (a Keycloak service account or authentik token without manage-* scope — writes then fail at the server). There is no read-only switch, policy file, or approval gate.

• Audit is the guarantee, and it is not bypassable. Every call — MCP and CLI alike — lands an audit row in ~/.identity-aiops/audit.db (relocatable via IDENTITY_AIOPS_HOME): params, status, and the risk tier.
• IDENTITY_AUDIT_APPROVED_BY / IDENTITY_AUDIT_RATIONALE are optional annotations recorded on the row (who/why); they are never required and never block.
• Risk tier — a descriptive label on the audit row derived from risk_level (enable_user, update_client_redirect_uris, rotate_client_secret = high; disable_user, revoke_user_sessions, require_password_reset = medium); it gates nothing. Writes support --dry-run and double confirmation at the CLI.
• Reversible writes capture the real fetched before-state and record an inverse descriptor (disable↔enable, reset-flag→clear, redirect-URI list replay). revoke_user_sessions and rotate_client_secret are irreversible (priorState only; secrets recorded masked).

References

• references/capabilities.md — full tool + platform + API-path reference
• references/cli-reference.md — CLI command reference
• references/setup-guide.md — onboarding, credentials, and connectivity
• references/agent-guardrails.md — running with a smaller / local model: the truncation and null-field contracts, the Keycloak-vs-authentik tool asymmetry, and a system prompt