Authentication & Authorization¶
Overview¶
VitalBridge uses a centralized identity architecture built around Keycloak.
Authentication and authorization are separated from business services and managed through standardized JWT access tokens.
The platform implements:
- Authentication
- Authorization
- Role-Based Access Control (RBAC)
- Tenant Isolation
- Service-Level Security Enforcement
Every request must be authenticated, authorized, and validated against tenant boundaries before business operations are executed.
Identity Architecture¶
VitalBridge delegates identity management to Keycloak.
flowchart TB
USER["User"]
KC["Keycloak"]
TOKEN["JWT Access Token"]
GATEWAY["API Gateway"]
SERVICE["Domain Service"]
USER --> KC
KC --> TOKEN
TOKEN --> GATEWAY
GATEWAY --> SERVICEKeycloak is responsible for:
- User authentication
- Access token issuance
- Refresh token management
- Role assignment
- Identity federation
Business services never authenticate users directly.
Authentication Flow¶
The authentication process begins when a user signs in.
sequenceDiagram
participant User
participant Keycloak
participant Gateway
participant Service
User->>Keycloak: Login
Keycloak-->>User: Access Token
User->>Gateway: Request + JWT
Gateway->>Gateway: Validate Token
Gateway->>Service: Forward Request
Service-->>User: ResponseOnly authenticated requests are allowed to reach domain services.
JWT Access Token¶
Every authenticated request includes a JWT access token.
The token contains identity and authorization information.
flowchart LR
JWT["JWT Token"]
SUB["User ID"]
ROLE["Role"]
TENANT["Tenant ID"]
EMAIL["Email"]
JWT --> SUB
JWT --> ROLE
JWT --> TENANT
JWT --> EMAILTypical claims include:
- user_id
- tenant_id
- role
- permissions
Services use these claims to enforce security policies.
Role-Based Access Control¶
VitalBridge uses RBAC to control platform access.
flowchart TB
SUPER["ROLE_SUPER_ADMIN"]
TENANT["ROLE_TENANT_ADMIN"]
PROVIDER["ROLE_PROVIDER"]
PATIENT["ROLE_PATIENT"]Super Administrator¶
Platform-wide access.
Responsibilities:
- Tenant onboarding
- Tenant lifecycle management
- Platform administration
Can access:
- All tenants
Tenant Administrator¶
Organization-level access.
Responsibilities:
- Manage providers
- Manage patients
- Configure tenant settings
Can access:
- Their tenant only
Provider¶
Clinical access.
Responsibilities:
- Manage schedules
- View appointments
- Conduct consultations
Can access:
- Their tenant only
Patient¶
Patient access.
Responsibilities:
- Book appointments
- Manage profile
- Attend consultations
Can access:
- Their own resources
Tenant Context¶
Authentication alone is insufficient.
Every request must also belong to a tenant.
flowchart LR
USER["Authenticated User"]
TOKEN["JWT"]
TENANT["Tenant Context"]
SERVICE["Domain Service"]
USER --> TOKEN
TOKEN --> TENANT
TENANT --> SERVICEThis ensures that users cannot access resources owned by another tenant.
Authorization Flow¶
Authorization occurs at multiple layers.
flowchart LR
REQUEST["Incoming Request"]
AUTH["Validate JWT"]
ROLE["Validate Role"]
TENANT["Validate Tenant"]
RESOURCE["Validate Ownership"]
EXECUTE["Execute Business Logic"]
REQUEST --> AUTH
AUTH --> ROLE
ROLE --> TENANT
TENANT --> RESOURCE
RESOURCE --> EXECUTEEvery step must succeed before the request is processed.
Service-Level Enforcement¶
The API Gateway performs initial validation.
However, domain services must perform their own security checks.
flowchart LR
USER["User"]
GW["API Gateway"]
SERVICE["Domain Service"]
USER --> GW
GW --> SERVICE
GW -->|"Authenticated"| SERVICE
SERVICE -->|"Authorize"| SERVICESecurity must never rely solely on gateway validation.
Each service independently validates:
- Roles
- Tenant ownership
- Resource ownership
Resource Ownership¶
Authorization extends beyond roles.
Example:
A patient may access only their own appointments.
flowchart LR
PATIENT["Patient"]
APPT1["Own Appointment"]
APPT2["Other Patient Appointment"]
PATIENT --> APPT1
PATIENT -. Access Denied .-> APPT2Similarly:
- Providers may access only their schedules
- Patients may access only their records
- Tenant Administrators may access only tenant-owned resources
Security Principles¶
VitalBridge follows several core security principles.
Least Privilege¶
Users receive only the permissions necessary to perform their duties.
Defense in Depth¶
Security is enforced at:
- Gateway Layer
- Service Layer
- Database Layer
Zero Trust¶
No service trusts incoming requests without validation.
Tenant Isolation¶
Tenant boundaries are enforced independently of role validation.
Security Architecture¶
flowchart TB
USER["User"]
KC["Keycloak"]
GW["API Gateway"]
SERVICES["Domain Services"]
USER --> KC
KC --> GW
GW --> SERVICES
SERVICES -->|"Role Validation"| SERVICES
SERVICES -->|"Tenant Validation"| SERVICES
SERVICES -->|"Resource Validation"| SERVICESArchitectural Rules¶
VitalBridge enforces the following rules:
Required¶
- All requests must be authenticated
- All requests must contain tenant context
- All services must validate authorization
- Resource ownership must be verified
- JWT tokens must be validated
Forbidden¶
- Anonymous access
- Cross-tenant access
- Shared credentials
- Trusting gateway authorization alone
- Direct service bypass
Relationship to Other Architectural Patterns¶
Authentication and authorization work alongside other platform patterns.
flowchart TB
AUTH["Authentication"]
RBAC["Authorization"]
TENANT["Multi-Tenancy"]
CQRS["CQRS"]
EVENTS["Event-Driven Architecture"]
AUTH --> RBAC
RBAC --> TENANT
TENANT --> CQRS
CQRS --> EVENTSTogether these patterns provide the foundation for a secure, multi-tenant healthcare platform.