[antoinetoussaint-byte]

A workload on managed Postgres should authenticate as itself — login is a cloud principal, password is a short-lived token, no password exists to seed, project or rotate. This makes that reachable from the library, for both the serving path and migrations, without any consuming service naming a cloud.

Classification

Fix, at the place that owns the behaviour. Every piece lands in the library that already owns "how a service reaches its database"; nothing is added above it, and no consumer learns a cloud's name. The one thing deliberately left undone is listed under Follow-ups rather than worked around.

What it adds

WithExternalIdentity(declaration) — the consumer forwards an opaque declaration from its configuration and does not interpret it. The library owns the vocabulary (azure-entra, gcp-cloud-sql), the resolution table and every cloud call. No default: an empty or unrecognized declaration is refused at startup naming the set it could have been, because the absence of a declaration and a declaration of absence are different states. Refused beside WithAccessTokenProvider, since both authenticate the same pools.

The Cloud SQL issuer, which solves the part that actually matters: several distinct logins from one pod. A pod holds one ServiceAccount and therefore one primary cloud identity, while this library keeps its capabilities on separate logins on purpose. The login each connection names picks the path — the pod's own service account uses its ambient credential, any other login is exchanged for that principal's token through the IAM Credentials API. The cloud principal is derived from the login rather than declared twice: a service-account login is the email with .gserviceaccount.com stripped, so appending it reverses that exactly and the two cannot drift. Two token sources, not one: the database credential is minted at sqlservice.login and only the exchange is authorized at cloud-platform, so a token reaching Postgres can do nothing but log in.

ConnectionProfile.ServerTrustAnchorPEM — the server's authority as a configured value, not a mounted file. sslrootcert is a file only because the DSN is a string; pgx takes a tls.Config programmatically and this library already builds and checks one. A configuration plane that delivers values but not files can therefore deliver a verifiable connection. A certificate authority is public information, so this is ordinary configuration rather than a secret.

PinnedAuthorityTLS — a transport that verifies the chain against a pinned authority and deliberately does not match the hostname. It exists because a managed instance can have no verifiable name: the instance publishes no DNS record and its certificate is issued to an instance connection name, so verify-full has nothing to match and refuses every connection. Pinning inverts the question — when the only trusted root is the instance's own per-instance authority, verifying the chain is establishing which instance answered, because no other server can present a certificate that authority signed. The name was never the identity. The anchor is therefore mandatory on this transport: without a pinned root the same shape accepts any public authority and is strictly weaker than the mode it replaces.

Migrations take the same path. bootstrap.Options grows the same two declarations under the same names, through the same resolution table and the same anchor parse. The in-process owner connection takes the credential per backend via stdlib.OptionBeforeConnect and the authority as a pool. The migrate subprocess can use neither — separate process, own driver — so it takes the authority as a file staged beside the migrations the run already removes, and the credential through its environment, never its arguments, which stay world-readable in /proc/<pid>/cmdline for the child's life. A fresh token per lineage, because a long run can outlive one.

Also closed on the way through: an explicit profile accepted a password and a credential provider. The token replaces the password on every backend, so the URL's never authenticated — it was dead config reading as the live credential, and it hid an external-identity URL still carrying the seeded password it was meant to stop carrying.

Reuse

Reused: AccessTokenProvider and installAccessTokenProvider, which already existed as the per-connection credential seam; ConnectionProfile/ParseConnection as the single judge of a connection; the Azure Entra issuer, moved behind the declaration rather than rewritten; stdlib.OptionBeforeConnect for the migration owner; x509.CertPool and pgx's own verify-ca verifier.

Deliberately not built: a Cloud SQL connector dialer. It would have handled TLS and IAM together, but it is GCP-specific at the transport layer — the shape this change exists to abstract away — and pulls a large dependency into a library every service links. Deliberately not used: google.golang.org/api/impersonate, whose module graph is far larger than the exchange it wraps; the IAM Credentials call is made directly, which kept the added dependency surface to golang.org/x/oauth2 and cloud.google.com/go/compute/metadata. Swapping it back is a contained change if the owner prefers the wrapper. Deliberately not replaced: WithAccessTokenProvider, which remains correct for a service that mints its own credential — a projected token file rewritten by a sidecar is the right answer for a one-shot Job, and carries no cloud knowledge into this library.

AzureEntraWorkloadIdentity becomes unexported. It had no consumers, and leaving it exported leaves a cloud reachable from above the library, which is what this change exists to prevent.

Verified live, in a cluster

A read-only probe Job ran on a GKE cluster against a private Cloud SQL instance, under a ServiceAccount federated to a database service account. Measured, in one run:

1. the metadata server mints a token for the pod's own service account;
2. that token is accepted as the Postgres password — TLS 1.3, and the connected login is the service-account email minus its suffix, so the derivation above is exact;
3. pinning a different instance's authority is refused, so the pin is a control rather than a comment;
4. the system CA bundle cannot verify the server at all — so a verify-ca against system trust, which is how such a connection is often spelled, fails here. The anchor is not optional for this engine.

The probe used no code from this PR, so a failure would have been environmental rather than mine. It wrote nothing: SELECT 1 and catalog reads. It has been deleted.

Not verified

• Impersonation across logins. The probe used the pod's own identity directly, because no roles/iam.serviceAccountTokenCreator binding existed to exchange with. The multi-login path is covered by unit tests against a stub IAM endpoint and by the fail-closed refusals, but it has not run against the real API. It fails closed rather than reusing one credential for two logins.
• No migration was run against a managed instance, and no pool from this library has opened a connection to one.
• The Azure issuer is unchanged in behaviour and was not re-verified.

Follow-ups, not worked around

cmd/managed-bootstrap is not wired to the new bootstrap.Options fields. The root module pins a published libs/go rather than replacing it with the tree, so the command cannot see them until the library is released and that pin moves. Adding a replace would make the root build against local sources while its release builds against the pin — two states nobody can reproduce — so the ordering stands: publish, bump, then wire two environment reads.

Size

~470 hand-written non-test lines, ~500 test lines, two files touched outside the new ones. All library packages pass go test -race ./...; go vet clean; the root module builds and its conformance suite passes.