Oracle Cloud Infrastructure Documentation

Kerberos Authentication for OCI Database with PostgreSQL

Learn how to enable and manage Kerberos authentication on your OCI Database with PostgreSQL database system.

This topic explains Kerberos authentication, its benefits, prerequisites, limitations, and step-by-step procedures for enabling, managing, and disabling Kerberos authentication on your PostgreSQL database system.

Kerberos is an industry-standard authentication protocol that provides secure, centralized client-server authentication using cryptographic tickets instead of passwords. Integrating Kerberos with OCI Database with PostgreSQL enables you to leverage centralized credential management, strengthen security, and reduce the risks associated with password-based authentication.

Kerberos authentication is supported through PostgreSQL’s in-built GSSAPI.

Benefits of Kerberos authentication for OCI Database with PostgreSQL include the following:
  • Centralized credential management and single sign-on (SSO) capabilities.
  • Eliminates passwords from network authentication flows.
  • Integrates with common enterprise identity systems such as Active Directory and MIT Kerberos.

Workflow

Kerberos is a network authentication protocol designed for strong client/server authentication using secret-key cryptography. The typical workflow is:

  1. You authenticate with a trusted Key Distribution Center (KDC) and receive a ticket-granting ticket (TGT).
  2. When connecting to the PostgreSQL database, present a service ticket from the KDC to the server.
  3. The PostgreSQL server verifies the ticket using a secure keytab file. No password is transmitted over the network.

Prerequisites

To use Kerberos authentication for OCI Database with PostgreSQL, you must have the following prerequisites:
  • An operational Kerberos infrastructure, such as Active Directory or MIT Kerberos.
  • Access to OCI Vault and required OCI permissions.
  • Privileged access to your KDC and OCI resources.
  • Familiarity with PostgreSQL user/role management.

Setting Up Kerberos Authentication

Perform these tasks to set up Kerberos authentication for OCI Database with PostgreSQL.

Step 1: Create Service Principal and Keytab in Your KDC

Active Directory

  1. Create a dedicated service account.
  2. Map all required PostgreSQL endpoint FQDNs as SPNs for the account.
  3. Generate a keytab file with strong encryption, for example:
    ktpass /out odsp.krb5.keytab /princ postgres/<database_fqdn>@your.realm /mapuser <service_user> /crypto AES256-SHA1 +rndpass ...

    Ensure sure only approved encryption types are used, for example: aes256-cts-hmac-sha256-128)

MIT Kerberos

For each endpoint, add a principal and generate a keytab, for example:
kadmin.local -q "addprinc -randkey postgres/<database_fqdn>@your.realm"
kadmin.local -q "ktadd -k odsp.krb5.keytab postgres/<database_fqdn>@your.realm"

Step 2: Store Keytab in OCI Vault

  1. Upload the keytab file as a secret in OCI Vault.
    For more information, see Managing Secrets.
  2. Give your PostgreSQL database system access to read this secret by updating your IAM policy, for example: 
    allow any-user to SECRET_BUNDLE_READ in compartment <compartment_ocid> where all {request.user.id='<database_system_ocid>', target.secret.id='<secret_ocid>'}

Step 3: Enable Kerberos in the PostgreSQL Database System

Using the CLI or API, edit your PostgreSQL database system:
  1. Set Kerberos Authentication to ENABLED.
  2. Provide your Kerberos Realm name, the keytab secret OCID, and version.
The system downloads the keytab, updates postgresql.conf and pg_hba.conf, and reloads PostgreSQL.

Step 4: Designate Users for Kerberos Authentication

  1. Sign in to the PostgreSQL database system as a user with the oci_admin_role.
  2. For each required Kerberos principal, create a corresponding user and assign the odsp_kerberos role: 
    CREATE ROLE "kerberos_user@your.realm" WITH LOGIN;
GRANT odsp_kerberos TO "kerberos_user@your.realm";
  3. Assign all other roles/permissions as needed.
  4. Each Kerberos principal requires its own PostgreSQL database system user.

Kerberos Client Usage

On the client system, run the following command:

kinit kerb_user@your.realm
psql "sslmode=prefer host=<database_fqdn> dbname=<datbase_name> user=kerb_user@your.realm"

Disabling Kerberos Authentication

Using the CLI or API, edit your PostgreSQL database system to Set Kerberos Authentication to DISABLED. For more information, see Editing a Database System.

This action removes the keytab configuration and disables Kerberos authentication.

Keytab Rotation and Maintenance

Regularly rotate Kerberos service principal credentials in accordance with your security policy.

To rotate Kerberos credentials while minimizing disruptions you need to do it as two step process:

  1. First add the new keytab as a new secret in OCI Vault.
  2. Update the PostgreSQL database system to have both keytabs: the new keytab secret as currentCredential and the existing keytab secret as backupCredential.

After a while, update the PostgreSQL database system to have only one keytab: the new keytab secret as currentCredential, backupCredential=null.

Note

Allow for potential short disruptions in authentication during the keytab/key rotation.

Troubleshooting

Perform the following tasks to address any issues that occur:

  • Check PostgreSQL service logs for Kerberos authentication failures.
  • Ensure clocks are synced between PostgreSQL database systems, clients, and the KDC.
  • Verify proper SPN, keytab, and encryption settings if authentication issues occur.

Limitations

Note the following limitations for using Kerberos Authentication for OCI Database with PostgreSQL:

  • Kerberos authentication is an additional layer of security. You can still use password authentication.
  • Each Kerberos principal that requires database access must have a corresponding PostgreSQL user/role created and granted the odsp_kerberos role.
  • Because PostgreSQL doesn't support group-based authentication, you must create a PostgreSQL user for each Kerberos principal.
  • You're responsible for all service principal (SPN) and keytab management.
  • Kerberos is sensitive to clock drift. Ensure NTP or an equivalent service is running everywhere.
  • Brief authentication failures are possible during keytab rotation, especially in MIT Kerberos environments.
  • KDC outages prevent Kerberos-authenticated users from signing in, but password-authenticated users remain unaffected.
  • The PostgreSQL database system must have permission to access secrets in OCI Vault containing the keytab.