feat(scim): store a per-provider SCIM token

internal/models/sso.go

@@ -1,8 +1,10 @@
 package models
 
 import (
+	"crypto/sha256"
 	"database/sql"
 	"database/sql/driver"
+	"encoding/hex"
 	"encoding/json"
 	"net/url"
 	"reflect"
@@ -13,6 +15,7 @@ import (
 	"github.com/crewjam/saml/samlsp"
 	"github.com/gofrs/uuid"
 	"github.com/pkg/errors"
+	"github.com/supabase/auth/internal/crypto"
 	"github.com/supabase/auth/internal/storage"
 )
 
@@ -23,6 +26,8 @@ type SSOProvider struct {
 	SAMLProvider SAMLProvider `has_one:"saml_providers" fk_id:"sso_provider_id" json:"saml,omitempty"`
 	SSODomains   []SSODomain  `has_many:"sso_domains" fk_id:"sso_provider_id" json:"domains"`
 
+	SCIMTokenHash *string `db:"scim_token_hash" json:"-"`
+
 	CreatedAt time.Time `db:"created_at" json:"created_at"`
 	UpdatedAt time.Time `db:"updated_at" json:"updated_at"`
 }
@@ -39,6 +44,19 @@ func (p SSOProvider) Type() string {
 	return "saml"
 }
 
+func (p *SSOProvider) GenerateSCIMToken() string {
+	token := "scim_" + crypto.SecureAlphanumeric(32)
+	hash := toSHA256(token)
+	p.SCIMTokenHash = &hash
+
+	return token
+}
+
+func toSHA256(token string) string {
+	sum := sha256.Sum256([]byte(token))
+	return hex.EncodeToString(sum[:])
+}
+
 type SAMLAttribute struct {
 	Name    string      `json:"name,omitempty"`
 	Names   []string    `json:"names,omitempty"`
@@ -222,6 +240,20 @@ func FindSSOProviderByResourceID(tx *storage.Connection, id string) (*SSOProvide
 	return &ssoProvider, nil
 }
 
+func FindSSOProviderBySCIMToken(tx *storage.Connection, token string) (*SSOProvider, error) {
+	var ssoProvider SSOProvider
+
+	if err := tx.Q().Where("scim_token_hash = ?", toSHA256(token)).First(&ssoProvider); err != nil {
+		if errors.Cause(err) == sql.ErrNoRows {
+			return nil, SSOProviderNotFoundError{}
+		}
+
+		return nil, errors.Wrap(err, "error finding SSO provider by SCIM token")
+	}
+
+	return &ssoProvider, nil
+}
+
 func FindSSOProviderForEmailAddress(tx *storage.Connection, emailAddress string) (*SSOProvider, error) {
 	parts := strings.Split(emailAddress, "@")
 	emailDomain := strings.ToLower(parts[1])

internal/models/sso_test.go

@@ -1,6 +1,8 @@
 package models
 
 import (
+	"crypto/sha256"
+	"encoding/hex"
 	"net/url"
 	"slices"
 	"testing"
@@ -469,3 +471,88 @@ func (ts *SSOTestSuite) TestFindSSOProviderByResourceID() {
 		require.Nil(ts.T(), got)
 	}
 }
+
+func (ts *SSOTestSuite) TestGenerateSCIMToken() {
+	provider := &SSOProvider{
+		SAMLProvider: SAMLProvider{
+			EntityID:    "https://example.com/saml/metadata/",
+			MetadataXML: "<example />",
+		},
+	}
+	require.Nil(ts.T(), provider.SCIMTokenHash)
+
+	token := provider.GenerateSCIMToken()
+
+	ts.Run("returns a scim_ prefixed token with 160 bits of randomness", func() {
+		require.Regexp(ts.T(), `^scim_[a-z2-7]{32}$`, token)
+	})
+
+	ts.Run("stores the SHA-256 digest of the token", func() {
+		sum := sha256.Sum256([]byte(token))
+
+		require.NotNil(ts.T(), provider.SCIMTokenHash)
+		require.Equal(ts.T(), hex.EncodeToString(sum[:]), *provider.SCIMTokenHash)
+	})
+
+	ts.Run("never stores the token itself", func() {
+		require.NotContains(ts.T(), *provider.SCIMTokenHash, token)
+	})
+
+	ts.Run("generates a distinct token on every call", func() {
+		require.NotEqual(ts.T(), token, provider.GenerateSCIMToken())
+	})
+}
+
+func (ts *SSOTestSuite) TestFindSSOProviderBySCIMToken() {
+	provider := &SSOProvider{
+		SAMLProvider: SAMLProvider{
+			EntityID:    "https://example.com/saml/metadata/1",
+			MetadataXML: "<example />",
+		},
+	}
+
+	token := provider.GenerateSCIMToken()
+	require.NoError(ts.T(), ts.db.Eager().Create(provider))
+
+	withoutToken := &SSOProvider{
+		SAMLProvider: SAMLProvider{
+			EntityID:    "https://example.com/saml/metadata/2",
+			MetadataXML: "<example />",
+		},
+	}
+	require.NoError(ts.T(), ts.db.Eager().Create(withoutToken))
+
+	ts.Run("resolves the provider that owns the token", func() {
+		found, err := FindSSOProviderBySCIMToken(ts.db, token)
+
+		require.NoError(ts.T(), err)
+		require.Equal(ts.T(), provider.ID, found.ID)
+	})
+
+	ts.Run("an unknown token resolves nothing", func() {
+		found, err := FindSSOProviderBySCIMToken(ts.db, "scim_unknown_token")
+
+		require.Nil(ts.T(), found)
+		require.True(ts.T(), IsNotFoundError(err))
+	})
+
+	ts.Run("an empty token does not match a provider without one", func() {
+		found, err := FindSSOProviderBySCIMToken(ts.db, "")
+
+		require.Nil(ts.T(), found)
+		require.True(ts.T(), IsNotFoundError(err))
+	})
+
+	ts.Run("rotation stops the previous token from resolving", func() {
+		newToken := provider.GenerateSCIMToken()
+		require.NoError(ts.T(), ts.db.Update(provider))
+
+		found, err := FindSSOProviderBySCIMToken(ts.db, newToken)
+		require.NoError(ts.T(), err)
+		require.Equal(ts.T(), provider.ID, found.ID)
+
+		found, err = FindSSOProviderBySCIMToken(ts.db, token)
+		require.Nil(ts.T(), found)
+		require.True(ts.T(), IsNotFoundError(err))
+	})
+}

migrations/20260731000000_add_scim_token_hash_to_sso_providers.up.sql

@@ -0,0 +1,9 @@
+-- Holds the SHA-256 hex digest of the provider's SCIM token.
+/* auth_migration: 20260731000000 */
+alter table only {{ index .Options "Namespace" }}.sso_providers
+    add column if not exists scim_token_hash text null;
+
+/* auth_migration: 20260731000000 */
+create unique index if not exists sso_providers_scim_token_hash_idx
+    on {{ index .Options "Namespace" }}.sso_providers (scim_token_hash)
+        where scim_token_hash is not null;