Tableau Connector for PostgreSQL

Build 25.0.9434

Configuring a Connection

After Installing the Connector you can connect and create a Data Source for data in PostgreSQL.

Setting Up a Data Source

Complete the following steps to connect to the data:

  1. Under Connect | To a Server, click More....
  2. Select the data source called PostgreSQL by CData.
  3. Enter the information required for the connection.
  4. Click Sign In.
  5. If necessary, select a Database and Schema to discover what tables and views are available.

Using the Connection Builder

The connector makes the most common connection properties available directly in Tableau. However, it can be difficult to use if you need to use more advanced settings or need to troubleshoot connection issues. The connector includes a separate connection builder that allows you to create and test connections outside of Tableau.

There are two ways to access the connection builder:

  • On Windows, use a shortcut called Connection Builder in the Start menu, under the CData Tableau Connector for PostgreSQL folder.
  • You can also start the connection builder by going to the driver install directory and running the .jar file in the lib directory.

In the connection builder, you can set values for connection properties and click Test Connection to validate that they work. You can also use the Copy to Clipboard button to save the connection string. This connection string can be given to the Connection String option included in the connector connection window in Tableau.

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, unless you connect via Tableau. 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. For details about connecting via Tableau, see Tableau Integrated Azure, below.

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.

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 option:

  • Transfer an OAuth settings file
    • Authenticate on another device, then copy the stored token file to the headless environment.

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.

Tableau Integrated Azure AD

Tableau Integrated Azure AD enables users to log in to protected resources via Proof Key for Code Exchange (PKCE). PKCE is an extension to the auth code flow that is designed to prevent cross-site request forgery and authorization code injection attacks.

It is not necessary to create a custom OAuth application to log in via Tableau Integrated Azure. Instead:

  1. Log in to the Tableau Server console.
  2. At the list of Installed Connections, click PostgreSQL by CData.
  3. In the General tab, to go the AuthScheme field and select Tableau Integrated AzureAD.
  4. Enter the OAuth Instance URL.

    The OAuth instance URL can be entered either in the format:
    https://login.microsoft.online.com/common, where common indicates the tenant environment, or
    https://login.microsoftonline.us/common, where login.microsoftonline.us is the Azure environment.

Logging in via Tableau Integrated Azure AD provides a Tableau login screen, which creates a similar experience to the more typical OAuth experience.

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 Tableau 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.

Next Step

See Using the Connector to create data visualizations.

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