Configuring runtime database

The runtime database (also known as the High Volume Database) is used to store OAuth and OIDC token and grant attributes. It may also be used for distributed session storage. The IBM Security Verify Access OIDC Provider (ISVAOP) requires this component to be configured.

PostgreSQL, Oracle, and Db2 are currently supported.

Follow the Docker and Docker deployment cookbook to set up verify-access-postgresql.

Follow the Running ISVA on IBM Cloud to deploy the runtime database on a Kubernetes cluster.

If there is a preference to run PostgreSQL off-the-shelf, execute the schema SQL available in the Resources Github Repository.

Modifying an existing PostgreSQL runtime database

If PostgreSQL is already in use as the runtime database for Verify Access Runtime, some schema updates are required.

CREATE TABLE IF NOT EXISTS OAUTH20_JTI ( 
    JWT_TYPE   INT          NOT NULL, 
    JWT_ID     VARCHAR(200) NOT NULL, 
    EXPIRED_AT BIGINT       NOT NULL, 
    CONSTRAINT PK_JTIS PRIMARY KEY(JWT_TYPE, JWT_ID) 
);

CREATE INDEX IF NOT EXISTS IX_JTIS_EXPIRED ON OAUTH20_JTI (EXPIRED_AT);

Modifying an existing Oracle runtime database

If Oracle is already in use as the runtime database for Verify Access Runtime, some schema updates are required.

CREATE TABLE OAUTH20_JTI
(
    JWT_TYPE   INT           NOT NULL,
    JWT_ID     VARCHAR(200)  NOT NULL,
    EXPIRED_AT NUMBER(19, 0) NOT NULL,
    CONSTRAINT PK_JTIS PRIMARY KEY (JWT_TYPE, JWT_ID)
);

CREATE INDEX JTIS_EXPIRED ON OAUTH20_JTI (EXPIRED_AT);

Modifying an existing Db2 runtime database

If Db2 is already in use as the runtime database for Verify Access Runtime, some schema updates are required.

CREATE TABLE OAUTH20_JTI
(
  JWT_TYPE   INT           NOT NULL,
  JWT_ID     VARCHAR(200)  NOT NULL,
  EXPIRED_AT BIGINT NOT NULL,

  CONSTRAINT PK_JTIS PRIMARY KEY (JWT_TYPE, JWT_ID)
);

CREATE INDEX JTIS_EXPIRED ON OAUTH20_JTI (EXPIRED_AT);

This adds a table to hold JSON Web Token IDs to detect reuse of the jti claim in JSON Web Tokens, such as client assertions. The full schema is provided in the Resources Github Repository.

Configuring the OIDC Provider

The IBM Security Verify Access OIDC Provider connects to a running postgres database instance by reading the runtime_db configuration stanza in storage.yml. Read more about the storage.yml documentation.

The example below configures the runtime database to also store short-lived session information for multi-step flows, such as the authorization code grant flow.

The following steps can be followed to configure the database:

  1. Update database_name, host, port and credential in storage.yml.

  2. (Optional) If the database is set up to only accept TLS connections, configure the ssl property with the appropriate certificate information. There are several options available for certificate and key management. See Key Managament.

  3. (Optional) The database password can be obfuscated using an obfuscation key, if one is provided. See Generating Secrets. This is recommended.

runtime_db: mypq                                            # Configuration of runtime database. Points to the database server connection.
session_cache:
  type: db                                                  # Specifies the type of session cache, in-memory, redis, or db.
server_connections:                                         # Server connections
  - name: mypq                                              # Connection name
    type: postgresql                                        # Connection type, `redis`, `ldap`, `postgresql`
    database_name: verify-access                            # Specifies the database name. For database types only.
    hosts:                                                  # List of host information (IP and port)
      - hostname: postgresql                                # Server's hostname
        hostport: 5432                                      # Server's host port
    credential:                                             # Credential information to connect to the server
      username: postgres                                    # Specifies the username to access the server.
      password: 'OBF:gJDSuqEFmORCR2Uw3FsAmFKomjYLmhMwdDG2XoUxtQ0='
                                                            # Specifies the password to access the server. It is recommended to obfuscate this.
    ssl:
      certificate:                                          # The SSL connection certificate array.
        - ks:postgres_keys                                  # The SSL keystore to be used for SSL connections. ks: indicates keystore.
      mutual_auth:
        key: ks:rt_profile_keys/postgres                    # When mutual TLS is needed, specify the keystore and label that contains the client's private key.
        certificate: ks:rt_profile_keys/postgres            # When mutual TLS is needed, specify the keystore and label of the client's leaf certificate.
        ca:                                                 
          - ks:rt_profile_keys/ca                           # When mutual TLS is needed, specify the keystore and label of the client's CA certificate.
      disable_hostname_verification: false                  # The SSL connection validates the hostname.
    conn_settings:                                          # Connection settings
      max_idle_time: 10                                     # Maximum idle time in seconds
      min_pool_size: 5                                      # Minimum connection pool size
      max_pool_size: 50                                     # Maximum connection pool size
      connect_timeout: 5                                    # Connect timeout, in seconds
      aged_timeout: 30                                      # Aged timeout, in seconds

Troubleshooting

  • When the PostgreSQL instance is not able to connect, the error below is shown. Check the hostname and port details.

    verify-access-oidc-provider_1           | [09/11/2022 14:17:12.01 UTC] (internal.modules.db.postgresDB.startup) W [CORR_ID-313d5b0a-750d-443b-b9b5-d0892a50d4e9] "Failed to connect to DB: failed to connect to `host=isvaop-postgresql user=postgres database=verify-access`: hostname resolving error (lookup pentest-isva-postgresql111 on 127.0.0.11:53: no such host)"
    
  • When bad credentials are used or the SSL settings are invalid, the error below is shown. Check the database credentials configured and the SSL settings.

    verify-access-oidc-provider_1         | [09/11/2022 14:20:19.052 UTC] (internal.modules.db.postgresDB.startup) W [CORR_ID-ae582afe-1eb2-4129-92dd-2a829555779b] "Failed to connect to DB: failed to connect to `host=isvaop-postgresql user=postgres-isvaop database=verify-access`: server error (FATAL: no pg_hba.conf entry for host \"172.19.0.5\", user \"postgres-isvaop\", database \"verify-access\", SSL on (SQLSTATE 28000))"
    
  • If the OIDC Provider is not able to connect to the runtime database during startup, the container will terminate.