Merge pull request #11 from mauriciozanettisalomao/feat/lfxv2-493-user-email-to-sub-lookup-authelia

[LFXV2-493] User email to sub lookup - Authelia

Author: mauriciozanettisalomao

README.md

@@ -149,8 +149,9 @@ nats request lfx.auth-service.email_to_sub zephyr.stormwind@mythicaltech.io
 **Important Notes:**
 - This service searches for users by their **primary email** only
 - Linked/alternate email addresses are **not** supported for lookup
-- The service works with both Auth0 and mock repositories based on configuration
+- The service works with Auth0, Authelia, and mock repositories based on configuration
 - The returned subject identifier is the canonical user identifier used throughout the system
+- For Authelia-specific SUB identifier details and how they are populated, see: [`internal/infrastructure/authelia/README.md`](internal/infrastructure/authelia/README.md)
 
 ---
 

charts/lfx-v2-auth-service/Chart.yaml

@@ -5,5 +5,5 @@ apiVersion: v2
 name: lfx-v2-auth-service
 description: LFX Platform V2 Auth Service chart
 type: application
-version: 0.2.3
+version: 0.2.4
 appVersion: "latest"

charts/lfx-v2-auth-service/values.yaml

@@ -96,3 +96,5 @@ app:
       value: lfx-platform-authelia
     AUTHELIA_SECRET_NAME:
       value: authelia-users
+    AUTHELIA_OIDC_USERINFO_URL:
+      value: https://auth.k8s.orb.local/api/oidc/userinfo

cmd/server/service/providers.go

@@ -149,11 +149,17 @@ func newUserReaderWriter(ctx context.Context) port.UserReaderWriter {
 			secretName = "authelia-users"
 		}
 
+		oidcUserInfoURL := os.Getenv(constants.AutheliaOIDCUserInfoURLEnvKey)
+		if oidcUserInfoURL == "" {
+			oidcUserInfoURL = "https://auth.k8s.orb.local/api/oidc/userinfo"
+		}
+
 		config := map[string]string{
-			"configmap-name":  configMapName,
-			"namespace":       configMapNamespace,
-			"daemon-set-name": daemonSetName,
-			"secret-name":     secretName,
+			"configmap-name":    configMapName,
+			"namespace":         configMapNamespace,
+			"daemon-set-name":   daemonSetName,
+			"secret-name":       secretName,
+			"oidc-userinfo-url": oidcUserInfoURL,
 		}
 
 		// Create Authelia user repository with NATS client for storage

go.mod

@@ -9,9 +9,13 @@ require (
 	github.com/auth0/go-auth0 v1.28.0
 	github.com/golang-jwt/jwt/v5 v5.3.0
 	github.com/nats-io/nats.go v1.45.0
+	github.com/stretchr/testify v1.11.1
+	go.yaml.in/yaml/v2 v2.4.2
 	goa.design/clue v1.2.3
 	goa.design/goa/v3 v3.22.2
+	golang.org/x/crypto v0.42.0
 	golang.org/x/oauth2 v0.31.0
+	golang.org/x/sync v0.17.0
 	gopkg.in/yaml.v3 v3.0.1
 	k8s.io/apimachinery v0.34.1
 	k8s.io/client-go v0.34.1
@@ -56,17 +60,13 @@ require (
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/segmentio/asm v1.2.0 // indirect
 	github.com/spf13/pflag v1.0.6 // indirect
-	github.com/stretchr/testify v1.11.1 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
 	go.devnw.com/structs v1.0.0 // indirect
 	go.opentelemetry.io/otel v1.38.0 // indirect
 	go.opentelemetry.io/otel/trace v1.38.0 // indirect
-	go.yaml.in/yaml/v2 v2.4.2 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/crypto v0.42.0 // indirect
 	golang.org/x/mod v0.28.0 // indirect
 	golang.org/x/net v0.44.0 // indirect
-	golang.org/x/sync v0.17.0 // indirect
 	golang.org/x/sys v0.36.0 // indirect
 	golang.org/x/term v0.35.0 // indirect
 	golang.org/x/text v0.29.0 // indirect

internal/domain/model/user.go

@@ -102,6 +102,15 @@ func (u User) BuildEmailIndexKey(ctx context.Context) string {
 	return u.buildIndexKey(ctx, "email", data)
 }
 
+// BuildSubIndexKey builds the index key for the sub
+func (u User) BuildSubIndexKey(ctx context.Context) string {
+	data := strings.TrimSpace(strings.ToLower(u.Sub))
+	if data == "" {
+		return ""
+	}
+	return u.buildIndexKey(ctx, "sub", data)
+}
+
 // sanitize sanitizes the user metadata by cleaning up string fields
 func (um *UserMetadata) userMetadataSanitize() {
 	if um.Name != nil {

internal/domain/model/user_test.go

@@ -802,6 +802,244 @@ func TestUser_BuildEmailIndexKey(t *testing.T) {
 	}
 }
 
+func TestUser_BuildSubIndexKey(t *testing.T) {
+	tests := []struct {
+		name     string
+		sub      string
+		expected string
+	}{
+		{
+			name:     "valid sub",
+			sub:      "auth0|123456789",
+			expected: "", // Will be calculated
+		},
+		{
+			name:     "empty sub",
+			sub:      "",
+			expected: "",
+		},
+		{
+			name:     "sub with whitespace",
+			sub:      "  auth0|123456789  ",
+			expected: "", // Will be calculated (should be trimmed)
+		},
+		{
+			name:     "sub with uppercase",
+			sub:      "AUTH0|123456789",
+			expected: "", // Will be calculated (should be lowercase)
+		},
+		{
+			name:     "sub with mixed case and whitespace",
+			sub:      "  Auth0|123456789  ",
+			expected: "", // Will be calculated (should be trimmed and lowercase)
+		},
+		{
+			name:     "only whitespace",
+			sub:      "   ",
+			expected: "",
+		},
+		{
+			name:     "google oauth sub",
+			sub:      "google-oauth2|123456789012345678901",
+			expected: "", // Will be calculated
+		},
+		{
+			name:     "github oauth sub",
+			sub:      "github|12345678",
+			expected: "", // Will be calculated
+		},
+		{
+			name:     "sub with special characters",
+			sub:      "provider|user@domain.com",
+			expected: "", // Will be calculated
+		},
+		{
+			name:     "long sub string",
+			sub:      "provider|" + strings.Repeat("a", 100),
+			expected: "", // Will be calculated
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			user := User{Sub: tt.sub}
+			ctx := context.Background()
+
+			result := user.BuildSubIndexKey(ctx)
+
+			// Calculate expected hash
+			var expectedHash string
+			if tt.expected != "" {
+				expectedHash = tt.expected
+			} else {
+				// Check if this is a case where we expect empty string explicitly
+				normalizedSub := strings.TrimSpace(strings.ToLower(tt.sub))
+				if normalizedSub == "" {
+					expectedHash = "" // Empty subs should return empty string
+				} else {
+					hash := sha256.Sum256([]byte(normalizedSub))
+					expectedHash = hex.EncodeToString(hash[:])
+				}
+			}
+
+			if result != expectedHash {
+				t.Errorf("BuildSubIndexKey() = %q, want %q", result, expectedHash)
+			}
+
+			// Verify it's valid hex if not empty
+			if result != "" {
+				if _, err := hex.DecodeString(result); err != nil {
+					t.Errorf("BuildSubIndexKey() result is not valid hex: %v", err)
+				}
+				// Verify the result is a valid hex string of correct length (64 chars for SHA256)
+				if len(result) != 64 {
+					t.Errorf("BuildSubIndexKey() result length = %d, want 64", len(result))
+				}
+			}
+		})
+	}
+}
+
+func TestUser_BuildSubIndexKey_Normalization(t *testing.T) {
+	// Test that normalization works correctly (trimming and lowercase)
+	testCases := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{
+			name:     "uppercase to lowercase",
+			input:    "AUTH0|123456789",
+			expected: "auth0|123456789",
+		},
+		{
+			name:     "leading and trailing whitespace",
+			input:    "  auth0|123456789  ",
+			expected: "auth0|123456789",
+		},
+		{
+			name:     "mixed case with whitespace",
+			input:    "  Auth0|User123  ",
+			expected: "auth0|user123",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			user1 := User{Sub: tc.input}
+			user2 := User{Sub: tc.expected}
+			ctx := context.Background()
+
+			result1 := user1.BuildSubIndexKey(ctx)
+			result2 := user2.BuildSubIndexKey(ctx)
+
+			if result1 != result2 {
+				t.Errorf("BuildSubIndexKey() normalization failed: input %q gave %q, expected %q gave %q",
+					tc.input, result1, tc.expected, result2)
+			}
+
+			// Verify the normalized result matches expected hash
+			hash := sha256.Sum256([]byte(tc.expected))
+			expectedHash := hex.EncodeToString(hash[:])
+
+			if result1 != expectedHash {
+				t.Errorf("BuildSubIndexKey() = %q, want %q for normalized input", result1, expectedHash)
+			}
+		})
+	}
+}
+
+func TestUser_BuildSubIndexKey_Consistency(t *testing.T) {
+	// Test that the same input always produces the same output
+	user := User{Sub: "auth0|123456789"}
+	ctx := context.Background()
+
+	result1 := user.BuildSubIndexKey(ctx)
+	result2 := user.BuildSubIndexKey(ctx)
+
+	if result1 != result2 {
+		t.Errorf("BuildSubIndexKey() not consistent: first=%q, second=%q", result1, result2)
+	}
+
+	// Verify it's not empty and is valid hex
+	if result1 == "" {
+		t.Error("BuildSubIndexKey() returned empty string for valid sub")
+	}
+
+	if _, err := hex.DecodeString(result1); err != nil {
+		t.Errorf("BuildSubIndexKey() result is not valid hex: %v", err)
+	}
+
+	if len(result1) != 64 {
+		t.Errorf("BuildSubIndexKey() result length = %d, want 64", len(result1))
+	}
+}
+
+func TestUser_BuildSubIndexKey_EdgeCases(t *testing.T) {
+	tests := []struct {
+		name        string
+		sub         string
+		expectEmpty bool
+	}{
+		{
+			name:        "nil-like empty string",
+			sub:         "",
+			expectEmpty: true,
+		},
+		{
+			name:        "only spaces",
+			sub:         "   ",
+			expectEmpty: true,
+		},
+		{
+			name:        "only tabs",
+			sub:         "\t\t\t",
+			expectEmpty: true,
+		},
+		{
+			name:        "mixed whitespace",
+			sub:         " \t \n ",
+			expectEmpty: true,
+		},
+		{
+			name:        "single character",
+			sub:         "a",
+			expectEmpty: false,
+		},
+		{
+			name:        "unicode characters",
+			sub:         "provider|用户123",
+			expectEmpty: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			user := User{Sub: tt.sub}
+			ctx := context.Background()
+
+			result := user.BuildSubIndexKey(ctx)
+
+			if tt.expectEmpty {
+				if result != "" {
+					t.Errorf("BuildSubIndexKey() = %q, expected empty string", result)
+				}
+			} else {
+				if result == "" {
+					t.Error("BuildSubIndexKey() returned empty string, expected non-empty")
+				}
+				// Verify it's valid hex
+				if _, err := hex.DecodeString(result); err != nil {
+					t.Errorf("BuildSubIndexKey() result is not valid hex: %v", err)
+				}
+				if len(result) != 64 {
+					t.Errorf("BuildSubIndexKey() result length = %d, want 64", len(result))
+				}
+			}
+		})
+	}
+}
+
 func TestUser_BuildEmailIndexKey_Normalization(t *testing.T) {
 	// Test that different representations of the same email produce the same hash
 	ctx := context.Background()

internal/infrastructure/authelia/README.md

@@ -102,6 +102,35 @@ The Authelia integration requires the following configuration parameters:
 - NATS server connection details (inherited from main service configuration)
 - Key-Value bucket configuration for user data storage
 
+## Subject Identifier (SUB) Management
+
+### SUB Generation and Persistence
+
+The Subject Identifier (SUB) in Authelia is a deterministic UUID that uniquely identifies each user within the system. Key characteristics:
+
+- **Deterministic Generation**: The SUB is a UUID that is consistently generated for each user by Authelia
+- **Token-Based Persistence**: To ensure consistent data retrieval from Authelia, the SUB is only persisted when a user is updated using a valid authentication token
+- **OIDC UserInfo Endpoint**: The SUB can be retrieved from Authelia's OIDC UserInfo endpoint at `/api/oidc/userinfo` using a valid token
+
+### Token-Based User Updates
+
+When updating user metadata through the auth service, the SUB is populated by accessing Authelia's UserInfo endpoint with the provided token:
+
+```bash
+# Example: Update user metadata with token (this populates the SUB)
+nats req --server nats://lfx-platform-nats.lfx.svc.cluster.local:4222 "lfx.auth-service.user_metadata.update" '{
+  "token": "authelia_at_Tx****",
+  "user_metadata": {
+    "city": "Metropolis"
+  }
+}'
+```
+
+This process ensures that:
+- The SUB is retrieved from Authelia's authoritative source
+- User data consistency is maintained across the system
+- The canonical user identifier is properly established for future lookups
+
 ## Security Considerations
 
 - User passwords are automatically generated and stored as bcrypt hashes in ConfigMaps