@cdmbase/wiki-browser 12.0.18-alpha.10

package/lib/templates/content/docs/adminide-modules/project-tools/auth-providers.md

@@ -0,0 +1,1317 @@
+# Auth Provider Management System - Comprehensive Documentation
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [What This Functionality Is About](#what-this-functionality-is-about)
+3. [How to Execute the Functionality](#how-to-execute-the-functionality)
+4. [Implementation Details](#implementation-details)
+5. [State Management](#state-management)
+6. [GraphQL Integration](#graphql-integration)
+7. [Backend Architecture & Inngest Integration](#backend-architecture--inngest-integration)
+8. [Important Notes and Best Practices](#important-notes-and-best-practices)
+
+---
+
+## Overview
+
+The Auth Provider Management System enables organizations to configure and manage authentication providers (Keycloak and Auth0) for their tenants. It provides a comprehensive interface for creating, updating, testing, and managing authentication configurations with support for both managed and self-hosted Keycloak instances.
+
+**Primary Entry Point:** `AuthProvidersManagement.tsx`
+
+---
+
+## What This Functionality Is About
+
+### Core Purpose
+
+The Auth Provider Management System enables organizations to:
+
+1. **Configure Authentication Providers**: Set up Keycloak or Auth0 authentication for tenants
+2. **Manage Provider Settings**: Configure realms, clients, redirect URIs, and identity providers
+3. **Test Credentials**: Verify authentication provider configurations work correctly
+4. **Support Multiple Deployment Types**: Handle both managed and self-hosted Keycloak instances
+5. **Tenant Association**: Link authentication providers to specific tenants within an organization
+
+### Key Features
+
+- ✅ **Multi-Provider Support**: Keycloak (managed/self-hosted) and Auth0
+- ✅ **Realm Management**: Create and configure Keycloak realms
+- ✅ **Client Configuration**: Manage OAuth2/OIDC clients with redirect URIs
+- ✅ **Identity Provider Integration**: Configure social login providers (Google, GitHub, etc.)
+- ✅ **Credential Testing**: Test authentication provider credentials before saving
+- ✅ **Secret Management**: Secure storage of admin credentials and client secrets
+- ✅ **Environment-Based Configuration**: Associate providers with environment tags
+- ✅ **State Machine Management**: Predictable state transitions using XState
+
+---
+
+## How to Execute the Functionality
+
+### Accessing the Auth Provider Management
+
+1. **Navigate to the Route**: Access via organization route with `orgName` parameter
+2. **Prerequisites**:
+    - User must be authenticated
+    - User must have appropriate permissions for the organization
+    - At least one tenant must exist in the organization
+
+### Creating a New Auth Provider
+
+1. **Click "Create New Auth Provider" Button**: Located in the header
+2. **Select Tenant**: Choose a tenant from the modal (only tenants without existing providers are recommended)
+3. **Choose Provider Type**: Select Keycloak or Auth0
+4. **Configure Settings**:
+    - **Keycloak**: Realm name, redirect URIs, signup settings, identity providers
+    - **Auth0**: Domain, client ID, client secret, redirect URI
+5. **Test Credentials** (Optional): Click "Test" to verify configuration
+6. **Submit**: Click "Save" to create the provider
+7. **Result**: Provider is created, modal closes, list refreshes
+
+### Viewing Auth Provider Details
+
+1. **Expand Provider**: Click on any provider card to expand and view details
+2. **View Configuration**: See realm name, client ID, domain, and other settings
+3. **View Identity Providers**: See configured social login providers (for Keycloak)
+
+### Editing an Auth Provider
+
+1. **Click "Edit" Button**: Located in the action buttons for each provider
+2. **Modify Settings**: Update realm name, redirect URIs, identity providers, etc.
+3. **Test Credentials** (Optional): Verify changes work
+4. **Submit**: Click "Save" to update
+5. **Result**: Provider is updated, modal closes, list refreshes
+
+### Testing Credentials
+
+1. **Click "Test" Button**: Located in the action buttons
+2. **Wait for Result**: System attempts to obtain OAuth2 token
+3. **View Result**: Success or error message displayed inline
+4. **Interpret Results**:
+    - **Success**: Green notification with token details
+    - **Failure**: Red notification with error details
+
+### Viewing Configuration Details
+
+1. **Click "Configuration" Button**: Opens modal with saved configuration
+2. **View Secrets**: See Realm Name, Client ID, Client Secret, Keycloak URL
+3. **Copy to Clipboard**: Click 📋 button to copy any field
+
+### Deleting an Auth Provider
+
+1. **Click "Delete" Button**: Located in the action buttons
+2. **Confirm**: Confirm deletion in the modal
+3. **Result**: Provider is deleted, Keycloak realm removed (if managed), secrets cleaned up
+
+---
+
+## Implementation Details
+
+### Component Hierarchy
+
+```
+AuthProvidersManagement (Main Container)
+├── Auth Providers List (Collapsible Cards)
+│   ├── Provider Header (Expandable)
+│   ├── Provider Details (Expanded View)
+│   └── Action Buttons (Edit, Test, Delete, Configuration)
+├── Tenant Selection Modal
+│   └── Tenant List with Provider Status
+├── Create Auth Provider Modal
+│   └── AuthProvidersComponent
+│       ├── Tenant Selector (if not hidden)
+│       ├── Provider Type Selector
+│       ├── KeycloakBasicConfigForm
+│       ├── KeycloakIdentityProvidersForm
+│       └── Auth0Form
+├── Edit Auth Provider Modal
+│   └── AuthProvidersComponent (pre-populated)
+└── Configuration Modal (View Saved Details)
+```
+
+### Key Components
+
+#### 1. AuthProvidersManagement (`AuthProvidersManagement.tsx`)
+
+**Purpose**: Main orchestrator component for auth provider management.
+
+**Responsibilities**:
+
+- Organization context management
+- Tenant list loading
+- Auth provider list management
+- Modal state management
+- Credential testing orchestration
+
+**Key Features**:
+
+- Fetches tenants to determine organization ID
+- Loads auth providers by organization ID
+- Manages multiple modals (create, edit, config, tenant selection)
+- Handles credential testing with inline results
+- Provides collapsible provider cards
+
+**State Management**:
+
+```typescript
+const [showCreateModal, setShowCreateModal] = useState(false);
+const [showEditModal, setShowEditModal] = useState(false);
+const [showConfigModal, setShowConfigModal] = useState(false);
+const [showTenantSelection, setShowTenantSelection] = useState(false);
+const [expandedProviderId, setExpandedProviderId] = useState<string | null>(null);
+const [testingCredentials, setTestingCredentials] = useState<string | null>(null);
+```
+
+#### 2. AuthProvidersComponent (`AuthProvidersComponent.tsx`)
+
+**Purpose**: Reusable form component for creating and editing auth providers.
+
+**Features**:
+
+- Multi-step form with XState machine
+- Provider type selection (Keycloak/Auth0)
+- Tenant selection (optional, can be hidden)
+- Dynamic form steps based on provider type
+- Pre-population for edit mode
+
+**Form Steps**:
+
+1. **Tenant Selection** (if not hidden)
+2. **Provider Type Selection**
+3. **Basic Configuration** (Keycloak realm/Auth0 domain)
+4. **Identity Providers** (Keycloak only)
+5. **Review & Submit**
+
+**Key Behaviors**:
+
+- Auto-loads existing config when `tenantId` prop is provided
+- Validates required fields before submission
+- Handles both create and update operations
+- Integrates with XState machine for state management
+
+#### 3. KeycloakBasicConfigForm (`KeycloakBasicConfigForm.tsx`)
+
+**Purpose**: Form for Keycloak basic configuration.
+
+**Fields**:
+
+- Realm Name (required)
+- Redirect URIs (required, array)
+- Allowed New Users (checkbox)
+- Confirm Email (checkbox)
+- Self-Hosted toggle
+- Self-Hosted Config (domain, admin credentials) - if self-hosted
+
+**Validation**:
+
+- Realm name must be unique
+- At least one redirect URI required
+- Self-hosted requires domain and admin credentials
+
+#### 4. KeycloakIdentityProvidersForm (`KeycloakIdentityProvidersForm.tsx`)
+
+**Purpose**: Form for configuring social identity providers.
+
+**Supported Providers**:
+
+- Google
+- GitHub
+- Facebook
+- Microsoft
+- And more...
+
+**Configuration per Provider**:
+
+- Client ID
+- Client Secret
+- Enabled/Disabled toggle
+
+#### 5. Auth0Form (`Auth0Authentication.tsx`)
+
+**Purpose**: Form for Auth0 configuration.
+
+**Fields**:
+
+- Auth0 Domain (required)
+- Client ID (required)
+- Client Secret (required)
+- Redirect URI (required)
+- Auth0 URL (auto-generated)
+
+---
+
+## State Management
+
+### XState Machine (`authProvidersMachine.ts`)
+
+The auth provider management uses XState for multi-step form state management.
+
+#### Machine Context
+
+```typescript
+interface AuthProviderMachineContext {
+    tenant?: ITenant;
+    providerType?: AuthProviderName;
+    keycloakConfig?: IKeycloakConfig;
+    auth0Config?: IAuth0Config;
+    currentStep: StepType;
+    hideTenantSelector: boolean;
+    authProviderConfig?: IAuthProvider;
+}
+```
+
+#### Machine States
+
+1. **tenantSelection**: Selecting tenant (if not hidden)
+2. **providerSelection**: Choosing provider type
+3. **keycloakBasicConfig**: Keycloak basic settings
+4. **keycloakIdentityProviders**: Keycloak social providers
+5. **auth0Config**: Auth0 configuration
+6. **review**: Review before submission
+
+#### Key Events
+
+- `SET_TENANT`: Set selected tenant
+- `SET_PROVIDER_TYPE`: Set provider type (Keycloak/Auth0)
+- `SET_KEYCLOAK_CONFIG`: Update Keycloak configuration
+- `SET_AUTH0_CONFIG`: Update Auth0 configuration
+- `NEXT_STEP`: Move to next step
+- `PREVIOUS_STEP`: Move to previous step
+- `SET_AUTH_PROVIDER_CONFIG`: Load existing config for editing
+- `SET_HIDE_TENANT_SELECTOR`: Hide tenant selector
+
+---
+
+## GraphQL Integration
+
+### Queries
+
+#### FetchAuthProvidersByOrganizationId
+
+```graphql
+query FetchAuthProvidersByOrganizationId($organizationId: ID!) {
+    fetchAuthProvidersByOrganizationId(organizationId: $organizationId) {
+        id
+        provider
+        tenant {
+            id
+            tenantId
+        }
+        keycloak {
+            realmName
+            clientId
+            redirectUris
+            identityProviders {
+                key
+                enabled
+            }
+            selfHosted
+            selfHostedConfig {
+                domain
+            }
+        }
+        auth0 {
+            auth0Domain
+            clientId
+            auth0Url
+        }
+        environmentTag {
+            id
+            name
+        }
+    }
+}
+```
+
+#### FetchAuthProviderByTenantId
+
+```graphql
+query FetchAuthProviderByTenantId($tenantId: ID!) {
+    fetchAuthProviderByTenantId(tenantId: $tenantId) {
+        ...AuthProviderFragment
+    }
+}
+```
+
+### Mutations
+
+#### CreateAuthProvider
+
+```graphql
+mutation CreateAuthProvider($input: AuthProviderInput!) {
+    createAuthProvider(input: $input) {
+        ...AuthProviderFragment
+    }
+}
+```
+
+**Input Structure**:
+
+```typescript
+{
+  tenant: string; // tenantId (UUID string)
+  environmentTag: string; // Environment tag ID
+  project: string; // Project ID
+  organization?: string; // Organization ID (optional)
+  provider: AuthProviderName; // 'keycloak' or 'auth0'
+  keycloak?: {
+    realmName: string;
+    redirectUris: string[];
+    allowedNewUsers: boolean;
+    confirmEmail: boolean;
+    identityProviders?: Array<{
+      key: string;
+      clientId: string;
+      clientSecret: string;
+      enabled: boolean;
+    }>;
+    selfHosted: boolean;
+    selfHostedConfig?: {
+      domain: string;
+      adminUsername: string;
+      adminPassword: string;
+      realmName: string;
+      adminClientId: string;
+      clientSecret: string;
+    };
+    authFlow: AuthFlow; // 'pkce' or 'implicit'
+  };
+  auth0?: {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    auth0Url: string;
+    auth0Domain: string;
+  };
+}
+```
+
+#### UpdateAuthProvider
+
+```graphql
+mutation UpdateAuthProvider($id: ID!, $input: AuthProviderInput!) {
+    updateAuthProvider(id: $id, input: $input) {
+        ...AuthProviderFragment
+    }
+}
+```
+
+#### DeleteAuthProvider
+
+```graphql
+mutation DeleteAuthProvider($id: ID!) {
+    deleteAuthProvider(id: $id)
+}
+```
+
+#### TestAuthProviderCredentials
+
+```graphql
+mutation TestAuthProviderCredentials($authProviderId: ID!) {
+    testAuthProviderCredentials(authProviderId: $authProviderId) {
+        success
+        message
+        details
+    }
+}
+```
+
+### Apollo Client Configuration
+
+- **Fetch Policy**: `network-only` for queries (always fetch fresh data)
+- **Refetch Queries**: Automatic refetch after mutations
+- **Error Handling**: Centralized via `onError` callbacks
+
+---
+
+## Backend Architecture & Inngest Integration
+
+### Overview
+
+The Auth Provider Management System uses an **event-driven architecture** with **Inngest** for asynchronous Keycloak configuration. The backend service handles immediate database operations and secret storage, while Inngest functions handle Keycloak realm/client creation and configuration.
+
+### Architecture Pattern
+
+1. **Service Layer** (`AuthProviderService`): Handles database operations and triggers Inngest events
+2. **Inngest Functions**: Handle Keycloak API operations (realm creation, client configuration, identity providers)
+3. **Secret Management**: Environment service stores sensitive credentials securely
+
+### Backend Service Layer
+
+#### AuthProviderService (`AuthProviderService.ts`)
+
+**Purpose**: Core service for auth provider CRUD operations.
+
+**Key Methods**:
+
+##### `createAuthProvider(input: IAuthProviderInput)`
+
+**Flow**:
+
+1. Resolves tenant ID using `defaultTenantIdMapper`
+2. Finds tenant by `tenantId` to get MongoDB `id`
+3. Generates unique `clientId` and `clientSecret` for Keycloak
+4. Stores secrets in environment service (for self-hosted Keycloak or Auth0)
+5. Creates auth provider record in MongoDB
+6. **Triggers Inngest Event**: `AUTH_MGMT_CONFIGURE_KEYCLOAK_SETTINGS_EVENT` (for Keycloak only)
+    - **Condition**: Only triggers if `input.provider === AuthProviderName.Keycloak`
+    - **Event Sending**:
+        ```typescript
+        await this.inngestClient.send({
+            name: WorkflowNamespace.AUTH_MGMT_CONFIGURE_KEYCLOAK_SETTINGS_EVENT,
+            data: updatedInput, // Full IAuthProviderInput with generated clientId/clientSecret
+        });
+        ```
+    - **Timing**: Event is sent **after** database record is created
+    - **Non-blocking**: Service doesn't wait for Inngest function to complete
+7. Returns created auth provider immediately
+
+**Inngest Event Payload**:
+
+```typescript
+{
+  name: 'auth-mgmt/configure-keycloak-settings-trigger',
+  data: {
+    tenant: string,              // tenantId (UUID)
+    provider: 'keycloak',
+    keycloak: {
+      realmName: string,
+      clientId: string,          // Generated unique ID
+      clientSecret: string,      // Generated unique secret
+      redirectUris: string[],
+      allowedNewUsers: boolean,
+      confirmEmail: boolean,
+      identityProviders: Array<{
+        key: string,
+        clientId: string,
+        clientSecret: string,
+        enabled: boolean
+      }>,
+      selfHosted: boolean,
+      selfHostedConfig?: { ... },
+      authFlow: 'pkce' | 'implicit'
+    },
+    environmentTag: string,
+    project: string,
+    organization?: string
+  }
+}
+```
+
+**Important**:
+
+- Auth0 providers **do not** trigger Inngest events (no Keycloak configuration needed)
+- Event is queued by Inngest and processed asynchronously
+- Service method returns immediately, Keycloak configuration happens in background
+
+##### `updateAuthProvider(id: string, input: IAuthProviderInput)`
+
+**Flow**:
+
+1. Finds existing auth provider
+2. Resolves tenant ID and finds tenant
+3. Updates secrets in environment service (if changed)
+4. **Detects Auth Flow Change**:
+    - Compares existing `authFlow` with new `authFlow`
+    - Sets `flowChanged` flag if different
+    - Stores `previousAuthFlow` for reference
+5. Updates auth provider record in MongoDB
+6. **Triggers Inngest Event**: `AUTH_MGMT_UPDATE_KEYCLOAK_SETTINGS_EVENT` (for Keycloak only)
+    - **Condition**: Only triggers if `input.provider === AuthProviderName.Keycloak`
+    - **Event Sending**:
+        ```typescript
+        await this.inngestClient.send({
+            name: WorkflowNamespace.AUTH_MGMT_UPDATE_KEYCLOAK_SETTINGS_EVENT,
+            data: {
+                ...existingAuthProvider,
+                ...input,
+                flowChanged: boolean,
+                previousAuthFlow: AuthFlow,
+            },
+        });
+        ```
+    - **Timing**: Event is sent **after** database record is updated
+    - **Non-blocking**: Service doesn't wait for Inngest function to complete
+7. Returns updated auth provider immediately
+
+**Inngest Event Payload**:
+
+```typescript
+{
+  name: 'auth-mgmt/update-keycloak-settings-trigger',
+  data: {
+    // Existing auth provider fields
+    id: string,
+    tenant: string,
+    provider: 'keycloak',
+    keycloak: {
+      // Merged: existing + new values
+      realmName: string,
+      clientId: string,
+      clientSecret: string,
+      redirectUris: string[],
+      allowedNewUsers: boolean,
+      confirmEmail: boolean,
+      identityProviders: Array<{ ... }>,
+      selfHosted: boolean,
+      selfHostedConfig?: { ... },
+      authFlow: 'pkce' | 'implicit'  // New auth flow
+    },
+    // Additional metadata
+    flowChanged: boolean,            // true if auth flow changed
+    previousAuthFlow: 'pkce' | 'implicit'  // Previous flow value
+  }
+}
+```
+
+**Important**:
+
+- `flowChanged` flag determines if client needs to be deleted/recreated
+- Event contains merged data (existing + new values)
+- Inngest function uses this to determine which steps to execute
+
+##### `deleteAuthProvider(id: string)`
+
+**Flow**:
+
+1. Finds auth provider
+2. **For Managed Keycloak**: Deletes realm via `KeycloakInternalAdminService`
+3. Deletes secrets from environment service
+4. Deletes auth provider record from MongoDB
+5. Returns success boolean
+
+**Note**: Self-hosted Keycloak realms are not deleted (user manages them).
+
+##### `getAuthProviderByTenantId(tenantId: string)`
+
+**Flow**:
+
+1. Resolves tenant ID and finds tenant
+2. Finds auth provider by tenant MongoDB `id`
+3. Fetches secrets from environment service
+4. **For Keycloak**: Fetches identity providers and client secret from Keycloak API
+5. Formats response with all secrets merged
+6. Returns formatted auth provider
+
+**Secret Fetching**:
+
+- Self-hosted Keycloak: Uses `KeycloakTenantAdminService` with admin credentials
+- Managed Keycloak: Uses `KeycloakInternalAdminService`
+- Auth0: Fetches from environment service
+
+##### `testAuthProviderCredentials(authProviderId: string)`
+
+**Purpose**: Tests authentication provider credentials by attempting OAuth2 token exchange.
+
+**Flow for Keycloak**:
+
+1. Fetches auth provider
+2. Determines Keycloak URL (managed vs self-hosted)
+3. Fetches client secret from Keycloak API
+4. Calls token endpoint: `POST /realms/{realm}/protocol/openid-connect/token`
+5. Uses `client_credentials` grant type
+6. Returns success/failure with details
+
+**Flow for Auth0**:
+
+1. Fetches auth provider
+2. Fetches client secret from environment service
+3. Calls token endpoint: `POST https://{domain}/oauth/token`
+4. Uses `client_credentials` grant type with audience
+5. Returns success/failure with details
+
+#### Secret Management
+
+**Environment Service Integration**:
+
+Secrets are stored in environment service with keys:
+
+- `KeycloakAdminUsername`: Admin username (self-hosted)
+- `KeycloakAdminPassword`: Admin password (self-hosted)
+- `KeycloakAdminClientSecret`: Admin client secret (self-hosted)
+- `Auth0ClientSecret`: Auth0 client secret
+
+**Secret Keys Structure**:
+
+```typescript
+{
+    tenantId: string; // MongoDB ObjectId
+    environmentTag: string; // Environment tag ID
+    projectId: string; // Project ID
+}
+```
+
+### Inngest Event-Driven Workflow
+
+#### Overview
+
+Inngest handles all asynchronous Keycloak API operations. When an auth provider is created or updated, the service immediately returns success to the frontend, while Inngest processes the Keycloak configuration in the background. This ensures fast user experience while handling potentially slow Keycloak API calls.
+
+#### Event Namespace
+
+**Trigger Events** (what functions listen for):
+
+- `AUTH_MGMT_CONFIGURE_KEYCLOAK_SETTINGS_EVENT`: Configure new Keycloak provider
+- `AUTH_MGMT_UPDATE_KEYCLOAK_SETTINGS_EVENT`: Update existing Keycloak provider
+
+**Function IDs**:
+
+- `AUTH_MGMT_CONFIGURE_KEYCLOAK_SETTINGS`: Function for initial configuration
+- `AUTH_MGMT_UPDATE_KEYCLOAK_SETTINGS`: Function for updates
+
+**Event Payload Structure**:
+
+```typescript
+// For CREATE
+{
+  name: 'auth-mgmt/configure-keycloak-settings-trigger',
+  data: IAuthProviderInput {
+    tenant: string,
+    provider: 'keycloak',
+    keycloak: {
+      realmName: string,
+      clientId: string,
+      clientSecret: string,
+      redirectUris: string[],
+      allowedNewUsers: boolean,
+      confirmEmail: boolean,
+      identityProviders: Array<{
+        key: string,        // 'google', 'github', etc.
+        clientId: string,
+        clientSecret: string,
+        enabled: boolean
+      }>,
+      selfHosted: boolean,
+      selfHostedConfig?: {
+        domain: string,
+        adminUsername: string,
+        adminPassword: string,
+        realmName: string,
+        adminClientId: string,
+        clientSecret: string
+      },
+      authFlow: 'pkce' | 'implicit'
+    }
+  }
+}
+
+// For UPDATE
+{
+  name: 'auth-mgmt/update-keycloak-settings-trigger',
+  data: IAuthProviderInput & {
+    flowChanged?: boolean,
+    previousAuthFlow?: AuthFlow
+  }
+}
+```
+
+#### Inngest Functions
+
+##### 1. `configureKeycloakAuthSettingFunction`
+
+**Purpose**: Creates Keycloak realm and client for new auth provider.
+
+**Trigger**: `AUTH_MGMT_CONFIGURE_KEYCLOAK_SETTINGS_EVENT`
+
+**Function Registration**:
+
+```typescript
+inngest.createFunction(
+  { id: 'auth-mgmt-configure-keycloak-settings' },
+  { event: 'auth-mgmt/configure-keycloak-settings-trigger' },
+  async ({ event, step }) => { ... }
+)
+```
+
+**Detailed Workflow Steps**:
+
+1. **Data Extraction & Preparation**
+    - Extracts `keycloakConfiguration` from event data
+    - Parses realm name, client ID, client secret, redirect URIs
+    - Extracts identity providers array
+    - Determines if self-hosted or managed
+
+2. **Web Origins Extraction** (Before any Keycloak calls)
+    - Iterates through `redirectUris` array
+    - For each redirect URI:
+        - Parses URL using `new URL(redirectUri)`
+        - Extracts `origin` (protocol + domain + port)
+        - Adds to `webOrigins` array (deduplicated)
+    - **Purpose**: Web origins are required for CORS configuration in Keycloak
+    - **Example**: `https://example.com/callback` → `https://example.com`
+
+3. **Step: `create-realm-and-client`** (Managed Keycloak only)
+    - **Condition**: Only executes if `selfHosted === false`
+    - **Operation**: Calls `KeycloakInternalAdminService.Instance.createRealmAndClient()`
+    - **Parameters**:
+        ```typescript
+        {
+          realm: realmName,                    // Realm name
+          clientId: clientId,                  // Generated client ID
+          clientSecret: clientSecret,          // Generated client secret
+          redirectUris: redirectUris || [],   // Array of redirect URIs
+          webOrigins: webOrigins,              // Extracted web origins
+          signupSetting: {
+            allowNewUsers: allowedNewUsers,   // Boolean
+            confirmEmail: confirmEmail         // Boolean
+          },
+          authFlow: authFlow || AuthFlow.Pkce  // 'pkce' or 'implicit'
+        }
+        ```
+    - **What Happens**:
+        - Creates new Keycloak realm with specified name
+        - Creates OAuth2/OIDC client within the realm
+        - Configures client with redirect URIs and web origins
+        - Sets up signup settings (user registration, email confirmation)
+        - Configures authentication flow (PKCE or Implicit)
+        - Assigns realm management roles to the client
+    - **Error Handling**: If this step fails, entire function fails (realm creation is critical)
+
+4. **Step: `configure-identity-providers`** (Both managed and self-hosted)
+    - **Condition**: Executes if `identityProviders?.length > 0`
+    - **Process**: Iterates through each identity provider in the array
+    - **For Each Provider**:
+        - **Managed Keycloak**:
+            - Uses `KeycloakInternalAdminService.Instance.configureIdentityProviderInternal()`
+            - **Parameters**:
+                ```typescript
+                {
+                  realm: realmName,
+                  idpAlias: provider.key,        // 'google', 'github', etc.
+                  providerId: provider.key,       // Same as alias
+                  enabled: provider.enabled,      // Boolean
+                  identityProvidersConfig: {
+                    clientId: provider.clientId,
+                    clientSecret: provider.clientSecret
+                  }
+                }
+                ```
+        - **Self-Hosted Keycloak**:
+            - Creates `KeycloakTenantAdminService` instance from self-hosted config
+            - Uses admin credentials from `selfHostedConfig`
+            - Calls `configureIdentityProvider()` with same parameters
+            - **Service Creation**:
+                ```typescript
+                KeycloakTenantAdminService.fromSelfHostedConfig({
+                    domain: selfHostedConfig.domain,
+                    adminClientId: selfHostedConfig.adminClientId,
+                    adminUsername: selfHostedConfig.adminUsername,
+                    adminPassword: selfHostedConfig.adminPassword,
+                    realmName: selfHostedConfig.realmName,
+                    clientSecret: selfHostedConfig.clientSecret,
+                });
+                ```
+    - **Error Handling**:
+        - Individual provider failures are **logged but don't stop the process**
+        - Each provider is processed independently
+        - Errors logged as: `❌ Failed to process provider {key}: {error}`
+        - Success logged as: `✅ Provider processed: {key} (enabled: {enabled})`
+    - **Result**: All enabled identity providers are configured in Keycloak
+
+**Return Value**:
+
+```typescript
+{ status: 'success', realm: realmName }
+```
+
+**Important Notes**:
+
+- Self-hosted Keycloak **skips** realm/client creation (assumes realm exists)
+- Identity provider configuration happens for both managed and self-hosted
+- Web origins are automatically derived from redirect URIs
+- Individual identity provider failures don't fail the entire operation
+
+##### 2. `updateKeycloakAuthSettingFunction`
+
+**Purpose**: Updates existing Keycloak configuration.
+
+**Trigger**: `AUTH_MGMT_UPDATE_KEYCLOAK_SETTINGS_EVENT`
+
+**Function Registration**:
+
+```typescript
+inngest.createFunction(
+  { id: 'auth-mgmt-update-keycloak-settings' },
+  { event: 'auth-mgmt/update-keycloak-settings-trigger' },
+  async ({ event, step }) => { ... }
+)
+```
+
+**Detailed Workflow Steps**:
+
+1. **Data Extraction & Preparation**
+    - Extracts `keycloakConfiguration` from event data
+    - Checks `flowChanged` flag (indicates if auth flow changed)
+    - Extracts `previousAuthFlow` if available
+    - Determines new auth flow: `authFlow || AuthFlow.Pkce`
+
+2. **Web Origins Extraction** (Same as configure function)
+    - Extracts web origins from redirect URIs
+    - Used for client updates
+
+3. **Service Instance Creation** (Self-hosted only)
+    - If `selfHosted === true`:
+        - Creates `KeycloakTenantAdminService` instance
+        - Uses credentials from `selfHostedConfig`
+        - Instance used for all self-hosted operations
+
+4. **Step: `update-realm-settings`** (Conditional)
+    - **Condition**: Executes if signup settings have non-null values
+    - **Signup Settings**:
+        ```typescript
+        {
+          allowNewUsers: allowedNewUsers,  // Boolean or null
+          confirmEmail: confirmEmail         // Boolean or null
+        }
+        ```
+    - **Managed Keycloak**:
+        - Calls `KeycloakInternalAdminService.Instance.updateRealmSettings()`
+        - **Parameters**: `{ realm: realmName, signupSettings }`
+    - **Self-Hosted Keycloak**:
+        - Calls `KeycloakTenantAdminServiceInstance.updateRealmSettings()`
+        - **Parameters**: `{ realm: selfHostedConfig.realmName, signupSettings }`
+    - **What Happens**: Updates realm-level settings for user registration and email confirmation
+    - **Error Handling**: Throws error if update fails (critical operation)
+
+5. **Step: `delete-and-recreate-client`** (Conditional - Auth Flow Changed)
+    - **Condition**: Executes if:
+        - `authFlowChanged === true`
+        - `selfHosted === false` (only for managed Keycloak)
+        - `clientId` exists
+    - **Why**: Auth flow (PKCE vs Implicit) requires different client configuration. Cannot be changed on existing client.
+    - **Process**:
+        1. **Delete Existing Client**:
+            - Calls `KeycloakInternalAdminService.Instance.deleteClientInternal(realmName, clientId)`
+            - Removes old client with old flow configuration
+        2. **Create New Client**:
+            - Calls `KeycloakInternalAdminService.Instance.createClientAndAssignRealmManagementRoles()`
+            - **Parameters**:
+                ```typescript
+                {
+                  realm: realmName,
+                  clientId: clientId,              // Same client ID
+                  clientSecret: clientSecret,      // Same client secret
+                  redirectUris: redirectUris || [],
+                  webOrigins: webOrigins,
+                  authFlow: newAuthFlow            // New flow (PKCE or Implicit)
+                }
+                ```
+            - Creates new client with new flow configuration
+            - Assigns realm management roles
+    - **Error Handling**: Throws error if deletion or creation fails
+
+6. **Step: `update-client-settings`** (Conditional - Auth Flow Unchanged)
+    - **Condition**: Executes if:
+        - `authFlowChanged === false` (flow didn't change)
+        - `redirectUris?.length > 0 || webOrigins.length > 0` (has redirect URIs)
+        - `clientId` exists
+        - `selfHosted === false` (only for managed Keycloak)
+    - **Operation**: Calls `KeycloakInternalAdminService.Instance.updateClientInternal()`
+    - **Parameters**:
+        ```typescript
+        {
+          realm: realmName,
+          clientId: clientId,
+          redirectUris: redirectUris || [],
+          webOrigins: webOrigins
+        }
+        ```
+    - **What Happens**: Updates existing client's redirect URIs and web origins
+    - **Error Handling**: Throws error if update fails
+
+7. **Step: `configure-identity-providers`** (Always executes if providers exist)
+    - **Process**: Iterates through `identityProviders` array
+    - **For Each Provider**:
+        - **Managed Keycloak**:
+            - Uses `KeycloakInternalAdminService.Instance.configureIdentityProviderInternal()`
+            - Updates or creates identity provider configuration
+        - **Self-Hosted Keycloak**:
+            - Uses `KeycloakTenantAdminServiceInstance.configureIdentityProviderInternal()`
+            - Updates or creates identity provider configuration
+    - **Parameters** (same as configure function):
+        ```typescript
+        {
+          realm: realmName,
+          idpAlias: provider.key,
+          providerId: provider.key,
+          enabled: provider.enabled,
+          identityProvidersConfig: {
+            clientId: provider.clientId,
+            clientSecret: provider.clientSecret
+          }
+        }
+        ```
+    - **Error Handling**:
+        - **Important**: Unlike configure function, errors here **throw and stop the process**
+        - Each provider error throws: `new Error('Failed to process provider', err)`
+        - This ensures all identity providers are successfully updated
+
+**Return Value**:
+
+```typescript
+{ status: 'success', realm: realmName }
+```
+
+**Important Notes**:
+
+- Auth flow changes require client deletion and recreation (cannot be updated in place)
+- Self-hosted Keycloak skips client operations (user manages clients)
+- Identity provider updates are atomic (all must succeed)
+- Realm settings update is optional (only if values provided)
+
+#### Inngest Function Registration
+
+**Location**: `packages-modules/user-auth0/server/src/modules/user-auth/inngest/functions.ts`
+
+**Registration**:
+
+```typescript
+export const inngestFunctionsFactory = (args: { container: Container; inngest: Inngest }) => [
+    configureKeycloakAuthSettingFunction(args.inngest),
+    updateKeycloakAuthSettingFunction(args.inngest),
+    // ... other functions
+];
+```
+
+**When Functions Execute**:
+
+- Functions are registered at server startup
+- Inngest listens for events matching the function's event pattern
+- When service sends event, Inngest queues the function execution
+- Functions execute asynchronously in background
+
+#### Error Handling in Inngest Functions
+
+**Configure Function**:
+
+- Realm/client creation failure: **Function fails** (critical)
+- Identity provider failure: **Logged, continues** (non-critical)
+
+**Update Function**:
+
+- Realm settings failure: **Function fails** (critical)
+- Client deletion/recreation failure: **Function fails** (critical)
+- Client update failure: **Function fails** (critical)
+- Identity provider failure: **Function fails** (all must succeed)
+
+**Retry Behavior**:
+
+- Inngest automatically retries failed functions
+- Retry strategy: Exponential backoff
+- Maximum retries: Configurable in Inngest dashboard
+
+#### Performance Considerations
+
+**Async Processing**:
+
+- Service methods return immediately after triggering Inngest events
+- Keycloak API operations happen asynchronously
+- Frontend doesn't wait for Keycloak configuration to complete
+
+**Step Isolation**:
+
+- Each `step.run()` is isolated and can be retried independently
+- Inngest tracks step execution state
+- Failed steps can be retried without re-running successful steps
+
+**Idempotency**:
+
+- Functions are designed to be safely retried
+- Identity provider configuration is idempotent (can be called multiple times)
+- Client creation checks for existing client before creating
+
+### Complete Data Flow
+
+#### Creating an Auth Provider
+
+```
+1. Frontend: User submits auth provider form
+   ↓
+2. GraphQL Mutation: createAuthProvider(input)
+   ↓
+3. AuthProviderService.createAuthProvider()
+   ├── Resolves tenant ID
+   ├── Generates clientId/clientSecret
+   ├── Stores secrets in environment service
+   ├── Creates auth provider in MongoDB
+   └── Triggers Inngest Event: AUTH_MGMT_CONFIGURE_KEYCLOAK_SETTINGS_EVENT
+   ↓
+4. Returns auth provider to frontend
+   ↓
+5. Inngest Function: configureKeycloakAuthSettingFunction
+   ├── Step 1: Create realm and client (managed only)
+   └── Step 2: Configure identity providers
+   ↓
+6. Keycloak realm and client created
+```
+
+#### Updating an Auth Provider
+
+```
+1. Frontend: User updates auth provider form
+   ↓
+2. GraphQL Mutation: updateAuthProvider(id, input)
+   ↓
+3. AuthProviderService.updateAuthProvider()
+   ├── Updates secrets in environment service
+   ├── Updates auth provider in MongoDB
+   └── Triggers Inngest Event: AUTH_MGMT_UPDATE_KEYCLOAK_SETTINGS_EVENT
+   ↓
+4. Returns updated auth provider to frontend
+   ↓
+5. Inngest Function: updateKeycloakAuthSettingFunction
+   ├── Step 1: Update realm settings
+   ├── Step 2: Delete/recreate client (if flow changed)
+   ├── Step 3: Update client settings (if flow unchanged)
+   └── Step 4: Configure identity providers
+```
+
+#### Testing Credentials
+
+```
+1. Frontend: User clicks "Test" button
+   ↓
+2. GraphQL Mutation: testAuthProviderCredentials(authProviderId)
+   ↓
+3. AuthProviderService.testAuthProviderCredentials()
+   ├── Fetches auth provider
+   ├── Fetches client secret (from Keycloak API or environment)
+   ├── Calls OAuth2 token endpoint
+   └── Returns success/failure with details
+   ↓
+4. Frontend displays result inline
+```
+
+### Keycloak Integration
+
+#### Managed Keycloak
+
+**Service**: `KeycloakInternalAdminService.Instance`
+
+**Operations**:
+
+- `createRealmAndClient()`: Creates realm and OAuth2 client
+- `updateRealmSettings()`: Updates realm signup settings
+- `updateClientInternal()`: Updates client redirect URIs
+- `deleteClientInternal()`: Deletes client
+- `configureIdentityProviderInternal()`: Configures social login providers
+- `getClientSecretInternal()`: Fetches client secret
+- `deleteRealmInternal()`: Deletes entire realm
+
+#### Self-Hosted Keycloak
+
+**Service**: `KeycloakTenantAdminService.fromSelfHostedConfig()`
+
+**Configuration**:
+
+- Domain: Keycloak server URL
+- Admin credentials: Username, password, client ID, client secret
+- Realm name: Target realm
+
+**Operations**:
+
+- `configureIdentityProvider()`: Configures social login providers
+- `updateRealmSettings()`: Updates realm settings
+- `getClientSecret()`: Fetches client secret
+
+### Auth Flow Types
+
+**PKCE (Authorization Code Flow with PKCE)**:
+
+- Recommended for web and mobile apps
+- More secure than implicit flow
+- Uses code verifier/challenge
+
+**Implicit Flow**:
+
+- Legacy flow
+- Less secure
+- Direct token return
+
+**Flow Change Handling**:
+
+- When auth flow changes, old client is deleted and new one created
+- This ensures proper configuration for the new flow type
+
+### Error Handling
+
+#### Service Layer Errors
+
+- **Database Errors**: Thrown immediately
+- **Keycloak API Errors**: Logged, may not fail entire operation
+- **Secret Storage Errors**: Logged, operation continues
+
+#### Inngest Function Errors
+
+- **Realm Creation Failures**: Logged, operation fails
+- **Identity Provider Failures**: Logged individually, doesn't stop other providers
+- **Client Update Failures**: Logged, operation fails
+
+### Security Considerations
+
+1. **Secret Storage**: All secrets stored in environment service, not in database
+2. **Client Secret Generation**: Unique secrets generated for each provider
+3. **Admin Credentials**: Only stored for self-hosted Keycloak, in environment service
+4. **Token Testing**: Uses OAuth2 client credentials flow (secure)
+5. **Realm Isolation**: Each tenant gets its own realm (managed Keycloak)
+
+---
+
+## Important Notes and Best Practices
+
+### 1. Tenant ID Resolution
+
+**Critical Distinction**:
+
+- `tenantId`: UUID string (used in API calls)
+- `tenant.id`: MongoDB ObjectId (stored in AuthProvider.tenant)
+
+**Usage**:
+
+```typescript
+// Frontend passes tenantId (UUID)
+// Backend resolves to MongoDB id for storage
+const tenant = await tenantRepository.find({ tenantId });
+authProvider.tenant = tenant.id; // MongoDB ObjectId
+```
+
+### 2. One Provider Per Tenant
+
+**Important**: Each tenant can have only one auth provider. The system:
+
+- Checks for existing provider when creating
+- Shows warning if provider already exists
+- Allows editing existing provider instead
+
+### 3. Self-Hosted vs Managed Keycloak
+
+**Managed Keycloak**:
+
+- Realm is created automatically
+- Realm is deleted when provider is deleted
+- Uses internal admin service
+
+**Self-Hosted Keycloak**:
+
+- Realm must exist before configuration
+- Realm is not deleted when provider is deleted
+- Requires admin credentials
+- Uses tenant admin service
+
+### 4. Secret Management
+
+**Storage**:
+
+- Secrets stored in environment service, not database
+- Retrieved on-demand when needed
+- Never logged or exposed in responses
+
+**Keycloak Client Secret**:
+
+- Fetched from Keycloak API (not stored)
+- Regenerated deterministically if needed
+- Different for managed vs self-hosted
+
+### 5. Identity Provider Configuration
+
+**Supported Providers**:
+
+- Google, GitHub, Facebook, Microsoft, etc.
+- Each requires client ID and secret from provider
+- Can be enabled/disabled per provider
+
+**Configuration**:
+
+- Configured asynchronously via Inngest
+- Individual provider failures don't stop others
+- Updates require full provider array
+
+### 6. Auth Flow Changes
+
+**Important**: Changing auth flow (PKCE ↔ Implicit) requires:
+
+- Deleting old client
+- Creating new client with new flow
+- This is handled automatically by Inngest
+
+### 7. Credential Testing
+
+**Purpose**: Verify configuration before saving or after changes.
+
+**Process**:
+
+- Uses OAuth2 client credentials flow
+- Attempts to obtain access token
+- Returns success/failure with details
+
+**Best Practice**: Always test credentials after configuration changes.
+
+### 8. Redirect URI Validation
+
+**Format**: Must be valid URLs
+
+- `https://example.com/callback`
+- `http://localhost:3000/callback` (development)
+
+**Web Origins**: Automatically extracted from redirect URIs
+
+- Used for CORS configuration
+- Must match redirect URI origins
+
+### 9. Error Recovery
+
+**Keycloak API Failures**:
+
+- Logged but may not fail entire operation
+- Identity provider failures are non-blocking
+- Realm/client creation failures are blocking
+
+**Retry Strategy**:
+
+- Inngest functions can be retried
+- Service operations are idempotent where possible
+
+### 10. Type Safety
+
+**Key Interfaces**:
+
+- `IAuthProvider`: Auth provider data structure
+- `IAuthProviderInput`: Input for create/update
+- `IKeycloakConfig`: Keycloak configuration
+- `IAuth0Config`: Auth0 configuration
+
+**Type Guards**:
+
+- Always check provider type before accessing config
+- Handle undefined/null cases gracefully
+
+---
+
+## Summary
+
+The Auth Provider Management System provides a comprehensive interface for managing authentication providers (Keycloak and Auth0) for tenants. It leverages React, XState for form state management, GraphQL for data operations, and Inngest for asynchronous Keycloak configuration.
+
+**Key Takeaways**:
+
+**Frontend**:
+
+- ✅ Multi-step form with XState machine
+- ✅ Support for Keycloak (managed/self-hosted) and Auth0
+- ✅ Credential testing before saving
+- ✅ Configuration details viewing
+- ✅ One provider per tenant constraint
+
+**Backend**:
+
+- ✅ Event-driven architecture with Inngest
+- ✅ Keycloak realm and client management
+- ✅ Identity provider configuration
+- ✅ Secure secret management via environment service
+- ✅ Support for both managed and self-hosted Keycloak
+- ✅ Auth flow change handling (PKCE ↔ Implicit)
+
+## Testing
+
+For testing keycloak authentication using PKCE and Implicit flow follow this example
+
+https://github.com/huzaifaali14/keycloak-auth