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:

{
  "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

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

{
  "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

{
  "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

{
  "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

HTTPS Required: All OIDC endpoints must use HTTPS
Secret Storage: Store client secrets securely
Token Validation: All ID tokens are validated against provider’s JWKS
State Parameter: Prevents CSRF attacks
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.