Microsoft Entra authentication for Azure PostgreSQL

Every option needs the same two settings - irt.db.auth-mode=azure-entra and irt.db.username set to the PostgreSQL role name. What differs is only where the token comes from:

Both managed identity types work equally well. Keep in mind that the database role is bound to the identity’s object id, not to its name, and a system-assigned identity lives and dies with the resource it belongs to: rebuilding the VM produces a new object id and silently breaks the database role even though every name stays the same, so the role has to be linked again (step 4). A user-assigned identity survives host replacement.

A service principal is a fallback rather than an equal option - it reintroduces a stored secret with an expiry date. Use it only where no managed identity is available.

Keep both methods enabled for the whole migration. That’s a fully supported state and it’s what makes rollback possible. The flag is --microsoft-entra-auth on the current Azure CLI and --active-directory-auth on the LTS channel.

From the portal: open the server → Settings → Security → under Authentication method choose PostgreSQL and Microsoft Entra authentication → Save.

Only an Entra administrator can create or link Entra database roles, so this must come before step 4. Add yourself here.

On the LTS CLI the command group is ad-admin. Use -t ServicePrincipal for an app registration or managed identity.

From the portal: the same Security page → Microsoft Entra authentication → Add Microsoft Entra Admins → pick the user or group → Save. The picker resolves the object id for you.

The last command returns the two values you need:

In the portal, both ids are shown on the Overview page of the identity, and the identity is attached to the host under its Security → Identity page.

Connect to the postgres database as the Entra administrator - the pgaadauth functions exist only there, and elsewhere they fail with a confusing No function matches the given name error:

The token goes through PGPASSWORD because it’s longer than psql’s interactive prompt accepts.

Existing password-based deployment (the common case). The database, the schema and the role Figaf Tool connects as already exist, and only the credential is changing. Attach the Entra identity to that existing role:

Ownership, grants, default privileges and search_path stay as they are, irt.db.username keeps its current value, and rollback is removing the label. Nothing else is needed on the database side.

New installation. Create the role, then the database, schema and privileges. Figaf Tool doesn’t create its database or schema, and an Entra role is an ordinary non-superuser, so both must exist beforehand:

figaf_app is a free choice of role name - it’s what goes into irt.db.username. The two false arguments are isAdmin and isMfa; isMfa must stay false for a machine identity, whose token carries no multifactor claim. The ALTER DEFAULT PRIVILEGES lines matter too: without them the next upgrade creates objects the application can’t read.

Either way, confirm the binding registered with SELECT * FROM pgaadauth_list_principals(false);.

Figaf Tool uses pg_trgm for text search indexes, and optionally vector for embedding features. Azure refuses to create any extension that isn’t listed in the azure.extensions server parameter. The parameter is a list and setting it replaces the whole value, so read it first:

Add VECTOR as well if the embedding features are wanted. The portal equivalent (server → Server parameters → azure.extensions) is safer, because it shows the current selection as checkboxes and submits the full set. No restart is needed.

pg_trgm also has to be resolvable from the application’s schema. Figaf Tool pins search_path to its own schema, so an extension created without a SCHEMA clause lands in public where the application can’t resolve its operators, and start-up fails with operator class "gin_trgm_ops" does not exist, reported as a misleading Unable to start web server. To see where it already lives, from the application database:

Set irt.db.append-pg-trgm-schema-to-search-path=true in step 7 for any Azure deployment: it’s mandatory if the extension sits in public, and otherwise costs one catalog query at start-up.

Figaf Tool doesn’t bundle the Azure libraries. They are supplied the same way the PostgreSQL driver already is: as jar files in the folder passed to the JVM with -Dloader.path. The files are only needed by a deployment that uses Entra authentication - with irt.db.auth-mode absent or set to password no Azure code is loaded, so upgrading a password-based deployment requires nothing and after a rollback the jars can stay in place.

On a standalone deployment, check the PostgreSQL driver first. The authenticationPluginClassName parameter was introduced in pgjdbc 42.6.0, and earlier drivers ignore unknown connection parameters silently:

The jar is often renamed to a bare postgresql.jar, so the file name proves nothing - read the manifest. When replacing it, move the old jar out of the folder rather than leaving both, because every jar in a loader.path directory joins the classpath.

Then place these eight jars in the same folder. All are published by Microsoft on Maven Central and MIT licensed:

Don’t substitute other versions - this set is what the shipped application was verified against. If Maven Central isn’t reachable from the host, pull the same coordinates through your own artifact proxy or ask Figaf support for the eight files as a bundle.

In the Docker distribution the entrypoint already passes -Dloader.path=/libs, so the jars are added by mapping a volume with them to /libs, for example -v /opt/figaf/libs:/libs. Mounting a volume there hides the driver baked into the image, so the mapped folder also needs its own postgresql.jar of 42.6.0 or later next to the eight Azure jars.

A managed identity (and AKS workload identity) takes its token from the local instance metadata endpoint 169.254.169.254, which Azure doesn’t support reaching through an HTTP proxy. If the host has one configured, exclude that address for the Figaf Tool process.

These are ordinary application properties - pass them on the java command line or put them into config/application.yml beside the jar:

A minimal config/application.yml for a user-assigned managed identity:

For a system-assigned identity, AKS Workload ID or a service principal, remove the whole azure: block - everything else stays identical. For a service principal, additionally set AZURE_CLIENT_ID, AZURE_TENANT_ID and AZURE_CLIENT_SECRET as environment variables of the application process. Don’t leave those three set in an environment that should use a managed identity: they take precedence over it, and the deployment then works only until the secret expires.

In the Docker distribution the same configuration is passed as environment variables, with IRT_DB_PASSWORD left unset:

In Entra mode the container skips the two psql statements it normally runs to create the database and schema, because those need a static password. It logs Skipping database and schema creation because IRT_DB_AUTH_MODE is azure-entra, both must already exist - create them as described in step 4. The BTP image isn’t covered: it takes its credentials from the Cloud Foundry service binding and there is no managed identity on that platform.

A healthy start-up logs, in order:

The first line ends with managed identity client id: <client-id> when the property is set, and with the default Azure credential chain will be used when it isn’t. Seeing the client-id form where you intended a system-assigned identity means the property is still set somewhere.

Then confirm from a SQL client that the role is bound to the intended object id (SELECT * FROM pgaadauth_list_principals(false);) and that the application connects as the expected role (SELECT current_user;).

Up to this point rollback is reverting one property and restarting, and leaving both authentication methods enabled is fully supported. The only thing Entra-only buys is that a leaked or stale password becomes useless:

Then delete the old password from wherever the deployment stored it.

Enable Azure SDK logging first. Without it the Azure library is silent, and the PostgreSQL driver only ever reports a missing or malformed password without being able to say why. Three independent settings are needed, and any one of them left out produces complete silence:

The Azure Identity library then logs every credential it tries and stops at the first success (Azure Identity ⇒ Attempted credential ManagedIdentityCredential returns a token). A complete absence of Azure Identity ⇒ lines means the library was never invoked at all, so suspect the driver version first and then a missing jar. Turn the three settings off once the deployment is healthy.