identity-aiops
Operate and audit self-hosted Keycloak/authentik identity estates through governed MCP tools for diagnostics, reads, and audited writes.
Run RCAs and audits: login-failure cause classification, stale/dormant access, OAuth client misconfiguration, and MFA coverage.
Read identity state: users, groups, clients, sessions, credentials, realm settings, identity providers, login events, admin events, and overview.
Perform governed writes: disable/enable users, revoke sessions, require password reset, replace redirect URIs, and rotate client secrets.
Preview writes with dry-run, apply/list undo tokens, and rely on audit logging, risk tiers, and masked prior-state recording.
Work across Keycloak and authentik, with some Keycloak-only capabilities returning definitive platform errors on authentik.
Provides governed identity operations for authentik: listing and inspecting users, groups, clients, identity providers, sessions, and authentication events; analyzing login failures, stale access, client misconfigurations, and MFA coverage; and performing audited write actions such as disabling or enabling users and revoking user sessions.
Provides governed identity operations for Keycloak: listing and inspecting users, clients, groups, sessions, and events; analyzing login failures, stale access, client misconfigurations, and MFA coverage; and performing audited, reversible write actions such as disabling users, revoking sessions, requiring password resets, updating client redirect URIs, and rotating client secrets.
Identity AIops
Audit availability: Real writes require a committed
pendingaudit row and stop before contacting the platform if storage is unavailable. Reads and previews may continue with a warning; new audit rows store outcome summaries rather than full responses.
Governed AI-ops for self-hosted identity providers — Keycloak + authentik.
identity-aiops gives AI agents (and the humans supervising them) a safe,
audited way to operate the identity plane of self-built and small/mid-size
infrastructure: who can sign in, what failed and why, which OAuth clients are
misconfigured, and who still has no second factor. It is built for teams
running their own Keycloak or authentik who want agent-driven identity
operations with receipts — every tool call is audited, and writes carry
risk-tier labels with dry-run previews and undo tokens.
Verification status: modelled on the public Keycloak admin REST API and authentik API v3 and exercised against mocked responses; there is no recorded end-to-end run against a live instance yet.
identity-aiops doctoris the fastest live check — seedocs/VERIFICATION.md.
What it does
Area | Tools |
Realm / system | overview, realm settings (brute-force protection, password/OTP policy), identity providers |
Users | list/search, detail, count, sessions, credentials (MFA surface), groups, members, lockout status |
Events | authentication events, admin/config-change events |
Clients | list, detail, per-client sessions, session stats |
Flagship RCA |
|
Governed writes |
|
29 MCP tools: 21 reads (including the 4 analyses) + 6 governed writes + 2 undo
tools (undo_list, undo_apply). The
same tools work on both platforms — a per-target platform field selects the
API shape (auth flow + resource paths).
Related MCP server: firewall-aiops
Supported platforms
Platform | API | Auth |
keycloak | Admin REST API ( | OAuth2 client-credentials grant against |
authentik | API v3 ( | Long-lived API token (Bearer) |
Platform notes: require_password_reset, rotate_client_secret,
client_sessions, client_session_stats, and user_lockout_status are
Keycloak-shaped (authentik has no equivalent endpoint — the tools return a
teaching error there). authentik contributes the global session list used by
the stale-access audit's orphaned-session check.
Missing a platform (Authelia, Zitadel, Ory...), an endpoint, or an analysis you need? 缺功能提 issue/PR 欢迎留言 — open an issue or PR at https://github.com/AIops-tools/Identity-AIops, feature requests welcome.
What this tool does, and does not, decide
It delivers identity-provider operations — reads and writes — accurately and
records every one of them. It does not decide whether a write is allowed to
happen. That is the agent's judgement, or the permission of the account you
connect it with: give the Keycloak service account (or authentik token) only
the roles you want the agent to have — view-users / view-events /
view-clients and no manage-* — and the writes fail at the server, the place
that actually owns the permission.
So there is no read-only switch, no policy file, no approval gate to configure.
The one thing the tool guarantees is that nothing is silent: every call, over
MCP and over the CLI alike, lands an audit row in
~/.identity-aiops/audit.db, and reversible writes still capture their
before-state (fetched, never guessed) and record a replayable inverse.
Each tool declares a
risk_level, carried into the audit row as a descriptive tier — so a reviewer can see at a glance that a row was, say, a high-risk secret rotation. It is a label, not a gate.
Running a smaller / local model? See agent-guardrails.md — it lists the guardrails this tool now enforces for you (so you don't spend prompt budget restating them) and gives a ready-made system prompt for what's left.
Quick start
As a Claude Code plugin
One install gives an agent both the skill and the MCP server:
/plugin marketplace add AIops-tools/marketplace
/plugin install identity-aiops@aiops-toolsThe MCP server is fetched with uv and pinned to the
package version this plugin declares, so an audit row can be traced back to the
code that wrote it. Credentials are still configured with identity-aiops init — see below.
As an OpenClaw plugin
The same bundle is published on ClawHub, where one install delivers the skill and its MCP server together:
openclaw plugins install clawhub:@zw008/identity-aiops
openclaw skills info identity-aiops # expect: Visible to model: yesRestart the OpenClaw gateway afterwards so it loads the plugin. The MCP server is
fetched with uv, pinned to this exact release, so
uvx has to be on PATH — without it the skill still installs but reports
Visible to model: no. Credentials are configured exactly as below.
As a CLI or standalone MCP server
uv tool install identity-aiops # or: pipx install identity-aiops
identity-aiops init # wizard: target + realm + credential (encrypted)
identity-aiops doctor # token acquisition + user-count probe per target
identity-aiops overview # one-shot estate summaryFor Keycloak, create a confidential client with Service accounts roles
enabled and grant its service account the realm-management roles you want the
agent to have (start with view-users, view-events, view-clients; add
manage-users / manage-clients only if you want the governed writes). For
authentik, create an API token for a (least-privileged) admin user.
CLI surface: users (list/show/sessions/credentials + disable/enable/
revoke-sessions/require-reset), clients (list/show + set-redirect-uris/
rotate-secret), events, overview, doctor, secret, init, mcp.
Write commands take --dry-run and always double-confirm; execution is
delegated to the governed MCP twins so CLI writes land in the audit log too.
MCP configuration
{
"mcpServers": {
"identity-aiops": {
"command": "uvx",
"args": ["--from", "identity-aiops", "identity-aiops-mcp"],
"env": {
"IDENTITY_AIOPS_MASTER_PASSWORD": "<master password for secrets.enc>"
}
}
}
}env-block caveat: MCP clients launch the server with a minimal environment — variables from your shell profile are NOT inherited. Anything the server needs (
IDENTITY_AIOPS_MASTER_PASSWORD, an alternateIDENTITY_AIOPS_HOME,IDENTITY_AUDIT_APPROVED_BYto attribute writes on the audit trail) must be set in theenvblock above.
Governance
Every MCP tool runs through the vendored governance harness
(identity_aiops/governance/, zero external dependencies):
Audit — every call (including errors) lands in
~/.identity-aiops/audit.dbwith params, status, and risk level, plus any optional approver/rationale annotation. It records; it does not authorize.Budget — per-session call/time budgets and a runaway breaker (
IDENTITY_MAX_TOOL_CALLS,IDENTITY_MAX_TOOL_SECONDS,IDENTITY_RUNAWAY_MAX) — a safety backstop, not an authorization gate.Risk tier — reads are
low; containment/hygiene writes (disable_user,revoke_user_sessions,require_password_reset) aremedium; access-granting or boundary-replacing writes (enable_user,update_client_redirect_uris,rotate_client_secret) arehigh. The tier is a descriptive label carried onto the audit row, not a gate — whether a write runs is the agent's judgement or the connecting account's permissions.IDENTITY_AUDIT_APPROVED_BY/IDENTITY_AUDIT_RATIONALEare optional annotations recorded when set, never required.Undo — reversible writes capture the REAL prior state (fetched before mutating, never guessed) and record a replayable inverse descriptor in
~/.identity-aiops/undo.db. Irreversible writes (revoke_user_sessions,rotate_client_secret) record priorState only — the secret is stored masked, never in clear.Sanitize — every string an IdP returns is folded through an injection-safe normaliser (bounded length, control characters stripped) before an agent sees it.
Secrets — credentials live Fernet-encrypted (scrypt-derived key) in
~/.identity-aiops/secrets.enc, never plaintext on disk; a legacyIDENTITY_<TARGET>_SECRETenv var is honoured as fallback andidentity-aiops secret migratemoves it in. TLS verification defaults ON.
Configuration
~/.identity-aiops/config.yaml (created by init):
targets:
- name: sso1
platform: keycloak
base_url: https://sso.example.com
realm: master
username: identity-aiops-agent # the confidential client's client_id
verify_ssl: true
- name: ak1
platform: authentik
base_url: https://auth.example.com
verify_ssl: trueSet IDENTITY_AIOPS_HOME to relocate all state (config, secrets, audit,
undo). IDENTITY_AIOPS_CONFIG points the MCP server at an alternate
config file.
Development
uv sync
uv run pytest -q
uv run ruff check .MIT License. Part of the AIops-tools line — governed AI-ops tooling for self-hosted infrastructure.
Available Tools
29 toolsadmin_eventsARead-only
[READ] Recent admin/config-change events (who changed what, from where).
Args: max_results: Page bound (default 200, max 500). target: IdP target name from config; omit for the default.
Returns {"events": [...], "returned": N, "limit": L, "truncated": bool}, with truncated measured rather than guessed. On authentik the single event feed is post-filtered to admin actions, so truncated also reports feed rows that were never examined.
Inputs: target, max_results.
client_detailARead-only
[READ] One client's normalized detail by internal id.
Args: client_id: Internal id (Keycloak UUID / authentik provider pk), from list_clients. target: IdP target name from config; omit for the default.
Inputs: client_id (required), target.
client_misconfig_auditARead-only
[READ] Ranked OAuth/OIDC client risk: wildcard/http redirect URIs, public clients with secrets, implicit flow, missing PKCE, password grant — per-client riskScore with evidence and actions.
Args: max_clients: Clients to pull (default 200). target: IdP target name from config; omit for the default.
Returns "inputsTruncated": true when the client list hit max_clients — a clean result over a clipped list is not evidence of a clean estate.
Inputs: target, max_clients.
client_sessionsARead-only
[READ] Active user sessions on one client (Keycloak).
KEYCLOAK ONLY. authentik has no per-provider session listing, so on an authentik target this returns {"error": "Resource 'client_sessions' is not mapped for platform 'authentik'..."}. That is a platform-capability answer, not a fault: switch approach (user_sessions per user) rather than retrying or reporting the tool as broken.
Args: client_id: Internal id, from list_clients. max_results: Page bound (default 200). target: IdP target name from config; omit for the default.
Returns {"sessions": [...], "returned": N, "limit": L, "truncated": bool}, with truncated measured rather than guessed.
Inputs: client_id (required), target, max_results.
client_session_statsARead-only
[READ] Active-session counts per client, busiest first (Keycloak).
KEYCLOAK ONLY. authentik has no per-client session rollup, so on an authentik target this returns {"error": "Resource 'client_session_stats' is not mapped for platform 'authentik'..."}. A platform-capability answer, not a fault — do not retry.
Args: target: IdP target name from config; omit for the default.
Returns {"clients": [...], "returned": N, "truncated": false} — the rollup is unbounded, so this listing is always complete.
Inputs: target.
disable_userADestructive
[WRITE][risk=medium] Disable a user (blocks sign-in); reversible.
The containment move for a compromised/stale account. Reads the user first so the harness records an undo that restores the prior enabled state. Live sessions survive — pair with revoke_user_sessions. Pass dry_run=True to preview.
Refuses to disable the account this tool authenticates as — including under dry_run, which must report a refusal rather than preview a call that will be refused.
Args: user_id: User id (Keycloak UUID / authentik pk), from list_users. dry_run: If True, preview without changing. target: IdP target name from config; omit for the default.
Inputs: user_id (required), target, dry_run.
enable_userADestructive
[WRITE][risk=high] Re-enable a user (restores sign-in); reversible.
Re-granting access reverses a containment action, so it is tagged risk=high on the audit row (a descriptive label, not a gate). Whether it should run is the agent's judgement or the connecting account's permissions, not the tool's. Pass dry_run=True to preview.
Args: user_id: User id, from list_users. dry_run: If True, preview without changing. target: IdP target name from config; omit for the default.
Inputs: user_id (required), target, dry_run.
group_membersARead-only
[READ] Members of one group, normalized user rows.
Args: group_id: Group id, from list_groups. max_results: Page bound (default 200). target: IdP target name from config; omit for the default.
Returns {"members": [...], "returned": N, "limit": L, "truncated": bool}, with truncated measured rather than guessed.
Inputs: group_id (required), target, max_results.
identity_overviewARead-only
[READ] One-shot summary: platform/realm, user/client/IdP counts, and the size of the recent failed-login feed. Lead with this.
Args: target: IdP target name from config; omit for the default.
Inputs: target.
list_clientsARead-only
[READ] OAuth/OIDC clients in the realm, normalized (redirect URIs, public/confidential, grant flags, PKCE method).
Args: max_results: Page bound (default 200). target: IdP target name from config; omit for the default.
Returns {"clients": [...], "returned": N, "limit": L, "truncated": bool}, with truncated measured rather than guessed. Fields the IdP did not return are null — a null pkceMethod means no PKCE method is pinned.
Inputs: target, max_results.
list_groupsARead-only
[READ] Groups in the realm.
Args: max_results: Page bound (default 200). target: IdP target name from config; omit for the default.
Returns {"groups": [...], "returned": N, "limit": L, "truncated": bool}, with truncated measured rather than guessed.
Inputs: target, max_results.
list_identity_providersARead-only
[READ] Federated identity providers / sources configured on the IdP.
Args: target: IdP target name from config; omit for the default.
Returns {"identityProviders": [...], "returned": N, "truncated": false} — the IdP returns the complete set, so this listing is never clipped.
Inputs: target, max_results.
list_usersARead-only
[READ] Users in the realm, normalized across Keycloak/authentik.
Args: search: Optional username/email search string. max_results: Page bound (default 200). target: IdP target name from config; omit for the default.
Returns {"users": [...], "returned": N, "limit": L, "truncated": bool}. truncated is measured (one extra user is fetched); when true, more users exist — re-run with a higher max_results before drawing a realm-wide conclusion. Fields the IdP did not return are null, never "".
Inputs: search, target, max_results.
login_eventsARead-only
[READ] Recent authentication events, normalized (time/type/user/ip/client/error).
Args: event_type: Platform vocabulary — Keycloak LOGIN / LOGIN_ERROR, authentik login / login_failed (case-insensitive). user: Optional username / user-id filter. max_results: Page bound (default 200, max 500). target: IdP target name from config; omit for the default.
Returns {"events": [...], "returned": N, "limit": L, "truncated": bool}. truncated is measured (one extra event is fetched), not guessed — when it is true, more events exist; re-run with a higher max_results rather than treating the partial feed as the whole picture. Optional fields an event did not carry are null, never "".
Inputs: user, target, event_type, max_results.
login_failure_rcaARead-only
[READ] RCA over the failed-auth feed: separates brute-force (spray or targeted) from a misconfigured client from an expired-credential storm and a lockout storm — each finding carries its numbers, cause, and action.
Args: window_minutes: Trailing analysis window (default 60). max_events: Failed-login events to pull (default 500). target: IdP target name from config; omit for the default.
Returns "feedTruncated": true when the event feed hit max_events — every count is then a lower bound; re-run with a higher max_events before concluding a threshold was not reached.
Inputs: target, max_events, window_minutes.
mfa_coverage_analysisARead-only
[READ] Second-factor coverage: overall %, the users without MFA, and the factor types counted. Pulls one credential list per user (bounded).
Args: max_users: Users to sample (default 200 — one API call each). target: IdP target name from config; omit for the default.
Returns "inputsTruncated": true when the realm is larger than max_users — coveragePct then describes the sample, not the realm.
Inputs: target, max_users.
realm_infoBRead-only
[READ] Realm / instance settings relevant to identity hygiene (brute-force protection, password policy, OTP policy, registration).
Args: target: IdP target name from config; omit for the default.
Inputs: target.
require_password_resetADestructive
[WRITE][risk=medium] Require a password reset at next sign-in (Keycloak required actions); reversible — the undo clears the flag only if this call set it. Pass clear=True to remove a pending requirement instead.
Args: user_id: User id, from list_users. clear: If True, REMOVE the pending reset requirement (the undo path). dry_run: If True, preview without changing. target: IdP target name from config; omit for the default.
Inputs: user_id (required), clear, target, dry_run.
revoke_user_sessionsADestructive
[WRITE][risk=medium] Revoke ALL of a user's sessions. IRREVERSIBLE — no undo; the prior session count is recorded (audit shows the blast radius).
Args: user_id: User id whose sessions to revoke, from list_users. dry_run: If True, preview without revoking. target: IdP target name from config; omit for the default.
Inputs: user_id (required), target, dry_run.
rotate_client_secretADestructive
[WRITE][risk=high] Rotate a client's secret. IRREVERSIBLE — the old secret is invalidated; only masked fingerprints are recorded/returned, never the value.
Refuses to rotate the client this tool authenticates as: that would revoke its own credential with no undo to fall back on — including under dry_run, which must report a refusal rather than preview a call that will be refused. Rotate that one from the admin console and re-store it with 'identity-aiops secret set'.
Every deployment using this client must be updated with the new secret (fetch it from the admin console over a trusted channel). Pass dry_run=True to preview.
Args: client_id: Client internal id, from list_clients. dry_run: If True, preview without rotating. target: IdP target name from config; omit for the default.
Inputs: client_id (required), target, dry_run.
stale_access_auditARead-only
[READ] Dormant-access audit: enabled users idle > N days, accounts that never signed in, service accounts with interactive logins, and sessions orphaned by disabled/unknown users.
Args: stale_days: Idle threshold in days (default 90). max_users: Users to pull (default 500). target: IdP target name from config; omit for the default.
Returns "inputsTruncated" per input feed and "truncated" when a finding list was capped at maxRows; the *Count fields are always the full totals.
Inputs: target, max_users, stale_days.
undo_applyADestructive
[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.
The inverse runs through its own governed tool, so it is audited and carries its own risk tier there. Pass dry_run=True to preview the inverse call without executing it. A token can only be applied once.
Args:
undo_id: The undoId from undo_list (or an _undo_id in a write result).
dry_run: If True, preview the inverse tool + params without running it.
target: Passed through to the inverse tool when it accepts a target.
Inputs: undo_id (required), target, dry_run.
undo_listARead-only
[READ] List recorded, not-yet-applied undo tokens (most recent first).
Each entry names the original tool, the inverse tool that undo_apply
would run, and a human note. Use the undoId with undo_apply.
Returns {"undos": [...], "returned": N, "limit": L, "truncated": bool}.
truncated is measured (one extra row is fetched), not guessed from a
length coincidence: when it is true there are MORE tokens than shown, so
re-run with a higher limit rather than reporting the list as complete.
Each entry carries effectVerified. False means the original write lost
its response, so the change it reverses is PROBABLE, not confirmed — check
the live state before applying, and do not report the result as a restore
of a state that may never have been reached.
Args: limit: Max rows to return (default 50, capped at 500). target: Unused (undo state is host-local); accepted for CLI uniformity.
Inputs: limit, target.
update_client_redirect_urisADestructive
[WRITE][risk=high] REPLACE a client's redirect-URI list; reversible — the prior list is captured and the undo replays it.
Redirect URIs are the OAuth flow's security boundary, so this is tagged risk=high on the audit row (a descriptive label, not a gate). Pass the FULL desired list (this replaces, not appends) and dry_run=True to preview.
Args: client_id: Client internal id, from list_clients. redirect_uris: The complete new redirect-URI list. dry_run: If True, preview without changing. target: IdP target name from config; omit for the default.
Inputs: client_id (required), redirect_uris (required), target, dry_run.
user_countARead-only
[READ] Total user count in the realm (the cheap health probe).
Args: target: IdP target name from config; omit for the default.
Inputs: target.
user_credentialsARead-only
[READ] A user's configured credentials/authenticators — the MFA surface.
Args: user_id: User id, from list_users. target: IdP target name from config; omit for the default.
Returns {"credentials": [...], "returned": N, "truncated": false, "secondFactors": N} — always the user's complete credential set.
Inputs: user_id (required), target.
user_detailARead-only
[READ] One user's full detail (enabled state, required actions, attributes).
Args: user_id: User id (Keycloak UUID / authentik pk), from list_users. target: IdP target name from config; omit for the default.
Inputs: user_id (required), target.
user_lockout_statusARead-only
[READ] Brute-force lockout status for one user (Keycloak attack-detection).
KEYCLOAK ONLY. authentik keeps no per-user lockout register, so on an authentik target this returns {"error": "Resource 'user_lockout' is not mapped for platform 'authentik'..."}. That is a definitive answer about the platform, not a fault: do not retry it and do not report the tool as broken — use login_failure_rca on the failed-auth feed instead.
Args: user_id: User id, from list_users. target: IdP target name from config; omit for the default.
Inputs: user_id (required), target.
user_sessionsARead-only
[READ] A user's active sessions (id, IP, start/last access, clients).
Args: user_id: User id, from list_users. target: IdP target name from config; omit for the default.
Returns {"sessions": [...], "returned": N, "truncated": false} — the IdP returns the user's whole session set, so this listing is always complete.
Inputs: user_id (required), target, max_results.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Tools are mostly cleanly separated by resource and action: user_* (list/detail/count/sessions/credentials), client_* (list/detail/sessions/session_stats), group_*, and event tools. The main friction is between aggregate analyses (mfa_coverage_analysis, login_failure_rca) and the raw listings that feed them (user_credentials, login_events), and between client_sessions (per-client) and user_sessions (per-user) — but descriptions consistently clarify each. No two tools genuinely do the same thing.
Consistently snake_case throughout with no camelCase or arbitrary mixing. It alternates between verb_noun (list_users, revoke_user_sessions, disable_user) and noun_qualifier (user_detail, user_count, client_sessions), but stays internally predictable within each resource family. Minor deviation from a single verb_noun pattern only.
29 tools is on the heavy side and nudges past the well-scoped range, but the domain genuinely spans users, clients, groups, sessions, events, five distinct audits, write/remediation actions, and an undo subsystem. Each tool maps to a real operation, so it is borderline-heavy rather than bloat.
Read coverage is strong (users, clients, groups, sessions, events, IdP/realm config) and the write/undo surface covers containment and remediation with reversibility tracking. Gaps are lifecycle writes — no create/delete user or client, no group membership or attribute mutation — though those may be intentionally out of scope for an audit-and-containment server.
Maintenance
Related MCP Connectors
Fail-closed policy guardrails for AI agents running kubectl, terraform, helm, and argocd.
Remote MCP for Copilot CLI switch gate MCP, structured receipts, audit logs, and reviewer-ready evid
IaC, CI and dependency security review for coding agents: local scan CLI plus hosted OAuth MCP.
Capability-routed CLI/MCP: signed provenance exports, WCAG-validated themes, sovereign deploy modes.
Related MCP Servers
- AlicenseAqualityBmaintenanceGoverned Prometheus + Grafana operations — firing-alert and scrape-target RCA, alert noise/flapping analysis, silences, and dashboards, with unbypassable audit logging (MCP + CLI), budget/runaway guards, dry-run, and undo/rollback.39MIT
- AlicenseAqualityBmaintenanceGoverned OPNsense + pfSense firewall operations — gateway-health, rule-shadow, and blocked-traffic RCA, with guarded rule/alias writes, unbypassable audit logging (MCP + CLI), budget/runaway guards, dry-run, and undo/rollback.352MIT
- AlicenseAqualityBmaintenanceGoverned CI/CD operations for self-hosted GitLab and Gitea — pipeline-failure, runner, artifact-bloat, and stale-branch RCA, with unbypassable audit logging (MCP + CLI), budget/runaway guards, dry-run, and undo/rollback.28MIT
- AlicenseAqualityBmaintenanceGoverned MinIO object-storage operations — capacity, exposure-surface audit, lifecycle, and healing RCA, with guarded bucket writes, unbypassable audit logging (MCP + CLI), budget/runaway guards, dry-run, and undo/rollback.48MIT