keycloak
Keycloak identity and access management including realms, clients, authentication flows, themes, and user federation. Activate for OAuth2, OIDC, SAML, SSO, identity providers, and authentication configuration.
When & Why to Use This Skill
This Claude skill provides comprehensive management for Keycloak Identity and Access Management (IAM). It enables the automated configuration of realms, clients, and authentication flows while supporting industry-standard protocols like OAuth2, OIDC, and SAML. By streamlining complex tasks such as user federation, SSO integration, and security auditing, it ensures robust and scalable access control for modern application infrastructures.
Use Cases
- Automating the setup and lifecycle management of Keycloak realms, clients, and role-based access control (RBAC).
- Implementing and testing advanced authentication flows, including Multi-Factor Authentication (MFA), OTP, and WebAuthn.
- Integrating Single Sign-On (SSO) capabilities with external identity providers and social logins using OIDC or SAML.
- Configuring user federation with LDAP or Active Directory to synchronize and manage corporate identities.
- Customizing Keycloak themes and security policies, including token lifespan and brute-force protection settings.
| name | keycloak |
|---|---|
| description | Keycloak identity and access management including realms, clients, authentication flows, themes, and user federation. Activate for OAuth2, OIDC, SAML, SSO, identity providers, and authentication configuration. |
Keycloak Skill
Provides comprehensive Keycloak identity and access management capabilities for the Alpha Members Platform.
When to Use This Skill
Activate this skill when working with:
- Keycloak realm configuration
- Client setup and management
- Authentication flows (MFA, OTP, WebAuthn)
- User federation (LDAP, Active Directory)
- Identity providers (SAML, OIDC, social login)
- Theme customization
- Role-based access control
Quick Reference
Common Commands
# Start Keycloak in dev mode
docker-compose up keycloak keycloak-db -d
# Export realm configuration
docker exec keycloak /opt/keycloak/bin/kc.sh export \
--realm alpha-members \
--dir /tmp/export \
--users realm_file
# Import realm
docker exec keycloak /opt/keycloak/bin/kc.sh import \
--dir /opt/keycloak/data/import
# Get admin token
curl -X POST "http://localhost:8080/realms/master/protocol/openid-connect/token" \
-d "client_id=admin-cli" \
-d "username=admin" \
-d "password=admin" \
-d "grant_type=password"
# Health check
curl http://localhost:8080/health/ready
Admin REST API
# Base URL
KEYCLOAK_URL="http://localhost:8080"
REALM="alpha-members"
# List users
curl -H "Authorization: Bearer $TOKEN" \
"$KEYCLOAK_URL/admin/realms/$REALM/users"
# Create client
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
"$KEYCLOAK_URL/admin/realms/$REALM/clients" \
-d '{"clientId": "new-client", "enabled": true}'
# Get realm roles
curl -H "Authorization: Bearer $TOKEN" \
"$KEYCLOAK_URL/admin/realms/$REALM/roles"
Realm Configuration
alpha-members Realm
{
"realm": "alpha-members",
"enabled": true,
"sslRequired": "external",
"registrationAllowed": true,
"registrationEmailAsUsername": true,
"verifyEmail": true,
"bruteForceProtected": true,
"failureFactor": 5,
"maxFailureWaitSeconds": 900
}
Default Roles
- admin - Full administrative access
- member - Standard member access
- guest - Limited guest access
Client Roles (member-api)
- members:read
- members:write
- members:delete
- members:admin
Authentication Flows
Browser Flow (Default)
- Cookie (ALTERNATIVE)
- Identity Provider Redirector (ALTERNATIVE)
- Forms:
- Username/Password (REQUIRED)
- Conditional OTP (CONDITIONAL)
Custom MFA Flow
alpha-mfa-flow:
- Username Password Form (REQUIRED)
- Conditional OTP:
- Condition: User Role (admin)
- OTP Form (REQUIRED)
Client Configuration
member-api (Backend Service)
{
"clientId": "member-api",
"enabled": true,
"clientAuthenticatorType": "client-secret",
"serviceAccountsEnabled": true,
"directAccessGrantsEnabled": true,
"publicClient": false,
"protocol": "openid-connect"
}
member-ui (Frontend SPA)
{
"clientId": "member-ui",
"enabled": true,
"publicClient": true,
"standardFlowEnabled": true,
"implicitFlowEnabled": false,
"directAccessGrantsEnabled": false,
"redirectUris": ["http://localhost:3000/*"],
"webOrigins": ["+"],
"protocol": "openid-connect",
"attributes": {
"pkce.code.challenge.method": "S256"
}
}
Token Configuration
Access Token Lifespan: 1 hour (3600s)
Implicit Flow Lifespan: 15 minutes (900s)
SSO Session Idle: 30 minutes (1800s)
SSO Session Max: 10 hours (36000s)
Offline Session Idle: 30 days (2592000s)
OIDC Endpoints
Authorization: /realms/alpha-members/protocol/openid-connect/auth
Token: /realms/alpha-members/protocol/openid-connect/token
UserInfo: /realms/alpha-members/protocol/openid-connect/userinfo
Logout: /realms/alpha-members/protocol/openid-connect/logout
JWKS: /realms/alpha-members/protocol/openid-connect/certs
Discovery: /realms/alpha-members/.well-known/openid-configuration
Theme Customization
Theme Structure
keycloak/themes/alpha/
├── theme.properties
├── login/
│ ├── theme.properties
│ ├── resources/css/login.css
│ └── messages/messages_en.properties
├── account/
└── email/
Theme Properties
parent=keycloak
import=common/keycloak
styles=css/login.css
locales=en
User Federation
LDAP Configuration
Vendor: Active Directory
Connection URL: ldaps://ldap.corporate.com:636
Users DN: OU=Users,DC=corporate,DC=com
Username Attribute: sAMAccountName
Edit Mode: READ_ONLY
Sync Mode: IMPORT
Security Best Practices
- Enable brute force protection
- Require email verification
- Use SSL/TLS in production (sslRequired: all)
- Configure proper token lifetimes
- Enable audit logging
- Use PKCE for public clients
- Implement MFA for admin roles
Project Files
- Realm Config:
keycloak/realm-config/alpha-realm.json - Docker:
docker/docker-compose.yml(keycloak service) - Themes:
keycloak/themes/alpha/
Related Agents
- keycloak-realm-admin - Realm and client management
- keycloak-theme-developer - Theme customization
- keycloak-identity-specialist - Federation and SSO
- keycloak-auth-flow-designer - Authentication flows
- keycloak-security-auditor - Security review
Troubleshooting
# Check Keycloak logs
docker logs keycloak -f --tail=100
# Test OIDC configuration
curl http://localhost:8080/realms/alpha-members/.well-known/openid-configuration
# Validate token
curl -X POST "http://localhost:8080/realms/alpha-members/protocol/openid-connect/token/introspect" \
-d "client_id=member-api" \
-d "client_secret=$CLIENT_SECRET" \
-d "token=$ACCESS_TOKEN"