Skip to main content

SAML / SCIM SSO

QuickstartAPI ReferenceAuth GuideWebhooksFHIR & HL7SAML / SCIM SSOOpenAPI & SwaggerAPI VersioningAsyncAPI ContractSDK PackagingEvent SchemasRecipesTroubleshooting

SAML / SCIM Enterprise Identity Federation

Last updated: 2026-02-17

This document covers enterprise identity integration in Bounded Health.

1. Components implemented

  • SAML SSO endpoints for SP-initiated login and ACS callback
  • Employer-level SSO configuration API
  • SCIM 2.0 user provisioning endpoints with employer-scoped bearer token auth
  • SCIM Group endpoints for directory group sync
  • Clerk sign-in token bridging in SAML callback flow
  • SCIM endpoint throttling and deprovision safeguards

2. SSO configuration endpoint

GET|POST /api/employer/sso

Auth:

  • Clerk session or API key with sso:manage

Supported configuration fields:

  • samlEnabled
  • samlMetadataUrl
  • samlEntryPoint
  • samlCertificate
  • samlIssuer
  • samlNameIdFormat
  • samlEmailAttribute
  • samlFirstNameAttribute
  • samlLastNameAttribute
  • scimEnabled
  • rotateScimToken

Important:

  • POST may return a new scimBearerToken exactly once when SCIM is enabled or rotated.

3. SAML endpoints

  • GET /api/auth/saml/start/{employerId}
    • Starts SP-initiated flow and redirects to IdP
  • POST /api/auth/saml/callback/{employerId}
    • Validates assertion and resolves/creates local user
    • Ensures Clerk user exists and issues Clerk sign-in token redirect
  • GET /api/auth/saml/metadata/{employerId}
    • Returns SP metadata XML for IdP setup

4. SCIM endpoints

  • GET /api/scim/v2/ServiceProviderConfig
  • GET /api/scim/v2/ResourceTypes
  • GET /api/scim/v2/Users
  • POST /api/scim/v2/Users
  • GET /api/scim/v2/Users/{userId}
  • PATCH /api/scim/v2/Users/{userId}
  • DELETE /api/scim/v2/Users/{userId}
  • GET /api/scim/v2/Groups
  • POST /api/scim/v2/Groups
  • GET /api/scim/v2/Groups/{groupId}
  • PATCH /api/scim/v2/Groups/{groupId}
  • DELETE /api/scim/v2/Groups/{groupId}

SCIM auth:

  • Authorization: Bearer <scim_token>
  • Token is hashed in storage and tenant-scoped

5. SCIM behavior details

User Provision (POST /Users)

  • Creates PATIENT users under employer tenant
  • Supports userName, emails[0].value, externalId, active
  • If user exists in a different employer tenant, returns conflict

User Patch (PATCH /Users/{userId})

Supported replace operations:

  • active
  • externalId
  • userName
  • patch payloads with value object are also supported

User Delete (DELETE /Users/{userId})

  • Soft-deactivates user under tenant scope
  • Revokes API keys created by the user (if any)
  • Attempts to revoke active Clerk sessions when backend credentials are configured

Group Provision (POST /Groups)

  • Creates tenant-scoped SCIM groups
  • Supports displayName, externalId, and optional members
  • Validates that all members belong to the authenticated employer tenant

Group Patch (PATCH /Groups/{groupId})

Supports:

  • displayName replacement
  • externalId replacement
  • member add/remove/replace operations

Group Delete (DELETE /Groups/{groupId})

  • Deletes group and memberships under tenant scope

Tenant isolation:

  • Mutations are constrained by id + employerId checks
  • Cross-tenant user/group updates are blocked

6. Endpoint hardening

  • SCIM request rate limiting is enforced before token validation
  • SCIM auth and routes return SCIM-compliant error envelopes
  • Deprovision flow includes soft delete plus credential/session cleanup attempts

7. Error model

SCIM errors return SCIM-compliant envelope:

json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "401",
  "detail": "Bearer token required"
}

8. Security and operations

  • Rotate SCIM token on admin turnover or suspected leak
  • Limit SAML certificate update access to privileged administrators
  • Audit monitor:
    • sso.config.update
    • auth.saml.login
    • auth.saml.provision
    • scim.user.provision
    • scim.user.update
    • scim.user.deactivate
    • scim.group.create
    • scim.group.update
    • scim.group.delete

9. Enterprise rollout checklist

  • Configure SAML metadata/certificate and validate IdP login
  • Validate ACS callback with real assertion payload in staging
  • Enable SCIM and store token in IdP provisioning secret manager
  • Run end-to-end provisioning lifecycle:
    • user create/update/deactivate
    • group create/update/delete
  • Confirm tenant isolation by negative tests across employers