@bluealba/platform-cli 1.0.1 → 1.0.2

package/docs/guides/identity-providers.mdx

@@ -0,0 +1,1007 @@
+---
+title: Identity Providers Configuration
+description: Complete guide to configuring and using Identity Providers (IDPs) with the Blue Alba Platform - Okta, Microsoft Entra ID, OneLogin, GitHub, and AWS Cognito
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The Blue Alba Platform supports multiple Identity Providers (IDPs) for authentication, allowing you to integrate with your organization's existing identity management infrastructure. This guide covers how to configure and use each supported IDP.
+
+## Overview
+
+The platform uses OAuth 2.0 / OpenID Connect (OIDC) protocols to integrate with identity providers. Each provider follows the standard OAuth 2.0 Authorization Code flow with PKCE for enhanced security.
+
+### Supported Identity Providers
+
+<CardGrid stagger>
+  <Card title="Okta" icon="seti:config">
+    Enterprise identity and access management with comprehensive features including Universal Directory and group synchronization.
+  </Card>
+
+  <Card title="Microsoft Entra ID" icon="seti:config">
+    Azure Active Directory integration with Microsoft 365, security groups, and conditional access policies.
+  </Card>
+
+  <Card title="OneLogin" icon="seti:config">
+    SSO and unified access management with role and group mapping capabilities.
+  </Card>
+
+  <Card title="GitHub" icon="github">
+    Developer-friendly authentication with organization and team-based authorization.
+  </Card>
+
+  <Card title="AWS Cognito" icon="seti:config">
+    Amazon's managed identity service with user pools, custom attributes, and MFA support.
+  </Card>
+</CardGrid>
+
+---
+
+## Configuration Methods
+
+The platform supports two methods for configuring identity providers:
+
+### 1. Database Configuration (Recommended)
+
+Providers configured in the database are:
+- **Editable**: Can be added, updated, or removed via Admin UI or API
+- **Multi-tenant**: Different providers can be configured per tenant
+- **Dynamic**: Changes take effect without restarting the service
+- **Secure**: Credentials stored securely in the database
+
+**To configure via Admin UI**:
+1. Navigate to Admin UI → Authentication → Identity Providers
+2. Click "Add Provider"
+3. Select provider type and enter configuration details
+4. Save and activate the provider
+
+### 2. Environment Variables (Legacy)
+
+Providers can also be configured via environment variables. This method is:
+- **Read-only**: Cannot be modified via UI or API
+- **Global**: Same provider configuration for all tenants
+- **Static**: Requires service restart for changes
+
+<Aside type="caution" title="Migration Notice">
+  Environment variable configuration is maintained for backward compatibility but is considered legacy. New deployments should use database configuration for better flexibility and multi-tenancy support.
+</Aside>
+
+---
+
+## Provider Configuration
+
+Each provider requires specific configuration parameters. Below are detailed setup instructions for each supported IDP.
+
+<Tabs>
+  <TabItem label="Okta">
+
+### Okta Configuration
+
+Okta is an enterprise-grade identity and access management platform with comprehensive SSO capabilities.
+
+#### Prerequisites
+
+- Okta account (Developer or Enterprise)
+- Admin access to create OAuth applications
+- Okta domain (e.g., `dev-12345.okta.com`)
+
+#### Step 1: Create OAuth Application in Okta
+
+1. Log into your Okta Admin Console
+2. Navigate to **Applications** → **Applications**
+3. Click **Create App Integration**
+4. Select **OIDC - OpenID Connect**
+5. Choose **Web Application**
+6. Configure the application:
+   - **App integration name**: `Blue Alba Platform`
+   - **Sign-in redirect URIs**: `https://your-platform.com/auth/okta/callback`
+   - **Sign-out redirect URIs**: `https://your-platform.com`
+   - **Controlled access**: Choose your preferred access policy
+7. Click **Save**
+8. Note the **Client ID** and **Client Secret**
+
+#### Step 2: Configure Authorization Server
+
+1. Navigate to **Security** → **API** → **Authorization Servers**
+2. Select your authorization server (usually `default`)
+3. Note the **Issuer URI** (e.g., `https://dev-12345.okta.com/oauth2/default`)
+
+#### Step 3: Configure Groups (Optional)
+
+To enable group synchronization:
+1. Navigate to **Directory** → **Groups**
+2. Ensure your users are assigned to appropriate groups
+3. Okta groups will be automatically synchronized to the platform
+
+#### Step 4: Configure Provider in Blue Alba Platform
+
+**Via Admin UI**:
+- **Provider Type**: Okta
+- **Provider Name**: `okta` (or custom name)
+- **Issuer URL**: `https://dev-12345.okta.com/oauth2/default`
+- **Client ID**: Your Okta application client ID
+- **Client Secret**: Your Okta application client secret
+- **Active**: Enabled
+
+**Via Environment Variables** (Legacy):
+
+```bash
+# Enable Okta provider
+AUTH_ENV_MIGRATION_ENABLED=true
+AUTH_OKTA_ENABLED=true
+
+# Okta Configuration
+AUTH_OKTA_ISSUER=https://dev-12345.okta.com/oauth2/default
+AUTH_OKTA_CLIENT_ID=0oa1b2c3d4e5f6g7h8i9
+AUTH_OKTA_CLIENT_SECRET=your_client_secret_here
+
+# Optional: Custom scope
+AUTH_OKTA_SCOPE=openid profile offline_access email
+
+# Optional: Redirect URL override
+AUTH_OKTA_REDIRECT_URL=https://your-platform.com/auth/okta/callback
+
+# Optional: Custom logout URI
+AUTH_OKTA_LOGOUT_URI=https://your-platform.com
+```
+
+#### Features
+
+- **Single Sign-On (SSO)**: Seamless authentication via Okta
+- **Group Synchronization**: Automatic sync of Okta groups
+- **User Provisioning**: Automatic user creation on first login
+- **Universal Directory**: Support for Okta's user directory
+- **Logout Support**: Proper session termination with Okta
+
+#### Technical Details
+
+**OAuth Endpoints**:
+- Authorization: `/v1/authorize`
+- Token: `/v1/token`
+- User Info: `/v1/userinfo`
+
+**Scope**: `openid profile offline_access email`
+
+**Group Sync**: Uses Okta Users API to fetch user groups
+
+**Logout**: Supports `id_token_hint` for logout
+
+  </TabItem>
+
+  <TabItem label="Microsoft Entra ID">
+
+### Microsoft Entra ID (Azure AD) Configuration
+
+Microsoft Entra ID (formerly Azure Active Directory) enables authentication for Microsoft 365 users and integration with Azure services.
+
+#### Prerequisites
+
+- Azure subscription with Entra ID tenant
+- Admin access to create app registrations
+- Tenant ID and domain name
+
+#### Step 1: Register Application in Azure Portal
+
+1. Navigate to [Azure Portal](https://portal.azure.com)
+2. Go to **Microsoft Entra ID** → **App registrations**
+3. Click **New registration**
+4. Configure the application:
+   - **Name**: `Blue Alba Platform`
+   - **Supported account types**: Choose based on your needs (usually single tenant)
+   - **Redirect URI**: Select **Web** and enter `https://your-platform.com/auth/entra-id/callback`
+5. Click **Register**
+6. Note the **Application (client) ID** and **Directory (tenant) ID**
+
+#### Step 2: Create Client Secret
+
+1. In your app registration, go to **Certificates & secrets**
+2. Click **New client secret**
+3. Add a description and select expiration period
+4. Click **Add**
+5. **Important**: Copy the secret value immediately (it won't be shown again)
+
+#### Step 3: Configure API Permissions
+
+1. Go to **API permissions**
+2. Click **Add a permission** → **Microsoft Graph**
+3. Select **Delegated permissions**
+4. Add the following permissions:
+   - `openid`
+   - `profile`
+   - `email`
+   - `User.Read`
+   - `GroupMember.Read.All` (for group sync)
+5. Click **Grant admin consent** (if you have admin privileges)
+
+#### Step 4: Configure Provider in Blue Alba Platform
+
+**Via Admin UI**:
+- **Provider Type**: Entra ID
+- **Provider Name**: `entra-id` (or custom name)
+- **Issuer URL**: `https://login.microsoftonline.com/{tenant-id}`
+- **Client ID**: Your Azure application client ID
+- **Client Secret**: Your Azure application client secret
+- **Active**: Enabled
+
+**Via Environment Variables** (Legacy):
+
+```bash
+# Enable Entra ID provider
+AUTH_ENV_MIGRATION_ENABLED=true
+AUTH_ENTRAID_ENABLED=true
+
+# Entra ID Configuration
+AUTH_ENTRAID_ISSUER=https://login.microsoftonline.com/12345678-1234-1234-1234-123456789012
+AUTH_ENTRAID_CLIENT_ID=87654321-4321-4321-4321-210987654321
+AUTH_ENTRAID_CLIENT_SECRET=your_client_secret_here
+
+# Optional: Custom token URL
+AUTH_ENTRAID_TOKEN_URL=https://login.microsoftonline.com/12345678-1234-1234-1234-123456789012/oauth2/v2.0/token
+
+# Optional: Custom user info URL
+AUTH_ENTRAID_USER_INFO_URL=https://graph.microsoft.com/oidc/userinfo
+```
+
+#### Features
+
+- **Microsoft 365 Integration**: Authenticate users from your Microsoft 365 tenant
+- **Security Groups**: Automatic synchronization of Entra ID security groups
+- **Conditional Access**: Support for conditional access policies
+- **Microsoft Graph API**: Integration with Microsoft Graph for user and group data
+- **MFA Support**: Leverages Entra ID's multi-factor authentication
+
+#### Technical Details
+
+**OAuth Endpoints**:
+- Authorization: `/oauth2/v2.0/authorize`
+- Token: `/oauth2/v2.0/token`
+- User Info: `https://graph.microsoft.com/oidc/userinfo` (absolute URL)
+
+**Scope**: `openid profile email`
+
+**Group Sync**: Uses Microsoft Graph API to fetch user groups
+
+**API Integration**: Requires Microsoft Graph API permissions
+
+  </TabItem>
+
+  <TabItem label="OneLogin">
+
+### OneLogin Configuration
+
+OneLogin provides enterprise SSO and unified access management with comprehensive role and group mapping.
+
+#### Prerequisites
+
+- OneLogin account (Developer or Enterprise)
+- Admin access to create OAuth applications
+- OneLogin subdomain (e.g., `acme.onelogin.com`)
+
+#### Step 1: Create OAuth Application in OneLogin
+
+1. Log into your OneLogin Admin Portal
+2. Navigate to **Applications** → **Applications**
+3. Click **Add App**
+4. Search for **OpenId Connect (OIDC)** and select it
+5. Configure the application:
+   - **Display Name**: `Blue Alba Platform`
+   - **Redirect URIs**: `https://your-platform.com/auth/onelogin/callback`
+   - **Login URL**: `https://your-platform.com`
+6. Click **Save**
+7. Go to the **SSO** tab
+8. Note the **Client ID** and **Client Secret**
+
+#### Step 2: Configure Token Settings
+
+1. In the **SSO** tab, configure:
+   - **Application Type**: Web
+   - **Token Endpoint**: Authentication Methods should include **POST**
+   - **Token Timeout**: Set according to your security requirements
+2. Save the configuration
+
+#### Step 3: Assign Users
+
+1. Go to the **Users** tab
+2. Assign users or rules for user assignment
+3. Users will now be able to authenticate via OneLogin
+
+#### Step 4: Configure Provider in Blue Alba Platform
+
+**Via Admin UI**:
+- **Provider Type**: OneLogin
+- **Provider Name**: `onelogin` (or custom name)
+- **Issuer URL**: `https://acme.onelogin.com/oidc/2`
+- **Client ID**: Your OneLogin application client ID
+- **Client Secret**: Your OneLogin application client secret
+- **Extras**: Add `{ "region": "us" }` or `{ "region": "eu" }` based on your OneLogin region
+- **Active**: Enabled
+
+**Via Environment Variables** (Legacy):
+
+```bash
+# Enable OneLogin provider
+AUTH_ENV_MIGRATION_ENABLED=true
+AUTH_ONELOGIN_ENABLED=true
+
+# OneLogin Configuration
+AUTH_ONELOGIN_ISSUER=https://acme.onelogin.com/oidc/2
+AUTH_ONELOGIN_CLIENT_ID=abc123def456
+AUTH_ONELOGIN_CLIENT_SECRET=your_client_secret_here
+
+# OneLogin Region (us or eu)
+AUTH_ONELOGIN_REGION=us
+
+# Optional: Subdomain (alternative to full issuer URL)
+AUTH_ONELOGIN_SUBDOMAIN=acme
+```
+
+#### Features
+
+- **SSO Integration**: Seamless single sign-on
+- **Role Mapping**: Map OneLogin roles to platform roles
+- **Group Management**: Automatic group synchronization
+- **API Access**: Integration with OneLogin API for user management
+- **Multi-region Support**: Support for US and EU regions
+- **Logout Support**: Proper session termination
+
+#### Technical Details
+
+**OAuth Endpoints**:
+- Authorization: `/oidc/2/auth`
+- Token: `/oidc/2/token`
+- User Info: `/oidc/2/me`
+
+**Scope**: `openid profile email`
+
+**Group Sync**: Uses OneLogin API to fetch user groups
+
+**Logout**: Supports `id_token_hint` for logout
+
+**Region Specific**: API and OAuth URLs vary by region (US/EU)
+
+  </TabItem>
+
+  <TabItem label="GitHub">
+
+### GitHub OAuth Configuration
+
+GitHub OAuth enables authentication for developers and teams, with support for organization and team-based authorization.
+
+#### Prerequisites
+
+- GitHub account
+- Access to create OAuth apps in your organization (or personal account)
+- Organization membership (for organization-based access control)
+
+#### Step 1: Create OAuth App in GitHub
+
+1. Navigate to GitHub Settings:
+   - **For Organization**: Go to your organization → Settings → Developer settings → OAuth Apps
+   - **For Personal**: Go to your profile → Settings → Developer settings → OAuth Apps
+2. Click **New OAuth App**
+3. Configure the application:
+   - **Application name**: `Blue Alba Platform`
+   - **Homepage URL**: `https://your-platform.com`
+   - **Authorization callback URL**: `https://your-platform.com/auth/github/callback`
+   - **Application description**: (Optional) Description of your platform
+4. Click **Register application**
+5. Note the **Client ID**
+6. Click **Generate a new client secret**
+7. Note the **Client Secret** (it won't be shown again)
+
+#### Step 2: Configure Provider in Blue Alba Platform
+
+**Via Admin UI**:
+- **Provider Type**: GitHub
+- **Provider Name**: `github` (or custom name)
+- **Issuer URL**: `https://github.com`
+- **Client ID**: Your GitHub OAuth app client ID
+- **Client Secret**: Your GitHub OAuth app client secret
+- **Active**: Enabled
+
+**Via Environment Variables** (Legacy):
+
+```bash
+# Enable GitHub provider
+AUTH_ENV_MIGRATION_ENABLED=true
+AUTH_GITHUB_ENABLED=true
+
+# GitHub Configuration
+AUTH_GITHUB_ISSUER=https://github.com
+AUTH_GITHUB_CLIENT_ID=Iv1.a1b2c3d4e5f6g7h8
+AUTH_GITHUB_CLIENT_SECRET=your_client_secret_here
+
+# Optional: Redirect URL override
+AUTH_GITHUB_REDIRECT_URL=https://your-platform.com/auth/github/callback
+```
+
+#### Features
+
+- **GitHub Authentication**: Authenticate users via GitHub accounts
+- **Organization Membership**: Verify organization membership
+- **Team-based Authorization**: Map GitHub teams to platform groups
+- **Public Profile Access**: Access to user's public GitHub profile
+- **Email Verification**: Access to user's verified email addresses
+- **Developer Friendly**: Ideal for developer-focused applications
+
+#### Technical Details
+
+**OAuth Endpoints**:
+- Authorization: `/login/oauth/authorize`
+- Token: `/login/oauth/access_token`
+- User Info: `https://api.github.com/user` (absolute URL)
+
+**Scope**: `user:email offline_access`
+
+**No Built-in Group Sync**: Groups must be managed separately or mapped from organizations/teams
+
+**API Access**: Integrates with GitHub REST API
+
+#### Limitations
+
+**No Enterprise Features**: Basic OAuth doesn't include advanced enterprise features
+
+**Rate Limiting**: Subject to GitHub API rate limits
+
+**Organization Access**: Requires organization membership for team-based features
+
+  </TabItem>
+
+  <TabItem label="AWS Cognito">
+
+### AWS Cognito Configuration
+
+AWS Cognito is Amazon's managed identity service providing user pools with MFA, custom attributes, and Lambda trigger support.
+
+#### Prerequisites
+
+- AWS account with Cognito access
+- IAM permissions to create and configure user pools
+- Cognito User Pool created
+
+#### Step 1: Create User Pool
+
+1. Navigate to [AWS Cognito Console](https://console.aws.amazon.com/cognito)
+2. Click **Create user pool**
+3. Configure sign-in options:
+   - Select **Email** as sign-in option
+   - Choose password requirements
+4. Configure security requirements:
+   - Set password policy
+   - Enable MFA if desired
+5. Configure sign-up experience:
+   - Choose required attributes (email, name, etc.)
+   - Add custom attributes if needed
+6. Configure message delivery:
+   - Set up email provider (SES or Cognito default)
+7. Integrate your app:
+   - **User pool name**: `blue-alba-platform-users`
+   - **App type**: Web application
+   - **App client name**: `blue-alba-platform-client`
+   - **Client secret**: Generate a client secret
+   - **Callback URLs**: `https://your-platform.com/auth/cognito/callback`
+   - **Sign out URLs**: `https://your-platform.com`
+8. Review and create
+
+#### Step 2: Configure Hosted UI Domain
+
+1. In your User Pool, go to **App integration** → **Domain**
+2. Choose **Cognito domain** or **Custom domain**
+3. Enter a domain prefix (e.g., `acme-auth`)
+4. Save changes
+5. Note the full domain: `https://acme-auth.auth.us-east-1.amazoncognito.com`
+
+#### Step 3: Note Configuration Details
+
+From your User Pool, gather:
+- **User Pool ID**: Found in pool details (e.g., `us-east-1_ABC123DEF`)
+- **App Client ID**: From App integration → App clients
+- **App Client Secret**: From App integration → App clients
+- **Domain**: Your Cognito domain from previous step
+- **Region**: Your AWS region (e.g., `us-east-1`)
+
+#### Step 4: Configure Provider in Blue Alba Platform
+
+**Via Admin UI**:
+- **Provider Type**: Cognito
+- **Provider Name**: `cognito` (or custom name)
+- **Issuer URL**: `https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123DEF`
+- **Client ID**: Your Cognito app client ID
+- **Client Secret**: Your Cognito app client secret
+- **Extras**: Add `{ "region": "us-east-1", "userPoolId": "us-east-1_ABC123DEF", "domain": "acme-auth.auth.us-east-1.amazoncognito.com" }`
+- **Active**: Enabled
+
+**Via Environment Variables** (Legacy):
+
+```bash
+# Enable Cognito provider
+AUTH_ENV_MIGRATION_ENABLED=true
+AUTH_COGNITO_ENABLED=true
+
+# Cognito Configuration
+AUTH_COGNITO_USER_POOL_ID=us-east-1_ABC123DEF
+AUTH_COGNITO_CLIENT_ID=1a2b3c4d5e6f7g8h9i0j1k2l3m
+AUTH_COGNITO_CLIENT_SECRET=your_client_secret_here
+AUTH_COGNITO_DOMAIN=acme-auth.auth.us-east-1.amazoncognito.com
+AUTH_COGNITO_REGION=us-east-1
+
+# Optional: Redirect URL override
+AUTH_COGNITO_REDIRECT_URL=https://your-platform.com/auth/cognito/callback
+```
+
+#### Features
+
+- **Managed User Pools**: AWS-managed user directory
+- **Custom Attributes**: Add custom user attributes
+- **MFA Integration**: Built-in multi-factor authentication
+- **Lambda Triggers**: Customize authentication flow with Lambda functions
+- **Social Identity Providers**: Can federate with Facebook, Google, Amazon, Apple
+- **SAML Federation**: Support for enterprise SAML providers
+- **Advanced Security**: Compromised credential detection, risk-based authentication
+- **Group Management**: Cognito groups synchronized to platform
+
+#### Technical Details
+
+**OAuth Endpoints**:
+- Authorization: `/oauth2/authorize`
+- Token: `/oauth2/token`
+- User Info: `/oauth2/userInfo`
+
+**Scope**: `openid profile email`
+
+**Group Sync**: Uses Cognito Admin API to fetch user groups
+
+**Logout**: Custom logout flow with `client_id` and `logout_uri`
+
+**Issuer Format**: `https://cognito-idp.{region}.amazonaws.com/{userPoolId}`
+
+#### AWS-Specific Considerations
+
+**Cost**: Pay per monthly active user (free tier available)
+
+**Regional**: User pools are region-specific
+
+**IAM Credentials**: May need AWS credentials for advanced API access
+
+**Lambda Customization**: Can customize flows with Lambda triggers
+
+  </TabItem>
+</Tabs>
+
+---
+
+## Common Configuration Parameters
+
+All identity providers share common configuration parameters:
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| **Provider Type** | Yes | The type of IDP (okta, entra-id, onelogin, github, cognito) |
+| **Provider Name** | Yes | Unique name for the provider (used in login URLs) |
+| **Issuer URL** | Yes | The OAuth issuer URL (IDP base URL) |
+| **Client ID** | Yes | OAuth client/application ID from IDP |
+| **Client Secret** | Yes | OAuth client secret from IDP |
+| **Active** | Yes | Whether the provider is enabled |
+| **Scope** | No | OAuth scopes (defaults set per provider) |
+| **Redirect URL** | No | Override default callback URL |
+| **Logout URI** | No | Custom logout redirect URL |
+| **Extras** | No | Provider-specific additional configuration (JSON) |
+
+---
+
+## Authentication Flow
+
+All providers follow the standard OAuth 2.0 Authorization Code flow:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Browser
+    participant Gateway
+    participant IDP
+    participant Platform
+
+    User->>Browser: Click "Login with [Provider]"
+    Browser->>Gateway: GET /auth/login?provider=okta
+    Gateway->>Gateway: Generate PKCE challenge & state
+    Gateway->>Browser: Redirect to IDP
+    Browser->>IDP: GET /authorize?client_id=...&redirect_uri=...
+    IDP->>User: Show login page
+    User->>IDP: Enter credentials
+    IDP->>IDP: Authenticate user
+    IDP->>Browser: Redirect with authorization code
+    Browser->>Gateway: GET /auth/callback?code=xyz&state=abc
+    Gateway->>IDP: POST /token (exchange code for tokens)
+    IDP->>Gateway: Access token + ID token
+    Gateway->>IDP: GET /userinfo (with access token)
+    IDP->>Gateway: User info (email, name, etc.)
+    Gateway->>Platform: Create/update user
+    Gateway->>Platform: Sync groups
+    Gateway->>Gateway: Generate platform JWT
+    Gateway->>Browser: Set auth cookie + redirect to app
+    Browser->>User: Logged in successfully
+```
+
+---
+
+## User Provisioning
+
+When a user authenticates for the first time, the platform automatically:
+
+1. **Creates User Record**: A new user account is created in the platform database
+2. **Maps User Info**: User information from IDP is mapped to platform user fields:
+   - Username/Email
+   - Display Name
+   - First Name / Last Name
+   - IDP user ID (for linking)
+3. **Syncs Groups**: User's groups from IDP are synchronized to the platform
+4. **Assigns Roles**: Groups are used to determine user roles and permissions
+5. **Generates JWT**: A platform JWT token is created with user identity and permissions
+
+### User Info Mapping
+
+Each provider has a custom mapper that translates IDP user info to platform format:
+
+```typescript
+// Example: Okta user info mapping
+{
+  // IDP provides:
+  sub: "00u1a2b3c4d5e6f7g8h",
+  email: "john.doe@acme.com",
+  name: "John Doe",
+  given_name: "John",
+  family_name: "Doe",
+
+  // Platform maps to:
+  username: "john.doe@acme.com",
+  displayName: "John Doe",
+  firstName: "John",
+  lastName: "Doe",
+  authProviderUserId: "00u1a2b3c4d5e6f7g8h",
+  authProviderName: "okta"
+}
+```
+
+---
+
+## Group Synchronization
+
+Most providers support automatic group synchronization, which maps IDP groups to platform groups:
+
+### Providers with Group Sync
+
+| Provider | Group Sync | API Used | Notes |
+|----------|------------|----------|-------|
+| **Okta** | Yes | Okta Users API | Fetches all groups user is a member of |
+| **Entra ID** | Yes | Microsoft Graph API | Requires `GroupMember.Read.All` permission |
+| **OneLogin** | Yes | OneLogin API | Fetches roles and groups |
+| **Cognito** | Yes | Cognito Admin API | Fetches Cognito user pool groups |
+| **GitHub** | No | N/A | Groups must be managed in platform |
+
+### Group Sync Process
+
+1. User authenticates with IDP
+2. Platform retrieves access token
+3. Platform calls IDP's group API with access token
+4. IDP returns list of groups user belongs to
+5. Platform creates/updates corresponding groups in database
+6. User is assigned to these groups in platform
+7. Groups determine user's roles and permissions
+
+### Configuring Group Sync
+
+**For Entra ID**:
+- Ensure app has `GroupMember.Read.All` permission
+- Grant admin consent for the permission
+- Groups will be automatically synced on login
+
+**For Okta**:
+- No additional configuration needed
+- All Okta groups are automatically synced
+
+**For OneLogin**:
+- Ensure API credentials have group read access
+- Groups and roles are synced
+
+**For Cognito**:
+- Ensure user is member of Cognito groups
+- Groups must be created in Cognito User Pool first
+- IAM credentials may be needed for Admin API access
+
+---
+
+## Multi-Tenant Configuration
+
+The platform supports multiple identity providers per tenant, enabling:
+
+- **Different IDPs per Tenant**: Each tenant can use a different IDP
+- **Multiple IDPs per Tenant**: A single tenant can support multiple IDPs
+- **Provider Isolation**: IDP configurations are isolated per tenant
+
+### Configuration
+
+When configuring a provider in the database, you can associate it with specific tenants:
+
+1. Create provider configuration
+2. Link provider to tenant(s) via `oauth_provider_tenants` table
+3. Users from each tenant authenticate via their configured IDP
+
+### Login Flow with Multi-Tenancy
+
+```
+1. User goes to: https://your-platform.com
+2. Platform detects tenant (from subdomain or user input)
+3. Platform shows available IDPs for that tenant
+4. User selects IDP
+5. Authentication proceeds via selected IDP
+```
+
+---
+
+## Testing Your Configuration
+
+After configuring an identity provider, test the integration:
+
+### 1. Basic Authentication Test
+
+```bash
+# Navigate to login URL
+https://your-platform.com/auth/login?provider=okta
+
+# You should be redirected to IDP login page
+# After authentication, you should be redirected back with JWT cookie
+```
+
+### 2. Verify User Creation
+
+1. Authenticate a test user
+2. Check Admin UI → Users
+3. Verify user record was created with correct details
+
+### 3. Verify Group Sync
+
+1. Ensure test user has groups in IDP
+2. Authenticate the user
+3. Check user's groups in Admin UI → Users → [User] → Groups
+4. Verify groups match IDP groups
+
+### 4. Test Logout
+
+```bash
+# Navigate to logout URL
+https://your-platform.com/auth/logout
+
+# Verify you're logged out from both platform and IDP
+```
+
+### 5. Check Logs
+
+Monitor gateway service logs for authentication events:
+
+```bash
+# Look for successful authentication logs
+[AuthenticationService] User authenticated: john.doe@acme.com
+[GroupsService] Synced 3 groups for user: john.doe@acme.com
+[UsersService] Created new user: john.doe@acme.com
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+<Aside type="tip" title="Enable Debug Logging">
+  Set `LOG_LEVEL=debug` in gateway service environment to see detailed OAuth flow logs.
+</Aside>
+
+#### "Invalid redirect_uri"
+
+**Cause**: The redirect URI in your platform doesn't match the one configured in IDP.
+
+**Solution**:
+- Verify redirect URI in IDP matches: `https://your-platform.com/auth/{provider}/callback`
+- Ensure protocol (http vs https) matches
+- Check for trailing slashes
+
+#### "Invalid client_id or client_secret"
+
+**Cause**: Incorrect credentials entered in platform configuration.
+
+**Solution**:
+- Double-check client ID and secret from IDP
+- Ensure no extra spaces or characters
+- Regenerate secret if needed
+
+#### "User info not found" or "Email not provided"
+
+**Cause**: IDP not configured to return required user attributes.
+
+**Solution**:
+- Verify OAuth scopes include `profile` and `email`
+- Check IDP app configuration allows access to user info
+- For Entra ID, ensure API permissions are granted
+
+#### Groups Not Syncing
+
+**Cause**: Missing API permissions or group access.
+
+**Solution**:
+- **Entra ID**: Grant `GroupMember.Read.All` permission and admin consent
+- **Okta**: Verify API token has group read access
+- **OneLogin**: Check API credentials have group permissions
+- **Cognito**: Ensure IAM credentials for Admin API
+
+#### "State mismatch" or CSRF errors
+
+**Cause**: State parameter doesn't match between authorization and callback.
+
+**Solution**:
+- This usually indicates session storage issues
+- Check Redis or session store is working correctly
+- Verify state parameter is being stored and retrieved
+
+#### Token Expired Errors
+
+**Cause**: IDP access token has expired.
+
+**Solution**:
+- Ensure `offline_access` scope is included (for refresh tokens)
+- Configure token refresh logic
+- Check IDP token lifetime settings
+
+#### CORS Errors
+
+**Cause**: Browser blocking requests due to CORS policy.
+
+**Solution**:
+- Not typical for OAuth flows (server-side redirects)
+- If using SPA authentication, configure CORS properly
+- Ensure using standard OAuth flow, not implicit flow
+
+---
+
+## Security Best Practices
+
+<Aside type="caution" title="Security Recommendations">
+
+**Credential Security**:
+- Store client secrets securely (use database encryption or secrets manager)
+- Rotate client secrets regularly (e.g., every 90 days)
+- Use environment variables only for non-production environments
+- Never commit secrets to version control
+
+**OAuth Security**:
+- Always use HTTPS in production (required for OAuth)
+- Implement PKCE (Proof Key for Code Exchange) - platform does this automatically
+- Validate state parameter to prevent CSRF attacks
+- Use short-lived authorization codes
+- Implement token rotation for refresh tokens
+
+**Application Security**:
+- Limit OAuth scopes to minimum required
+- Implement proper session timeout
+- Monitor for unusual authentication patterns
+- Enable MFA in IDP when possible
+- Use secure, HTTP-only cookies for session tokens
+
+**Access Control**:
+- Implement principle of least privilege
+- Regularly review group and role assignments
+- Audit authentication and authorization events
+- Monitor for unauthorized access attempts
+
+**Compliance**:
+- Ensure IDP configuration meets regulatory requirements
+- Implement audit logging for authentication events
+- Review and comply with data residency requirements
+- Document authentication flows for compliance audits
+
+</Aside>
+
+---
+
+## Advanced Configuration
+
+### Custom Provider (Generic OIDC)
+
+The platform also supports generic OpenID Connect providers that aren't pre-configured:
+
+```javascript
+// Via Admin UI, select "Custom" provider type
+{
+  "type": "custom",
+  "name": "my-custom-idp",
+  "issuer": "https://idp.example.com",
+  "clientId": "your-client-id",
+  "clientSecret": "your-client-secret",
+  "authUrl": "https://idp.example.com/oauth2/authorize",
+  "tokenUrl": "https://idp.example.com/oauth2/token",
+  "userInfoUrl": "https://idp.example.com/oauth2/userinfo",
+  "mapUsername": "email",
+  "mapDisplayName": "name",
+  "mapFirstName": "given_name",
+  "mapLastName": "family_name"
+}
+```
+
+### Conditional Provider Access
+
+Configure which providers are available based on:
+- **Tenant**: Different IDPs per tenant
+- **Domain**: Email domain-based IDP selection
+- **Application**: Different IDPs per application
+
+### Provider Chaining
+
+For complex scenarios, you can chain multiple providers:
+1. Primary IDP for employees (e.g., Entra ID)
+2. Secondary IDP for partners (e.g., Okta)
+3. Social IDP for public users (e.g., GitHub)
+
+---
+
+## API Reference
+
+### Get Available Providers
+
+```bash
+GET /api/auth/providers
+
+Response:
+[
+  {
+    "name": "okta",
+    "type": "okta",
+    "displayName": "Okta",
+    "active": true
+  },
+  {
+    "name": "entra-id",
+    "type": "entra-id",
+    "displayName": "Microsoft Entra ID",
+    "active": true
+  }
+]
+```
+
+### Login with Provider
+
+```bash
+GET /auth/login?provider=okta&returnTo=/dashboard
+
+# Redirects to IDP login page
+# After success, redirects to returnTo URL
+```
+
+### Logout
+
+```bash
+POST /auth/logout
+
+# Clears platform session
+# Optionally redirects to IDP logout
+```
+
+---
+
+## Related Documentation
+
+- **[Authentication System Architecture](/_/docs/architecture/authentication-system/)** - Deep dive into authentication architecture
+- **[Authorization System](/_/docs/architecture/authorization-system/)** - Understanding RBAC and permissions
+- **[Multi-Tenancy](/_/docs/architecture/multi-tenancy/)** - Tenant isolation and management
+- **[Gateway Architecture](/_/docs/architecture/gateway-architecture/)** - How gateway handles authentication
+
+---
+
+## Support
+
+For issues with identity provider configuration:
+
+1. **Check Logs**: Gateway service logs contain detailed OAuth flow information
+2. **Review IDP Documentation**: Each IDP has specific requirements and quirks
+3. **Test Credentials**: Verify client ID and secret are correct
+4. **Verify Redirect URIs**: Ensure they match between platform and IDP
+5. **Check Permissions**: Verify IDP app has necessary permissions (groups, user info, etc.)
+
+If problems persist, enable debug logging and review the complete OAuth flow in the logs.