feat: Add SCIM v2 support #2115

felixmccuaig · 2025-08-16T06:22:30Z

What kind of change does this PR introduce?

Feature: SCIM v2.0 provider management with database-backed multi-tenancy

What is the current behavior?

No SCIM support exists
External identity providers cannot provision/deprovision users via SCIM protocol

What is the new behavior?

Database-backed SCIM Provider Management

New scim_providers table with UUID-based provider isolation
Admin API endpoints for SCIM provider CRUD operations:
- POST /admin/scim-providers - Create new provider (auto-generates secure token)
- GET /admin/scim-providers - List all providers
- GET /admin/scim-providers/{provider_id} - Get provider details
- POST /admin/scim-providers/{provider_id}/rotate-token - Rotate bearer token
- DELETE /admin/scim-providers/{provider_id} - Delete provider
Each provider gets a unique UUID and cryptographically secure bearer token
Users are isolated per provider via scim_provider_id foreign key

SCIM v2.0 Endpoints

All endpoints under /scim/v2:

GET /ServiceProviderConfig - SCIM capabilities
GET /ResourceTypes - Available resource types
GET /Schemas - SCIM schemas
Users Resource:
- GET /Users - List with pagination and filtering
- POST /Users - Create user
- GET /Users/{id} - Get user
- PUT /Users/{id} - Replace user
- PATCH /Users/{id} - Update user (RFC7644 operations)
- DELETE /Users/{id} - Deprovision user

Authentication

Bearer token authentication using provider-specific tokens from database
Tokens validated against scim_providers.token_hash (SHA-256)
Per-request provider context for user isolation

User Mapping

userName / emails[0].value → user email
name.givenName, name.familyName, displayName → user_metadata
externalId → scim_external_id column
scim_provider_id → links user to provider

Filtering

Minimal filter support:

filter=userName eq "[email protected]"
filter=externalId eq "ext-123"

Deprovisioning

Default: Ban user for 100 years (soft deprovision)
Optional: Soft delete if GOTRUE_SCIM_BAN_ON_DEACTIVATE=false
Never hard deletes users

Configuration

New environment variables:

GOTRUE_SCIM_ENABLED=true|false          # Default: false
GOTRUE_SCIM_BASE_URL=http://...         # For Location headers
GOTRUE_SCIM_DEFAULT_AUDIENCE=authenticated
GOTRUE_SCIM_BAN_ON_DEACTIVATE=true|false # Default: true

Note: SCIM bearer tokens are now managed via the database and admin API, not env vars.

Database Changes

New migration adds scim_providers table:

id (UUID, primary key)
name (text, provider name)
token_hash (text, SHA-256 of bearer token)
created_at, updated_at (timestamps)

New columns on users table:

scim_external_id (text, nullable) - External IdP identifier
scim_provider_id (UUID, nullable, FK to scim_providers) - Provider isolation

Tests

internal/api/scim_test.go:
- ServiceProviderConfig schema validation
- Full user lifecycle: create → get → patch active=false → delete
- Verifies soft deprovision (user remains in DB, is disabled)
- Pagination and filtering tests
- Provider isolation tests (users only visible to their provider)
- Admin API tests (create/list/get/rotate/delete providers)
internal/api/middleware_test.go:
- SCIM enablement gate
- Database-backed bearer token authentication

How to Test Locally

# Start database
bash hack/postgresd.sh

# Run migrations
bash hack/migrate.sh postgres

# Run tests
go test ./internal/api -v -run SCIM

# Manual test - create provider
curl -X POST http://localhost:9999/admin/scim-providers \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"My IdP"}'

# Use returned token for SCIM operations
curl -H "Authorization: Bearer <scim-token>" \
  http://localhost:9999/scim/v2/ServiceProviderConfig

Additional Context

Multi-tenant by design: Each SCIM provider operates in isolation with UUID-based partitioning
Backward compatible: Disabled by default, gated behind GOTRUE_SCIM_ENABLED
Groups not included: This PR implements Users only; Groups can be added later
Security: Tokens are SHA-256 hashed in database, never stored in plaintext
Future work: Group support, advanced filtering, bulk operations

🤖 Generated with Claude Code

…, filters, soft deprovision; config + routing; tests for endpoints and middleware

felixmccuaig · 2025-08-16T06:26:53Z

Hello guys, wanting to add SCIM support. I've implemented it using: github.com/elimity-com/scim and would love to hear your thoughts because we need SCIM support for our customers :)

Happy to make any changes needed to get this over the line.

… remains separate from SAML SSO user and SCIM deprovision only disables SCIM user

… aud check; merge security & SAML tests into scim_test.go

cstockton · 2025-08-17T16:04:08Z

Hi @felixmccuaig! First let me say thank you on behalf of the auth team for the work you've done here. I've approved the workflows to run, it looks like the next step will be to make sure the changes pass gofmt / gosec / linter. Since this is a significant / security sensitive change, it may take a little time to get merged as everyone on the auth team will need to give it a very thorough review.

…00 error

hf · 2025-08-18T08:59:05Z

Wow this is excellent! Thank you for the contribution!

felixmccuaig · 2025-08-18T09:02:32Z

Yeah there might be a bit of back and fourth on this one, esp since we're in aus 😆

Addresses gosec G115 integer overflow vulnerability by ensuring page and count values are non-negative before converting to uint64 in pagination parameters.

hf

Really well done for an initial contribution!

internal/api/middleware.go

internal/api/scim.go

hf · 2025-08-18T09:06:13Z

internal/api/scim.go

+}
+
+// Users create
+func (a *API) SCIMUsersCreate(w http.ResponseWriter, r *http.Request) error {


The current implementation means that:

SCIM users don't have a password

They aren't associated with an SSO identity

They can only log in via email magic link / OTP

Is it useful like this? We need to figure out how to give authentication ability to SCIM created users, without making a security hole.

Might be best to just keep the SCIM remove user API for now.

hf · 2025-08-18T09:07:05Z

internal/api/scim.go

+    err = db.Transaction(func(tx *storage.Connection) error {
+        if terr := tx.Create(user); terr != nil { return terr }
+        if user.GetEmail() != "" {
+            if _, terr := a.createNewIdentity(tx, user, "email", map[string]any{"email": user.GetEmail(), "email_verified": true, "sub": user.ID.String()}); terr != nil {
+                return terr
+            }
+        }
+        return nil
+    })
+    if err != nil { return err }


There is probably some low-hanging fruit, if the SCIM provider could be identified and cross-referenced to an SSO provider, then instead of an email identity you'd create the SSO identity, resolving my previous comment.

Instead of a scim_external_id on the raw app meta data, let's maybe create a SCIM identity proper:

Provider ID scim:<ID of SCIM server>

Identity ID <scim_external_id>

That brings up the question of SCIM server management, which right now happens via the Basic Auth mechanism? Maybe it's best to have this live in the database under (example table):

create table auth.scim_providers (id uuid primary key, password_hash text);

Then when the SCIM server is authenticated, instead of looking up the provider from config, you'd look it up from this table.

internal/api/scim.go

hf · 2025-08-18T15:42:31Z

One more note on security, we need to make sure that SCIM providers can only manage the users they control. A malicious SCIM provider shouldn't be able to delete a user managed by another one.

…back - Use secure password comparison with crypto/subtle.ConstantTimeCompare for SCIM basic auth - Create proper auth.scim_providers table with password hashes for provider management - Convert all map-based responses to proper Go structs (ServiceProviderConfig, ResourceTypes, Schemas) - Implement JSON parsing for filter values instead of manual string trimming - Add dedicated scim_external_id column with index instead of raw_app_meta_data storage - Implement comprehensive SCIM provider isolation system ensuring providers only manage their own users - Add database migrations for new scim_providers, scim_external_id, and scim_provider_id columns - Update User model with SCIMExternalID and SCIMProviderID fields using storage.NullString

felixmccuaig · 2025-09-03T13:21:37Z

@hf okay to re run checks?

hf · 2025-09-03T13:24:49Z

We are now internally tracking this as a project.

felixmccuaig · 2025-09-03T13:28:54Z

Nice, does that mean the supabase team will take care of it?

hf · 2025-09-03T13:49:59Z

Nice, does that mean the supabase team will take care of it?

We'll see exactly how it works, but this codebase is a great foundation to build upon.

felixmccuaig · 2025-09-03T22:56:57Z

Sounds good :)

Merged latest changes from supabase/auth master branch to keep SCIM implementation up to date. Resolved merge conflict in configuration.go by preserving both SCIM configuration and new Experimental/Reloading configurations from upstream. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Format code with gofmt to pass CI checks - Update createAccountFromExternalIdentity call signature in scim_test.go to match new 5-parameter signature (added emailOptional boolean) - Update vendor directory with missing dependencies - Resolve merge conflict in configuration.go preserving both SCIM and new Experimental/Reloading configurations All linting and security checks pass (gofmt, go vet, staticcheck, gosec). Tests run successfully except for pre-existing SAML test issue unrelated to SCIM changes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

…solation Priority 1 implementation for production-ready SCIM with multiple enterprise customers: **Provider Management:** - Add `scim_providers` table with UUID-based stable provider IDs - Implement CRUD operations for provider lifecycle management - Store bcrypt-hashed tokens for security - Support per-provider audience scoping and soft deletes **Admin API Endpoints:** - POST /admin/scim-providers - Create provider (returns token once) - GET /admin/scim-providers - List all providers - GET /admin/scim-providers/:id - Get specific provider - POST /admin/scim-providers/:id/rotate-token - Rotate token securely - DELETE /admin/scim-providers/:id - Soft delete provider **Authentication Refactor:** - Replace config-based token arrays with database lookups - Use stable UUID provider IDs instead of array indexes - Remove backward compatibility (BasicAuth and config tokens) - Authenticate via scim_providers table with bcrypt verification **SCIM Error Handling:** - Implement RFC 7644 Section 3.12 compliant error responses - Add structured SCIM error types (SCIMError) - Integrate with existing error handling pipeline - Return proper schemas, status, and detail fields **Configuration Cleanup:** - Remove GOTRUE_SCIM_TOKENS (deprecated) - Remove GOTRUE_SCIM_BASIC_USER/PASSWORD (deprecated) - Keep GOTRUE_SCIM_ENABLED, BASE_URL, DEFAULT_AUDIENCE, BAN_ON_DEACTIVATE - Update tests to use database providers **Benefits:** - ✅ Stable provider IDs that never change - ✅ Proper multi-tenant isolation per enterprise customer - ✅ API-based provider management (no config file changes) - ✅ Audit trails with created_at/updated_at/deleted_at - ✅ Secure token storage with bcrypt - ✅ RFC-compliant SCIM error responses 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Fix assignment mismatch in TestSCIM_AuthRequired - Update middleware_test to use database-backed SCIM providers - Add SCIMProvider table to TruncateAll for proper test cleanup - Use unique provider names per test to prevent duplicate key errors - Restore and fix TestSCIMSAML_UserSeparationAndDeprovision test All tests now pass with proper database-backed authentication. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Add bounds checking for uint64 to int conversion in pagination to prevent integer overflow (G115) - Add explicit error handling for JSON encoding in SCIM error responses (G104) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

coveralls · 2025-10-06T10:24:18Z

Pull Request Test Coverage Report for Build 18277261236

Details

381 of 791 (48.17%) changed or added relevant lines in 10 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage decreased (-0.7%) to 66.866%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
internal/api/middleware.go	30	31	96.77%
internal/api/errors.go	2	5	40.0%
internal/api/scim_errors.go	4	67	5.97%
internal/models/scim_provider.go	35	99	35.35%
internal/api/scim.go	280	406	68.97%
internal/api/scim_admin.go	0	153	0.0%

Totals
Change from base Build 18170389302:	-0.7%
Covered Lines:	13765
Relevant Lines:	20586

💛 - Coveralls

SCIM v2 (Users) minimal implementation: endpoints, auth, content-type…

e188f87

…, filters, soft deprovision; config + routing; tests for endpoints and middleware

felixmccuaig requested a review from a team as a code owner August 16, 2025 06:22

felixmccuaig changed the title ~~SCIM v2 (Users) minimal implementation: endpoints, auth, content-type, filters, soft deprovision; config + routing; tests for endpoints and middleware~~ feat: Add SCIM v2 support Aug 16, 2025

felixmccuaig added 4 commits August 16, 2025 16:39

tests(scim+saml): add integration test ensuring SCIM-provisioned user…

700e4da

… remains separate from SAML SSO user and SCIM deprovision only disables SCIM user

scim: scope to single audience via config; harden GET/PATCH/DELETE by…

defe72e

… aud check; merge security & SAML tests into scim_test.go

test(env): add SCIM config keys for test environment

6ef4140

docs(env): add SCIM configuration keys to example.env

c311d49

fix: remove unused writeSCIMError function to resolve staticcheck U10…

e6cc59f

…00 error

fix: add bounds checking for page/count before uint64 conversion in SCIM

8766c56

Addresses gosec G115 integer overflow vulnerability by ensuring page and count values are non-negative before converting to uint64 in pagination parameters.

hf reviewed Aug 18, 2025

View reviewed changes

felixmccuaig requested a review from hf September 2, 2025 11:38

felixmccuaig and others added 2 commits October 4, 2025 14:52

felixmccuaig force-pushed the scim branch from 5a977fd to 1880a4f Compare October 4, 2025 05:06

felixmccuaig and others added 3 commits October 4, 2025 15:27

feat: Add SCIM v2 support #2115

Are you sure you want to change the base?

feat: Add SCIM v2 support #2115

Conversation

felixmccuaig commented Aug 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What kind of change does this PR introduce?

What is the current behavior?

What is the new behavior?

Database-backed SCIM Provider Management

SCIM v2.0 Endpoints

Authentication

User Mapping

Filtering

Deprovisioning

Configuration

Database Changes

Tests

How to Test Locally

Additional Context

Uh oh!

felixmccuaig commented Aug 16, 2025

Uh oh!

cstockton commented Aug 17, 2025

Uh oh!

hf commented Aug 18, 2025

Uh oh!

felixmccuaig commented Aug 18, 2025

Uh oh!

hf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hf Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

hf Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

hf Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hf commented Aug 18, 2025

Uh oh!

felixmccuaig commented Sep 3, 2025

Uh oh!

hf commented Sep 3, 2025

Uh oh!

felixmccuaig commented Sep 3, 2025

Uh oh!

hf commented Sep 3, 2025

Uh oh!

felixmccuaig commented Sep 3, 2025

Uh oh!

coveralls commented Oct 6, 2025

Pull Request Test Coverage Report for Build 18277261236

Details

💛 - Coveralls

Uh oh!

Uh oh!

felixmccuaig commented Aug 16, 2025 •

edited

Loading