Configuration Primer

Suggest Edits

IBM Security Verify Access OIDC Provider (ISVAOP) uses a prescribed configuration directory structure that is loaded into /var/isvaop/config directory within the container filesystem. There is no reliance on a configuration database and any changes in the configuration requires a restart of the container instance. Configuration updates can be orchestrated using tools available on systems, such as Kubernetes.

Overview

The ISVAOP configuration contains the following:

  • 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

📘

Note

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

The following structure is expected in /var/isvaop/config directory in the container filesystem. There are different ways to load configuration into this directory that has been covered in each specific deployment environment, such as Kubernetes.

config
 |
 - provider.yml
 - attributesources.yml
 - storage.yml
 - ldapcfg.yml
 - clients
 |    |
 |    - <clientID1>.yml
 |    - <clientIDn>.yml
 |
 - javascript
 |    |
 |    - accesspolicy
 |    |     |
 |    |     - <policy>.js
 |    |
 |    - mappingrule
 |          |
 |          - <pretoken>.js
 |          - <posttoken>.js
 |
 - keystore
 |    |
 |    - <keystoreName>
 |          |
 |          - personal
 |          |   |
 |          |   - <personal_label1>.pem
 |          |   - <personal_labeln>.pem
 |          |
 |          - signer
 |          |   |
 |          |   - <signer_label1>.pem
 |          |   - <signer_labeln>.pem
 |          - <name>.p12
 |          - <name>.obf
 |
 - templates
      |
      - C
         |
         - static
         |     |
         |     - ibm-logo.png
         |     - styles.css
         |
         - user_consent.html
         - user_error.html
         - user_authorize_success.html
         - user_authorize_failed.html

Apart from this, it is also possible to reference certificate files directly relative to the /var/isvaop/config directory. For more information, see Key Management.

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.

  • If no personal certificate is available for the HTTPS connection, 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 ###

  • Create directories {config_root}/keystore/server_keys/signer and {config_root}/keystore/server_keys/personal.

  • Copy the server_cert.pem to {config_root}/keystore/server_keys/signer and server_key.pem to {config_root}/keystore/server_keys/personal.

  • Open provider.yml and verify that server/ssl is configured to use the server_keys keystore.

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 6 months ago