Merge branch 'feature/731-forwarded-user-email' into 'master'

feat(auth): bind console-created clones to users via forwarded email

Closes #731

See merge request postgres-ai/database-lab!1173

Author: Sarumyan

engine/cmd/cli/commands/teleport/SETUP.md

@@ -297,7 +297,7 @@ supplied by the operator to match an existing Teleport taxonomy.
 | `dblab` | `"true"` | Marks the resource as DBLab-managed; used by the agent matcher and user roles |
 | `dblab_instance` | `<environment-id>` | Owning DBLab instance; used internally to keep reconciliation isolated per instance |
 | `clone_id` | clone ID | DB resources only |
-| `dblab_user` | authenticated user (email local part) | DB resources only, set when clone binding is enabled and the creator used a personal token |
+| `dblab_user` | authenticated user (full email address) | DB resources only, set when clone binding is enabled and the creator used a personal token |
 | `environment` | `<environment-id>` | Set **only** when no custom `environment` label is provided (backwards compatibility) |
 
 > **Important:** Each DBLab instance must use a **unique** `--environment-id`.
@@ -366,17 +366,24 @@ platform:
 ```
 
 When `bindClonesToUser` is enabled, a clone created with a **personal per-user
-token** is labeled `dblab_user: <email local part>` — the part of the
-authenticated user's email before `@`, matching Teleport's
-`email.local(external.email)`. The clone's Postgres username (`db.username`) is
-**not** changed, so existing connection strings, Joe, and CI automation keep
-working.
+token** is labeled `dblab_user: <email>` — the authenticated user's full email
+address, matching Teleport's `external.email`. The clone's Postgres username
+(`db.username`) is **not** changed, so existing connection strings, Joe, and CI
+automation keep working.
 
 Clones created with the shared `verificationToken` (for example CI pipelines or
 Joe) carry **no** `dblab_user` label. They are created normally — not rejected —
 but are not reachable through a per-user role that matches on `dblab_user`; grant
 those callers access through a broader role instead.
 
+A trusted proxy that authenticates with the shared `verificationToken` on behalf
+of a known user (for example the PostgresAI Platform serving console requests)
+can assert the acting user by sending the `X-Forwarded-User-Email` header. The
+Engine then labels the clone exactly as if that user had used a personal token.
+The header is ignored on personal-token requests and when authorization is
+disabled; asserting an identity grants the caller nothing beyond what the shared
+token already allows.
+
 ### Restrict access with a per-user role
 
 ```yaml
@@ -388,32 +395,40 @@ spec:
   allow:
     db_labels:
       dblab: ['true']
-      dblab_user: ['{{email.local(external.email)}}']
+      dblab_user: ['{{external.email}}']
     db_names: ['*']
     db_users: ['*']
 ```
 
-With this role a user can reach only the clones labeled with their own email
-local part, e.g. `jsmith@acme.com` reaches resources labeled `dblab_user: jsmith`.
+With this role a user can reach only the clones labeled with their own email,
+e.g. `jsmith@acme.com` reaches resources labeled `dblab_user: jsmith@acme.com`.
 
 ### Limitations
 
-- **Two identity sources must agree.** The label is computed from the email the
+- **Two identity sources must agree.** The label is the full email the
   PostgresAI Platform returns at clone-create time, while Teleport matches
-  against `email.local(external.email)` from its own SSO/IdP at connect time.
-  Both sides preserve case, and the `dblab_user` label is
-  case-sensitive, so the two emails must match **exactly, including case**
-  (`JSmith@acme.com` and `jsmith@acme.com` are different). If they differ, the
-  user is denied access to their own clone (it fails closed). Make sure the
-  Platform and the Teleport IdP emit the same address for each user.
-- Users whose email local parts collide across domains
-  (`jsmith@acme.com` vs `jsmith@other.com`) map to the same `dblab_user` value.
-- Email local parts that cannot be represented as a Teleport label value
-  (those containing `+` or other characters outside `[a-zA-Z0-9._-]`) cause the
-  personal-token clone-create request to be rejected rather than silently
-  rewritten, so the Engine label always equals Teleport's computed value.
+  against `external.email` from its own SSO/IdP at connect time. Both sides
+  preserve case, and the `dblab_user` label is case-sensitive, so the two emails
+  must match **exactly, including case** (`JSmith@acme.com` and `jsmith@acme.com`
+  are different). If they differ, the user is denied access to their own clone
+  (it fails closed). Make sure the Platform and the Teleport IdP emit the same
+  address for each user. This includes the **domain**: because the full address
+  is compared, a source that normalizes the domain case on only one side
+  (`user@Acme.io` vs `user@acme.io`) also fails closed, even though DNS treats
+  the two as the same mailbox.
+- Email addresses that cannot be represented as a Teleport label value
+  (those containing `+` or other characters outside `[a-zA-Z0-9._@-]`) produce an
+  **unlabeled** clone with a warning in the Engine log — the label is never
+  silently rewritten, so when a label is present it always equals Teleport's
+  value. Such users need a broader role to reach their clones.
 - Clones created before binding was enabled, or with the shared token, have no
   `dblab_user` label; recreate them with a personal token to apply it.
+- Upgrading from a build that labeled clones with the email **local part**:
+  existing Teleport `db` resources keep their old `dblab_user: <local part>`
+  label — reconciliation matches resources by name and does not relabel them —
+  so once the role matches on `{{external.email}}` those users lose access.
+  Remove the affected `db` resources (or recreate the clones) so the sidecar
+  re-registers them with the full-email label.
 
 ## Connecting to a clone
 

engine/cmd/cli/commands/teleport/serve_test.go

@@ -379,7 +379,7 @@ func TestParseListDBsOutput(t *testing.T) {
 
 func TestBuildDBYAML(t *testing.T) {
 	t.Run("with owner user", func(t *testing.T) {
-		res := dbResource{Name: "dblab-clone-prod-abc-5432", Port: 5432, EnvID: "prod", CloneID: "abc", OwnerUser: "testuser"}
+		res := dbResource{Name: "dblab-clone-prod-abc-5432", Port: 5432, EnvID: "prod", CloneID: "abc", OwnerUser: "jsmith@acme.io"}
 		yaml, err := buildDBYAML(res, nil)
 		require.NoError(t, err)
 		s := string(yaml)
@@ -388,7 +388,7 @@ func TestBuildDBYAML(t *testing.T) {
 		assert.Contains(t, s, `dblab_instance: "prod"`)
 		assert.Contains(t, s, `environment: "prod"`)
 		assert.Contains(t, s, `clone_id: "abc"`)
-		assert.Contains(t, s, `dblab_user: "testuser"`)
+		assert.Contains(t, s, `dblab_user: "jsmith@acme.io"`)
 		assert.Contains(t, s, `uri: "127.0.0.1:5432"`)
 	})
 

engine/internal/srv/mw/auth.go

@@ -18,6 +18,11 @@ import (
 // VerificationTokenHeader defines the verification token name that should be passed in request headers.
 const VerificationTokenHeader = "Verification-Token"
 
+// ForwardedUserEmailHeader carries the acting user's email asserted by a trusted caller
+// authenticated with the shared verification token (e.g. the Platform proxying console
+// requests). It is ignored on personal-token requests and when authorization is disabled.
+const ForwardedUserEmailHeader = "X-Forwarded-User-Email"
+
 // wsTokenKey defines the name of web-sockets token parameter that should be passed in query string.
 const wsTokenKey = "token"
 
@@ -42,7 +47,7 @@ func NewAuth(verificationToken string, personalTokenVerifier platform.PersonalTo
 // resolved user identity (for personal tokens) to the request context.
 func (a *Auth) Authorized(h http.HandlerFunc) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		ctx, ok := a.authenticate(r.Context(), r.Header.Get(VerificationTokenHeader))
+		ctx, ok := a.authenticate(r.Context(), r.Header.Get(VerificationTokenHeader), r.Header.Get(ForwardedUserEmailHeader))
 		if !ok {
 			api.SendUnauthorizedError(w, r)
 			return
@@ -67,32 +72,49 @@ func (a *Auth) AdminMW(h http.Handler) http.Handler {
 }
 
 func (a *Auth) isAccessAllowed(ctx context.Context, token string) bool {
-	_, ok := a.authenticate(ctx, token)
+	_, ok := a.authenticate(ctx, token, "")
 
 	return ok
 }
 
 // authenticate validates the token and, for a valid personal token, returns a
-// context carrying the resolved user identity. The shared verification token is
-// authorized but carries no identity.
-func (a *Auth) authenticate(ctx context.Context, token string) (context.Context, bool) {
+// context carrying the resolved user identity. The shared verification token
+// carries no identity of its own, but a shared-token caller may assert the
+// acting user via forwardedEmail; the assertion is trusted because the shared
+// token already grants full instance access.
+func (a *Auth) authenticate(ctx context.Context, token, forwardedEmail string) (context.Context, bool) {
 	if a.verificationToken == "" {
 		return ctx, true
 	}
 
 	if subtle.ConstantTimeCompare([]byte(a.verificationToken), []byte(token)) == 1 {
-		return ctx, true
+		return withForwardedIdentity(ctx, forwardedEmail), true
 	}
 
 	if a.personalTokenVerifier != nil && a.personalTokenVerifier.IsPersonalTokenEnabled() {
 		if identity, ok := a.personalTokenVerifier.AuthenticatePersonalToken(ctx, token); ok {
-			return context.WithValue(ctx, userIdentityKey, identity), true
+			return WithUserIdentity(ctx, identity), true
 		}
 	}
 
 	return ctx, false
 }
 
+// withForwardedIdentity attaches the identity asserted by a shared-token caller.
+func withForwardedIdentity(ctx context.Context, email string) context.Context {
+	if email == "" {
+		return ctx
+	}
+
+	return WithUserIdentity(ctx, platform.UserIdentity{Email: email})
+}
+
+// WithUserIdentity returns a context carrying the given user identity, as
+// attached by the middleware for personal-token and forwarded identities.
+func WithUserIdentity(ctx context.Context, identity platform.UserIdentity) context.Context {
+	return context.WithValue(ctx, userIdentityKey, identity)
+}
+
 // UserIdentityFromContext returns the authenticated user identity attached to
 // the context by Authorized, if present.
 func UserIdentityFromContext(ctx context.Context) (platform.UserIdentity, bool) {

engine/internal/srv/mw/auth_test.go

@@ -170,6 +170,57 @@ func TestAuthorized_UserIdentity(t *testing.T) {
 	}
 }
 
+func TestAuthorized_ForwardedIdentity(t *testing.T) {
+	testCases := []struct {
+		name              string
+		verificationToken string
+		token             string
+		forwardedEmail    string
+		wantStatus        int
+		wantOK            bool
+		wantEmail         string
+	}{
+		{name: "shared token with forwarded email attaches identity", verificationToken: testVerificationToken,
+			token: testVerificationToken, forwardedEmail: "console@acme.io", wantStatus: http.StatusOK, wantOK: true, wantEmail: "console@acme.io"},
+		{name: "shared token without forwarded email has no identity", verificationToken: testVerificationToken,
+			token: testVerificationToken, wantStatus: http.StatusOK},
+		{name: "personal token ignores forwarded email", verificationToken: testVerificationToken,
+			token: testPlatformAccessToken, forwardedEmail: "spoofed@acme.io", wantStatus: http.StatusOK, wantOK: true, wantEmail: "u@acme.io"},
+		{name: "wrong token with forwarded email is unauthorized", verificationToken: testVerificationToken,
+			token: "wrong", forwardedEmail: "console@acme.io", wantStatus: http.StatusUnauthorized},
+		{name: "disabled authorization ignores forwarded email", verificationToken: "",
+			token: "", forwardedEmail: "console@acme.io", wantStatus: http.StatusOK},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			var gotIdentity platform.UserIdentity
+
+			var gotOK bool
+
+			auth := NewAuth(tc.verificationToken, MockPersonalTokenVerifier{isPersonalTokenEnabled: true, email: "u@acme.io"})
+			handler := auth.Authorized(func(w http.ResponseWriter, r *http.Request) {
+				gotIdentity, gotOK = UserIdentityFromContext(r.Context())
+				w.WriteHeader(http.StatusOK)
+			})
+
+			req := httptest.NewRequest(http.MethodGet, "/clone", nil)
+			req.Header.Set(VerificationTokenHeader, tc.token)
+
+			if tc.forwardedEmail != "" {
+				req.Header.Set(ForwardedUserEmailHeader, tc.forwardedEmail)
+			}
+
+			rec := httptest.NewRecorder()
+			handler(rec, req)
+
+			require.Equal(t, tc.wantStatus, rec.Code)
+			assert.Equal(t, tc.wantOK, gotOK)
+			assert.Equal(t, tc.wantEmail, gotIdentity.Email)
+		})
+	}
+}
+
 func TestAdminMW(t *testing.T) {
 	okHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusOK)

engine/internal/srv/routes.go

@@ -631,13 +631,7 @@ func (s *Server) createClone(w http.ResponseWriter, r *http.Request) {
 	}
 
 	if s.Platform != nil && s.Platform.BindClonesToUser() {
-		owner, err := ownerFromContext(r.Context())
-		if err != nil {
-			api.SendBadRequestError(w, r, err.Error())
-			return
-		}
-
-		cloneRequest.DB.OwnerUser = owner
+		cloneRequest.DB.OwnerUser = ownerFromContext(r.Context())
 	}
 
 	if cloneRequest.Snapshot != nil && cloneRequest.Snapshot.ID != "" {
@@ -728,53 +722,63 @@ func (s *Server) createClone(w http.ResponseWriter, r *http.Request) {
 	log.Dbg(fmt.Sprintf("Clone ID=%s is being created", newClone.ID))
 }
 
-// maxOwnerLabelLength caps the derived owner label length.
-const maxOwnerLabelLength = 63
+// maxOwnerLabelLength caps the derived owner label length; RFC 5321 limits an
+// email address to 254 characters.
+const maxOwnerLabelLength = 254
 
 // safeOwnerLabel restricts the derived owner label to characters valid as a
 // Teleport label value (a subset of the sidecar's safeYAMLValue), so the engine
-// label always matches Teleport's computed email.local value.
-var safeOwnerLabel = regexp.MustCompile(`^[a-zA-Z0-9._-]+$`)
+// label always matches Teleport's external.email value.
+var safeOwnerLabel = regexp.MustCompile(`^[a-zA-Z0-9._@-]+$`)
 
 // ownerFromContext resolves the clone owner label from the authenticated user
-// identity on the context. It returns an empty string and no error when no
-// identity is present, so shared-token callers create unlabeled clones. A
-// resolved personal-token identity with an empty email is logged as a likely
-// misconfiguration (the Platform is not returning the user email) and also
-// yields an unlabeled clone. It errors only when an identity is present with an
-// email that cannot be represented as a valid owner label.
-func ownerFromContext(ctx context.Context) (string, error) {
+// identity on the context. It returns an empty string when no identity is
+// present, when the identity has no email, or when the email cannot be
+// represented as a valid owner label — such requests create unlabeled clones
+// instead of failing; the fallback is logged as a warning so a misconfiguration
+// (the Platform not returning the email) or an unlabelable address (e.g. a
+// plus-tagged local part) stays visible without blocking clone creation.
+func ownerFromContext(ctx context.Context) string {
 	identity, ok := mw.UserIdentityFromContext(ctx)
 	if !ok {
-		return "", nil
+		return ""
 	}
 
 	if identity.Email == "" {
 		log.Warn("clone-to-user binding is enabled but the authenticated identity has no email; " +
 			"creating an unlabeled clone (check that the Platform returns the user email)")
 
-		return "", nil
+		return ""
+	}
+
+	owner, err := ownerFromEmail(identity.Email)
+	if err != nil {
+		log.Warn(fmt.Sprintf("clone-to-user binding is enabled but no owner label can be derived: %v; "+
+			"creating an unlabeled clone", err))
+
+		return ""
 	}
 
-	return ownerFromEmail(identity.Email)
+	return owner
 }
 
-// ownerFromEmail extracts the email local part exactly as Teleport's
-// email.local(external.email) does — mail.ParseAddress, then the part before the
-// first "@" — and validates that it is usable as a Teleport label value, so the
-// engine label always matches Teleport's value.
+// ownerFromEmail normalizes the email exactly as Teleport's external.email trait
+// carries it — mail.ParseAddress strips any display name and surrounding
+// whitespace — and validates that the full address is usable as a Teleport label
+// value, so the engine label always matches Teleport's external.email value. The
+// full address is used (not just the local part) so users whose local parts
+// collide across domains still map to distinct labels.
 func ownerFromEmail(email string) (string, error) {
 	addr, err := mail.ParseAddress(email)
 	if err != nil {
 		return "", fmt.Errorf("cannot parse email %q: %w", email, err)
 	}
 
-	local, _, _ := strings.Cut(addr.Address, "@")
-	if !isValidOwnerLabel(local) {
+	if !isValidOwnerLabel(addr.Address) {
 		return "", fmt.Errorf("cannot derive a valid owner label from email %q", email)
 	}
 
-	return local, nil
+	return addr.Address, nil
 }
 
 // isValidOwnerLabel reports whether name is usable as a Teleport dblab_user