Bind Teleport clone access to authenticated user

Author: agneum

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` | clone username | DB resources only, when known |
+| `dblab_user` | authenticated user (email local part) | 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`.
@@ -350,6 +350,71 @@ spec:
 > the sidecar does not set, add it with `--label writable=readwrite`, otherwise
 > access is denied.
 
+## Per-User Clone Access
+
+By default, every Teleport user who holds a role granting access to DBLab
+resources can connect to **any** clone. To make access per-user, the Engine can
+attach a trusted `dblab_user` label to each clone, derived from the
+**authenticated user's identity** rather than from any client-supplied value.
+
+### Enable binding in server.yml
+
+```yaml
+platform:
+  enablePersonalTokens: true   # required — identity comes from the personal token
+  bindClonesToUser: true
+```
+
+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.
+
+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.
+
+### Restrict access with a per-user role
+
+```yaml
+kind: role
+version: v7
+metadata:
+  name: dblab-self-access
+spec:
+  allow:
+    db_labels:
+      dblab: ['true']
+      dblab_user: ['{{email.local(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`.
+
+### Limitations
+
+- **Two identity sources must agree.** The label is computed from the 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.
+- 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.
+
 ## Connecting to a Clone
 
 Once everything is running, users connect through Teleport:

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

@@ -97,7 +97,7 @@ func (s *service) reconcile(ctx context.Context) {
 			continue
 		}
 
-		res := dbResource{Name: name, Port: port, EnvID: s.cfg.EnvironmentID, CloneID: clone.ID, Username: clone.DB.Username}
+		res := dbResource{Name: name, Port: port, EnvID: s.cfg.EnvironmentID, CloneID: clone.ID, OwnerUser: clone.DB.OwnerUser}
 
 		s.mu.Lock()
 		err = createDB(ctx, s.cfg, res)

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

@@ -66,6 +66,7 @@ type WebhookPayload struct {
 	Port          uint   `json:"port,omitempty"`
 	Username      string `json:"username,omitempty"`
 	DBName        string `json:"dbname,omitempty"`
+	OwnerUser     string `json:"owner_user,omitempty"`
 	ContainerName string `json:"container_name,omitempty"`
 }
 
@@ -304,7 +305,7 @@ func (s *service) handleCloneCreate(ctx context.Context, p *WebhookPayload) erro
 
 	name := CloneServiceName(s.cfg.EnvironmentID, p.EntityID, int(p.Port))
 
-	res := dbResource{Name: name, Port: int(p.Port), EnvID: s.cfg.EnvironmentID, CloneID: p.EntityID, Username: p.Username}
+	res := dbResource{Name: name, Port: int(p.Port), EnvID: s.cfg.EnvironmentID, CloneID: p.EntityID, OwnerUser: p.OwnerUser}
 
 	s.mu.Lock()
 	err := createDB(ctx, s.cfg, res)

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

@@ -378,8 +378,8 @@ func TestParseListDBsOutput(t *testing.T) {
 }
 
 func TestBuildDBYAML(t *testing.T) {
-	t.Run("with username", func(t *testing.T) {
-		res := dbResource{Name: "dblab-clone-prod-abc-5432", Port: 5432, EnvID: "prod", CloneID: "abc", Username: "testuser"}
+	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"}
 		yaml, err := buildDBYAML(res, nil)
 		require.NoError(t, err)
 		s := string(yaml)
@@ -392,8 +392,8 @@ func TestBuildDBYAML(t *testing.T) {
 		assert.Contains(t, s, `uri: "127.0.0.1:5432"`)
 	})
 
-	t.Run("without username", func(t *testing.T) {
-		res := dbResource{Name: "dblab-clone-prod-abc-5432", Port: 5432, EnvID: "prod", CloneID: "abc", Username: ""}
+	t.Run("without owner user", func(t *testing.T) {
+		res := dbResource{Name: "dblab-clone-prod-abc-5432", Port: 5432, EnvID: "prod", CloneID: "abc", OwnerUser: ""}
 		yaml, err := buildDBYAML(res, nil)
 		require.NoError(t, err)
 		s := string(yaml)
@@ -440,8 +440,8 @@ func TestBuildDBYAML(t *testing.T) {
 		require.Error(t, err)
 	})
 
-	t.Run("invalid username", func(t *testing.T) {
-		res := dbResource{Name: "valid-name", Port: 5432, EnvID: "prod", CloneID: "abc", Username: "user\ninjection"}
+	t.Run("invalid owner user", func(t *testing.T) {
+		res := dbResource{Name: "valid-name", Port: 5432, EnvID: "prod", CloneID: "abc", OwnerUser: "user\ninjection"}
 		_, err := buildDBYAML(res, nil)
 		require.Error(t, err)
 	})

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

@@ -103,8 +103,8 @@ func dbResourceLabels(res dbResource, custom map[string]string) map[string]strin
 	labels := baseLabels(res.EnvID, custom)
 	labels[labelCloneID] = res.CloneID
 
-	if res.Username != "" {
-		labels[labelUser] = res.Username
+	if res.OwnerUser != "" {
+		labels[labelUser] = res.OwnerUser
 	}
 
 	return labels
@@ -149,11 +149,11 @@ type tctlDB struct {
 
 // dbResource holds parameters for creating a Teleport DB resource.
 type dbResource struct {
-	Name     string
-	Port     int
-	EnvID    string
-	CloneID  string
-	Username string
+	Name      string
+	Port      int
+	EnvID     string
+	CloneID   string
+	OwnerUser string
 }
 
 func runTctl(ctx context.Context, tctlPath, identityFile, proxyAddr string, args ...string) ([]byte, error) {

engine/configs/config.example.ci_checker.yml

@@ -40,6 +40,10 @@ platform:
   # If true: "verificationToken" is known only to admin, users use their own tokens,
   #           and any token can be revoked not affecting others
   enablePersonalTokens: true
+  # Label each clone with a trusted Teleport dblab_user tag from the authenticated
+  # user's email local part; requires enablePersonalTokens. Shared-token clones
+  # (e.g. CI) are left untagged rather than rejected; the Postgres username is unchanged.
+  #  bindClonesToUser: false
 
 
 source:

engine/configs/config.example.logical_generic.yml

@@ -193,4 +193,5 @@ platform:
 #  orgKey: "org_key" # Organization key
 #  accessToken: "${PGAI_PLATFORM_ACCESS_TOKEN}" # Token for authorization in Platform API; get it at https://postgres.ai/console/YOUR_ORG_NAME/tokens
 #  enablePersonalTokens: true # Enable authorization with personal tokens of the organization's members.
+#  bindClonesToUser: false # Label each clone with a trusted Teleport dblab_user tag from the authenticated user's email local part (requires enablePersonalTokens); shared-token clones are left untagged and the clone's Postgres username is unchanged.
 #

engine/configs/config.example.logical_rds_iam.yml

@@ -193,4 +193,5 @@ platform:
 #  orgKey: "org_key" # Organization key
 #  accessToken: "${PGAI_PLATFORM_ACCESS_TOKEN}" # Token for authorization in Platform API; get it at https://postgres.ai/console/YOUR_ORG_NAME/tokens
 #  enablePersonalTokens: true # Enable authorization with personal tokens of the organization's members.
+#  bindClonesToUser: false # Label each clone with a trusted Teleport dblab_user tag from the authenticated user's email local part (requires enablePersonalTokens); shared-token clones are left untagged and the clone's Postgres username is unchanged.
 #

engine/configs/config.example.physical_generic.yml

@@ -174,4 +174,5 @@ platform:
 #  orgKey: "org_key" # Organization key
 #  accessToken: "${PGAI_PLATFORM_ACCESS_TOKEN}" # Token for authorization in Platform API; get it at https://postgres.ai/console/YOUR_ORG_NAME/tokens
 #  enablePersonalTokens: true # Enable authorization with personal tokens of the organization's members.
+#  bindClonesToUser: false # Label each clone with a trusted Teleport dblab_user tag from the authenticated user's email local part (requires enablePersonalTokens); shared-token clones are left untagged and the clone's Postgres username is unchanged.
 #

engine/configs/config.example.physical_pgbackrest.yml

@@ -204,4 +204,5 @@ platform:
 #  orgKey: "org_key" # Organization key
 #  accessToken: "${PGAI_PLATFORM_ACCESS_TOKEN}" # Token for authorization in Platform API; get it at https://postgres.ai/console/YOUR_ORG_NAME/tokens
 #  enablePersonalTokens: true # Enable authorization with personal tokens of the organization's members.
+#  bindClonesToUser: false # Label each clone with a trusted Teleport dblab_user tag from the authenticated user's email local part (requires enablePersonalTokens); shared-token clones are left untagged and the clone's Postgres username is unchanged.
 #