refactor: extract a provisioned user type

Author: xlgmokha

internal/api/scim/core/user.go

@@ -5,11 +5,24 @@ type Email struct {
 	Primary bool   `json:"primary"`
 }
 
+// Name holds the components of the user's name, per RFC 7643, Section 4.1.1.
+type Name struct {
+	Formatted  string `json:"formatted,omitempty"`
+	FamilyName string `json:"familyName,omitempty"`
+	GivenName  string `json:"givenName,omitempty"`
+	MiddleName string `json:"middleName,omitempty"`
+}
+
+func (n Name) IsZero() bool {
+	return n == Name{}
+}
+
 // User is the core User resource defined in RFC 7643, Section 4.1.
 type User struct {
 	Schemas  []SchemaURI `json:"schemas"`
 	ID       string      `json:"id"`
 	UserName string      `json:"userName"`
+	Name     *Name       `json:"name,omitempty"`
 	Emails   []Email     `json:"emails,omitempty"`
 	Meta     Meta        `json:"meta"`
 }

internal/api/scim/core/user_test.go

@@ -51,4 +51,22 @@ func TestUser(t *testing.T) {
 		require.NoError(t, err)
 		require.NotContains(t, string(body), "emails")
 	})
+
+	t.Run("omits the name when there is none", func(t *testing.T) {
+		user.Name = nil
+
+		body, err := json.Marshal(user)
+
+		require.NoError(t, err)
+		require.NotContains(t, string(body), `"name"`)
+	})
+
+	t.Run("serializes only the name components that are set", func(t *testing.T) {
+		user.Name = &Name{FamilyName: "Jensen", GivenName: "Barbara"}
+
+		body, err := json.Marshal(user)
+
+		require.NoError(t, err)
+		require.Contains(t, string(body), `"name":{"familyName":"Jensen","givenName":"Barbara"}`)
+	})
 }

internal/api/scim/mapper.go

@@ -17,22 +17,51 @@ func NewUserMapper(baseURL string) UserMapper {
 	return UserMapper{baseURL: baseURL}
 }
 
-func (m UserMapper) MapFrom(u *models.User) *core.User {
-	id, email := u.ID.String(), u.GetEmail()
+func (m UserMapper) MapFrom(in models.ProvisionedUser) *core.User {
+	id := in.ID.String()
 
 	meta := core.NewMeta(m.baseURL, core.ResourceTypeUser, core.EndpointUsers, id)
-	meta.Created, meta.LastModified = u.CreatedAt.UTC(), u.UpdatedAt.UTC()
+	meta.Created, meta.LastModified = in.CreatedAt.UTC(), in.UpdatedAt.UTC()
 
 	user := &core.User{
 		Schemas:  []core.SchemaURI{core.SchemaUser},
 		ID:       id,
-		UserName: email,
+		UserName: userName(in),
+		Name:     name(in),
 		Meta:     meta,
 	}
 
-	if email != "" {
-		user.Emails = []core.Email{{Value: email, Primary: true}}
+	if address := email(in); address != "" {
+		user.Emails = []core.Email{{Value: address, Primary: true}}
 	}
 
 	return user
 }
+
+func email(in models.ProvisionedUser) string {
+	if email := in.Claim("email"); email != "" {
+		return email
+	}
+	return in.GetEmail()
+}
+
+func userName(in models.ProvisionedUser) string {
+	if userName := in.Claim("preferred_username"); userName != "" {
+		return userName
+	}
+	return email(in)
+}
+
+func name(in models.ProvisionedUser) *core.Name {
+	name := core.Name{
+		Formatted:  in.Claim("name"),
+		FamilyName: in.Claim("family_name"),
+		GivenName:  in.Claim("given_name"),
+		MiddleName: in.Claim("middle_name"),
+	}
+
+	if name.IsZero() {
+		return nil
+	}
+	return &name
+}

internal/api/scim/mapper_test.go

@@ -16,19 +16,25 @@ func TestUserMapper(t *testing.T) {
 	createdAt := time.Date(2026, 7, 21, 19, 41, 41, 0, time.UTC)
 	updatedAt := time.Date(2026, 7, 22, 8, 12, 3, 0, time.UTC)
 
-	newModel := func(email string) *models.User {
-		return &models.User{
-			ID:        id,
-			Email:     storage.NullString(email),
-			CreatedAt: createdAt,
-			UpdatedAt: updatedAt,
+	newModel := func(email string, claims map[string]interface{}) models.ProvisionedUser {
+		in := models.ProvisionedUser{
+			User: &models.User{
+				ID:        id,
+				Email:     storage.NullString(email),
+				CreatedAt: createdAt,
+				UpdatedAt: updatedAt,
+			},
 		}
+		if claims != nil {
+			in.Identity = &models.Identity{IdentityData: claims}
+		}
+		return in
 	}
 
 	mapper := NewUserMapper("http://localhost:9999/scim/v2")
 
 	t.Run("maps a user onto the core User resource", func(t *testing.T) {
-		user := mapper.MapFrom(newModel("bjensen@example.com"))
+		user := mapper.MapFrom(newModel("bjensen@example.com", nil))
 
 		require.Equal(t, []core.SchemaURI{core.SchemaUser}, user.Schemas)
 		require.Equal(t, id.String(), user.ID)
@@ -38,20 +44,20 @@ func TestUserMapper(t *testing.T) {
 	})
 
 	t.Run("omits emails when the user has no email", func(t *testing.T) {
-		user := mapper.MapFrom(newModel(""))
+		user := mapper.MapFrom(newModel("", nil))
 
 		require.Empty(t, user.UserName)
 		require.Nil(t, user.Emails)
 	})
 
 	t.Run("builds the location from the base URL", func(t *testing.T) {
-		user := NewUserMapper("https://auth.example.com/scim/v2").MapFrom(newModel("bjensen@example.com"))
+		user := NewUserMapper("https://auth.example.com/scim/v2").MapFrom(newModel("bjensen@example.com", nil))
 
 		require.Equal(t, "https://auth.example.com/scim/v2/Users/"+id.String(), user.Meta.Location)
 	})
 
 	t.Run("normalizes the timestamps to UTC", func(t *testing.T) {
-		model := newModel("bjensen@example.com")
+		model := newModel("bjensen@example.com", nil)
 		model.CreatedAt = createdAt.In(time.FixedZone("MDT", -6*60*60))
 
 		user := mapper.MapFrom(model)
@@ -61,7 +67,69 @@ func TestUserMapper(t *testing.T) {
 		require.Equal(t, updatedAt, user.Meta.LastModified)
 	})
 
+	t.Run("prefers the email the provider supplied over the user record", func(t *testing.T) {
+		user := mapper.MapFrom(newModel("stale@example.com", map[string]interface{}{
+			"email": "bjensen@example.com",
+		}))
+
+		require.Equal(t, "bjensen@example.com", user.UserName)
+		require.Equal(t, []core.Email{{Value: "bjensen@example.com", Primary: true}}, user.Emails)
+	})
+
+	t.Run("falls back to the user record when the provider supplied no email", func(t *testing.T) {
+		user := mapper.MapFrom(newModel("bjensen@example.com", map[string]interface{}{
+			"sub": id.String(),
+		}))
+
+		require.Equal(t, "bjensen@example.com", user.UserName)
+		require.Equal(t, []core.Email{{Value: "bjensen@example.com", Primary: true}}, user.Emails)
+	})
+
+	t.Run("prefers preferred_username for the userName", func(t *testing.T) {
+		user := mapper.MapFrom(newModel("", map[string]interface{}{
+			"preferred_username": "bjensen",
+			"email":              "bjensen@example.com",
+		}))
+
+		require.Equal(t, "bjensen", user.UserName)
+		require.Equal(t, []core.Email{{Value: "bjensen@example.com", Primary: true}}, user.Emails)
+	})
+
+	t.Run("maps the name components the provider supplied", func(t *testing.T) {
+		user := mapper.MapFrom(newModel("", map[string]interface{}{
+			"name":        "Ms. Barbara Jane Jensen, III",
+			"family_name": "Jensen",
+			"given_name":  "Barbara",
+			"middle_name": "Jane",
+		}))
+
+		require.Equal(t, &core.Name{
+			Formatted:  "Ms. Barbara Jane Jensen, III",
+			FamilyName: "Jensen",
+			GivenName:  "Barbara",
+			MiddleName: "Jane",
+		}, user.Name)
+	})
+
+	t.Run("omits the name when the provider supplied no components", func(t *testing.T) {
+		require.Nil(t, mapper.MapFrom(newModel("bjensen@example.com", nil)).Name)
+		require.Nil(t, mapper.MapFrom(newModel("bjensen@example.com", map[string]interface{}{
+			"sub": id.String(),
+		})).Name)
+	})
+
+	t.Run("ignores claims that are not strings", func(t *testing.T) {
+		user := mapper.MapFrom(newModel("bjensen@example.com", map[string]interface{}{
+			"email":       12345,
+			"given_name":  []string{"Barbara"},
+			"family_name": "Jensen",
+		}))
+
+		require.Equal(t, "bjensen@example.com", user.UserName)
+		require.Equal(t, &core.Name{FamilyName: "Jensen"}, user.Name)
+	})
+
 	t.Run("satisfies the Mapper interface", func(t *testing.T) {
-		var _ Mapper[*models.User, *core.User] = NewUserMapper("")
+		var _ Mapper[models.ProvisionedUser, *core.User] = NewUserMapper("")
 	})
 }

internal/api/scim/server.go

@@ -19,7 +19,7 @@ type TokenExtractor func(r *http.Request) (string, error)
 type Server struct {
 	db                    *storage.Connection
 	extract               TokenExtractor
-	users                 Mapper[*models.User, *core.User]
+	users                 Mapper[models.ProvisionedUser, *core.User]
 	serviceProviderConfig *core.ServiceProviderConfig
 }
 

internal/api/scim/users.go

@@ -19,7 +19,7 @@ func (srv *Server) UserByID(w http.ResponseWriter, r *http.Request) error {
 	}
 
 	provider := shared.GetSSOProvider(ctx)
-	user, err := models.FindUserByIDAndSSOProviderID(srv.db.WithContext(ctx), id, provider.ID)
+	user, err := provider.FindProvisionedUserByID(srv.db.WithContext(ctx), id)
 	if err != nil {
 		if models.IsNotFoundError(err) {
 			return userNotFound(w)

internal/api/scim_test.go

@@ -139,7 +139,7 @@ type scimTenant struct {
 	token    string
 }
 
-func seedSCIMTenant(t *testing.T, conn *storage.Connection, token, email string) *scimTenant {
+func seedSCIMTenant(t *testing.T, conn *storage.Connection, token, email string, extraClaims ...map[string]interface{}) *scimTenant {
 	t.Helper()
 
 	id := uuid.Must(uuid.NewV4()).String()
@@ -160,10 +160,17 @@ func seedSCIMTenant(t *testing.T, conn *storage.Connection, token, email string)
 	user.IsSSOUser = true
 	require.NoError(t, conn.Create(user))
 
-	identity, err := models.NewIdentity(user, "sso:"+provider.ID.String(), map[string]interface{}{
+	claims := map[string]interface{}{
 		"sub":   user.ID.String(),
 		"email": email,
-	})
+	}
+	for _, extra := range extraClaims {
+		for key, value := range extra {
+			claims[key] = value
+		}
+	}
+
+	identity, err := models.NewIdentity(user, provider.ProviderType(), claims)
 	require.NoError(t, err)
 	require.NoError(t, conn.Create(identity))
 
@@ -225,6 +232,43 @@ func TestSCIMUsers(t *testing.T) {
 		require.Equal(t, http.StatusOK, get(b.user.ID.String(), b.token).Code)
 	})
 
+	t.Run("maps the attributes the provider supplied", func(t *testing.T) {
+		c := seedSCIMTenant(t, conn, "scim_token_c", "stale@example.com", map[string]interface{}{
+			"email":              "bjensen@example.com",
+			"preferred_username": "bjensen",
+			"name":               "Ms. Barbara Jane Jensen, III",
+			"family_name":        "Jensen",
+			"given_name":         "Barbara",
+		})
+
+		w := get(c.user.ID.String(), c.token)
+
+		require.Equal(t, http.StatusOK, w.Code)
+		require.JSONEq(t, fmt.Sprintf(`{
+			"schemas": [%q],
+			"id": %q,
+			"userName": "bjensen",
+			"name": {
+				"formatted": "Ms. Barbara Jane Jensen, III",
+				"familyName": "Jensen",
+				"givenName": "Barbara"
+			},
+			"emails": [{"value": "bjensen@example.com", "primary": true}],
+			"meta": {
+				"resourceType": "User",
+				"created": %q,
+				"lastModified": %q,
+				"location": "%s/scim/v2/Users/%s"
+			}
+		}`,
+			scimCore.SchemaUser,
+			c.user.ID,
+			c.user.CreatedAt.UTC().Format(time.RFC3339Nano),
+			c.user.UpdatedAt.UTC().Format(time.RFC3339Nano),
+			config.API.ExternalURL, c.user.ID,
+		), w.Body.String())
+	})
+
 	t.Run("hides a user belonging to another provider", func(t *testing.T) {
 		w := get(b.user.ID.String(), a.token)
 

internal/models/identity.go

@@ -93,6 +93,18 @@ func FindIdentityByIdAndProvider(tx *storage.Connection, providerId, provider st
 	return identity, nil
 }
 
+// FindIdentityByUserIDAndProvider searches for the identity linking a user to a provider.
+func FindIdentityByUserIDAndProvider(tx *storage.Connection, userID uuid.UUID, provider string) (*Identity, error) {
+	identity := &Identity{}
+	if err := tx.Q().Where("user_id = ? AND provider = ?", userID, provider).First(identity); err != nil {
+		if errors.Cause(err) == sql.ErrNoRows {
+			return nil, IdentityNotFoundError{}
+		}
+		return nil, errors.Wrap(err, "error finding identity")
+	}
+	return identity, nil
+}
+
 // FindIdentitiesByUserID returns all identities associated to a user ID.
 func FindIdentitiesByUserID(tx *storage.Connection, userID uuid.UUID) ([]*Identity, error) {
 	identities := []*Identity{}

internal/models/provisioned_user.go

@@ -0,0 +1,20 @@
+package models
+
+// ProvisionedUser is a user as seen through one SSO provider. The identity
+// carries the claims that provider supplied, so attributes read from it are
+// scoped to that provider rather than to the user record, which is shared
+// across every provider the user is linked to.
+type ProvisionedUser struct {
+	*User
+	Identity *Identity
+}
+
+// Claim returns the string claim the provider supplied under key, or an empty
+// string when it is absent or not a string.
+func (p ProvisionedUser) Claim(key string) string {
+	if p.Identity == nil {
+		return ""
+	}
+	value, _ := p.Identity.IdentityData[key].(string)
+	return value
+}