Kong Gateway Google Cloud Postgres database authentication with GCP IAM and Workload Identity

You can use GCP Identity and Access Management (IAM) and Workload Identity authentication to connect to the Google Cloud Postgres database that you use for Kong Gateway. This page explains how to configure IAM and Workload Identity authentication to secure your database settings and connections.

With authentication enabled, you don’t need a password to connect to a database instance. Instead, you use a temporary authentication token. Because GCP manages the authentication externally, the database doesn’t store user credentials. If you’re using Google Cloud Postgres for Kong Gateway’s database, you can enable authentication on your running cluster. This eliminates the need to store user credentials on both the Kong Gateway (pg_password) and Google Cloud Postgres sides.

GCP authentication has some limitations. Go through each one before you use this feature in your production environment:

• This feature cannot be used together with databases from other cloud providers, such as AWS RDS. These auth providers are mutually exclusive.
• When pg_gcp_auth is enabled, the pg_password won’t be used. You can’t use both methods at the same time.
• Any incorrect configuration on the GCP side will result in a failure in initializing the database connection, such as an improperly configured managed identity or a missing role inside GCP Postgres.

For additional recommendations and limitations, see the IAM authentication restrictions in the Google Cloud documentation.

You can enable GCP authentication through an environment variable or the Kong Gateway configuration file. You can enable it for both read-write and read-only modes, or for read-only mode only.

Note: When GCP authentication is enabled, Kong Gateway ignores the corresponding password configurations. If authentication is enabled only for read-only mode, the read-write settings—such as pg_user and pg_password—remain unaffected and continue to function as usual.

Configuring your GCP resources

Before you enable GCP authentication, you must configure your Google Cloud Postgres database and the IAM role or Workload Identity that Kong Gateway uses.

• A GCP service account key. The service account must have sufficiently broad permissions; at minimum, it must be able to access GCP Postgres.
• A database user bound to the GCP service account with the Cloud SQL Instance User role (roles/cloudsql.instanceUser). The user must also be able to connect to the GCP Postgres instance from their GCP VM using psql.
• For IAM database authentication, you need a principal with the cloudsql.instances.login permission to log in to an instance, which is included in the Cloud SQL Instance User role.

Configuring GCP authentication in Kong Gateway

Before you enable GCP authentication, you must do the following in the kong.conf file:

• Remove pg_password or pg_ro_password.
• Check that pg_user or pg_ro_user matches the username you defined in the IAM policy and created in the Postgres RDS database.

KONG_PG_GCP_AUTH=on

KONG_PG_GCP_AUTH=off # This variable can be omitted because off is the default value
KONG_PG_RO_GCP_AUTH=on

KONG_PG_USER='username@project-name.iam'        # Postgres user.
KONG_PG_DATABASE='kong'                         # The database name to connect to.
KONG_PG_HOST='35.200.xx.yy'                     # Host of the Postgres server.
KONG_PG_PORT='5432'                             # Port of the Postgres server.
KONG_PG_GCP_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"example-project-294816","private_key_id":"a7b3c9d2e8f1g4h6i5j7k9m2n4p6q8r1","private_key":"-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANB…………………………..…5xX5yY5zA==\n-----END PRIVATE KEY-----\n","client_email":"example-sa@example-project-294816.iam.gserviceaccount.com","client_id":"103847562938475629384","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/example-sa%40example-project-294816.iam.gserviceaccount.com","universe_domain":"googleapis.com"}'

pg_gcp_auth=on

pg_ro_gcp_auth=on

pg_user = username@project-name.iam        # Postgres user.
pg_database = kong                         # The database name to connect to.
pg_host = 35.200.xx.yy                     # Host of the Postgres server.
pg_port = 5432                             # Port of the Postgres server.
pg_gcp_service_account_json={"type":"service_account","project_id":"example-project-294816","private_key_id":"a7b3c9d2e8f1g4h6i5j7k9m2n4p6q8r1","private_key":"-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANB…………………………..…5xX5yY5zA==\n-----END PRIVATE KEY-----\n","client_email":"example-sa@example-project-294816.iam.gserviceaccount.com","client_id":"103847562938475629384","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/example-sa%40example-project-294816.iam.gserviceaccount.com","universe_domain":"googleapis.com"}