-
Notifications
You must be signed in to change notification settings - Fork 0
Core Concepts Authentication and Authorization Model
Referenced Files in This Document
- auth-overview.md
- http-auth-middleware.ts
- http-auth-callback.ts
- http-auth-oidc-redirect.ts
- bearer-validate.ts
- oidc-state-store.ts
- keycloak README.md
- kairos-realm.json
- deploy-configure-keycloak-realms.py
- audit-log.md
- oauth-refresh.ts
- token.ts
- login.ts
- logout.ts
- spaces.ts
- protected-space-write-guard.ts
- Introduction
- Authentication Architecture Overview
- OIDC Integration
- Token Management
- Role-Based Access Control
- Space-Based Permissions
- Protected Resources
- Session Management
- Keycloak Configuration
- Audit Logging
- Security Best Practices
- Troubleshooting Guide
- Conclusion
This document provides comprehensive coverage of the authentication and authorization model implemented in the system. It explains how OpenID Connect (OIDC) integration works, token management strategies, role-based access control (RBAC), space-based permissions, and fine-grained access control mechanisms. The document also covers Keycloak integration, audit logging for security compliance, and security best practices for secure deployment.
The authentication system is built around modern OIDC standards, providing secure user authentication through external identity providers while maintaining robust authorization controls at both resource and space levels.
The authentication architecture follows a distributed model where the application integrates with an OIDC-compliant identity provider (Keycloak) to handle user authentication. The system implements multiple authentication flows for different client types including web browsers, CLI applications, and API clients.
graph TB
subgraph "Client Layer"
WebUI[Web UI]
CLI[CLI Application]
API[API Clients]
end
subgraph "Application Layer"
AuthMiddleware[Auth Middleware]
TokenValidator[Token Validator]
SessionManager[Session Manager]
RBAC[RBAC Engine]
end
subgraph "Identity Provider"
Keycloak[Keycloak Server]
UserStore[User Database]
RoleStore[Role Store]
end
subgraph "Storage Layer"
Redis[(Redis Cache)]
AppDB[(Application DB)]
end
WebUI --> AuthMiddleware
CLI --> AuthMiddleware
API --> AuthMiddleware
AuthMiddleware --> TokenValidator
TokenValidator --> Keycloak
TokenValidator --> Redis
RBAC --> RoleStore
RBAC --> AppDB
SessionManager --> Redis
SessionManager --> AppDB
Keycloak --> UserStore
Keycloak --> RoleStore
Diagram sources
Section sources
The system implements full OpenID Connect integration with Keycloak as the primary identity provider. The OIDC flow supports standard authorization code flow with PKCE for enhanced security.
sequenceDiagram
participant Client as "Client Application"
participant App as "Kairos App"
participant Keycloak as "Keycloak Server"
participant StateStore as "OIDC State Store"
Client->>App : GET /auth/oidc/redirect
App->>StateStore : Generate state + nonce
App->>Keycloak : Redirect with auth request
Note over App,Keycloak : Includes PKCE challenge
Keycloak-->>Client : Login page
Client->>Keycloak : User credentials
Keycloak-->>App : Callback with code + state
App->>StateStore : Validate state
App->>Keycloak : Exchange code for tokens
Keycloak-->>App : Access token + ID token + refresh token
App->>App : Create session
App-->>Client : Set session cookie
Diagram sources
The OIDC configuration includes support for multiple identity providers, custom scopes, and claim mapping. The system validates OIDC responses and extracts user claims for authorization decisions.
Section sources
The system implements comprehensive token management including JWT validation, refresh token handling, and token caching strategies.
flowchart TD
Start([Token Request]) --> Validate["Validate Token Format"]
Validate --> CheckCache{"Token in Cache?"}
CheckCache --> |Yes| ReturnCached["Return Cached Token"]
CheckCache --> |No| ValidateRemote["Validate with Identity Provider"]
ValidateRemote --> Valid{"Token Valid?"}
Valid --> |No| RefreshFlow["Initiate Refresh Flow"]
Valid --> |Yes| ExtractClaims["Extract User Claims"]
ExtractClaims --> CacheToken["Cache Token"]
CacheToken --> SetExpiry["Set Expiration"]
SetExpiry --> ReturnToken["Return Token"]
RefreshFlow --> GetRefreshToken["Get Refresh Token"]
GetRefreshToken --> ExchangeTokens["Exchange for New Tokens"]
ExchangeTokens --> UpdateCache["Update Cache"]
UpdateCache --> ReturnNewToken["Return New Token"]
ReturnCached --> End([Token Available])
ReturnNewToken --> End
ReturnToken --> End
Diagram sources
The system supports multiple token types including access tokens, ID tokens, and refresh tokens. Each token type has specific scopes and expiration policies.
Section sources
The authorization system implements role-based access control (RBAC) that maps user roles to specific permissions across resources and spaces.
classDiagram
class User {
+string id
+string username
+string email
+Role[] roles
+Permission[] permissions
}
class Role {
+string name
+Permission[] permissions
+boolean isSystemRole
}
class Permission {
+string resource
+string action
+string scope
}
class Space {
+string id
+string name
+Role[] roles
+Permission[] permissions
}
class Resource {
+string id
+string type
+string owner
+Permission[] permissions
}
User --> Role : "has many"
Role --> Permission : "contains"
Space --> Role : "defines"
Resource --> Permission : "requires"
User --> Space : "accesses"
User --> Resource : "operates on"
Diagram sources
The permission evaluation engine checks user roles against required permissions for each resource operation. It supports hierarchical role inheritance and space-scoped permissions.
Section sources
Spaces provide a namespace isolation mechanism with granular access control. Each space can have its own set of users, roles, and permissions.
erDiagram
SPACE {
uuid id PK
string name
string description
timestamp created_at
boolean is_protected
}
SPACE_ROLE {
uuid id PK
uuid space_id FK
string role_name
array permissions
}
SPACE_USER {
uuid id PK
uuid space_id FK
uuid user_id FK
uuid role_id FK
}
RESOURCE {
uuid id PK
string type
string content
uuid space_id FK
uuid owner_id FK
timestamp created_at
}
SPACE ||--o{ SPACE_ROLE : "has many"
SPACE ||--o{ SPACE_USER : "contains"
SPACE ||--o{ RESOURCE : "owns"
SPACE_USER }o--|| SPACE_ROLE : "assigned"
Diagram sources
The system enforces space-based access control for all CRUD operations. Protected spaces require explicit permissions even for space members.
Section sources
Protected resources implement fine-grained access control with support for ownership-based permissions, inherited permissions, and dynamic authorization rules.
Resources are protected at multiple levels:
- Public: No authentication required
- Authenticated: Requires valid user session
- Space-scoped: Requires space membership
- Protected: Requires explicit write permissions
- Admin-only: Requires administrative privileges
The authorization system supports dynamic rules that can evaluate context-specific conditions beyond simple role checks.
Section sources
The system implements secure session management with support for concurrent sessions, session persistence, and automatic cleanup.
stateDiagram-v2
[*] --> Unauthenticated
Unauthenticated --> Authenticating : "Start OIDC Flow"
Authenticating --> Active : "Login Success"
Authenticating --> Failed : "Login Error"
Active --> Refreshing : "Token Expiring"
Refreshing --> Active : "Token Refreshed"
Refreshing --> Expired : "Refresh Failed"
Active --> Idle : "Inactivity Timeout"
Idle --> Active : "Activity Detected"
Active --> Logout : "Logout Request"
Expired --> Unauthenticated : "Re-authentication Required"
Logout --> Unauthenticated
Failed --> Unauthenticated
Diagram sources
Sessions are stored in Redis with configurable TTL and support for distributed session sharing across multiple application instances.
Section sources
Keycloak serves as the primary identity provider with comprehensive configuration options for realms, clients, and user management.
The Keycloak realm configuration defines the authentication domain, including user attributes, roles, and client settings.
Clients are registered with specific redirect URIs, scopes, and authentication flows tailored to different use cases.
Section sources
The system implements comprehensive audit logging for security compliance and threat detection. All authentication events, authorization decisions, and sensitive operations are logged with detailed context.
flowchart LR
subgraph "Authentication Events"
LOGIN_SUCCESS["Login Success"]
LOGIN_FAILURE["Login Failure"]
TOKEN_REFRESH["Token Refresh"]
SESSION_CREATE["Session Created"]
SESSION_DESTROY["Session Destroyed"]
end
subgraph "Authorization Events"
ACCESS_GRANTED["Access Granted"]
ACCESS_DENIED["Access Denied"]
PERMISSION_CHECK["Permission Check"]
ROLE_ASSIGNMENT["Role Assignment"]
end
subgraph "Resource Operations"
RESOURCE_READ["Resource Read"]
RESOURCE_WRITE["Resource Write"]
RESOURCE_DELETE["Resource Delete"]
SPACE_ACCESS["Space Access"]
end
LOGIN_SUCCESS --> AUDIT_LOG["Audit Log"]
LOGIN_FAILURE --> AUDIT_LOG
TOKEN_REFRESH --> AUDIT_LOG
SESSION_CREATE --> AUDIT_LOG
SESSION_DESTROY --> AUDIT_LOG
ACCESS_GRANTED --> AUDIT_LOG
ACCESS_DENIED --> AUDIT_LOG
PERMISSION_CHECK --> AUDIT_LOG
ROLE_ASSIGNMENT --> AUDIT_LOG
RESOURCE_READ --> AUDIT_LOG
RESOURCE_WRITE --> AUDIT_LOG
RESOURCE_DELETE --> AUDIT_LOG
SPACE_ACCESS --> AUDIT_LOG
Diagram sources
Audit logs support real-time monitoring, alerting, and compliance reporting. Logs include user context, IP addresses, user agents, and detailed operation metadata.
Section sources
The authentication and authorization system follows industry best practices for secure implementation and deployment.
- PKCE Implementation: All OAuth2 flows use Proof Key for Code Exchange (PKCE) to prevent authorization code interception attacks
- Secure Token Storage: Tokens are stored securely with appropriate encryption and access controls
- Session Security: Sessions use secure cookies with HttpOnly, Secure, and SameSite flags
- Rate Limiting: Authentication endpoints implement rate limiting to prevent brute force attacks
- Principle of Least Privilege: Default deny policy with explicit allow rules
- Defense in Depth: Multiple layers of authorization checks at different system levels
- Input Validation: Comprehensive input validation and sanitization
- Context-Aware Authorization: Authorization decisions consider user context, resource sensitivity, and operational environment
- TLS Enforcement: All communications encrypted with TLS 1.3
- Secrets Management: Sensitive configuration managed through secure secret stores
- Network Isolation: Services deployed in isolated network segments
- Regular Security Audits: Automated vulnerability scanning and manual security reviews
Common authentication and authorization issues and their resolution steps.
Problem: Users cannot log in through OIDC
- Verify Keycloak connectivity and certificate validity
- Check redirect URI configuration matches exactly
- Validate client secrets and scopes
- Review browser console for CORS errors
Problem: Token validation failures
- Ensure clock synchronization between services
- Verify token signing keys are properly configured
- Check token expiration and refresh token validity
- Review token format and claim structure
Problem: Users lack expected permissions
- Verify role assignments in Keycloak
- Check space membership and role inheritance
- Review resource-level permission configurations
- Validate authorization rule logic
Problem: Space access denied
- Confirm user has space membership
- Check if space is marked as protected
- Verify write permissions for modification operations
- Review space owner permissions
Problem: Slow authentication responses
- Monitor Keycloak response times
- Check Redis performance for session storage
- Review token validation cache hit rates
- Analyze database query performance for permission checks
Section sources
The authentication and authorization model provides a comprehensive, secure, and scalable foundation for user access control. The system leverages modern OIDC standards, implements robust role-based and space-based permissions, and maintains detailed audit trails for security compliance.
Key strengths include:
- Standards Compliance: Full OIDC compatibility with industry best practices
- Granular Control: Fine-grained permissions at resource and space levels
- Scalability: Distributed architecture supporting high availability
- Security: Multiple layers of security controls and monitoring
- Flexibility: Extensible authorization framework supporting custom rules
The system is designed to evolve with changing security requirements while maintaining backward compatibility and operational simplicity.
-
- Authentication and Authorization Model
- Model Context Protocol (MCP) Fundamentals
- Tool and Adapter System
- Memory and Semantic Search System
- Workflow Orchestration Engine