# OIDC/SSO Setup Guide

The B12 SIS supports OpenID Connect (OIDC) for Single Sign-On with external identity providers.

## Overview

OIDC enables:

- Login via external identity providers (Google, Azure AD, Okta, etc.)
- Automatic user provisioning
- Centralized authentication management
- Multi-provider support

## Supported Providers

- Google Workspace
- Microsoft Azure AD
- Okta
- Auth0
- Any OIDC-compliant provider

## Configuration

### Add OIDC Provider (Admin API)

**Endpoint:** `POST /api/oidc/providers`

**Request:**
```json
{
  "name": "Google Workspace",
  "provider_type": "google",
  "client_id": "your-client-id.apps.googleusercontent.com",
  "client_secret": "your-client-secret",
  "issuer_url": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "scopes": ["openid", "email", "profile"],
  "auto_provision": true,
  "default_role_id": "user-role-uuid",
  "default_team_id": "main-team-uuid",
  "enabled": true
}
```

## Login Flow

### 1. Initiate Login

Redirect user to:

```
GET /api/oidc/login?provider=google
```

### 2. Authorization

User authenticates with the identity provider.

### 3. Callback

Provider redirects to:

```
GET /api/oidc/callback?code=xxx&state=yyy
```

### 4. Token Exchange

System exchanges authorization code for tokens.

### 5. User Provisioning

- If user exists: Update profile, return JWT
- If user doesn't exist and `auto_provision` enabled: Create user
- If user doesn't exist and `auto_provision` disabled: Return error

## Provider Configuration Examples

### Google Workspace

```json
{
  "name": "Google",
  "provider_type": "google",
  "issuer_url": "https://accounts.google.com",
  "client_id": "xxx.apps.googleusercontent.com",
  "client_secret": "xxx",
  "scopes": ["openid", "email", "profile"]
}
```

### Microsoft Azure AD

```json
{
  "name": "Microsoft",
  "provider_type": "azure",
  "issuer_url": "https://login.microsoftonline.com/{tenant}/v2.0",
  "client_id": "xxx",
  "client_secret": "xxx",
  "scopes": ["openid", "email", "profile"]
}
```

### Okta

```json
{
  "name": "Okta",
  "provider_type": "okta",
  "issuer_url": "https://your-domain.okta.com",
  "client_id": "xxx",
  "client_secret": "xxx",
  "scopes": ["openid", "email", "profile"]
}
```

## Admin Endpoints

### List Providers

`GET /api/oidc/providers`

### Get Provider

`GET /api/oidc/providers/:id`

### Update Provider

`PUT /api/oidc/providers/:id`

### Delete Provider

`DELETE /api/oidc/providers/:id`

### Get Provider Configuration

`GET /api/oidc/providers/:id/.well-known/openid-configuration`

## User Mapping

Map provider claims to SIS user fields:

| OIDC Claim | SIS Field |
|------------|-----------|
| `email` | `email` |
| `name` | `name` |
| `given_name` | First part of name |
| `family_name` | Last part of name |
| `picture` | `avatar` |

## Security Considerations

1. **HTTPS Required**: All OIDC endpoints must use HTTPS
2. **Secret Storage**: Store client secrets securely
3. **Token Validation**: All ID tokens are validated against provider's JWKS
4. **State Parameter**: Prevents CSRF attacks
5. **Nonce Validation**: Prevents replay attacks

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Invalid redirect URI | Update provider's allowed callback URLs |
| User not found | Enable auto_provision or pre-create user |
| Token validation failed | Check issuer URL and JWKS URI |
| Scope denied | Verify requested scopes are enabled |

See `docs/OIDC_SSO_SETUP.md` for detailed setup instructions.