CData Python Connector for PostgreSQL

Build 25.0.9454

Establishing a Connection

The objects available within our connector are accessible from the "cdata.postgresql" module. To use the module's objects directly:

  1. Import the module as follows: 
    import cdata.postgresql as mod
  2. To establish a connection string, call the connect() method from the connector object using an appropriate connection string, such as: 
    mod.connect("User=postgres;Password=admin;Database=postgres;Server=127.0.0.1;Port=5432")

Connecting to PostgreSQL

The following connection properties are usually required to connect to PostgreSQL.

  • Server: The host name or IP of the server hosting the PostgreSQL database.
  • User: The user which will be used to authenticate with the PostgreSQL server.

You can also optionally set the following:

  • Database: The database to connect to when connecting to the PostgreSQL Server. If this is not set, the user's default database will be used.
  • Port: The port of the server hosting the PostgreSQL database. 5432 by default.

Authenticating to PostgreSQL

PostgreSQL supports authentication through the following methods:
  • Standard
  • pg_hba.conf
    • MD5
    • SASL
  • Entra ID (Azure AD)
  • Azure Service Principal
    • AzureServicePrincipal
    • AzureServicePrincipalCert
  • Azure AD Password
  • Azure AD MSI
  • GCP Service Account
  • Amazon Web Services
  • Kerberos

Standard

Unless you select another scheme, Password is the default authentication mechanism the connector uses to connect to PostgreSQL Server.

To use standard authentication, set the AuthScheme to Password to connect to PostgreSQL with login credentials.

Then, to authenticate, set the Password associated with the authenticating user.

pg_hba.conf Auth Schemes

There are subtypes of the Password authentication scheme supported by the connector which must be enabled in the pg_hba.conf file on the PostgreSQL server.

See the PostgreSQL documentation for more information about authentication setup on the PostgreSQL Server.

MD5

The connector can authenticate by verifying the password with MD5. This authentication method must be enabled by setting the auth-method in the pg_hba.conf file to md5.

SASL

The connector can authenticate by verifying the password with SASL (particularly, SCRAM-SHA-256). This authentication method must be enabled by setting the auth-method in the pg_hba.conf file to scram-sha-256.

Entra ID (Azure AD)

Note: Microsoft has rebranded Azure AD as Entra ID. In topics that require the user to interact with the Entra ID Admin site, we use the same names Microsoft does. However, there are still CData connection properties whose names or values reference "Azure AD".

Microsoft Entra ID is a multi-tenant, cloud-based identity and access management platform. It supports OAuth-based authentication flows that enable the driver to access PostgreSQL endpoints securely.

Authentication to Entra ID via a web application always requires that you first create and register a custom OAuth application. This enables your application to define its own redirect URI, manage credential scope, and comply with organization-specific security policies.

For full instructions on how to create and register a custom OAuth application, see Creating an Entra ID (Azure AD) Application.

After setting AuthScheme to AzureAD, the steps to authenticate vary, depending on the environment. For details on how to connect from desktop applications, web-based workflows, or headless systems, see the following sections.

Desktop Applications

You can authenticate from a desktop application using either the driver's embedded OAuth application or a custom OAuth application registered in Microsoft Entra ID.

Option 1: Use the Embedded OAuth Application

This is a pre-registered application, included with the driver. It simplifies setup and eliminates the need to register your own credentials and is ideal for development environments, single-user tools, or any setup where quick and easy authentication is preferred.

Set the following connection properties:

  • AuthScheme: AzureAD
  • InitiateOAuth:
    • GETANDREFRESH – Use for the initial login. Launches the login page and saves tokens.
    • REFRESH – Use this setting when you have already obtained valid access and refresh tokens. Reuses stored tokens without prompting the user again.

When you connect, the driver opens the Microsoft Entra sign-in page in your default browser. After signing in and granting access, the driver retrieves the access and refresh tokens and saves them to the path specified by OAuthSettingsLocation.

Option 2: Use a Custom OAuth Application

If your organization requires more control, such as managing security policies, redirect URIs, or application branding, you can instead register a custom OAuth application in Microsoft Entra ID and provide its values during connection.

During registration, record the following values:

  • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
  • OAuthClientSecret: The client secret that was that was generated when you registered your custom OAuth application.
  • CallbackURL: A redirect URI you defined during application registration.

For full instructions on how to register a custom OAuth application and configure redirect URIs, see Creating an Entra ID (Azure AD) Application.

Set the following connection properties:

  • AuthScheme: AzureAD
  • InitiateOAuth:
    • GETANDREFRESH – Use for the initial login. Launches the login page and saves tokens.
    • REFRESH – Use this setting when you have already obtained valid access and refresh tokens. Reuses stored tokens without prompting the user again.
  • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
  • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.
  • CallbackURL: A redirect URI you defined during application registration.

After authentication, tokens are saved to OAuthSettingsLocation. These values persist across sessions and are used to automatically refresh the access token when it expires, so you don't need to log in again on future connections.

Web Applications

To authenticate from a web application, you must register a custom OAuth application in Microsoft Entra ID (formerly Azure Active Directory). Embedded OAuth apps are not supported in this context because web-based flows require a registered redirect URI and centralized credential management.

This approach is designed for hosted, multi-user environments where access must be delegated through a secure, standards-compliant OAuth workflow. It gives your organization control over the OAuth client, redirect URI, branding, and permissions scope.

Before you begin: Register a custom OAuth application in the Azure portal. During registration, collect the following values:

  • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
  • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.
  • CallbackURL: A redirect URI you defined during application registration.

For full instructions on how to register a custom OAuth application and configure redirect URIs, see Creating an Entra ID (Azure AD) Application.

To authenticate using AzureAD in a web application, configure the following connection properties:

  • AuthScheme: AzureAD
  • InitiateOAuth: OFF – Disables automatic login prompts.
  • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
  • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.
  • CallbackURL: A redirect URI you defined during application registration.

Because web applications typically manage OAuth flows manually on the server-side, InitiateOAuth must be set to OFF. This allows you to explicitly control when and how tokens are retrieved and exchanged using stored procedures.

After configuring these properties, follow the steps below to obtain and exchange OAuth tokens:

  1. Call the GetOAuthAuthorizationUrl stored procedure:
    • CallbackURL: Set to your registered redirect URI
  2. Open the returned URL in a browser. Sign in with a Microsoft Entra ID account and grant access.
  3. After signing in, you are redirected to your CallbackURL with a code parameter in the query string.
  4. Extract the code and pass it to the GetOAuthAccessToken stored procedure:
    • AuthMode: WEB
    • Verifier: The authorization code from the CallbackURL
  5. The procedure returns:
    • OAuthAccessToken: Used for authentication.
    • OAuthRefreshToken: Used to refresh the access token.
    • ExpiresIn: The lifetime of the access token in seconds.

To enable automatic token refresh, configure the following connection properties:

When InitiateOAuth is set to REFRESH, the driver uses the provided refresh token to request a new access token automatically.

After a successful connection, the driver saves the updated access and refresh tokens to the file specified by OAuthSettingsLocation.

You only need to repeat the full OAuth authorization flow if the refresh token expires, is revoked, or becomes invalid.

For more background on OAuth flows in Microsoft Entra ID, see Microsoft Entra Authentication Overview.

Headless Machines

Headless environments like CI/CD pipelines, background services, or server-based integrations do not have an interactive browser. To authenticate using AzureAD, you must complete the OAuth flow on a separate device with a browser and transfer the authentication result to the headless system.

Setup options:

  • Obtain and exchange a verifier code
    • Use another device to sign in and retrieve a verifier code, which the headless system uses to request tokens.
  • Transfer an OAuth settings file
    • Authenticate on another device, then copy the stored token file to the headless environment.

Using a Verifier Code

  1. On a device with a browser:
    • If using a custom OAuth app, set the following properties:
      • InitiateOAuth: OFF
      • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
      • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.
    • Call the GetOAuthAuthorizationUrl stored procedure to generate a sign-in URL.
    • Open the returned URL in a browser. Sign in and grant grant permissions to the driver. You are redirected to the callback URL, which contains the verifier code.
    • After signing in, save the value of the code parameter from the redirect URL. You will use this later to set the OAuthVerifier connection property.
  2. On the headless machine:
    • Set the following properties:
    • After tokens are saved, reuse them by setting:
      • InitiateOAuth: REFRESH
      • OAuthSettingsLocation: Make sure this location grants read and write permissions to the driver to enable the automatic refreshing of the access token.
      • For custom applications:
        • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
        • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.

Transferring OAuth Settings

  1. On a device with a browser:
    • Connect using the instructions in the Desktop Applications section.
    • After connecting, tokens are saved to the file path in OAuthSettingsLocation. The default filename is OAuthSettings.txt.

  2. On the headless machine:
    • Copy the OAuth settings file to the machine.
    • Set the following properties:
      • AuthScheme: AzureAD
      • InitiateOAuth: REFRESH
      • OAuthSettingsLocation: Make sure this location grants read and write permissions to the driver to enable the automatic refreshing of the access token.
      • For custom applications:
        • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
        • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.

After setup, the driver uses the stored tokens to refresh the access token automatically, no browser or manual login is required.

Note: Azure PostgreSQL Flexible servers are not supported. Only Azure PostgreSQL Single Server instances are supported.

Ensure that an Active Directory admin has been set in the Azure PostgreSQL instance (Active Directory admin > Set admin).

Next, set the following to connect:

  • User: The Azure Active Directory user you granted access to the Azure PostgreSQL server.
  • AzureTenant: The Directory (tenant) ID, found on the Overview page of the OAuth app used to authenticate to PostgreSQL on Azure.
  • Server: The Server name of the Azure PostgreSQL server, found on the Overview page of the Azure PostgreSQL instance.
  • Database: The database you'd like to connect to on the Azure PostgreSQL instance.
  • Port: The port of the server hosting the PostgreSQL database. 5432 by default.
  • InitiateOAuth: GETANDREFRESH.
  • OAuthClientId: The Application (client) ID, found on the Overview page of the OAuth app used to authenticate to PostgreSQL on Azure.
  • OAuthClientSecret: The Value of the client secret, generated at the Certificates and secrets page of the authenticating OAuth app.
  • CallbackURL: The Redirect URI you specified during the creation of your OAuth app.

Azure Service Principal

Note: Microsoft has rebranded Azure AD as Entra ID. In topics that require the user to interact with the Entra ID Admin site, we use the same names Microsoft does. However, there are still CData connection properties whose names or values reference "Azure AD".

Service principals are security objects within a Microsoft Entra ID (Azure AD) application that define what that application can do within a specific tenant. Service principals are created in the Entra admin center, also accessible through the Azure portal. As part of the creation process we also specify whether the service principal will access Entra resources via a client secret or a certificate.

Depending on the service you are connecting to, a tenant administrator may need to enable Service Principal authentication or assign the Service Principal to the appropriate roles or security groups.

Instead of being tied to a particular user, service principal permissions are based on the roles assigned to them. These roles determine which resources the application can access and which operations it can perform.

When authenticating using a service principal, you must register an application with an Entra tenant, as described in Creating a Service Principal App in Entra ID (Azure AD).

This subsection describes properties you must set before you can connect. These vary, depending on whether you will authenticate via a client secret or a certificate.

Authentication with Client Secret

Authentication with Certificate

Azure Password

To authenticate directly to Azure Active Directory using your Azure credentials, specify the following connection properties:

  • AuthScheme: AzurePassword.
  • User: The user account you use to connect to Azure.
  • Password: The password you use to connect to Azure.
  • AzureTenant: The Directory (tenant) ID, found on the Overview page of the OAuth app used to authenticate to PostgreSQL on Azure.
  • Server: The Server name of the Azure PostgreSQL server, found on the Overview page of the Azure PostgreSQL instance.
  • Database: The database you want to connect to on the Azure PostgreSQL instance.
  • Port: The port of the server hosting the PostgreSQL database. 5432 by default.

GCP Service Account

To authenticate to your PostgreSQL Google SQL Cloud Instance using a service account, you must create a new service account and have a copy of the accounts certificate. If you do not already have a service account, you can create one by following the procedure in Creating an Entra ID (Azure AD) Application. For a JSON file, set these properties:

  • AuthScheme: GCPServiceAccount.
  • InitiateOAuth: GETANDREFRESH.
  • OAuthJWTCertType: GOOGLEJSON.
  • OAuthJWTCert: The path to the .json file provided by Google.
  • OAuthJWTSubject (optional): Only set this value if the service account is part of a GSuite domain and you want to enable delegation. The value of this property should be the email address of the user whose data you want to access.

For a PFX file, set these properties instead:

  • AuthScheme: GCPServiceAccount.
  • InitiateOAuth: GETANDREFRESH.
  • OAuthJWTCertType: PFXFILE.
  • OAuthJWTCert: The path to the .pfx file provided by Google.
  • OAuthJWTIssuer: The email address of the service account. This address usually includes the domain, iam.gserviceaccount.com.
  • OAuthJWTCertPassword (optional): The .pfx file password. In most cases you must provide this since Google encrypts PFX certificates.
  • OAuthJWTCertSubject (optional): Set this only if you are using a OAuthJWTCertType which stores multiple certificates. Should not be set for PFX certificates generated by Google.
  • OAuthJWTSubject (optional): Only set this value if the service account is part of a GSuite domain and you want to enable delegation. The value of this property should be the email address of the user whose data you want to access.

Managed Service Identity (MSI)

If you are running PostgreSQL on an Azure VM and want to automatically obtain Managed Service Identity (MSI) credentials to connect, set AuthScheme to AzureMSI.

User-Managed Identities

To obtain a token for a managed identity, use the OAuthClientId property to specify the managed identity's client_id.

If your VM has multiple user-assigned managed identities, you must also specify OAuthClientId.

Amazon Web Services

To authenticate to Amazon Web Services, you need to obtain the proper credentials (AWS Keys) and set the configuration parameters.

Obtain AWS Keys

To obtain the credentials for an IAM user:
  1. Sign into the IAM console.
  2. In the navigation pane, select Users.
  3. To create or manage the access keys for a user, select the user and then navigate to the Security Credentials tab.
To obtain the credentials for your AWS root account:
  1. Sign into the AWS Management console with the credentials for your root account.
  2. Select your account name or number.
  3. In the menu that displays, select My Security Credentials.
  4. To manage or create root account access keys, click Continue to Security Credentials and expand the "Access Keys" section.

AWS IAM Roles

To authenticate through AWS, set AuthScheme to AwsIAMRoles.

To authenticate as an AWS role, set these properties:

  • AuthScheme: AwsIAMRoles.
  • User: The AWS-hosted PostgreSQL user that you granted the aws_iam role to. This user should map to an AWS user that has a role containing a policy which includes the rds-db:connect permission.
  • AWSRoleARN: The Role ARN for the role attached to the authenticating IAM user. This causes the connector to attempt to retrieve credentials for the specified role.
  • AWSAccessKey: The access key of the authenticating IAM user.
  • AWSSecretKey: The secret key of the authenticating IAM user.

If multi-factor authentication is required, specify the following:

  • CredentialsLocation: The location of the settings file where MFA credentials are saved. See the Credentials File Location page under Connection String Options for more information.
  • MFASerialNumber: The serial number of the MFA device if one is being used.
  • MFAToken: The temporary token available from your MFA device.
This causes the connector to submit the MFA credentials in the request to retrieve temporary authentication credentials.

Note: If you want to control the duration of the temporary credentials, set the TemporaryTokenDuration property (default: 3600 seconds).

Note: In some circumstances it might be preferable to use an IAM role for authentication, rather than the direct security credentials of an AWS root user. If you are specifying the AWSAccessKey and AWSSecretKey of an AWS root user, you cannot use roles.

Using AWS From an EC2 Instance

Set AuthScheme to AwsEC2Roles.

If you are using the connector from an EC2 Instance and have an IAM Role assigned to the instance, you can use the IAM Role to authenticate. Since the connector automatically obtains your IAM Role credentials and authenticates with them, it is not necessary to specify AWSAccessKey and AWSSecretKey.

If you are also using an IAM role to authenticate, you must additionally specify the following:

  • AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the connector to attempt to retrieve credentials for the specified role.
  • AWSExternalId (optional): Only required if you are assuming a role in another AWS account.

IMDSv2 Support

The PostgreSQL connector now supports IMDSv2. Unlike IMDSv1, the new version requires an authentication token. Endpoints and response are the same in both versions.

In IMDSv2, the PostgreSQL connector first attempts to retrieve the IMDSv2 metadata token and then uses it to call AWS metadata endpoints. If it is unable to retrieve the token, the connector reverts to IMDSv1.

Kerberos

The authentication with Kerberos is initiated by PostgreSQL Server when the CData Python Connector for PostgreSQL is trying to connect to it. You should setup Kerberos on the PostgreSQL Server to activate this authentication method. Once you have Kerberos authentication setup on the PostgreSQL Server, see Using Kerberos for details on how to authenticate with Kerberos by the connector.

Copyright (c) 2025 CData Software, Inc. - All rights reserved.
Build 25.0.9454