keycloak-skills

📚 Documentation • 🚀 Hosted Keycloak • 🤖 Keycloak Skills • 💬 Support

[!TIP]
Run this in our cloud, no setup needed. Phase Two hosts Keycloak with all of our extensions built in. Try it free with your own cluster →

Using a coding agent? Add the Phase Two Keycloak skills (launch post) to Claude Code, Cursor or Codex so your agent can set up passwordless login, SSO, organizations and clusters for you:

# Install the skills (connects to our hosted MCP server)
claude plugin marketplace add p2-inc/keycloak-skills
claude plugin install phasetwo@keycloak-skills
# Or connect to the MCP server directly
claude mcp add --transport http keycloak https://mcp.phasetwo.io/mcp

An Agent Skills marketplace for Phase Two — Claude Code, Cursor and Codex skills for configuring Keycloak/Phase Two extension behaviors, for both vanilla/self-hosted Keycloak and Phase Two hosted Keycloak.

Each plugin lives under plugins/<name>/, with one shared set of Agent Skills and a manifest per platform — Claude Code, Cursor and Codex.

Install

One plugin, three clients. Pick your guide:

The repo root is the marketplace. keycloak-skills is the marketplace name declared
in those files (it matches the repo name); phasetwo is the plugin inside it. That
pairing is what ids like phasetwo@keycloak-skills are built from.

Plugins

• phasetwo — a unified keycloak skill that routes Keycloak/Phase Two requests to the right guidance: passwordless login (magic link, email OTP, passkey, or passkey-or-magic-link), email OTP as a second factor, organization-membership login restriction, corporate SSO by email domain, social login and enterprise IdP federation, IdP-initiated SSO, and Phase Two cluster/deployment provisioning. New capabilities get added as reference docs under the same skill, once genuinely written and verified, rather than as new skills.

Dependency

The keycloak skill relies on the Keycloak MCP server to check deployment targets and verify changes against a live deployment. The plugin declares it in plugins/phasetwo/.mcp.json, so installing the plugin connects it — there is no command to run:

{ "mcpServers": { "keycloak": {
    "type": "http",
    "url": "https://mcp.phasetwo.io/mcp",
    "oauth": { "clientId": "claude-client", "callbackPort": 8787, "scopes": "openid" }
} } }

That file has to sit at the plugin root, beside .claude-plugin/. An mcpServers key inside plugin.json passes claude plugin validate --strict but is silently ignored at runtime — claude plugin details phasetwo reports MCP servers (0). Cursor is the exception: its manifest schema does accept mcpServers, which is why the Cursor build declares its own entry with a pinned OAuth client (see docs/install-cursor.md). Endpoints are unversioned and images are tagged by commit, so this URL picks up new server releases with no change here.

It is a remote server behind OAuth. Each client authenticates against its own
pre-registered OAuth client rather than registering one dynamically, so the only
prompt you ever see is the sign-in:

One per platform, so each carries only the redirect URIs that platform actually uses
and can be revoked on its own — the per-client walkthroughs are in the
install guides. Check the connection with /mcp in a session.

If you are using the skill without the plugin — a copy under ~/.claude/skills/, say — add it yourself, since nothing declares it for you:

claude mcp add --transport http keycloak https://mcp.phasetwo.io/mcp

Linting

This repo uses skillsaw to enforce Agent Skills structure and marketplace conventions. Config is in .skillsaw.yaml; repo-specific rules are in .skillsaw/rules.py.

License

This repository is dual-licensed by content type, so the skills carry an
attribution-and-share-alike condition while the code stays permissive:

Copyright 2026 Phase Two, Inc.

Every file whose format allows a comment carries an SPDX-License-Identifier
header, so a single SKILL.md or reference doc copied into someone's
.claude/skills/ still declares its own terms — the licensing does not live only
at the repo root. Files that cannot carry a comment (JSON, .jar, fixture
.txt) follow the table above and the mapping in NOTICE.

Bundled authentication-flow JSON under skills/*/assets/ is Apache-2.0 rather
than CC BY-SA: it is configuration you import into your own realm, and ShareAlike
should not reach your realm's config.

Attribution

If you redistribute, incorporate, or adapt the CC BY-SA 4.0 material, include
attribution substantially similar to:

Contains material from "keycloak-skills" by Phase Two, Inc.
https://github.com/p2-inc/keycloak-skills
Licensed under CC BY-SA 4.0.

Adaptations must indicate that changes were made, and must themselves be
distributed under CC BY-SA 4.0 or a compatible license.

Contributing

Contributors retain copyright in their contributions and license them to this
project under the license that applies to the file being changed — CC BY-SA 4.0
for skill content and documentation, Apache-2.0 for code. There is no CLA.