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`:

```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