ADR-005: Keycloak for Identity Management
6/1/25Less than 1 minuteArchitecture Decisions RecordsADR
ADR-005: Keycloak for Identity Management
Status
Accepted - December 2024
Context
The system requires secure authentication and authorization with support for:
- Multiple identity providers (Google, Microsoft, GitHub)
- Modern authentication protocols (OAuth 2.0, OIDC, SAML)
- Fine-grained authorization (role-based and attribute-based access control)
- Multi-tenant support for different user types
- Admin console for user and role management
- Integration with microservices architecture
Decision
Use Keycloak as the identity and access management solution.
Rationale
- Standard Protocols: Full OAuth 2.0, OIDC, and SAML support
- Identity Federation: Seamless integration with external identity providers
- Authorization: Role-based and attribute-based access control
- Admin Interface: Comprehensive web-based administration
- Open Source: No vendor lock-in with strong community support
- Scalability: Proven in enterprise environments
Implementation
Integration Architecture
Authentication Flow
public static class AuthenticationExtensions
{
public static IHostApplicationBuilder AddDefaultAuthentication(
this IHostApplicationBuilder builder,
string realm = "bookworm"
)
{
var services = builder.Services;
services
.AddAuthentication(options =>
{
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddKeycloakJwtBearer(
Components.KeyCloak,
realm,
options =>
{
options.RequireHttpsMetadata = false;
options.Audience = "account";
}
);
services
.AddAuthorizationBuilder()
.AddPolicy(
Authorization.Policies.Admin,
policy => policy.RequireRole(Authorization.Roles.Admin)
)
.AddPolicy(Authorization.Policies.User, policy => policy.RequireAuthenticatedUser())
.SetDefaultPolicy(new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build());
return builder;
}
}
Consequences
Positive
- Industry-standard security protocols
- Centralized identity management
- Rich admin console and user self-service
- Strong community and enterprise support
Negative
- Additional infrastructure component
- Complex initial setup and configuration
- Potential single point of failure