pediatric-ai-scribe-v3/docs/openid-setup.md

# OpenID Connect (OIDC) / PocketID Setup Guide

This guide explains how to configure Single Sign-On (SSO) authentication using OpenID Connect providers like PocketID, Keycloak, Azure AD, Okta, or Google.

## Overview

The application supports OIDC authentication alongside traditional email/password login. Once configured, users can:

- Sign in with their SSO provider (e.g., PocketID)
- Automatically link existing email accounts to their SSO identity
- Admins can optionally disable local password login entirely

## Prerequisites

1. An OpenID Connect provider (e.g., PocketID instance)
2. Admin access to this application
3. The public URL where your app is deployed (`APP_URL` in `.env`)

---

## Configuration Steps

### 1. Configure Your Identity Provider

First, register this application with your OIDC provider. You'll need:

**Redirect URI / Callback URL:**
```
https://your-domain.com/api/auth/oidc/callback
```

Replace `your-domain.com` with your actual `APP_URL` value.

**Example: PocketID Setup**

1. Log into your PocketID admin panel
2. Navigate to **Applications** → **Add Application**
3. Set the callback URL: `https://your-domain.com/api/auth/oidc/callback`
4. Copy the Client ID and Client Secret

**Example: Keycloak Setup**

1. Create a new client in your Keycloak realm
2. Set **Access Type** to `confidential`
3. Add Valid Redirect URI: `https://your-domain.com/api/auth/oidc/callback`
4. Save and note the Client ID and Client Secret from the Credentials tab

### 2. Enable OIDC in Application Settings

Log into your application as an **admin** user, then:

1. Navigate to **Admin Panel** → **Settings** (or access `/admin-settings.html`)
2. Look for the **OpenID Connect (SSO)** section
3. Fill in the following fields:

| Field | Description | Example |
|-------|-------------|---------|
| **Enabled** | Toggle to enable OIDC | `true` |
| **Issuer URL** | Your provider's discovery endpoint | `https://id.example.com` or `https://keycloak.example.com/realms/myrealm` |
| **Client ID** | Application client ID from your provider | `pediatric-scribe-client` |
| **Client Secret** | Application client secret (keep confidential) | `a1b2c3d4...` |
| **Button Label** | Text shown on the SSO login button | `Sign in with PocketID` |
| **Disable Local Auth** | Hide email/password login (optional) | `false` (keep disabled initially) |
| **Allowed IPs** | Restrict SSO to specific IP ranges (optional) | Leave blank for no restriction |

4. Click **Save Settings**

### 3. Test SSO Login

1. Log out or open an incognito browser window
2. Visit the login page
3. You should see a new button: **"Sign in with [Your Provider]"**
4. Click it and authenticate with your SSO provider
5. You'll be redirected back to the application and logged in

---

## Linking Existing Users to SSO

When a user signs in via OIDC for the first time, the system automatically links their account based on **email address matching**:

### Scenario 1: Existing User with Matching Email

If a user already has an account with email `doctor@example.com` and signs in via SSO with the same email:

1. The system finds the existing user by email
2. Links the SSO identity (`oidc_sub`) to the existing account
3. The user is logged in
4. Future logins can use either method (email/password OR SSO)

**Database update performed:**
```sql
UPDATE users
SET oidc_sub = '<provider-unique-id>',
    email_verified = true
WHERE email = 'doctor@example.com';
```

### Scenario 2: New User (No Matching Email)

If the SSO email doesn't match any existing user:

1. A new account is automatically created
2. The user is assigned the `user` role (first user becomes `admin`)
3. A random password is generated (not used for SSO logins)
4. The user is logged in

### Scenario 3: Disabled User

If an existing user is disabled (`disabled = true` in database):

- SSO login is blocked
- User sees an error message
- Admin must re-enable the account from the Admin Panel

---

## Manual Account Linking (CLI)

If you need to manually link an existing user to an SSO identity, use the PostgreSQL database directly:

```bash
# Connect to database
docker exec -it pediatric-ai-scribe-postgres psql -U pedscribe -d pedscribe

# Link user by setting their oidc_sub
UPDATE users
SET oidc_sub = 'provider-sub-12345',
    email_verified = true
WHERE email = 'doctor@example.com';
```

**Finding the `oidc_sub` value:**

The `oidc_sub` is the unique identifier from your OIDC provider (usually a UUID or numeric ID). To find it:

1. Have the user attempt SSO login once
2. Check the application logs for their `sub` claim:
   ```
   [OIDC] User logged in: sub=abc-123-def, email=doctor@example.com
   ```
3. Use that `sub` value in the UPDATE statement

---

## Security Considerations

### HTTPS Required in Production

OIDC requires HTTPS for security. Ensure your `APP_URL` uses `https://`:

```env
APP_URL=https://scribe.example.com
```

### Client Secret Protection

The client secret is stored encrypted in the database. The admin UI masks it after saving (shows `••••••••1234`).

**Never commit the client secret to Git or share it publicly.**

### IP Allowlisting (Optional)

To restrict SSO to specific networks (e.g., hospital VPN):

1. Set **Allowed IPs** in admin settings to comma-separated CIDR ranges:
   ```
   10.0.0.0/8, 192.168.1.0/24
   ```
2. Users outside these ranges will see an error when attempting SSO

### Disable Local Password Login

Once SSO is working, you can optionally disable traditional email/password login:

1. In Admin Settings, enable **Disable Local Auth**
2. The login page will only show the SSO button
3. Admins can still use the CLI to reset passwords if needed

**Warning:** Only disable local auth after confirming all users can access SSO. Keep one admin password as backup.

---

## Troubleshooting

### "SSO is not enabled" error

- Verify **Enabled** is set to `true` in admin settings
- Check application logs for OIDC configuration errors

### "Invalid state" or "Expired" error

- The OIDC flow timed out (5 minute window)
- Try logging in again
- If persistent, check server time synchronization

### "No email claim" error

Your OIDC provider didn't return an email address. Ensure:

1. The `email` scope is requested (default: `openid email profile`)
2. Your provider is configured to release email claims
3. The user's account has an email address set

### Email Mismatch

If a user has different emails in the app vs. SSO provider:

**Option 1: Update app email to match SSO**
```sql
UPDATE users SET email = 'new-email@example.com' WHERE id = 123;
```

**Option 2: Update SSO provider email to match app**
(Provider-specific — consult your IdP documentation)

### Callback URL Not Working

Double-check the redirect URI in your OIDC provider settings matches exactly:

```
https://your-domain.com/api/auth/oidc/callback
```

Common mistakes:
- Missing `https://`
- Trailing slash (don't include it)
- Wrong domain (must match `APP_URL` in `.env`)

---

## Provider-Specific Examples

### PocketID

```
Issuer URL: https://id.pockethost.io
Client ID: (from PocketID app settings)
Client Secret: (from PocketID app settings)
Redirect URI: https://your-domain.com/api/auth/oidc/callback
```

### Keycloak

```
Issuer URL: https://keycloak.example.com/realms/medical
Client ID: pediatric-scribe
Client Secret: (from Credentials tab)
Redirect URI: https://your-domain.com/api/auth/oidc/callback
```

### Azure AD / Entra ID

```
Issuer URL: https://login.microsoftonline.com/{tenant-id}/v2.0
Client ID: (Application ID from Azure)
Client Secret: (from Certificates & secrets)
Redirect URI: https://your-domain.com/api/auth/oidc/callback
```

Note: Azure requires app registration in Azure Portal first.

### Okta

```
Issuer URL: https://{your-okta-domain}.okta.com
Client ID: (from Okta application settings)
Client Secret: (from Okta application settings)
Redirect URI: https://your-domain.com/api/auth/oidc/callback
```

### Google (Workspace or Gmail)

```
Issuer URL: https://accounts.google.com
Client ID: (from Google Cloud Console)
Client Secret: (from Google Cloud Console)
Redirect URI: https://your-domain.com/api/auth/oidc/callback
```

Note: Google requires OAuth consent screen configuration.

---

## Environment Variables (Alternative to UI Config)

For deployment automation, you can set OIDC config via environment variables instead of the admin UI:

```env
# .env file
OIDC_ENABLED=true
OIDC_ISSUER=https://id.example.com
OIDC_CLIENT_ID=my-client-id
OIDC_CLIENT_SECRET=my-client-secret
OIDC_BUTTON_LABEL=Sign in with PocketID
OIDC_DISABLE_LOCAL_AUTH=false
```

**Note:** UI settings take precedence over environment variables. If set in both places, the database values are used.

---

## HIPAA Compliance Notes

OIDC does not transmit PHI to the identity provider. Only authentication-related data (email, name) is exchanged.

For HIPAA compliance:
- Ensure your OIDC provider has appropriate safeguards
- Use a self-hosted provider (Keycloak, PocketID) within your secure network
- Or use a HIPAA-compliant SaaS provider with a BAA
- Enable audit logging for all SSO login events (automatically logged in `audit_log` table)

---

## Audit Logging

All SSO login events are logged in the `audit_log` table:

```sql
SELECT * FROM audit_log WHERE action = 'login_oidc' ORDER BY created_at DESC;
```

Logged fields:
- User ID
- Action: `login_oidc`
- IP address
- Details: Issuer URL
- Timestamp

---

## Support

For issues specific to:
- **This application**: Check application logs with `docker logs pediatric-ai-scribe`
- **Your OIDC provider**: Consult provider documentation (PocketID, Keycloak, Azure, etc.)
- **Network/TLS issues**: Verify `APP_URL` matches your reverse proxy configuration

Common log locations:
```bash
# Application logs
docker logs pediatric-ai-scribe

# PostgreSQL logs
docker logs pediatric-ai-scribe-postgres
```