Microsoft Azure PostgreSQL Auth client library for .NET

The Microsoft.Azure.PostgreSQL.Auth library provides Entra ID (formerly Azure Active Directory) authentication support for the Npgsql PostgreSQL driver. It enables passwordless authentication to Azure Database for PostgreSQL using Azure Identity credentials.

Source code | Package (NuGet) | Product documentation

Getting started

Install the package

Install the client library for .NET with NuGet:

dotnet add package Microsoft.Azure.PostgreSQL.Auth --prerelease

Prerequisites

  • An Azure subscription
  • An Azure Database for PostgreSQL server with Entra ID authentication enabled
  • An Entra ID administrator configured on the PostgreSQL server
  • The application's Entra ID identity created as a database user with appropriate permissions

Authenticate the client

This library extends the Npgsql NpgsqlDataSourceBuilder with Entra ID authentication. Use any TokenCredential from Azure.Identity:

var credential = new DefaultAzureCredential();
var builder = new NpgsqlDataSourceBuilder("Host=<< YOUR SERVER >>.postgres.database.azure.com;Database=<< YOUR DATABASE >>;SSL Mode=Require");
builder.UseEntraAuthentication(credential);

Key concepts

Entra ID authentication

The library configures token-based authentication by:

  1. Extracting the username from the Entra ID token claims
  2. Setting up a password provider that supplies fresh tokens for each connection

Supported identity types

  • User identities — extracted from upn, preferred_username, or unique_name claims
  • Managed identities — extracted from the xms_mirid claim
  • Service principals — extracted from available token claims

Thread safety

The UseEntraAuthentication and UseEntraAuthenticationAsync extension methods configure the NpgsqlDataSourceBuilder and are intended to be called once during setup. The resulting NpgsqlDataSource is thread-safe per Npgsql documentation.

Additional concepts

Client options | Handling failures | Diagnostics | Mocking | Client lifetime

Examples

Synchronous authentication

var credential = new DefaultAzureCredential();
var builder = new NpgsqlDataSourceBuilder("Host=<< YOUR SERVER >>.postgres.database.azure.com;Database=<< YOUR DATABASE >>;SSL Mode=Require");
builder.UseEntraAuthentication(credential);

Asynchronous authentication

var credential = new DefaultAzureCredential();
var builder = new NpgsqlDataSourceBuilder("Host=<< YOUR SERVER >>.postgres.database.azure.com;Database=<< YOUR DATABASE >>;SSL Mode=Require");
await builder.UseEntraAuthenticationAsync(credential);

Troubleshooting

Common errors

  • "Could not determine username from token claims" — The token does not contain a recognized username claim. Ensure the identity has the correct permissions and the token contains one of: upn, xms_mirid, preferred_username, or unique_name.
  • NotSupportedException when calling Build() — A password is already set in the connection string. Remove the Password parameter when using Entra ID authentication.

Logging

This library uses the standard Azure SDK logging mechanisms. For details on configuring logging, see Logging with the Azure SDK for .NET.

Next steps

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (for example, label, comment). Follow the instructions provided by the bot. You'll only need to do this action once across all repositories using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

  • Last updated on