Identity Aiops

Use this skill whenever the user needs to operate a Keycloak or authentik identity provider — a one-shot overview, realm settings, users with sessions/credentials/groups/lockout status, authentication and admin events, OAuth/OIDC clients, four flagship RCAs (login-failure/lockout-storm, stale access, client misconfiguration, MFA coverage), and governed writes (disable/enable a user, revoke sessions, require a password reset, replace redirect URIs, rotate a client secret). Always use this skill for "Keycloak", "authentik", "realm", "SSO users", "login failures", "brute force logins", "locked out users", "stale accounts", "service account misuse", "redirect URI", "PKCE", "implicit flow", "client secret rotation", "MFA coverage", "who has no 2FA" when the context is a Keycloak/authentik IdP. Do NOT use when the target is something other than a Keycloak/authentik identity provider (a hypervisor, storage appliance, backup product, container-orchestration cluster, firewall, database, or OT/industrial equipment) — route those to the appropriate other AIops-tools skill. Cloud IdPs (Okta, Entra ID, Auth0) are out of scope. Governed identity operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers).

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 graduated-autonomy risk tiers. 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

Group	Tools	Count	R/W
Realm / system	identity_overview, realm_info, list_identity_providers	3	read
Users / groups	list_users, user_detail, user_count, user_sessions, user_credentials, list_groups, group_members, user_lockout_status	8	read
Events	login_events, admin_events	2	read
Clients	list_clients, client_detail, client_sessions, client_session_stats	4	read
Flagship analyses	login_failure_rca, stale_access_audit, client_misconfig_audit, mfa_coverage_analysis	4	read
Writes	disable_user, revoke_user_sessions, require_password_reset	3	write (med)
Writes	enable_user, update_client_redirect_uris, rotate_client_secret	3	write (high)
Undo	undo_list, undo_apply	2	read + replay

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

bash

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 needs an approver)
• 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

If the user wants…	Use
Keycloak / authentik identity ops	identity-aiops (this skill)
A non-identity platform (hypervisor, storage, backup, cluster, network device/controller, firewall, database, containers, endpoints, local LLM governance, compliance evidence)	the appropriate other AIops-tools skill (proxmox-aiops, truenas-aiops, ceph-aiops, veeam-aiops, k8s-aiops, network-aiops, fabric-aiops, firewall-aiops, postgres-aiops, container-host-aiops, endpoint-aiops, ai-guardian, compliance-aiops, …)
Cloud IdPs (Okta, Entra ID, Auth0)	out of scope for this tool

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 <username> -n 200 → the raw failures behind the finding (authentik: --type login_failed).
4. identity-aiops users show <user-id> and identity-aiops users sessions <user-id> → is the account already compromised, i.e. did any attempt actually succeed?
5. Contain: identity-aiops users disable <user-id> --dry-run, then for real (reversible — the fetched before-state is captured and an enable_user inverse recorded).
6. identity-aiops users revoke-sessions <user-id> → 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 <user-id> 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 <name> / identity-aiops users show <user-id> → confirm each candidate is genuinely the account you think.
3. identity-aiops users sessions <user-id> → 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 <user-id> (reversible, undo-recorded).
5. identity-aiops users revoke-sessions <user-id> 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 <client-id>, identity-aiops clients list) and fix the integration to stop using interactive login. If a disable breaks something unexpectedly, identity-aiops undo apply <id> 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 <client-id> → the full current client configuration, so you replace the right values.
3. identity-aiops clients set-redirect-uris <client-id> --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 <client-id> (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 <id> 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 <user-id> → 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 <user-id> --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 <user-id> --clear removes the pending requirement, and identity-aiops undo apply <id> 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

• Every tool is audited to ~/.identity-aiops/audit.db (relocatable via IDENTITY_AIOPS_HOME).
• Secure by default: with no ~/.identity-aiops/rules.yaml, high-risk operations are denied unless IDENTITY_AUDIT_APPROVED_BY names an approver (set IDENTITY_AUDIT_RATIONALE too). identity-aiops init seeds a starter rules.yaml; an operator-authored rules file is honoured as-is.
• High-risk ops (enable_user, update_client_redirect_uris, rotate_client_secret) require the named approver; 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: read-only mode (IDENTITY_READ_ONLY), the truncation and null-field contracts, the Keycloak-vs-authentik tool asymmetry, and a system prompt