Guides

Configuration Primer

Suggest Edits

The IBM Security Verify Access OIDC Provider (ISVAOP) uses YAML documents for all configuration data. When the container starts, it will look in the /var/isvaop/config directory of the container for YAML documents.

There is no reliance on a configuration database and any changes in the configuration requires a restart of the container instance. Depending on your container environment, the files within the configuration directory can be bind mounted in, provided via a ConfigMap or any other mechanism which places the files in the configuration directory.

Overview

ISVAOP configuration can span across multiple YAML documents. This is useful for simplifying the management of configuration data.
A set of YAML files that contain:

  • Configuration settings for the OIDC Provider, storage, attribute sources etc.
  • Keystores and certificates
  • JavaScript customization in the form of mapping rules and access policies
  • Static OAuth and OIDC client configuration

The YAML documents are process based on these rules

📘

Note

Clients can be configured and managed on ISVAOP using the standards-based Dynamic client registration.
These clients are stored in the Runtime Database.

Configuration Starter Kit

The starter kit provides a boilerplate structure. It can be downloaded from Github Releases of the resources repository.

The starter kit cannot be used directly. It requires some changes.

  • Download the zip

  • Unzip the package into a directory. For example, isvaop_config. This is called {config_root} in the following steps.

HTTPS Connection

Follow the steps below to configure the HTTPS connection.

  • For the ISVAOP server to start, generate a self-signed certificate key pair.

    # Generate a key-pair
[demouser@demovm ~]$ openssl req -newkey rsa:2048 -nodes -keyout server_key.pem -x509 -days 365 -out server_cert.pem
### Some output ###

  • Keystore can be defined in the YAML files using different annotations, an example based on the key and certificate specified in the above step.

keystore:
  - name: keystore1
    type: pem
    certificate:
      - label: serverCert
        content: "@server_cert.pem"
    key:
      - label: serverKey
        content: "@server_key.pem"

  • Copy server_cert.pem and server_key.pem to {config_root}/.

  • Update provider.yml, server/ssl configuration.

server:
  ssl:
    key: ks:keystore1/serverKey                       # Name of the keystore/key for the ISVAOP HTTPS server.
    certificate: ks:keystore1/serverCert              # Name of the keystore/certificate for the ISVAOP HTTPS server.

JWT Signing

Follow the steps below to set up the keystore settings to sign JSON Web Tokens issued by the provider.

  • If no personal certificate is available to sign JWTs, generate a private key.

    # Generate a key-pair
[demouser@demovm ~]$ openssl genrsa -out rsakey.pem 2048
### Some output ###

  • Create directories with the path {config_root}/keystore/isvaop_signing/personal.

  • Copy rsakey.pem to {config_root}/keystore/isvaop_signing/personal.

  • Open provider.yml and verify that definition/token_settings/signing_* is correctly configured to point at this keystore and file name (file name is used as label).

  • Verify that the /jwks/signing_keystore is configured to this keystore.

Storage Settings

Follow the steps specified in the Runtime Database to configure the connection settings in storage.yml.

Conclusion

The configuration directory is now ready. Continue the deployment activities and use tasks to enhance this configuration for specific use cases.

Updated 4 months ago