Advanced Configuration

This guide walks through different use cases that go beyond a basic deployment. These features require extra configuration that needs to be done outside of pgAdmin. For example, deploying an LDAP server or a PostgreSQL database to use as the pgAdmin settings database.

Authentication Sources

The AUTHENTICATION_SOURCES setting in pgAdmin allows you to adjust the ways in which users can authenticate. By default, pgAdmin is setup to only allow internal users, users that are stored in the pgAdmin settings database, to authenticate. By adding options to the AUTHENTICATION_SOURCES list, you can enable other sources.

If you wanted your pgAdmin users to be able to authenticate via LDAP, in addition to using internal authentication, you would need to include ldap option in the AUTHENTICATION_SOURCES setting array:

spec:
  config:
    settings:
      AUTHENTICATION_SOURCES: ['ldap', 'internal']
Copy

The first source in the list will have a higher priority, meaning you can use ldap as your first source and internal as a fallback in case ldap fails.

LDAP Configuration

The pgAdmin config.py file has configuration options to enable LDAP authentication into pgAdmin. These settings will depend on your LDAP server. We will go through some simple examples here to show how you can connect to an LDAP server.

Basic connection

You will configure a majority of LDAP settings using the config.settings field. The first step to enabling LDAP is to update your AUTHENTICATION_SOURCES setting to include the new source. CPK requires that you enable the LDAP_AUTO_CREATE_USER setting so that pgAdmin will create a pgAdmin user for any LDAP user that successfully logs in.

spec:
  config:
    settings:
      AUTHENTICATION_SOURCES: ['ldap', 'internal']
      LDAP_AUTO_CREATE_USER: True # Required if using LDAP
Copy

This is also where you will configure your LDAP_SERVER_URI and other LDAP settings, like LDAP_SEARCH_BASE_DN or LDAP_ANONYMOUS_BIND. Reference the pgAdmin LDAP documentation for more information about LDAP settings.

LDAP Bind User and Password

Depending on your LDAP configuration, you might need to define a user and password that will bind pgAdmin to the LDAP server. These options are defined in config.py as LDAP_BIND_USER and LDAP_BIND_PASSWORD. You will define the LDAP_BIND_USER like you would any other setting. However, the LDAP_BIND_PASSWORD is not something that we recommend storing in your PGAdmin spec. Instead, CPK provides the ldapBindPassword field that lets you point at a Secret:

spec:
  config:
    settings:
      LDAP_BIND_USER: $user
    ldapBindPassword:
      name: ldappass
      key: $password
Copy

This field is a Secret key reference that will be mounted to the pgAdmin Pod. CPK will configure pgAdmin to look in the mounted file instead of using the plaintext LDAP_BIND_PASSWORD setting. This helps to keep you password secure.

Connection to a TLS LDAP server

If you are connecting to a LDAP server using TLS, you will need to provide cert files to secure the connection. Like we talked about in the configuration docs, you will need to mount your cert files to the pgAdmin Pod. Once the files are available to pgAdmin, you will need to tell pgAdmin where to look for them. This is done using the LDAP_CA_CERT_FILE, LDAP_CERT_FILE, and LDAP_KEY_FILE settings. Your final spec should include something like this:

spec:
  config:
    settings:
      LDAP_SERVER_URI: ldaps://my.ds.example.com
      LDAP_CA_CERT_FILE: /etc/pgadmin/conf.d/certs/ca.crt
      LDAP_CERT_FILE: /etc/pgadmin/conf.d/certs/tls.crt
      LDAP_KEY_FILE: /etc/pgadmin/conf.d/certs/tls.key
    files:
    - secret:
        name: openldap
        items:
          - key: ca.crt
            path: certs/ca.crt
          - key: tls.crt
            path: certs/tls.crt
          - key: tls.key
            path: certs/tls.key
Copy

OAuth2 Configuration

The pgAdmin config.py file also has configuration options to enable OAuth2 authentication for pgAdmin. These settings will depend on your OAuth2 server. As with LDAP, we will go through some simple examples here to show how you can connect to an OAuth2 server.

Example Configurations

You will configure the OAuth2 settings using the config.settings field. The first step to enabling OAuth2 is to update your AUTHENTICATION_SOURCES setting to include the new source. CPK requires that you enable the OAUTH2_AUTO_CREATE_USER setting so that pgAdmin will create a pgAdmin user for any OAuth2 user that successfully logs in. As shown below, more than one OAuth2 authentication source can be defined. Please note that in pgAdmin 8.12, OAUTH2_ICON, OAUTH2_BUTTON_COLOR and other settings are required. This will be updated in a future release.

config:
    settings:
      AUTHENTICATION_SOURCES: ['internal','oauth2']
      OAUTH2_AUTO_CREATE_USER: True
      OAUTH2_CONFIG:
        - OAUTH2_NAME: "google"
          OAUTH2_DISPLAY_NAME: "Google"
          OAUTH2_CLIENT_ID: "xxxxxxxxxxxxxxxxx"
          OAUTH2_CLIENT_SECRET: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          OAUTH2_TOKEN_URL: "https://oauth2.googleapis.com/token"
          OAUTH2_AUTHORIZATION_URL: "https://accounts.google.com/o/oauth2/auth"
          OAUTH2_API_BASE_URL: "https://openidconnect.googleapis.com/v1/"
          OAUTH2_SERVER_METADATA_URL: "https://accounts.google.com/.well-known/openid-configuration"
          OAUTH2_SCOPE: "openid email profile"
          OAUTH2_USERINFO_ENDPOINT: "userinfo"
          OAUTH2_BUTTON_COLOR: "red"
          OAUTH2_ICON: "None"
        - OAUTH2_NAME: "github"
          OAUTH2_DISPLAY_NAME: "Github"
          OAUTH2_CLIENT_ID: "xxxxxxxxxxxxxxxxx"
          OAUTH2_CLIENT_SECRET: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          OAUTH2_TOKEN_URL: "https://github.com/login/oauth/access_token"
          OAUTH2_AUTHORIZATION_URL: "https://github.com/login/oauth/authorize"
          OAUTH2_API_BASE_URL: "https://api.github.com/"
          OAUTH2_USERINFO_ENDPOINT: "user"
          OAUTH2_BUTTON_COLOR: "blue"
          OAUTH2_ICON: "None"
          OAUTH2_SCOPE: "user"
Copy

With the above configuration added to the PGAdmin deployment, you will see that you now have two new login options available:

External pgAdmin settings Database

Configuring an External database for pgAdmin user settings

By default, the pgAdmin user settings are stored in a local SQLite database. However, pgAdmin does provide a configuration setting for defining a database connection string to an external database. This setting is the CONFIG_DATABASE_URI parameter. The expected parameter must be given in the following format:

dialect+driver://username:password@host:port/databaseCopy

While it is possible to set this value directly in config.settings like other pgAdmin configuration settings, this connection string often contains sensitive information, so storage in a Secret is recommended. As a simple example, if you had a basic PostgresCluster named hippo, by default you could use a connection string similar to

postgresql://hippo:$MY_PASSWORD@hippo-primary.postgres-operator.svc:5432/hippoCopy

where $MY_PASSWORD is updated to your user password. By default, a PostgresCluster named hippo would have a Secret named hippo-pguser-hippo that contains a URI similar to the one above. To use that value for your external database, you would configure your PGAdmin as follows:

spec:
  config:
    configDatabaseURI:
      name: hippo-pguser-hippo
      key: uri
Copy

Just be sure to remember, when using Postgres 15+ you will need to verify your user has creation permissions in the default schema, as described in the quickstart). If the user does not have creation permissions, pgAdmin won't be able to create the needed tables!

In cases where you want to define a specific schema, you can also create your own Secret with more specific settings. For instance, if you wanted to use the connection string that specified a specific schema such as

postgresql://hippo:$MY_PASSWORD@hippo-primary.postgres-operator.svc:5432/hippo?options=-csearch_path=myschema
Copy

you could create a Secret as follows:

kubectl create secret generic config-db-uri-myschema --from-literal=uri="postgresql://hippo:$MY_PASSWORD@hippo-primary.postgres-operator.svc:5432/hippo?options=-csearch_path=myschema"
Copy

and then reference that Secret in your pgAdmin manifest

spec:
  config:
    configDatabaseURI:
      name: config-db-uri-myschema
      key: uri
Copy

As with LDAP bind password, the configDatabaseURI parameter is a Secret key reference that will be mounted to the pgAdmin Pod allowing you to avoid storing credentials in plaintext. Using this information, your pgAdmin instance will be able to store its user settings in whichever location you define independently of the PGAdmin Pod.