Configuration

Suggest Edits

Configuration

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.

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.

Refer to YAML Config Guide for full YAML configuration details.

Using Multiple Configuration YAML Documents

ISVAOP configuration can span across multiple YAML documents. This is useful for simplifying the management of configuration data.

YAML Documents Rules

ISVAOP combines all YAML documents found in /var/isvaop/config using the following rules:

  1. ISVAOP configuration documents must have the file extension .yaml or .yml.
  2. The following top-level keys can only be defined once across all configuration YAML documents.
    1. version
    2. definition
    3. jwks
    4. authentication
    5. template_macros
    6. ssl
    7. server
    8. javascript
    9. logging
    10. dynamic_registration
    11. secrets
    12. runtime_db
    13. session_cache
  3. The following top-level keys can be defined more than once in different configuration YAML files. When this occurs ISVAOP will combine all of the values.
    1. server_connections
    2. attribute_sources
    3. ldapcfg
    4. clients
    5. keystore
    6. rules
  4. When the configuration version is greater than or equal to 23.12, the following rules apply:
    1. Full YAML based configuration is supported.
    2. All configurations must supplied in the YAML configuration.
    3. attribute_map under definition references to attribute source under attribute_sources using name of the
      attribute source.
  5. When the configuration version is lesser than 23.12, the following rules apply:
    1. Full YAML based configuration is NOT supported.
    2. The following configurations must supplied in corresponding folders under /var/isvaop/config
      1. Customized template pages: templates
      2. Keystores: keystore
      3. JavaScript mapping rules: javascript/mappingrule
      4. JavaScript access policies: javascript/accesspolicy
      5. Static clients: clients
    3. attribute_map under definition references to attribute source under attribute_sources using id of the
      attribute source.

Example of Multiple Configuration YAML Documents

This example illustrates how multiple configuration YAML documents can be provided to ISVAOP. The following files are provided to the /var/isvaop/config path within the container.

  1. isvaop.yml
  2. oidc.yml
  3. runtimedb.yml
  4. session.yml
  5. ldap.yml
  6. attrsrc_value.yml
  7. keystores.yml
  8. rules.yml
  9. clients.yml

isvaop.yml - This file contains the top
level version, server, template_macros, logging, secrets, ssl, authentication and javascript keys. Each
document can provide more than one top level key, provided they are
following YAML Documents Rules.

# this file contains the ISVAOP server and related configurations
version: 23.12
server:
  ssl:
    key: "ks:rt_profile_keys/httpserver"
    certificate: "ks:rt_profile_keys/httpserver"
  pages:
    type: zip
    content: "@pages.zip"
template_macros:
  user_macros:
    - name
    - family_name
    - given_name
    - display_name
  request_macros:
    - authorization_details
    - claims
    - user_code
    - state
logging:
  level: debug
secrets:
  obf_key: "abcdef"
ssl:
  certificate:
    - ks:rt_profile
  disable_hostname_verification: true
authentication:
  endpoint: >-
    https://auth.isvaop.com:445/oauth2/auth
  callback_param_name: Target
javascript:
  timeout: 0
  max_load: 16
  max_idle_time: 600
  max_ctx_in_isolate: 50
  cleanup_frequency: 0
  use_pool: false

oidc.yml - This file contains the definition, jwks and dynamic_registration keys.

# this file contains the OIDC related configurations
definition:
  id: 1
  name: OIDC Definition
  grant_types:
    - authorization_code
    - implicit
    - password
    - client_credentials
    - refresh_token
    - 'urn:openid:params:grant-type:ciba'
  access_policy_id: 1
  pre_mappingrule_id: 100
  post_mappingrule_id: 101
  base_url: 'https://auth.isvaop.com:445'
  mtls_base_url: 'https://auth.isvaop.com:445'
  mtls_certificate_header_name: X-Client-Certificate
  features:
    enable_fault_tolerance: false
    enable_dynamic_registration: true
    consent_prompt: PROMPT_ONCE
    fapi_compliant: false
    enforce_par: false
    prefer_claims_at_userinfo: true
  token_settings:
    issuer: https://www.ibm.com
    signing_alg: PS512
    signing_keystore: rt_profile
    signing_keylabel: rsa256
    authorization_code_lifetime: 300
    access_token_lifetime: 7200
    id_token_lifetime: 3600
    refresh_token_lifetime: 64800
  attribute_map:
    name: name
    preferred_username: preferred_username
    email: email
  metadata:
    claims_supported:
      - iss
      - name
      - displayName
jwks:
  signing_keystore: rt_profile_keys
  encryption_keystore: rt_profile_keys
dynamic_registration:
  recipe: UK-OB
  mappingrule_id: dcr
  software_statement_validation:
    jwks_uri: >-
      https://oidc-dev-test.ite1.idng.ibmcloudsecurity.com/oidc/endpoint/default/jwks
    signing_algs:
      - PS256
      - ES256
  registration_endpoint_authentication:
    require_mtls: true
    require_bearer_token: true
    require_software_statement: false
    allow_custom_client_creds: true
  management_endpoint_authentication:
    require_mtls: true
    require_bearer_token: true
    require_software_statement: false
  registration_access_token:
    generate: true
    lifetime: 86400
    scopes:
      - cdr:registration

runtimedb.yml - This file contains the runtime_db and server_connections keys.

# this file contains the runtime db related configurations
runtime_db: db2srv
server_connections:
  - name: db2srv
    type: db2
    database_name: isvaop
    hosts:
      - hostname: db2pri.isvaop.com
        hostport: 50001
      - hostname: db2alt.isvaop.com
        hostport: 50001
    credential:
      username: db2inst1
      password: "OBF:U2FsdGVkX18T/grbo0K8FiJ4DtaTl3EqjRECDQrP/xQ="
    conn_settings:
      min_pool_size: 5
      max_pool_size: 50
      max_idle_time: 10
      connect_timeout: 5
      aged_timeout: 30
    ssl:
      certificate:
        - ks:db2client

session.yml - This file contains the session_cache and server_connections keys.

# this file contains the session cache related configurations
session_cache:
  type: redis
  cfg: redis-standalone
server_connections:
  - name: redis-standalone
    type: redis
    deployment:
      model: standalone
    hosts:
      - hostname: redis.isvaop.com
        hostport: 6390
    credential:
      username: isva
      password: "OBF:U2FsdGVkX18rz1DFhOzHmrG5GKCRQJsEMmTcN/5VxSA="
    ssl:
      certificate:
        - ks:rt_profile
    conn_settings:
      min_idle_size: 5
      idle_timeout: 10
      max_pool_size: 50
      connect_timeout: 5
      io_timeout: 3

ldap.yml - This file contains the server_connections, attribute_sources, and ldapcfg keys.

# this file contains the `server_connection`, `attribute_sources` and `ldapcfg` configuration for the ldap server `ldap_stg`
server_connections:
  - name: ldap_stg
    type: ldap
    hosts:
      - hostname: 192.168.1.232
        hostport: 389
        credential:
          bind_dn: cn=admin,dc=example,dc=org
          bind_password: "OBF:U2FsdGVkX18T/grbo0K8FiJ4DtaTl3EqjRECDQrP/xQ="
        ssl:
          certificate:
            - ks:rt_profile
    conn_settings:
      max_pool_size: 50
      connect_timeout: 3
attribute_sources:
  - id: 1
    name: name
    type: ldap
    value: displayName
    scope: subtree
    filter: (objectclass=*)
    selector: cn,displayName,mail
    srv_conn: ldap_stg
    baseDN: dc=example,dc=org
  - id: 2
    name: preferred_username
    type: ldap
    value: cn
    scope: subtree
    filter: (objectclass=*)
    selector: cn,displayName,mail
    srv_conn: ldap_stg
    baseDN: dc=example,dc=org
ldapcfg:
  - name: ldap_stg_example
    scope: subtree
    user_object_classes: top,Person,organizationalPerson,inetOrgPerson
    filter: (|(|(objectclass=ePerson)(objectclass=person))(objectclass=User))
    selector: objectClass,cn,sn,givenName,userPassword
    srv_conn: ldap_stg
    attribute: uid
    baseDN: dc=example,dc=org
  - name: ldap_stg_ibm
    scope: subtree
    user_object_classes: top,Person,organizationalPerson,inetOrgPerson
    filter: (|(|(objectclass=ePerson)(objectclass=person))(objectclass=User))
    selector: objectClass,cn,sn,givenName,userPassword
    srv_conn: ldap_stg
    attribute: uid
    baseDN: dc=ibm,dc=com

attrsrc_value.yml - This file contains the attribute_sources key.

# this file contains value ldap type attribute sources
attribute_sources:
  - id: 3
    name: company_name
    type: value
    value: IBM
  - id: 4
    name: company_url
    type: value
    value: "https://www.ibm.com"

keystores.yml - This file contains the keystore key.

# this file contains the keystores
keystore:
  - name: ks1
    type: p12
    content: "B64:<encoded_p12>"
    password: "OBF:<obfuscated_p12_password>"
  - name: ks2
    type: pem
    certificate:
      - label: cert01
        content: "B64:<encoded PEM>"
      - label: cert02
        content: "@<file>"
      - label: cert03
        content: |
          <inline PEM>
    key:
      - label: key01
        content: "B64:<encoded PEM>"
      - label: key02
        content: "@<file>"
      - label: key03
        content: |
          <inline PEM>
  - name: ks3
    type: zip
    content: "B64:<encoded zip>"
  - name: ks4
    type: path
    content: "keystore/ks4_contents"

rules.yml - This file contains the rules key.

# this file contains the JavaScript mapping rules and access policy
rules:
  mapping:
    - name: pretoken
      rule_type: javascript # optional, default to javascript
      content: "@<file>"
    - name: posttoken
      content: "B64:<data>"
    - name: cb_notify
      content: |
        <inline JS>
  access_policy:
    - name: default_policy
      content: |
        <inline JS>

clients.yml - This file container the clients key.

# this file defines the static clients
clients:
  - client_id: client01
    client_id_issued_at: 1642399207
    client_secret: secret
    client_name: Test Client 01
    enabled: true
    grant_types:
      - refresh_token
      - urn:openid:params:grant-type:ciba
    token_endpoint_auth_method: private_key_jwt
    token_endpoint_auth_signing_alg: PS256
    token_endpoint_auth_single_use_jti: false
    id_token_signed_response_alg: PS512
    request_object_signing_alg: ES512
    require_pushed_authorization_requests: false
    require_pkce: true
    backchannel_token_delivery_mode: poll
    backchannel_user_code_parameter: false
  - client_id: client01jarm
    client_id_issued_at: 1642399207
    client_secret: "secret"  # ahwouvzsvawraww
    client_name: Client JARM
    enabled: true
    grant_types:
      - password
      - refresh_token
      - authorization_code
      - implicit
    response_types:
      - code
      - token id_token
      - code id_token
      - code id_token token
      - code token
    redirect_uris:
      - https://www.google.com
      - https://isvaop.ibm.com:445
    token_endpoint_auth_method: default
    tls_client_auth_subject_dn: CN=clientID01,OU=security,O=IBM,L=singapore,ST=singapore,C=SG
    tls_client_certificate_bound_access_tokens: false
    id_token_signed_response_alg: none

These separate documents are equivalent to providing the following as a single YAML document:

# this file contains all configurations
version: 23.12
server:
  ssl:
    key: "ks:rt_profile_keys/httpserver"
    certificate: "ks:rt_profile_keys/httpserver"
  pages:
    type: zip
    content: "@pages.zip"
template_macros:
  user_macros:
    - name
    - family_name
    - given_name
    - display_name
  request_macros:
    - authorization_details
    - claims
    - user_code
    - state
logging:
  level: debug
secrets:
  obf_key: "abcdef"
ssl:
  certificate:
    - ks:rt_profile
  disable_hostname_verification: true
authentication:
  endpoint: >-
    https://auth.isvaop.com:445/oauth2/auth
  callback_param_name: Target
javascript:
  timeout: 0
  max_load: 16
  max_idle_time: 600
  max_ctx_in_isolate: 50
  cleanup_frequency: 0
  use_pool: false
definition:
  id: 1
  name: OIDC Definition
  grant_types:
    - authorization_code
    - implicit
    - password
    - client_credentials
    - refresh_token
    - 'urn:openid:params:grant-type:ciba'
  access_policy_id: default_policy
  pre_mappingrule_id: pretoken
  post_mappingrule_id: posttoken
  base_url: 'https://auth.isvaop.com:445'
  mtls_base_url: 'https://auth.isvaop.com:445'
  mtls_certificate_header_name: X-Client-Certificate
  features:
    enable_fault_tolerance: false
    enable_dynamic_registration: true
    consent_prompt: PROMPT_ONCE
    fapi_compliant: false
    enforce_par: false
    prefer_claims_at_userinfo: true
  token_settings:
    issuer: https://www.ibm.com
    signing_alg: PS512
    signing_keystore: rt_profile
    signing_keylabel: rsa256
    authorization_code_lifetime: 300
    access_token_lifetime: 7200
    id_token_lifetime: 3600
    refresh_token_lifetime: 64800
    request_object:
      lifetime: 3600
      require_expiry: true
      only_request_object_params: false
      enforce_single_usage: false
    backchannel_settings:
      default_expiry: 900
      maximum_expiry: 1800
      polling_interval: 5
      notifyuser_mappingrule_id: notifyuser
      checkstatus_mappingrule_id: checkstatus
  attribute_map:
    name: name
    preferred_username: preferred_username
    email: email
  metadata:
    claims_supported:
      - iss
      - name
      - displayName
jwks:
  signing_keystore: rt_profile_keys
  encryption_keystore: rt_profile_keys
dynamic_registration:
  recipe: UK-OB
  mappingrule_id: dcr
  software_statement_validation:
    jwks_uri: >-
      https://isvaop.ibmcloudsecurity.com/oidc/endpoint/default/jwks
    signing_algs:
      - PS256
      - ES256
  registration_endpoint_authentication:
    require_mtls: true
    require_bearer_token: true
    require_software_statement: false
    allow_custom_client_creds: true
  management_endpoint_authentication:
    require_mtls: true
    require_bearer_token: true
    require_software_statement: false
  registration_access_token:
    generate: true
    lifetime: 86400
    scopes:
      - cdr:registration
runtime_db: db2srv
session_cache:
  type: redis
  cfg: redis-standalone
server_connections:
  - name: db2srv
    type: db2
    database_name: isvaop
    hosts:
      - hostname: db2pri.isvaop.com
        hostport: 50001
      - hostname: db2alt.isvaop.com
        hostport: 50001
    credential:
      username: db2inst1
      password: "OBF:U2FsdGVkX18T/grbo0K8FiJ4DtaTl3EqjRECDQrP/xQ="
    conn_settings:
      min_pool_size: 5
      max_pool_size: 50
      max_idle_time: 10
      connect_timeout: 5
      aged_timeout: 30
    ssl:
      certificate:
        - ks:db2client
  - name: redis-standalone
    type: redis
    deployment:
      model: standalone
    hosts:
      - hostname: redis.isvaop.com
        hostport: 6390
    credential:
      username: isva
      password: "OBF:U2FsdGVkX18rz1DFhOzHmrG5GKCRQJsEMmTcN/5VxSA="
    ssl:
      certificate:
        - ks:rt_profile
    conn_settings:
      min_idle_size: 5
      idle_timeout: 10
      max_pool_size: 50
      connect_timeout: 5
      io_timeout: 3
  - name: ldap_stg
    type: ldap
    hosts:
      - hostname: 192.168.1.232
        hostport: 389
        credential:
          bind_dn: cn=admin,dc=example,dc=org
          bind_password: "OBF:U2FsdGVkX18T/grbo0K8FiJ4DtaTl3EqjRECDQrP/xQ="
        ssl:
          certificate:
            - ks:rt_profile
    conn_settings:
      max_pool_size: 50
      connect_timeout: 3
attribute_sources:
  - id: 1
    name: name
    type: ldap
    value: displayName
    scope: subtree
    filter: (|(|(objectclass=ePerson)(objectclass=person))(objectclass=User))
    selector: cn,displayName,mail
    srv_conn: ldap_stg
    baseDN: dc=ibm,dc=com
  - id: 2
    name: preferred_username
    type: ldap
    value: cn
    scope: subtree
    filter: (|(|(objectclass=ePerson)(objectclass=person))(objectclass=User))
    selector: cn,displayName,mail
    srv_conn: ldap_stg
    baseDN: dc=ibm,dc=com
  - id: 3
    name: email
    type: ldap
    value: mail
    scope: subtree
    filter: (|(|(objectclass=ePerson)(objectclass=person))(objectclass=User))
    selector: cn,displayName,mail
    srv_conn: ldap_stg
    baseDN: dc=ibm,dc=com
ldapcfg:
  - name: ldap_stg_example
    scope: subtree
    user_object_classes: top,Person,organizationalPerson,inetOrgPerson
    filter: (|(|(objectclass=ePerson)(objectclass=person))(objectclass=User))
    selector: objectClass,cn,sn,givenName,userPassword
    srv_conn: ldap_stg
    attribute: uid
    baseDN: dc=example,dc=org
  - name: ldap_stg_ibm
    scope: subtree
    user_object_classes: top,Person,organizationalPerson,inetOrgPerson
    filter: (|(|(objectclass=ePerson)(objectclass=person))(objectclass=User))
    selector: objectClass,cn,sn,givenName,userPassword
    srv_conn: ldap_stg
    attribute: uid
    baseDN: dc=ibm,dc=com
keystore:
  - name: ks1
    type: p12
    content: "B64:<encoded_p12>"
    password: "OBF:<obfuscated_p12_password>"
  - name: ks2
    type: pem
    certificate:
      - label: cert01
        content: "B64:<encoded PEM>"
      - label: cert02
        content: "@<file>"
      - label: cert03
        content: |
          <inline PEM>
    key:
      - label: key01
        content: "B64:<encoded PEM>"
      - label: key02
        content: "@<file>"
      - label: key03
        content: |
          <inline PEM>
  - name: ks3
    type: zip
    content: "B64:<encoded zip>"
  - name: ks4
    type: path
    content: "keystore/ks4_contents"
rules:
  mapping:
    - name: pretoken
      rule_type: javascript # optional, default to javascript
      content: "@<file>"
    - name: posttoken
      content: "B64:<data>"
    - name: cb_notify
      content: |
        <inline JS>
  access_policy:
    - name: default_policy
      content: |
        <inline JS>
clients:
  - client_id: client01
    client_id_issued_at: 1642399207
    client_secret: secret
    client_name: Test Client 01
    enabled: true
    grant_types:
      - refresh_token
      - urn:openid:params:grant-type:ciba
    token_endpoint_auth_method: private_key_jwt
    token_endpoint_auth_signing_alg: PS256
    token_endpoint_auth_single_use_jti: false
    id_token_signed_response_alg: PS512
    request_object_signing_alg: ES512
    require_pushed_authorization_requests: false
    require_pkce: true
    backchannel_token_delivery_mode: poll
    backchannel_user_code_parameter: false
  - client_id: client01jarm
    client_id_issued_at: 1642399207
    client_secret: "secret"  # ahwouvzsvawraww
    client_name: Client JARM
    enabled: true
    grant_types:
      - password
      - refresh_token
      - authorization_code
      - implicit
    response_types:
      - code
      - token id_token
      - code id_token
      - code id_token token
      - code token
    redirect_uris:
      - https://www.google.com
      - https://isvaop.ibm.com:445
    token_endpoint_auth_method: default
    tls_client_auth_subject_dn: CN=clientID01,OU=security,O=IBM,L=singapore,ST=singapore,C=SG
    tls_client_certificate_bound_access_tokens: false
    id_token_signed_response_alg: none

Special Types

There are special types which can used in addition to plain text within the YAML file. These special types can be used to substitute values from alternative sources.

TypeSyntax
Keystoreks:<keystore name>
Certificate or keyks:<keystore name>/<certificate or key label>
External File@<file name>
Base 64 DataB64:<base64 encoded string>
Obfuscated (Encrypted with Shared Secret) StringOBF:<obfuscated string>
Encrypted (Encrypted with RSA) StringENC:<encrypted string>

Special Types Available in Kubernetes

In addition to the standard special types, there are Kubernetes specific special types available when ISVAOP is running in a Kubernetes environment.

TypeSyntax
Kubernetes ConfigMapconfigmap:<configmap name>/<configmap field>
Kubernetes Secretsecret:<secret name>/<secret field>

Example Keystore and Certificate

Refer to Key Management for ks: prefix details and example.

Example File Reference

The following example shows how a file reference can be used to source content from an external file. In this example, a rate limiting rule will be loaded from an external file.

The following folder structure is present in the configuration directory /var/isvaop/config:

|-- server
|   `-- redis_stg.yml
`-- session.yml

In this example, server\redis_stg.yml is a simple YAML file with the content:

name: redis_stg
type: redis
deployment:
  model: standalone
hosts:
  - hostname: redis_stg.isvaop.top
    hostport: 6390
credential:
  username:
  password: "OBF:U2FsdGVkX18rz1DFhOzHmrG5GKCRQJsEMmTcN/5VxSA="

In the ISVAOP configuration file session.yml, the content of server\redis_stg.yml is included by specifying "@server\redis_stg.yml" as a value.

session_cache:
  type: redis
  cfg: redis_stg
server_connections:
  - "@server/redis_stg.yml"

This is equivalent to including the text content as-is within the YAML configuration data.

session_cache:
  type: redis
  cfg: redis_stg
server_connections:
  - name: redis_stg
    type: redis
    deployment:
      model: standalone
    hosts:
      - hostname: redis_stg.isvaop.top
        hostport: 6390
    credential:
      username:
      password: "OBF:U2FsdGVkX18rz1DFhOzHmrG5GKCRQJsEMmTcN/5VxSA="

Example Base 64 Data

For some types of data, it is not practical to store these as text within the configuration YAML and in some scenarios it is useful to be able to embed all data within a single configuration YAML document. In these cases, the values can be base 64 encoded and embedded as values within the configuration YAML.

The following example shows how a transformation rule can be embedded in the configuration YAML as base 64 encoded data.

First, generate the base 64 representation of the file. On UNIX-like systems this can be achieved with the base64
command.

$ base64 -w 0 -i default_policy.js
aW1wb3J0Q2xhc3MoUGFja2FnZXMuY29tLnRpdm9s...

In the ISVAOP configuration YAML, this can be placed on a single line preceded by the B64: prefix.

rules:
  access_policy:
    - name: default_policy
      content: "B64:aW1wb3J0Q2xhc3MoUGFja2FnZXMuY29tLnRpdm9s..."

This is equivalent to including the text content as-is within the YAML configuration data.

rules:
  access_policy:
    - name: default_policy
      content: |
        importClass(Packages.com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtils);

        IDMappingExtUtils.traceString("Username: " + context.getUser().getUsername());
        IDMappingExtUtils.traceString("Nonce: " + context.getRequest().getParameter("nonce"));
        IDMappingExtUtils.traceString("Response type: " + context.getProtocolContext().getAuthenticationRequest().getAuthenticationContext().getScope());
        IDMappingExtUtils.traceString("DefinitionName: " + context.getProtocolContext().getDefinitionName());
        IDMappingExtUtils.traceString("ClientName: " + context.getProtocolContext().getClientName());
        ...

Example Obfuscated (Encrypted with Shared Secret) String

Configuration data can also be provided as encrypted entries which are obfuscated using a shared secret/password. The shared secret is provided in the secrets section of the YAML and will be used to decrypt all OBF: prefixed entries found within the configuration YAML.

The following example shows the data p@ssw0rd being encrypted with the shared secret abcdef:

$ echo -n "p@ssw0rd" | openssl enc -aes256 \ 
    -pbkdf2 -pass pass:"abcdef" -md sha512 \
    -base64

Note that OpenSSL 1.1.1 or newer is required for the above command.

This command will produce a base 64 string similar to U2FsdGVkX1+0aFOU6f+0y7k6H6slVT0L7ztjRaHL7Sc=. Note that due to salting, you should expect that this command will produce a different encrypted representation of the input data each time it is executed.

The resulting encrypted base 64 string can be provided to ISVAOP using the OBF: prefix:

runtime_db: db2srv
server_connections:
  - name: db2srv
    type: db2
    database_name: isvaop
    hosts:
      - hostname: db2pri.isvaop.com
        hostport: 50001
    credential:
      username: db2inst1
      password: "OBF:U2FsdGVkX1+0aFOU6f+0y7k6H6slVT0L7ztjRaHL7Sc="

Example Encrypted (Encrypted with RSA) String

Configuration data can also be provided as RSA encrypted entries. The private key required to decrypt the entry is provided in the secrets section of the YAML and will be used to decrypt all ENC: prefixed entries found within the configuration YAML.

To use RSA encryption, generate a private certificate:

$ openssl genrsa -out private.pem 2048

This private certificate will be used to decrypt the entries and must be provided in the configuration YAML. To create encrypted entries, generate a corresponding public key which will be used for the encryption operations:

$ openssl rsa -pubout -in private.pem -out public.pem

The following example shows the data p@ssw0rd being encrypted with the public key public.pem and base64 encoded:

$ echo -n "p@ssw0rd" | openssl rsautl -encrypt -inkey public.pem -pubin | base64

This command will produce a base 64 encoded string. The encrypted base 64 encoded string can be provided to ISVAOP using the ENC: prefix:

runtime_db: db2srv
server_connections:
  - name: db2srv
    type: db2
    database_name: isvaop
    hosts:
      - hostname: db2pri.isvaop.com
        hostport: 50001
    credential:
      username: db2inst1
      password: "ENC:L2qQGwwPFqLzUK3..."

Example Kubernetes ConfigMap

The Kubernetes ConfigMap type can be used to directly reference a field from a particular ConfigMap within the ISVAOP configuration YAML. During bootstrapping, the ISVAOP container will use the Kubernetes REST API endpoints to retrieve the ConfigMap and substitute the value into the configuration YAML.

Consider the following ConfigMap named access-policy containing the fields default_policy_name, default_policy_type and default_policy.js:

kind: ConfigMap
apiVersion: v1
metadata:
  name: access-policy
  namespace: isvaop
data:
  default_policy.js: >
    importClass(Packages.com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtils);

    IDMappingExtUtils.traceString("Username: " +
    context.getUser().getUsername());
    ...
  default_policy_name: default_policy
  default_policy_type: javascript

To reference these values within the configuration YAML, use the syntax for the Kubernetes ConfigMap type:

rules:
  access_policy:
    - name: "configmap:access-policy/default_policy_name"
      type: "configmap:access-policy/default_policy_type"
      content: "configmap:access-policy/default_policy.js"

During bootstrapping, ISVAOP will retrieve the ConfigMap and substitute it into the configuration YAML:

rules:
  access_policy:
    - name: default_policy
      type: javascript
      content: |
        importClass(Packages.com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtils);

        IDMappingExtUtils.traceString("Username: " +
        context.getUser().getUsername());
        ...

Example Kubernetes Secret

The Kubernetes Secret type can be used to directly reference a field from a particular secret within the ISVAOP configuration YAML. During bootstrapping, the ISVAOP container will use the Kubernetes REST API endpoints to retrieve the secret and substitute the secret value into the configuration YAML.

Consider the following secret named storage containing the
fields db2srv_dbname, db2srv_hostname, db2srv_hostport, db2srv_username, and db2srv_password:

kind: Secret
apiVersion: v1
metadata:
  name: storage
  namespace: isvaop
data:
  db2srv_dbname: aXN2YW9w
  db2srv_hostname: ZGIyc3J2LmlzdmFvcC5jb20=
  db2srv_hostport: NTAwMDE=
  db2srv_username: ZGIyaW5zdDE=
  db2srv_password: YWRtaW4=
type: Opaque

To reference these values within the configuration YAML, use the syntax for the Kubernetes Secret type:

runtime_db: db2srv
server_connections:
  - name: db2srv
    type: db2
    database_name: secret:storage/db2srv_dbname
    hosts:
      - hostname: secret:storage/db2srv_hostname
        hostport: secret:storage/db2srv_hostport
    credential:
      username: secret:storage/db2srv_username
      password: secret:storage/db2srv_password

During bootstrapping, ISVAOP will retrieve the secret, base64 decode the data and substitute it into the configuration
YAML:

runtime_db: db2srv
server_connections:
  - name: db2srv
    type: db2
    database_name: isvaop
    hosts:
      - hostname: db2srv.isvaop.com
        hostport: 50001
    credential:
      username: db2inst1
      password: admin

Effective configuration

With the configuration split across multiple documents, we have introduced an environemnt variable to retrieve the effective configuration that will be used by the ISVAOP container. The effective configuration is essentially one YAML document with all the configuration combined together.

To enable accessing the YAML document set DEBUG_SAVE_EFFECTIVE_CONFIG_AS_FILE to true.

Once the contianer restarts, it will log the location of the YAML document. You can then use a terminal to access the effective config.

Example log

[03/23/2023 03:41:07.021 UTC] (internal.config.saveEffectiveConfigAsFile) I [CORR_ID-870f0857-66a0-42c0-be69-7e9f3e4ea324] "Environment variable DEBUG_SAVE_EFFECTIVE_CONFIG_AS_FILE is set to 'true', save effective configurations to file '/isvaop/config/7751bb5e-0090-40ae-b743-838c23b7444c/EffectiveConfig.yml'"

📘

Note

The effective configuration document may contain sensitive information, we recommend that DEBUG_SAVE_EFFECTIVE_CONFIG_AS_FILE is set to true only in
staging environment.

Updated 6 months ago