Keycloak Power

imageKeycloak imageKiro Power imageLicense

The first comprehensive Keycloak Power for Kiro IDE. Manage Keycloak through its Admin REST API and give Kiro grounded workflows for identity architecture, SSO federation, JWT claims, Organizations, and SaaS authorization.

Features

• Administer realms, clients, users, roles, groups, sessions, events, and client scopes.
• Configure OIDC, SAML, Google, Microsoft Entra ID, Okta, generic external IdPs, and LDAP/AD guidance.
• Create and operate Keycloak Organizations for Keycloak 26+ multi-tenant B2B/B2B2C deployments; manage isolated Organization Groups on Keycloak 26.6+.
• Provision secure BFF clients, fixed SaaS client roles, version-gated LDAP federation inspection, sanitized configuration baselines, and minimal token contracts.
• Govern changes through environment profiles, capability/permission discovery, target-bound plans, preconditions, audit correlation, snapshots, encrypted artifacts, selective copy and compensating rollback.
• Manage client scopes, mapper contracts, realms, clients, LDAP/AD, broker IdPs, authentication flows, roles, groups, Organizations, identity reconciliation and cryptographic JWT verification through explicit plan/apply workflows.
• Inspect JWT structure and claims locally without sending tokens to any service.
• Design authentication flows, MFA, protocol mappers, and authorization middleware contracts.
• Use focused skills that distinguish Keycloak authentication from SaaS-domain authorization.

Requirements

• Kiro IDE with custom Powers enabled.
• Keycloak 21+ for core Admin REST API operations; Keycloak 26+ and Organizations enabled for organization tools; Keycloak 26.6+ for Organization Groups. The power returns unsupported_feature with the minimum upgrade for older servers.
• A confidential client with Service Accounts Enabled and a client secret.
• A service account granted the least-privilege realm-management roles required by the operations you intend to perform. The server uses only Client Credentials Grant; it never uses Resource Owner Password Credentials.
• Node.js 22+ to run the bundled MCP server.

Quick start

1. Build the server:

   Set-Location .\mcp-server
   npm ci
   npm run build
   

2. In Kiro, open Powers, select Add Custom Power, select Import from folder, and choose the keycloak-power directory.
3. Make these values available to the MCP process:

   KEYCLOAK_URL=https://keycloak.example.com
   KEYCLOAK_REALM=master
   KEYCLOAK_CLIENT_ID=kiro-keycloak-admin
   KEYCLOAK_CLIENT_SECRET=<service-account-secret>
   

4. Start a new Kiro chat and ask, for example, “Liste os realms do Keycloak” or “Configure Organizations para um SaaS B2B”.

KEYCLOAK_URL may include a reverse-proxy context path, for example https://sso.example.com/auth; trailing slashes are normalized. KEYCLOAK_REALM is the realm where the admin client exists (commonly master), not necessarily the realm being managed.

Configure the Keycloak service account

1. In the admin console, create a confidential OpenID Connect client, such as kiro-keycloak-admin, in the administration realm.
2. Turn on Client authentication and Service accounts roles; do not enable Direct Access Grants for this Power.
3. On Credentials, generate and save the client secret in a secret manager. Do not commit it to the repository or mcp.json.
4. On Service account roles, select client realm-management and assign only necessary permissions. Typical read-only discovery needs query-realms, query-clients, query-users, and view-realm; realm mutation also needs roles such as manage-realm, manage-clients, manage-users, or manage-identity-providers.
5. Verify connectivity by asking Kiro to call get_server_info.

Environment configuration

The Power manifest contains no secret. Use Kiro's environment/secrets configuration or your operating system's environment to provide the values at runtime.

Secret delivery and version gates

create_bff_client requires KEYCLOAK_SECRET_SINK_COMMAND whenever it creates, reconciles, or rotates a BFF client. It sends a JSON record containing type, secretRef, realm, clientId, and the secret through the sink process's stdin, ignores sink stdout/stderr, and returns only { deliveredToVault: true, secretRef }. If Keycloak succeeds and the sink fails, rerun the same target without rotateSecret; the tool reads the current secret again and retries delivery without returning it to chat. Configure the command as a trusted local vault adapter; the MCP server does not implement a vendor-specific vault client or persist secrets.

list_user_federation_providers, get_user_federation_provider, and list_user_federation_mappers require KEYCLOAK_USER_FEDERATION_TESTED_VERSION to exactly match the connected server. test_user_federation_connection additionally requires KEYCLOAK_USER_FEDERATION_TEST_PATH, set only after testing that realm-relative path against that exact Keycloak version. It never accepts a bind password in input.

MCP tools

Tool inputs are validated for required strings and JSON-shaped configuration values. Every REST request surfaces Keycloak's HTTP status and message to make permissions, malformed request bodies, and unsupported server features diagnosable.

Example Kiro conversations

List the clients in the saas realm and show the redirect URIs for portal-web.

Create the acme organization with alias acme, domain acme.example, and add alice as a member.

Decode this JWT and explain why the API isn't receiving the tenant_id claim.

I need a client for an SPA. Use Authorization Code with PKCE, safe origins, and a groups mapper.

Development

Set-Location .\mcp-server
npm ci
npm run build

The server speaks MCP over standard input/output. Do not write log messages to stdout; diagnostics belong on stderr. See CONTRIBUTING.md for development, security, and pull-request rules.

Privacy and support

• Privacy policy: PRIVACY.md. This Power does not collect telemetry and only communicates with the KEYCLOAK_URL you configure.
• Support and bug reports: open an issue at github.com/Lucas-magalhaes1/keycloak-power/issues.

Documentation sources

The implementation follows the Keycloak documentation and Admin API reference. Organization guidance follows Keycloak's Organizations announcement. Content was rephrased for compliance with licensing restrictions.

License

Copyright 2026 Lucas Magalhães. Licensed under Apache-2.0.

Governed administration

The extended server keeps the existing read tools for compatibility and adds a plan-first control plane. Start with get_environment_profile, validate_connection, get_server_capabilities, and get_admin_permissions. A mutating workflow should then call a plan_* tool, show its sanitized diff and requiredConfirmation, optionally call create_snapshot, and only then call the matching apply tool with planId, planDigest, and the exact confirmation. Plans are held in memory for the current MCP process, include an expiry and a precondition fingerprint, and fail when the target changed after planning.

Core governance tools include plan_resource_operation, get_plan, list_plans, apply_plan, rollback_operation, get_audit_events, create_snapshot, list_snapshots, get_snapshot, plan_snapshot_restore, export_encrypted_baseline, import_encrypted_baseline, plan_resource_copy, and copy_resource. Generic plans reject token/credential endpoints and plaintext secret-shaped fields. Encrypted artifacts use AES-256-GCM with KEYCLOAK_ARTIFACT_KEY; the key and decrypted content never appear in the MCP response.

Extended catalog

Secret references

For write operations that need a Keycloak credential, pass a reference such as clientSecretRef, bindCredentialSecretRef, certificateRef, or secretRef. The configured resolver receives the reference and operation metadata through stdin and returns the value only to the in-process request handler. Secret generation and rotation send the generated value to the sink and return only delivery metadata. If the resolver or sink is not configured, the operation fails closed before mutation or before a generated credential can be accepted.

Compatibility and rollback limits

The server probes read capabilities and reports 401/403/404 separately. LDAP test/sync adapters require an exact operator-tested version and explicit test path; Organization Groups require Keycloak 26.6+. Built-in authentication flows are read-only for clone workflows and must be copied before changes. Rollback uses captured before representations where the Admin REST operation is reversible; it does not claim to restore deleted users, external LDAP/Entra state, sessions, already issued tokens, external IdP registrations or secrets invalidated by rotation.