Apply Composer changes: comprehensive API updates, migrations, middleware, and infrastructure improvements
- Add comprehensive database migrations (001-024) for schema evolution - Enhance API schema with expanded type definitions and resolvers - Add new middleware: audit logging, rate limiting, MFA enforcement, security, tenant auth - Implement new services: AI optimization, billing, blockchain, compliance, marketplace - Add adapter layer for cloud integrations (Cloudflare, Kubernetes, Proxmox, storage) - Update Crossplane provider with enhanced VM management capabilities - Add comprehensive test suite for API endpoints and services - Update frontend components with improved GraphQL subscriptions and real-time updates - Enhance security configurations and headers (CSP, CORS, etc.) - Update documentation and configuration files - Add new CI/CD workflows and validation scripts - Implement design system improvements and UI enhancements
This commit is contained in:
defiQUG
198
docs/tenants/IDENTITY_SETUP.md
Normal file
198
docs/tenants/IDENTITY_SETUP.md
Normal file
@@ -0,0 +1,198 @@
|
||||
# Identity Setup Guide - Keycloak Configuration
|
||||
|
||||
Guide for setting up sovereign identity management using Keycloak (NO Azure dependencies).
|
||||
|
||||
## Overview
|
||||
|
||||
Sankofa Phoenix uses Keycloak for identity management, providing a sovereign alternative to Azure AD with superior features:
|
||||
|
||||
- **Self-hosted**: No Microsoft dependencies
|
||||
- **Multi-realm support**: One realm per tenant for complete isolation
|
||||
- **Flexible authentication**: Custom flows, multiple providers
|
||||
- **Fine-grained permissions**: Beyond Azure RBAC
|
||||
- **Blockchain integration**: Optional blockchain-based identity verification
|
||||
|
||||
## Keycloak Installation
|
||||
|
||||
### Docker Compose
|
||||
|
||||
Keycloak is included in `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
keycloak:
|
||||
image: quay.io/keycloak/keycloak:latest
|
||||
environment:
|
||||
KEYCLOAK_ADMIN: admin
|
||||
KEYCLOAK_ADMIN_PASSWORD: admin
|
||||
KC_DB: postgres
|
||||
KC_DB_URL_HOST: postgres
|
||||
KC_DB_URL_DATABASE: keycloak
|
||||
KC_DB_USERNAME: postgres
|
||||
KC_DB_PASSWORD: postgres
|
||||
KC_HTTP_ENABLED: "true"
|
||||
ports:
|
||||
- "8080:8080"
|
||||
command: start-dev
|
||||
```
|
||||
|
||||
### Kubernetes Deployment
|
||||
|
||||
See `gitops/apps/keycloak/` for Kubernetes manifests.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```env
|
||||
KEYCLOAK_URL=https://keycloak.sankofa.nexus
|
||||
KEYCLOAK_REALM=master
|
||||
KEYCLOAK_CLIENT_ID=sankofa-api
|
||||
KEYCLOAK_CLIENT_SECRET=your-client-secret
|
||||
KEYCLOAK_MULTI_REALM=true
|
||||
```
|
||||
|
||||
### Multi-Realm Support
|
||||
|
||||
Enable multi-realm support for tenant isolation:
|
||||
|
||||
```env
|
||||
KEYCLOAK_MULTI_REALM=true
|
||||
```
|
||||
|
||||
When enabled, each tenant gets its own Keycloak realm automatically.
|
||||
|
||||
## Client Configuration
|
||||
|
||||
### API Client
|
||||
|
||||
1. Log in to Keycloak admin console
|
||||
2. Create new client:
|
||||
- Client ID: `sankofa-api`
|
||||
- Client Protocol: `openid-connect`
|
||||
- Access Type: `confidential`
|
||||
- Valid Redirect URIs: `*`
|
||||
- Service Accounts Enabled: `ON`
|
||||
|
||||
3. Get client secret from Credentials tab
|
||||
|
||||
### Portal Client
|
||||
|
||||
1. Create new client:
|
||||
- Client ID: `portal-client`
|
||||
- Client Protocol: `openid-connect`
|
||||
- Access Type: `confidential`
|
||||
- Valid Redirect URIs: `http://localhost:3000/*`
|
||||
- Web Origins: `http://localhost:3000`
|
||||
|
||||
## Identity Providers
|
||||
|
||||
### SAML Provider
|
||||
|
||||
Configure SAML provider for enterprise SSO:
|
||||
|
||||
1. Go to Identity Providers
|
||||
2. Add SAML provider
|
||||
3. Configure:
|
||||
- Alias: `saml-enterprise`
|
||||
- Display Name: `Enterprise SAML`
|
||||
- First Broker Login Flow: `first broker login`
|
||||
- Post Broker Login Flow: `browser`
|
||||
|
||||
### OIDC Provider
|
||||
|
||||
Configure OIDC provider for federated identity:
|
||||
|
||||
1. Go to Identity Providers
|
||||
2. Add OpenID Connect provider
|
||||
3. Configure:
|
||||
- Alias: `oidc-provider`
|
||||
- Provider URL: `https://provider.example.com`
|
||||
- Client ID: `client-id`
|
||||
- Client Secret: `client-secret`
|
||||
|
||||
### LDAP Provider
|
||||
|
||||
Configure LDAP for directory integration:
|
||||
|
||||
1. Go to User Federation
|
||||
2. Add LDAP provider
|
||||
3. Configure connection settings
|
||||
4. Sync users and groups
|
||||
|
||||
## Custom Authentication Flows
|
||||
|
||||
Create custom authentication flows (more flexible than Azure AD):
|
||||
|
||||
1. Go to Authentication
|
||||
2. Create new flow
|
||||
3. Add execution providers:
|
||||
- Username/Password form
|
||||
- OTP form
|
||||
- Blockchain verification (custom)
|
||||
- Conditional OTP
|
||||
|
||||
## Blockchain Identity Verification
|
||||
|
||||
Enable blockchain-based identity verification (unique to Phoenix):
|
||||
|
||||
1. Set `BLOCKCHAIN_IDENTITY_ENABLED=true`
|
||||
2. Configure blockchain RPC URL
|
||||
3. Identity verification is performed on-chain
|
||||
4. Immutable identity records
|
||||
|
||||
## Tenant Realm Creation
|
||||
|
||||
When a tenant is created, a Keycloak realm is automatically created if `KEYCLOAK_MULTI_REALM=true`:
|
||||
|
||||
- Realm name: Tenant ID
|
||||
- Display name: Tenant name
|
||||
- Enabled: True
|
||||
- Users can authenticate to tenant-specific realm
|
||||
|
||||
## User Management
|
||||
|
||||
### Adding Users to Tenant
|
||||
|
||||
Users are added to tenant via the API:
|
||||
|
||||
```graphql
|
||||
mutation {
|
||||
addUserToTenant(
|
||||
tenantId: "tenant-id"
|
||||
userId: "user-id"
|
||||
role: TENANT_ADMIN
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Roles and Permissions
|
||||
|
||||
Tenant roles are more granular than Azure RBAC:
|
||||
|
||||
- **TENANT_OWNER**: Full control
|
||||
- **TENANT_ADMIN**: Administrative access
|
||||
- **TENANT_USER**: Standard access
|
||||
- **TENANT_VIEWER**: Read-only
|
||||
- **TENANT_BILLING_ADMIN**: Billing management
|
||||
|
||||
Additional permissions can be set via JSON for fine-grained control.
|
||||
|
||||
## Comparison to Azure AD
|
||||
|
||||
| Feature | Azure AD | Keycloak (Phoenix) |
|
||||
|---------|----------|-------------------|
|
||||
| Self-hosted | No | Yes |
|
||||
| Multi-realm | Limited | Full support |
|
||||
| Custom flows | Limited | Full support |
|
||||
| Permissions | RBAC only | RBAC + JSON |
|
||||
| Blockchain | No | Yes |
|
||||
| Cost | Per-user licensing | Open source |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use strong passwords**: Enforce password policies
|
||||
2. **Enable MFA**: Require multi-factor authentication
|
||||
3. **Regular audits**: Review user access regularly
|
||||
4. **Monitor logs**: Track authentication attempts
|
||||
5. **Backup realms**: Export realm configurations regularly
|
||||
|
||||
Reference in New Issue
Block a user