Sankofa/docs/tenants/IDENTITY_SETUP.md

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:

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

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:

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:

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