Use Case 018: External Identity Provider Integration

Overview

Description

This use case describes how Application Manager integrates with external identity providers (OAuth 2.0, SAML 2.0, Azure AD/Entra ID, Google Workspace, Okta) to enable single sign-on (SSO) for ApplicationUsers. Rather than replacing existing enterprise authentication systems, Application Manager acts as a lightweight authorization layer—validating tokens from trusted identity providers, mapping external users to internal ApplicationUser records, and enforcing role-based access control. This allows organizations to leverage existing identity infrastructure while gaining centralized application management capabilities.

Actors

Preconditions

1. Application Manager is running and accessible
2. Administrator has access to external IdP configuration
3. Application Manager DNS/URL is accessible from IdP for callbacks
4. SSL certificates configured for HTTPS endpoints
5. Database schema for IdP configuration is initialized
6. Admin has idp:configure capability

Postconditions

Success Postconditions

1. Identity provider configured with OAuth/SAML credentials
2. Trust relationship established between IdP and Application Manager
3. User authenticated via external IdP
4. ApplicationUser record created/updated with external ID mapping
5. Session created with SSO-validated identity
6. User redirected to application or launch dashboard
7. SSO events logged in audit trail

Failure Postconditions

1. Authentication failure logged with reason
2. User shown clear error message with fallback options
3. No session created for failed authentication
4. Alert sent to administrator for repeated failures

Triggers

• Administrator configures new identity provider
• User clicks "Sign in with [Provider]" button
• Application redirects to Application Manager for SSO authentication
• IdP callback received after user authentication
• User token validation request from application
• Administrator tests IdP configuration

Basic Flow (Happy Path - Azure AD/Entra ID)

sequenceDiagram
    actor Admin as Administrator
    participant WebAdmin as Admin UI
    participant API as AppManager API
    participant DB as Database
    actor User as ApplicationUser
    participant App as Riptide Application
    participant WebLogin as Login UI
    participant AzureAD as Azure AD / Entra ID

    Note over Admin,AzureAD: IdP Configuration Phase
    
    Admin->>WebAdmin: Navigate to Identity Providers
    WebAdmin->>API: GET /api/v1/identity-providers
    API->>DB: Fetch configured IdPs
    DB->>API: IdP list
    API->>WebAdmin: IdP configurations
    
    Admin->>WebAdmin: Click "Add Identity Provider"
    WebAdmin->>Admin: Show IdP configuration form
    
    Admin->>WebAdmin: Select "Azure AD / Entra ID"
    Admin->>WebAdmin: Enter tenant ID, client ID, client secret
    WebAdmin->>API: POST /api/v1/identity-providers
    
    API->>API: Validate configuration
    API->>AzureAD: Test connection (OpenID discovery)
    AzureAD->>API: Configuration endpoints
    
    API->>DB: Store IdP configuration (encrypted secrets)
    DB->>API: IdP saved
    API->>DB: Log IdP configuration
    API->>WebAdmin: 201 Created (IdP details)
    WebAdmin->>Admin: Success: Azure AD configured
    
    Note over User,AzureAD: User SSO Authentication Flow
    
    User->>App: Navigate to application
    App->>WebLogin: Redirect to /login with returnUrl
    WebLogin->>User: Show login options
    
    Note over WebLogin,User: Login page shows:<br/>- Sign in with Azure AD<br/>- Sign in with Email/Password
    
    User->>WebLogin: Click "Sign in with Azure AD"
    WebLogin->>API: Initiate SSO flow
    API->>API: Generate state parameter (CSRF token)
    API->>DB: Store state for validation
    
    API->>WebLogin: Redirect to Azure AD authorize endpoint
    WebLogin->>AzureAD: Redirect user to login
    Note over AzureAD: User sees Azure AD login page
    
    AzureAD->>AzureAD: User enters Azure credentials
    AzureAD->>AzureAD: Validate user & check MFA
    
    AzureAD->>WebLogin: Redirect to callback with code & state
    WebLogin->>API: GET /auth/azuread/callback?code=xyz&state=abc
    
    API->>DB: Validate state parameter
    DB->>API: State valid
    
    API->>AzureAD: POST /token (exchange code for tokens)
    AzureAD->>API: Access token, ID token, user info
    
    API->>API: Validate ID token signature (JWT)
    API->>API: Extract user claims (email, name, sub)
    
    API->>DB: Find ApplicationUser by external ID
    
    alt User exists in Application Manager
        DB->>API: ApplicationUser found
        API->>API: Update last login timestamp
    else User does not exist
        API->>DB: Create ApplicationUser (auto-provisioning)
        DB->>API: New user created
        API->>API: Assign default roles for SSO users
    end
    
    API->>DB: Create session record
    DB->>API: Session created
    
    API->>DB: Log successful SSO login
    API->>WebLogin: Session token + redirect to app
    WebLogin->>App: Redirect with session token
    
    App->>API: Validate session token
    API->>DB: Verify session active
    DB->>API: Session valid
    API->>DB: Fetch user capabilities
    DB->>API: User roles & capabilities
    API->>App: User validated with capabilities
    
    App->>User: Display application dashboard

Alternative Flows

Alt-1: OAuth 2.0 Generic Provider (Google, GitHub)

Differences from Azure AD flow:

1. Administrator selects "OAuth 2.0 Generic" provider
2. Configures authorize URL, token URL, userinfo URL
3. Specifies claim mappings (email claim, name claim, ID claim)
4. OAuth flow follows standard authorization code grant
5. User info fetched from userinfo endpoint after token exchange

Alt-2: SAML 2.0 Provider (Okta, OneLogin)

Differences:

1. Administrator uploads IdP metadata XML or URL
2. Application Manager generates SP metadata for IdP configuration
3. User clicks "Sign in with SAML"
4. Application Manager sends SAML AuthnRequest
5. IdP redirects user to login page
6. IdP posts SAML Response to Application Manager callback
7. Application Manager validates SAML assertion signature
8. User claims extracted from SAML attributes
9. Session created and user logged in

Alt-3: Just-In-Time (JIT) User Provisioning

Trigger: User authenticates via IdP but doesn't exist in Application Manager

Flow:

1. SSO authentication succeeds
2. System checks for ApplicationUser with external ID
3. No user found
4. System extracts user info from IdP claims
5. System creates ApplicationUser automatically:
   • Email from IdP claim
   • FullName from IdP claim
   • ExternalUserId set to IdP subject ID
   • AuthMethod set to SSO
   • Default roles assigned (configured per IdP)
6. User linked to tenant (if specified in config)
7. Session created for new user
8. Audit log: "Auto-provisioned user from Azure AD"

Alt-4: Account Linking for Existing Users

Trigger: User with password auth wants to link SSO

Flow:

1. User authenticates with password
2. User navigates to Account Settings
3. User clicks "Link Azure AD Account"
4. System initiates SSO flow
5. User authenticates via Azure AD
6. System validates both sessions
7. System updates ApplicationUser with external ID
8. Future logins allowed via either method

Alt-5: SSO Authentication Failure

Trigger: IdP returns error or token validation fails

Flow:

1. User redirected to IdP and authenticates
2. IdP returns error (access_denied, invalid_scope)
3. Application Manager logs error details
4. User redirected to login page with error message
5. Error message shown: "Authentication failed: [reason]"
6. User can try again or use alternative login method
7. Alert sent to administrator after 5 failures in 10 minutes

Business Rules

Identity Provider Configuration

• BR-018-01: Only administrators with idp:configure capability can add/modify IdPs
• BR-018-02: IdP client secrets must be encrypted at rest (AES-256)
• BR-018-03: Maximum 10 identity providers per Application Manager instance
• BR-018-04: IdP configurations must be validated before activation
• BR-018-05: Disabled IdPs retain configuration but prevent new logins

User Provisioning Rules

• BR-018-06: JIT provisioning creates users only if enabled per IdP
• BR-018-07: SSO users inherit default roles specified in IdP configuration
• BR-018-08: External user ID must be unique across all ApplicationUsers
• BR-018-09: Email claim from IdP must be valid email format
• BR-018-10: Users cannot have both password and SSO auth methods simultaneously (unless explicitly linked)

Session Management Rules

• BR-018-11: SSO sessions have same timeout as password sessions (default: 8 hours)
• BR-018-12: SSO logout optionally redirects to IdP logout endpoint
• BR-018-13: Refresh tokens (if provided) stored encrypted and rotated
• BR-018-14: State parameter required for OAuth flows (CSRF protection)

Token Validation Rules

• BR-018-15: JWT tokens must be validated for signature, expiration, issuer, audience
• BR-018-16: SAML assertions must be validated for signature and timestamps
• BR-018-17: Token validation failures result in authentication rejection
• BR-018-18: IdP public keys cached for 24 hours, refreshed from JWKS endpoint

Data Requirements

IdentityProvider Entity

ExternalIdentity Entity

Claim Mappings JSON Structure

{
  "emailClaim": "email",
  "nameClaim": "name",
  "givenNameClaim": "given_name",
  "familyNameClaim": "family_name",
  "subjectClaim": "sub",
  "groupsClaim": "groups",
  "customClaims": {
    "department": "extension_Department",
    "employeeId": "extension_EmployeeId"
  }
}

API Endpoints

List Identity Providers

Endpoint: GET /api/v1/identity-providers

Response: 200 OK

{
  "providers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corp Azure AD",
      "type": "AzureAD",
      "isEnabled": true,
      "jitProvisioningEnabled": true,
      "createdAt": "2026-01-15T10:00:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Google Workspace",
      "type": "Google",
      "isEnabled": true,
      "jitProvisioningEnabled": false,
      "createdAt": "2026-02-01T14:30:00Z"
    }
  ]
}

Configure Identity Provider

Endpoint: POST /api/v1/identity-providers

Request Body (Azure AD example):

{
  "name": "Acme Corp Azure AD",
  "type": "AzureAD",
  "tenantId": "12345678-1234-1234-1234-123456789012",
  "clientId": "87654321-4321-4321-4321-210987654321",
  "clientSecret": "your-client-secret-here",
  "jitProvisioningEnabled": true,
  "defaultRoles": ["role-id-1", "role-id-2"],
  "allowedDomains": ["acme.com", "acmecorp.com"],
  "claimMappings": {
    "emailClaim": "email",
    "nameClaim": "name",
    "subjectClaim": "sub"
  }
}

Response: 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corp Azure AD",
  "type": "AzureAD",
  "isEnabled": true,
  "authorizeEndpoint": "https://login.microsoftonline.com/12345.../oauth2/v2.0/authorize",
  "tokenEndpoint": "https://login.microsoftonline.com/12345.../oauth2/v2.0/token",
  "createdAt": "2026-02-23T10:30:00Z"
}

Initiate SSO Login

Endpoint: GET /api/v1/auth/sso/initiate?provider={providerId}&returnUrl={url}

Response: 302 Redirect

Location: https://login.microsoftonline.com/...?
  client_id=...&
  response_type=code&
  redirect_uri=https://app-manager.example.com/auth/callback&
  scope=openid+profile+email&
  state=random-csrf-token

SSO Callback

Endpoint: GET /api/v1/auth/sso/callback?code={code}&state={state}

Processing:

1. Validate state parameter
2. Exchange code for tokens
3. Validate tokens
4. Create/update user
5. Create session
6. Redirect to returnUrl

Response: 302 Redirect

Location: {returnUrl}?sessionToken={token}

Performance Requirements

• PR-018-01: SSO initiation redirect completed within 500ms
• PR-018-02: Token exchange and validation completed within 2 seconds
• PR-018-03: JIT user provisioning completed within 3 seconds
• PR-018-04: IdP configuration validation completed within 5 seconds
• PR-018-05: JWT signature validation completed within 100ms

Security Considerations

OAuth/OIDC Security

• State parameter required for CSRF protection (random 256-bit)
• Code verifier (PKCE) used for mobile/SPA flows
• Tokens validated for signature, expiration, issuer, audience
• Client secrets encrypted at rest (AES-256)
• IdP discovery endpoints cached securely
• Nonce parameter used to prevent replay attacks

SAML Security

• SAML assertions validated for signature using IdP certificate
• Timestamps checked to prevent replay (NotBefore, NotOnOrAfter)
• Assertion encryption supported (optional)
• SP metadata signed
• Mutual TLS supported for high-security environments

Token Management

• Access tokens encrypted if stored
• Refresh tokens rotated on use
• Tokens expire per IdP policy
• Revocation endpoint called on logout (if supported)

Audit & Compliance

• All SSO events logged (success, failure, provisioning)
• Failed authentication attempts rate-limited
• PII from IdP claims handled per GDPR requirements
• Admin changes to IdP configuration audited

Testing Scenarios

Test Case TC-018-01: Azure AD SSO Login

Preconditions:

• Azure AD IdP configured and enabled
• Test user exists in Azure AD

Steps:

1. User navigates to application
2. User clicks "Sign in with Azure AD"
3. User redirected to Azure AD login
4. User enters Azure credentials
5. Azure AD redirects back with code
6. Application Manager exchanges code for tokens
7. User created/updated in database
8. Session created
9. User redirected to application

Expected Results:

• User authenticated successfully
• ApplicationUser record exists with correct external ID
• Session token returned
• Audit log contains SSO login event

Test Case TC-018-02: JIT User Provisioning

Preconditions:

• IdP configured with JIT provisioning enabled
• User does not exist in Application Manager

Steps:

1. New user authenticates via IdP
2. System detects user doesn't exist
3. System creates ApplicationUser from IdP claims
4. Default roles assigned
5. Session created

Expected Results:

• New ApplicationUser created
• Email, name populated from IdP
• ExternalUserId set correctly
• Default roles assigned
• Audit log: "User auto-provisioned from Azure AD"

Test Case TC-018-03: Invalid Token Rejection

Steps:

1. Simulate IdP callback with invalid token
2. System attempts to validate token

Expected Results:

• Token validation fails
• Error logged with details
• User shown authentication error
• No session created

Monitoring and Analytics

Metrics

• sso.login.success: Count of successful SSO logins (by IdP)
• sso.login.failure: Count of failed authentications (by reason)
• sso.jit.provisioning: Count of auto-provisioned users
• sso.token.validation.duration: Token validation latency
• sso.provider.availability: IdP endpoint health checks

Alerts

• IdP endpoint unreachable: Failed health checks > 3 in 5 minutes
• High authentication failure rate: > 10% failures in 1 hour
• Token validation errors: > 5 signature failures in 10 minutes

Dashboards

• SSO login trends (by IdP, by day)
• Authentication success/failure rates
• JIT provisioning statistics
• Token validation performance

Related Use Cases

• UC-002: Trial User Login and Session Management - Session creation
• UC-003: Application Access Validation - Token validation
• UC-015: Application User Provisioning - User creation
• UC-017: Team Member Invitation - Account linking
• UC-010: Activity Logging and Audit Trail - SSO event logging

Notes and Assumptions

Assumptions

1. Organization already has functioning IdP infrastructure
2. Users have valid accounts in external IdP
3. Network connectivity to IdP endpoints is reliable
4. SSL certificates properly configured

Implementation Notes

1. Prioritize Azure AD/Entra ID for MVP (widest enterprise adoption)
2. OAuth 2.0 generic provider supports Google, GitHub, GitLab
3. SAML 2.0 supports Okta, OneLogin, PingFederate
4. Consider rate limiting IdP API calls
5. Cache IdP discovery/metadata to reduce API calls

Future Enhancements

1. Support for SCIM 2.0 user provisioning from IdP
2. Group/role synchronization from IdP
3. Multi-factor authentication passthrough
4. Session management across multiple IdPs
5. Advanced claim transformation rules

Revision History