chore: support Entra authentication for Azure Database for PostgreSQL (#31855)

* chore: support Entra authentication for Azure Database for PostgreSQL Signed-off-by: Arjan Randhawa <arjan_randhawa@outlook.com> * chore: refactor methods (pr comments) Signed-off-by: Arjan Randhawa <arjan_randhawa@outlook.com> * chore: remove unsued helper function Signed-off-by: Arjan Randhawa <arjan_randhawa@outlook.com> * chore: Use Config over ConfigReader (PR Comments) Signed-off-by: Arjan <arjan_randhawa@outlook.com> * chore: Use consistent config name Signed-off-by: Arjan <arjan_randhawa@outlook.com> --------- Signed-off-by: Arjan Randhawa <arjan_randhawa@outlook.com> Signed-off-by: Arjan <arjan_randhawa@outlook.com>
2026-01-30 14:27:53 +00:00
parent 2141c20618
commit 8dd518a8ff
8 changed files with 592 additions and 17 deletions
@@ -106,6 +106,88 @@ When filling these out, you have 2 choices,

 If you opt for the second option of replacing the entire string, take care to not commit your `app-config.yaml` to source control. It may contain passwords that you don't want leaked.

+## Passwordless PostgreSQL in the Cloud
+
+If you want to host your PostgreSQL server in the cloud with passwordless authentication, you can use Azure Database for PostgreSQL with Microsoft Entra authentication or Google Cloud SQL for PostgreSQL with Cloud IAM.
+
+### Azure with Entra authentication
+
+Remove `password` from the connection configuration and set `type` to `azure`.
+
+Optionally set `tokenCredential` with the following properties. If no credential information is provided, it will default to using Default Azure Credential and a tokenRenewalOffsetTime of 5 minutes.
+
+#### Credential Selection
+
+The credential type is automatically inferred based on the fields you provide:
+
+- Client Secret Credential is used when all three are provided:
+  - `tenantId`
+  - `clientId`
+  - `clientSecret`
+- Managed Identity Credential is used when only `clientId` is provided. This enables user-assigned managed identity.
+- Default Azure Credential is used when no credential fields are provided. Default Azure Credential supports [many credential types](https://learn.microsoft.com/azure/developer/javascript/sdk/authentication/credential-chains#use-defaultazurecredential-for-flexibility), choosing one based on the runtime environment.
+
+#### Token Renewal
+
+Set `tokenRenewalOffsetTime` to control how early OAuth tokens should be refreshed.
+
+The value may be:
+
+- A human-readable string such as '1d', '2 hours', '30 seconds'
+- A duration object, e.g. { minutes: 3, seconds: 30 }
+
+Azure PostgreSQL uses short-lived Entra ID access tokens.
+By default, the database connector refreshes tokens 5 minutes before they expire.
+
+#### User Configuration
+
+Set `user` to the display name of your Entra ID group, service principal, or managed identity. Set it to the user principal name if you're authenticating with a user's credentials.
+
+#### Example
+
+```yaml title="app-config.yaml"
+backend:
+  database:
+    client: pg
+    connection:
+      # highlight-add-start
+      type: azure
+      tokenCredential:
+        tokenRenewalOffsetTime: 5 minutes
+      # highlight-add-end
+      host: ${POSTGRES_HOST}
+      port: ${POSTGRES_PORT}
+      user: ${POSTGRES_USER}
+      # highlight-remove-start
+      password: ${POSTGRES_PASSWORD}
+      # highlight-remove-end
+```
+
+### Google with Cloud IAM
+
+Remove `password` from the connection configuration and set `type` to `cloudsql`.
+
+Under the hood, this implements [Automatic IAM Database Authentication](https://github.com/GoogleCloudPlatform/cloud-sql-nodejs-connector?tab=readme-ov-file#automatic-iam-database-authentication).
+
+For an IAM user account, set `user` to the user's email address. For a service account, set `user` to the service account's email without the .gserviceaccount.com domain suffix.
+
+```yaml title="app-config.yaml"
+backend:
+  database:
+    client: pg
+    connection:
+      # highlight-add-start
+      type: cloudsql
+      instance: my-project:region:my-instance
+      # highlight-add-end
+      host: ${POSTGRES_HOST}
+      port: ${POSTGRES_PORT}
+      user: ${POSTGRES_USER}
+      # highlight-remove-start
+      password: ${POSTGRES_PASSWORD}
+      # highlight-remove-end
+```
+
 :::

 [Start the Backstage app](../index.md#2-run-the-backstage-app):