Appliance Configuration

This module contains documentation for system level configuration applicable for Appliance (VM) based Verify Identity Access deployments. Container configuration is defined under the container top level key. At a minimum an administrator should define the isva_base_url, isva_admin_user and isva_admin_password keys (or define the applicable environment variables).

Example

appliance:
  admin_cfg:
    session_timeout: 720
  activation: #Module activation codes
    webseal: !environment IVIA_BASE_CODE
    access_control: !environment IVIA_AAC_CODE
    federation: !environment IVIA_FED_CODE
  network:
    routes:
    - enabled: True
      comment: "Default route"
      address: "default"
      gateway: "192.168.42.1"
      interface: "1.1"
    interfaces:
    - label: "1.1"
      comment: "Default Interface"
      enabled: True
      ipv4:
        dhcp:
          enabled: False
          allow_management: False
          provides_default_route: False
        addresses:
        - address: "192.168.42.101"
          mask_or_prefix: "24"
          broadcast_address: "192.168.42.255"
          allow_management: True
          enabled: True
        - address: "192.168.42.102"
          mask_or_prefix: "24"
          broadcast_address: "192.168.42.255"
          allow_management: False
          enabled: True
      ipv6:
        dhcp:
          enabled: False
          allowManagement: False
    dns:
      auto: False
      primary_server: "9.9.9.9"

Appliance specific configuration

This section covers the configuration options which are only available on appliance or Virtual Machine deployments of Verify Identity Access.

The base configurator is responsible for completing the first steps (SLA), activating licensed modules, importing PKI and system wide settings like date/time/networking.

SLA / First steps

The configurator can be used to accept the Service License Agreement as well as the “first steps” LMI prompts, including enabling FIPS compliance. This is always done with the admin account using the default password. Failing this step does not result in autoconfig aborting.

src.ibmvia_autoconf.configure.IVIA_Configurator.accept_eula(self)
src.ibmvia_autoconf.configure.IVIA_Configurator.complete_setup(self)

Password update

The password of the management account may be updated once. This account must already exist on the appliance and have sufficient permission to complete all of the configuration required.

class src.ibmvia_autoconf.configure.IVIA_Configurator.Admin_Password

Example:

mgmt_user: 'administrator'
mgmt_pwd: 'S3cr37Pa55w0rd!'
mgmt_old_pwd: 'administrator'

Note

These properties are overridden by IVIA_MGMT_* environment variables

mgmt_old_pwd: str

Password to update for the Administrator user.

mgmt_pwd: str

Secret to authenticate as the Administrator user.

mgmt_user: str

Administrator user to run configuration as.

Administrator Configuration

System wide settings such as LMI log file configuration, account management and advanced tuning parameters.

To set system administrator settings use the admin_config key. A complete list of the available configuration properties can be found here. An example configuration is:

class src.ibmvia_autoconf.configure.IVIA_Configurator.Admin_Config

Examples:

admin_cfg:
  session_timeout: 7200
  sshd_client_alive: 300
  console_log_level: "AUDIT"
  accept_client_certs: true

The complete list of properties that can be set by this key can be found in the pyivia documentation.

accept_client_certs: bool | None

A boolean value which is used to control whether SSL client certificates are accepted by the local management interface. By default SSL client certificates are accepted.

access_log_fmt: str | None

The template string to use for the LMI access.log file. If not set the access log is disabled (default).

console_log_level: str | None

The console messaging level of the LMI (valid values include INFO, AUDIT, WARNING, ERROR and OFF). A default value of OFF is used.

enabled_server_protocols: int | None

TLS, TLSv1, TLSv1.1 and TLSv1.2.

Type:

Specifies which secure protocols will be accepted when connecting to the LMI. The supported options include

enabled_tls: List[str] | None

List of Enabled TLS protocols for the local management interface. Valid values include TLSv1, TLSv1.1 and TLSv1.2.

exclude_csrf_checking: str | None

A comma-separated string which lists the users for which CSRF checking should be disabled. Regular expressions are accepted, and any embedded commas should be escaped with the “ character. This option is required if you wish to access a Web service, using client certificates for authentication, from a non-browser based client. An example might be cn=scott,o=ibm,c=us,cn=admin,o=dummyCorp,c=*.

http_port: int | None

The TCP port on which the LMI will listen.

http_proxy: str | None

The proxy <host>:<port> to be used for HTTP communication from the LMI. The port component is optional and will default to 80.

https_port: int | None

The SSL port on which the LMI will listen. A default value of 443 is used.

https_proxy: str | None

The proxy <host>:<port> to be used for HTTPS communication from the LMI. The port component is optional and will default to 443.

lmi_debugging_enabled: bool | None

A boolean value which is used to control whether LMI debugging is enabled or not. By default debugging is disabled.

lmi_msg_timeout: int | None

This is a timeout (in seconds) for notification messages that appear in the LMI. A value of 0 indicates that the messages should not timeout. The default value is 5 seconds.

log_max_files: int | None

The maximum number of log files that are retained. The default value is 2.

log_max_size: int | None

The maximum size (in MB) that a log file can grow to before it is rolled over. The default value is 20

login_header: str | None

This is a customizable header that is displayed when accessing the login page in a web browser and after logging in via SSH. Multiple lines of text can be specified by using the sequence “n”, which will be interpreted as a line break.

login_msg: str | None

This is a customizable message that is displayed when accessing the login page in a web browser and after logging in via SSH. Multiple lines of text can be specified by using the sequence “n”, which will be interpreted as a line break.

max_heap_size: int | None

The minimum heap size, in megabytes, for the JVM.

max_pool_size: int | None

The maximum number of connections for the connection pool. The default value is 100.

max_threads: int | None

The maximum number of threads which will handle LMI requests. A default value of 6 is used.

min_heap_size: int | None

The minimum heap size, in megabytes, for the JVM.

min_threads: int | None

The minimum number of threads which will handle LMI requests. A default value of 6 is used.

session_inactive_timeout: int | None

The length of time, in minutes, that a session can remain idle before it is deleted (valid values = -1 - 720). A default value of 30 is used. A value of -1 disables the inactivity timeout.

session_timeout: int | None

The length of time, in minutes, that a session can remain idle before it is deleted (valid values``0 - 720``). A default value of 120 is used.

sshd_client_alive: int | None

The number of seconds that the server will wait before sending a null packet to the client. A value of -1 means using the default timeout settings.

sshd_port: int | None

The port on which the SSH daemon will listen. A default value of 22 is used. Please note that if using the appliance clustering capability all nodes in the cluster must be configured to use the same port for the SSH daemon.

swap_size: int | None

The amount of allocated swap space, in Megabytes. There must be enough disk space on the active partition to store the swap file, otherwise an error will be logged in the system log file and the default amount of swap space will be used. (only present in the response if a value has been set).

valid_verify_domains: str | None

This is a space separated list of valid domains for IBM Security Verify. These domains are used by the IBM Security Verify wizard to ensure that only valid hostnames are used.

validate_client_cert_identity: bool | None

The console messaging level of the LMI (valid values include INFO, AUDIT, WARNING, ERROR and OFF). A default value of OFF is used.

SSL Certificate database

X509 Certificates and PCKS12 key-files can be imported into Verify Identity Access SSL databases. The structure of this configuration option is to specify a yaml list of SSL databases. Each entry in the list has three keys: database name; personal certificates; and signer certificates. If a database does not exist on the appliance then it is created before files are imported.

SSL certificates are imported into the appliance by reading files from the file system. Therefore any PKI which is to be imported into the appliance must specify the fully-qualified path or be a path relative to the IVIA_CONFIG_BASE environment variable. A complete list of the available configuration properties can be found here. An example configuration is:

class src.ibmvia_autoconf.configure.IVIA_Configurator.SSL_Certificates

Example:

ssl_certificates:
- name: "lmi_trust_store"
  personal_certificates:
  - path: "ssl/lmi_trust_store/personal.p12"
    secret: "S3cr37"
  signer_certificates:
  - "ssl/lmi_trust_store/signer.pem"
- name: "rt_profile_keys"
  signer_certificates:
  - "ssl/rt_profile_keys/signer.pem"
- kdb_file: "my_keystore.kdb"
  stash_file: "my_keystore.sth"
class Load_Certificate
label: str

Name of retrieved X509 certificate alias in SSL database.

port: int

Port Web service is listening on.

server: str

Domain name or address of web service.

class Personal_Certificate
path: str

Path to file to import as a personal certificate.

secret: str | None

Optional secret to decrypt personal certificate.

kdb_file: str | None

Path to the .kdb file to import as a SSL database. Required if importing a SSL KDB.

load_certificates: List[Load_Certificate] | None

Load X509 certificates from a TCPS endpoints.

name: str | None

Name of SSL database to configure. If database does not exist it will be created. Either name or kdb_file must be defined.

personal_certificates: List[Personal_Certificate] | None

List of file paths for personal certificates (PKCS#12) to import.

signer_certificates: List[str] | None

List of file paths for signer certificates (PEM or DER) to import.

stash_file: str | None

Path to the .sth file for the specified kdb_file. Required if kdb_file is set.

Administrator Account Management

Administrator accounts, groups and permissions for managing Verify Identity Access features can be defined in two configuration entries. The first entry allows for the creation of users and groups which can be used to authenticate to the management interface. A complete list of the available configuration properties can be found here. An example configuration is:

class src.ibmvia_autoconf.configure.IVIA_Configurator.Account_Management

Example:

account_management:
  users:
  - name: !secret default/isva-secrets:cfgsvc_user
    operation: "update"
    password: !secret default/isva-secrets:cfgsvc_secret
    groups:
    - "aGroup"
    - "anotherGroup"
 groups:
 - name: "adminGroup"
   operation: "update"
   users:
   - "admin"
   - "anotherUser"
class Management_Group

Note

Groups are created before users; therefore if a user is being created and added to a group then this should be done in the user configuration entry.

id: str

Name of group to create.

operation: str

Operation to perform with group. add | update | delete.

users: List[str] | None

Optional list of users to add to group.

class Management_User
groups: List[str] | None

Optional list of groups to add user to.

name: str

Name of the user to create, remove or update.

operation: str

Operation to perform with user. add | update | delete.

password: str | None

Password to authenticate as user. Required if creating user.

groups: List[Management_Group] | None

Optional list of management groups to configure.

users: List[Management_User] | None

Optional list of management users to configure

Management Authorization

Administrators are also able to manage access to Verify Identity Access features. This allows for more fine grained control over which accounts are permitted to modify a deployment. Administrators are not able to create new features, however they can create “roles” which contains permissions for one or more features. Each feature in a role has two permission levels: read access (can view but cannot modify); and write access (permission to modify). A complete list of the available configuration properties can be found here. An example configuration is:

class src.ibmvia_autoconf.configure.IVIA_Configurator.Management_Authorization

Example:

management_authorization:
  authorization_enforcement: True
  roles:
  - operation: update
    name: "Configuration Service"
    users:
    - name: "cfgsvc"
      type: "local"
    features:
    - name: "shared_volume"
      access: "w"
class Role
class Feature
access: str

Access to grant to feature. r | w.

name: str

Name of feature.

class Group
name: str

name of group.

type: str

Type of group. local | remote.

class User
name: str

Name of user

type: str

Type of user. local | remote.

features: List[Feature]

List of features to authorize users / groups for.

groups: List[Group] | None

Optional list of groups to add to role.

name: str

Name of role.

operation: str

Operation to perform on authorization role. add | remove | update.

users: List[User] | None

Optional list of users to add to role.

authorization_enforcement: bool

Enable role based authorization for this deployment.

roles: List[Role] | None

Optional list of roles to modify for role based authorization.

Management Authentication

Administrators are able to configure how users are able to authenticate to the Verify Identity Access management interface. By default the management interface uses a local user registry, but administrators can configure a LDAP server or integrate a third party identity provider using the OIDC specification.

class src.ibmvia_autoconf.configure.IVIA_Configurator.Management_Authentication

Example:

management_authentication:
  auth_type: "federation"
  oidc:
    client_id: "27d55f1c-285a-11ef-81ec-14755ba358db"
    client_secret: "SDFGc3ffFSD3m4Xtg1"
    discovery_endpoint: "https://verify.ibm.com/.well-known/openid-configuration"
    require_pkce: true
    enable_admin_group: false
    enable_tokenmapping: false
class LDAP
admin_group_dn: str

Specifies the DN of the group to which all administrative users must belong.

anon_bind: bool

Specifies whether the LDAP user registry supports anonymous bind. If set to false, bind_dn and bind_password are required.

base_dn: str

Specifies the base DN which is used to house all administrative users.

bind_dn: str | None

Specifies the DN of the user which will be used to bind to the registry. This user must have read access to the directory. This parameter is required if anon_bind is false

bind_password: str | None

Specifies the password which is associated with the bind_dn. This parameter is required if anon_bind is false.

cert_label: str

Specifies the name of the certificate within the Key database that is used if client authentication is requested by the LDAP server.

debug: bool

Specifies whether the capturing of LDAP debugging information is enabled or not.

enable_ssh_pubkey_auth: bool | None

Specifies whether or not users in the LDAP server can log in via SSH using SSH public key authentication. If this value is not provided, it will default to false.

enable_usermapping: bool

Specifies whether mapping of the incoming client certificate DN is enabled.

group_member_attribute: str

Specifies the name of the LDAP attribute which is used to hold the members of a group.

host: str

Specifies the name of the LDAP server.

key_database: str

Specifies the name of the key database file (without any path information). This parameter is required if ssl is true

port: str

Specifies the port over which to communicate with the LDAP server.

ssh_pubkey_auth_attribute: str

Specifies the name of the LDAP attribute which contains a user’s public key data. This field is required if SSH public key authentication is enabled.

ssl: bool

Specifies whether SSL is used when the system communicates with the LDAP server.

user_attribute: str

Specifies the name of the LDAP attribute which holds the supplied authentication user name of the user.

usermapping_script: str

Specifies the javascript script that will map the incoming client certificate DN. The script will be passed a Map containing the certificate dn, rdns, principal, cert, san and the user_attribute, group_member_attribute and base_dn from this configuration. If not specified a default script is used. Only valid if enable_usermapping is true.

class OIDC
admin_group: str | None

The name of the group which a user must be a member of to be considered an administrator user. The default value is adminGroup.

client_id: str

The OIDC Client Identifier.

client_secret: str

The OIDC Client Secret.

discovery_endpoint: str

The OIDC Discovery (well-known) endpoint.

enable_admin_group: bool

Specifies whether a user must be a member of a particular group to be considered an administrator user.

enable_pkce: bool

Specifies whether the Public key Code Exchange extension is enforced.

enable_tokenmapping: bool

Specifies whether custom claim to identity mapping is performed using a JavaScript code fragment.

group_claim: str | None

The OIDC token claim to use as group membership. This claim can either be a String, or a list of Strings. The default value is groupIds.

keystore: str | None

The SSL Truststore to verify connections the the OIDC OP. The default value if lmi_trust_store.

tokenmapping_script: str

The custom JavaScript code fragment to map an identity token to a username/group membership.

user_claim: str | None

Specifies the OIDC token claim to use as the username. The default value is sub.

auth_type: str

Specifies whether the local user database or the remote LDAP user registry is used for authentication. If this parameter is set to local, then all other fields are ignored. Valid values include local, federation and remote.

ldap: LDAP | None

LDAP specific configuration properties. Only one of LDAP or OIDC should be defined

oidc: OIDC | None

OIDC specific configuration properties. Only one of LDAP or OIDC should be defined

Module Activation

License files to activate the Advanced Access Control, Federation and WebSEAL Reverse Proxy modules are imported in this step. Subsequent module configuration is dependant on one or more of these licenses being applied to an appliance or container. An example configuration is:

class src.ibmvia_autoconf.configure.IVIA_Configurator.Module_Activations

Example:

activation:
  webseal: "example"
  access_control: !secret verify-access/isva-secrets:access_control_code
  federation: !environment ISVA_ACCESS_CONTROL_CODE


activation:
  trial_license: issued/trial.pem
access_control: str | None

License code for the Advanced Access Control module.

federation: str | None

License for the Federations module.

trial_license: str | None

//isva-trial.verify.ibm.com/

Type:

Trial license file issued from https

webseal: str | None

License code for the WebSEAL Reverse Proxy module.

Advanced tuning parameters

Advanced Tuning Parameters can be set on an appliance to configure additional settings not exposed by the LMI. Any required advanced tuning parameters for your deployment will be communicated to you via support. An example configuration is:

class src.ibmvia_autoconf.configure.IVIA_Configurator.Advanced_Tuning_Parameter

Example:

advanced_tuning_parameters:
- name: "wga.rte.embedded.ldap.ssl.port"
  value: 636
- name: "password.policy"
  value: "minlen=8 dcredit=1 ucredit=1 lcredit=1"
  description: "Enforced PAM password quality for management accounts."
description: str | None

optional description of the Advanced Tuning Parameter.

name: str

Name of the Advanced Tuning Parameter.

operation: str

Operation which should be performed on advanced tuning parameter. Valid values include add | delete | update.

value: str

Value of the Advanced Tuning Parameter.

Configuration Snapshots

A snapshot can be applied to both Container and Appliance deployments to restore a previous configuration state. This is done via a signed archive file, generated by the deployment you are trying to preserve / re-create.

class src.ibmvia_autoconf.configure.IVIA_Configurator.Snapshot

Example:

snapshot: "snapshot/isva-2023-02-08.snapshot"
snapshot: str

Path to signed snapshot archive file.

Extensions

Extensions are used to install third party applications, such as platform monitoring tools, onto a Verify Identity Access appliance. An extension consists of: - A signed installation package from IBM Security Verify Identity Access App-Xchange - Some configuration properties in key/value format - Optionally, additional binaries (RPM, ZIP, ect) required by the extension.

The specific properties required to install an extension will change based on the type of extension being installed. Administrators can use a Web Browser to inspect HTTP requests when uploading an extension to a Verify Identity Access appliance to determine which properties are required for their particular extension.

class src.ibmvia_autoconf.configure.IVIA_Configurator.Extensions

Example:

extensions:
- extension: "Instana/instana.ext"
  third_party_packages:
  - "Instana/agent.rpm"
  properties:
    extId: "instanaAgent"
    instanaAgentKey: !environment INSTANA_AGENT_KEY
    instanaHost: !environment INSTANA_HOST
    instanaPort: 443
    mvnRepositoryUrl: "https://artifact-public.instana.io"
    mvnRepositoryFeaturesPath: "artifactory/features-public@id=features@snapshots@snapshotsUpdate=never"
    mvnRepositorySharedPath: "artifactory/shared@id=shared@snapshots@snapshotsUpdate=never"
extension: str

The signed extension file to be installed on Verify Identity Access.

properties: dict | None

Key-Value properties to give the extension during the installation process. This list of properties will vary with the type of extension being installed.

third_party_packages: str | None

An optional list of third party packages to be uploaded to Verify Identity Access as part of the installation process.

Remote Syslog

The remote system logging capabilities of Verify Identity Access deployments can be configured with this option. Administrators are able to define external servers where logs for Verify Identity Access sub-components should be forwarded to.

class src.ibmvia_autoconf.configure.IVIA_Configurator.Remote_Syslog

Example:

remote_syslog:
- server: "127.12.7.1"
  port: 514
  debug: False
  protocol: "udp"
  sources:
  - name: "WebSEAL:ISAM:request.log"
    tag: "isva-dev"
    facility: "local0"
    severity: "debug"
  - name: "Runtime Messages"
    tag: "isva-dev"
    facility: "syslog"
    severity: "info"
class Forwarder
facility: str

The syslog facility which will be used when sending messages to the remote syslog server. Valid values include kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, security, ftp, ntp, logaudit, logalert, clock, local0, local1, local2, local3, local4, local5, local6 and local7.

name: str

The name of the log file source. The list of available source names can be retrieved via the source_names Web service.

severity: int

The syslog severity which will be used when sending messages to the remote syslog server. Valid values include emerg, alert, crit, error, warning, notice, info and debug.

tag: str

The tag to be used to designate the messages which originate from this source. This tag will be prepended to all messages that are sent to the remote syslog server.

ca_certificate: str | None

The label which is used to identify within the SSL key file the CA certificate of the remote syslog server. This option is required if the protocol is tls.

client_certificate: str | None

The label which is used to identify within the SSL key file the client certificate which will be used during mutual authentication with the remote syslog server.

debug: bool

Whether the forwarder process will be started in debug mode. All trace messages will be sent to the log file of the remote syslog forwarder.

format: str | None

The format of the messages which are forwarded to the rsyslog server. Valid options include rfc-3164 and rfc-5424. Default value is rfc-3164

keyfile: str | None

The name of the key file which contains the SSL certificates used when communicating with the remote syslog server (e.g. pdsrv). This option is required if the protocol is tls.

permitted_peers: str | None

The subject DN of the remote syslog server. If this policy data is not specified any certificates which have been signed by the CA will be accepted.

port: int

The port on which the remote syslog server is listening.

protocol: str

The protocol which will be used when communicating with the remote syslog server. Valid values include udp, tcp and tls.

server: str

The IP address or host name of the remote syslog server.

sources: List[Forwarder]

The source of the log file entries which will be sent to the remote syslog server.

FIPS Compliance

Verify Identity Access can be configured to FIPS compliance when required. FIPS compliance can only be enabled on new (unconfigured) appliances and should be enabled before any other configuration options are applied.

class src.ibmvia_autoconf.configure.IVIA_Configurator.FIPS

Example:

fips:
  fips_enabled: True
  tls_v10_enabled: False
  tls_v11_enabled: False
fips_enabled: bool

Enable FIPS 140-2 Mode.

tls_v10_enabled: bool

Allow TLS v1.0 for LMI sessions.

tls_v11_enabled: bool

Allow TLS v1.1 for LMI sessions

Networking

The networking settings can be used to define networking routes, as well as interface address, netmask and gateway setting on a Verify Identity Access appliance. This configuration is also able to add hostfile entries as well as setting the hostname of Verify Identity Access. Care must be taken when configuring network interfaces to ensure that the interface used to configure the appliance is not changed (as this will result in the automation tool failing).

Note

Interfaces can only be updated using the LMI, they cannot be created.

class src.ibmvia_autoconf.appliance.Appliance_Configurator.Networking

Example:

network:
  hostname: "isam.myidp.ibm.com"
  host_file:
  - address: "192.168.42.102"
    hosts:
    - "www.myidp.ibm.com"
  - address: "192.168.42.101"
    hosts:
    - "isam.myidp.ibm.com"
  routes:
  - enabled: true
    address: "default"
    gateway: "192.168.42.1"
    interface: "1.1"
    metric: 0
    table: "main"
    comment: "Example route"
  interfaces:
  - ipv4:
      dhcp:
        enabled: false
    addresses:
    - address": "192.168.42.101"
      mask_or_prefix: "255.255.255.0"
      broadcast_address: "192.168.42.10"
      allow_mgmt: true
      enabled: true
    - address: "192.168.42.102"
      mask_or_prefix: "/24"
      broadcast_address: "192.168.42.10"
      allow_mgmt: false
      enabled: true
class DNS
auto: bool

true if DNS should be auto configured via dhcp.

auto_from_interface: str | None

Name or ID of interface whose dhcp will defined the dns settings.

primary_server: str | None

Primary DNS Server address.

search_domains: str | None

Comma-separated list of DNS search domains.

secondary_server: str | None

Secondary DNS Server address.

tertiary_server: str | None

Tertiary DNS Server address.

class HostEntry
address: str

IPv4 address to add for hosts.

hosts: List[str]

List of host names or domain names to add.

class Interface
class IPv4
class IPv4Address
address: str

IPv4 address to assign to interface.

allow_mgmt: bool

Use this address for the Local Management Interface.

broadcast_address: str

IPv4 address to use for broadcasting.

enabled: bool

Enable this address.

mask_or_prefix: str

IPv4 netmask or prefix to assign to address.

class IPv4DHCP
allow_mgmt: bool

Use a DHCP address for the Local Management Interface.

default_route: bool

Use DHCP to determine the default network route.

enabled: bool

Enable DHCP on this interface.

route_metric: int

Route metric.

addresses: List[IPv4Address] | None

Static IPv4 addresses assigned to an interface.

dhcp: IPv4DHCP | None

DHCP configuration for an interface.

comment: str

Comment to add to interface.

enabled: str

Enable this interface.

ipv4: IPv4

IPv4 settings.

label: str

System assigned label of interface.

vlan_id: str | None

System assigned vlan ID.

class Route
address: str

Network address to use for route.

comment: str | None

Optional comment to add to route.

enabled: bool

Enable this route.

gateway: str

Network gateway to use for route.

interface: str

Interface this route is attached to.

maks_or_prefix: str

Network bitmask or prefix to use for route.

metric: int

Route metric.

table: int

Route table.

dns: DNS | None

Domain Name Server settings for appliance

host_file: List[HostEntry] | None

Entries to add to an appliance’s hosts file.

hostname: str | None

Hostname to set for the Verify Identity Access appliance.

interfaces: List[Interface]

List of properties for attached interfaces.

routes: List[Route] | None

Optional list of routes to add to an interface.

Date / Time settings

The date and time settings can be adjusted on a Verify Identity Access appliance or synchronized to a external NTP server. Admins are also able to set the time zone of the appliance using canonical name.

To set the Date/Time configuration using either a NTP server or manually setting the date via a formatted string. A complete list of the available configuration properties can be found here. An example configuration is:

class src.ibmvia_autoconf.appliance.Appliance_Configurator.Date_Time

Example:

date_time:
  enable_ntp: true
  ntp_servers:
  - "time.ibm.com,192.168.0.1"
  time_zone: "Australia/Brisbane"
date_time: str | None

The current date and time, in the format YYYY-MM-DD HH:mm:ss

enable_ntp: bool

Enable Network Time Protocol synchronization.

ntp_servers: List[str] | None

List of hostnames or addresses to use as NTP servers.

time_zone: str

The id of the timezone the appliance is operating in.

Cluster Configuration

The cluster configuration options can be used to add additional servers to the Verify Identity Identity Access deployment. Currently only

external databases (HVDB and config) as well as Verify Identity Identity Access HA servers are supported.

This option is typically used in a container deployment to configure the HVDB connection. A complete list of the available configuration properties can be found here.

Note

PKI required to connect to any servers should be imported in the previous step.

class src.ibmvia_autoconf.appliance.Appliance_Configurator.Cluster_Configuration

Example:

cluster:
  config_db:
    address: "127.0.10.1"
    port: 1234
    username: "database_user"
    password: "database_password"
    ssl: True
    ssl_keystore: "lmi_trust_store.kdb"
    db_name: "isva_config"
  runtime_db:
    address: "postgresql"
    port: 5432
    type: "Postgresql"
    user: "postgres"
    password: !secret verify-access/isva-secrets:postgres-passwd
    ssl: False
    db_name: "isva_hvdb"
  cluster:
    sig_file: "cluster/signature_file"
    primary_master: "isva.primary.master"
    secondary_master: "isva.secondary.master"
    nodes:
    - "isva.node"
    restricted_nodes:
    - "isva.restricted.node"
class Cluster
nodes: List[str] | None

Verify Identity Access appliance designated as nodes.

primary_master: str

Verify Identity Access appliance designated as the primary master node.

restricted_nodes: List[str] | None

Verify Identity Access appliance designated as the restricted nodes.

secondary_master: str | None

Verify Identity Access appliance designated as the secondary master node.

sig_file: str

Signature file generated by the primary master; used to add nodes to the cluster.

class Database
db_name: str

Name of the database instance to use.

extra_config: dict | None

Database type specific configuration.

host: str

Hostname or address of database.

password: str

Password to authenticate as username.

port: str

Port database is listening on.

ssl: bool

Enable SSL encryption of connections.

ssl_keystore: str | None

SSL database to use to verify connections. Only valid if ssl == true.

type: str

Database type. “postgresql” | “db2” | “oracle”.

user: str

Username to authenticate to database as.

cluster: Cluster | None

Configuration for Verify Identity Access High Availability cluster nodes.

config_database: Database | None

Configuration for the config database.

runtime_database: Database | None

Configuration for the runtime (HVDB) database.

Managed Containers

The managed containers properties allows administrators to deploy IBM containerize products to IBM Verify Identity Access appliances. This is particularly useful for administrators with hardware based appliances, allowing them to deploy a greater range of IBM products with their existing hardware.

class src.ibmvia_autoconf.appliance.Appliance_Configurator.Managed_Containers

Example:

managed_containers:
  volumes:
  - name: "iag-config"
    archive: iag.zip
  images:
  - "icr.io/isva/verify-access-oidc-provider:23.03"
  registries:
  - host: "icr.io"
    proxy:
      host: "proxy.ibm.com"
      port: 3128
  deployments:
  - name: "IAG Deployment"
    image: "icr.io/isva/verify-access-oidc-provider:23.03"
    type: "iag"
    ports:
    - name: "https"
      value: "192.168.42.102:30443"
    volumes:
    - name: "config"
      value: "iag-config"
    env:
    - name: "LOG_FORMAT"
      value: "JSON"
class Deployment
class EnvProperties
name: str

Name of environment variable to create.

value: str

Value of environment variable.

class LoggingProperties
max_files: int | None

The maximum number of roll-over log files to keep. If a value is not specified, the default of 10 (10 files) will be used.

max_size: int | None

The maximum size of a log file, in megabytes, before it will be rolled over. If a value is not specified, the default of 10 (10MB) will be used.

class PortProperties
name: str

Name of the Metadata port mapping being forwarded to the host appliance.

value: str

Host port to map to. This can optionally include an interface address, eg. 192.168.42.201:30443

class VolumeProperties
name: str

Name of Metadata volume mount point.

value: str

Name or ID of the volume being mounted.

args: List[str] | None

An optional list of arguments to pass to the specified command.

command: str | None

An optional command from the metadata document to run instead of the container entrypoint.

env: List[EnvProperties]

Container environment variable properties.

image: str

Container image to use.

logging: LoggingProperties | None

Container logfile rollover properties.

name: str

Name of the container deployment.

ports: List[PortProperties]

Mapping between container ports and host ports.

type: str

Container deployment metadata type.

volumes: List[VolumeProperties]

Container volume mount properties.

class Registry
host: str

Domain or IP address of container registry.

proxy: Proxy | None

Proxy configuration for pulling images.

secret: str

Secret to authenticate to the container registry as user

user: str

User to authenticate to container registry as

class Volume
archive: str

Zip archive of volume contents.

name: str

Name of volume to be created/updated.

deployments: List[Deployment] | None

List of managed container deployments to create.

images: List[str] | None

List of image to be pulled. This should include registry and tag information, eg. icr.io/isva/verify-access-oidc-provider:23.03

registries: List[Registry] | None

List of container registry authentication/proxy configuration to apply.

volumes: List[Volume] | None

List of volumes to be created or updated.

Global Configuration

These configuration properties are common to the Access Control and Federation modules. You must have at least one of these modules activated in order to set these configuration properties.

The global configuration section documents configuration which is shared between the Access Control and Federation modules of Verify Identity Access. This includes Advanced Configuration Properties, HTTP template pages, JavaScript mapping rules, Point of Contact profiles, Access Policies and Server Connections.

Access Policies

Access policies can be applied to the deployment types:

  • SAML 2.0 identity provider federation

  • SAML 2.0 service provider partner to an identity provider federation

  • OpenID Connect and API Protection Definition

class src.ibmvia_autoconf.federation.FED_Configurator.Access_Policies

Example:

access_policies:
- name: "MyNewAccessPolicy"
  type: "JavaScript"
  policy_file: "path/to/policy.file"
  category: "OTP"
category: str | None

A grouping of related access polices. For example, category “OAUTH” identifies all the rules associated with the OAUTH flow. Maximum 256 bytes. Valid values are “InfoMap”, “AuthSVC”, “OAUTH”,”OTP”, “OIDC” and “SAML2_0”.

name: str

A unique name for the access policy. Maximum of 256 bytes.

policy_file: str

A file with the JavaScript content of the access policy.

type: str | None

System default type for each access policy. For example, “JavaScript”.

Attribute Sources

Identity attribute sources for federated identities.

class src.ibmvia_autoconf.federation.FED_Configurator.Attribute_Sources

Example:

attribute_sources:
- name: "username"
  type: "credential"
  value: "PrincipalName"
  properties:
  - key: "searchFilter"
    value: "(&(ObjectClass=inetOrgPerson)(memberOf=dc=ibm,dc=com))"
class Attribute_Source
class Property
key: str

The property key. Valid fields for LDAP include “serverConnection”, “scope”, “selector”, “searchFilter”, “baseDN”.

value: str

The property value.

name: str

The friendly name of the source attribute. It must be unique.

properties: List[Property] | None

The properties associated with an attribute source.

type: str

The type of the attribute source. Valid types are:

  • “credential”: The attribute is from the authenticated context.

  • “value”: The attribute is plain text from the value parameter.

  • “ldap”: The attribute is retrieved from an LDAP server.

value: str

The value of the source attribute. Credential type: The name of a credential attribute from the authenticated context which contains the value. Value type: The plain text to be used as the source attribute value. LDAP type: The name of the LDAP attribute to be used.

attribute_sources: List[Attribute_Source]

List of attribute sources to create or update.

Advanced Configuration Parameters

The Advanced Configuration Parameters entry is used to set module wide properties for authentication and authorization components. The list of available properties is dependant on the target version of Verify Identity Access being configured. Administrators are able to use the Verify Identity Access assigned identifier or the name of the property.

class src.ibmvia_autoconf.access_control.AAC_Configurator.Advanced_Configuration

Example:

advanced_configuration:
- name: "attributeCollection.authenticationContextAttributes"
  value: "resource,action,ac.uuid,header:userAgent,urn:ibm:demo:transferamount"
- name: "mmfa.transactionArchival.maxPendingPerUser"
  value: "1"
id: int | None

The Verify Identity Access assigned property id. Either the property ID or name must be defined.

name: str | None

The name of the advanced configuration property. Either the property ID or name must be defined.

value: str

The updated value of the advanced configuration property.

HTTP Template Files

This configuration option can be used to set files or directories containing HTML files which are compatible with the AAC and Federation templating engine. The directory structure of any directories to upload should follow the default top level directories. If you are defining a directory it should contain a trailing /.

class src.ibmvia_autoconf.access_control.AAC_Configurator.Template_Files

Example:

template_files:
- aac/isva_template_files.zip
- login.html
- 2fa.html
template_files: List[str]

List of files or zip-files to upload as HTML template pages. Path to files can be relative to the IVIA_CONFIG_BASE property or fully-qualified file paths.

JavaScript Mapping Rules

This configuration option can be used to upload different types or categories of JavaScript Mapping Rules. These rules are typically used to implement custom business logic for a particular integration requirement.

Note

Some types of mapping rules are defined elsewhere, eg OIDC pre/post token mapping rules must be defined with the OIDC definition they are associated with.

class src.ibmvia_autoconf.access_control.AAC_Configurator.Mapping_Rules

Examples:

mapping_rules:
- type: SAML2
  files:
  - saml20.js
  - adv_saml20.js
- type: InfoMap
  files:
   - mapping_rules/basic_user_email_otp.js
   - mapping_rules/basic_user_sms_otp.js
   - mapping_rules/ad_user_mfa.js
- type: Fido2
  files:
   - mediator.js
class Mapping_Rule
files: List[str]

List of files or directories to upload as JavaScript mapping rules. Path to files can be relative to the IVIA_CONFIG_BASE property or fully-qualified file paths.

type: str

Type of JavaScript rule to create. Valid values include InfoMap, AuthSVC, FIDO2, OAUTH, OTP, OIDC and SAML2_0.

mapping_rules: List[Mapping_Rule]

List of mapping rule types/files to upload.

Point Of Contact

The point of contact profile is used to control how the runtime server communicates with the point of contact server (usually WebSEAL).

class src.ibmvia_autoconf.federation.FED_Configurator.Point_Of_Contact_Profiles

Example:

point_of_contact:
  profiles:
  - name: "MyPoCProfile"
    description: "MyPoCProfile description"
    authenticate_callbacks:
    - index: 0
      module_reference_id: "websealPocAuthenticateCallback"
      parameters:
      - name: "authentication.level"
        value: "1"
    sign_in_callbacks:
    - index": 0
      module_reference_id: "websealPocSignInCallback"
      parameters:
      - name: "fim.user.response.header.name"
            value: "am-fim-eai-user-id"
    local_id_callbacks:
    - index: 0
      module_reference_id: "websealPocLocalIdentityCallback"
      parameters:
      - name: "fim.cred.request.header.name"
        value: "iv-creds"
    sign_out_callbacks:
    - index: 0
      module_reference_id: "websealPocSignOutCallback"
      parameters:
      - name: "fim.user.session.id.request.header.name"
            value: "user_session_id"
    authn_policy_callbacks:
    - index: 0
      module_reference_id: "genericPocAuthnPolicyCallback"
      parameters:
      - name: "authentication.level"
        value: "1"
class Point_Of_Contact_Profile
class Point_Of_Contact_Callback
class Point_Of_Contact_Parameter
name: str

The name of the parameter.

value: str

The value of the parameter.

index: int

A number reflects the position in the callbacks array.

module_reference_id: str

The module ID referenced in the callback. It must be one of the supported module IDs.

parameters: List[Point_Of_Contact_Parameter] | None

The parameters used by the callback.

authenticate_callbacks: List[Point_Of_Contact_Callback] | None

An array of callbacks for authentication.

authn_policy_callbacks: List[Point_Of_Contact_Callback] | None

An array of callbacks for authentication policy.

description: str | None

A description of the point of contact profile.

local_id_callbacks: List[Point_Of_Contact_Callback] | None

An array of callbacks for local identity.

name: str

A meaningful name to identify this point of contact profile.

sign_in_callbacks: List[Point_Of_Contact_Callback] | None

An array of callbacks for sign in.

sign_out_callbacks: List[Point_Of_Contact_Callback] | None

An array of callbacks for sign out.

active_profile: str

The name of the Point of Contact profile which should be the active profile. Only one profile can be active at a time.

profiles: List[Point_Of_Contact_Profile]

List of point of contact profiles to configure

Server Connections

Server connections are used to connect to third party infrastructure such as LDAP registries, email servers, SMS servers, ect. These connections are used by other AAC components to provide authentication/authorization services.

class src.ibmvia_autoconf.access_control.AAC_Configurator.Server_Connections

Example:

server_connections:
- name: "intent-svc"
  type: "web_service"
  description: "A connection to the intent service."
  properties:
    url: "http://ibmsec.intent.svc:16080"
    user: ""
    password: ""
    ssl: false
- name: "Cloud Identity tenant connection"
  type: "ci"
  description: "A connection to the companion CI Tenant."
  properties:
    ci_tenant: !secret default/isva-secrets:ci_tenant
    ci_client_id: !secret default/isva-secrets:ci_client_id
    ci_client_secret: !secret default/isva-secrets:ci_client_secret
    ssl_truststore: "rt_profile_keys.kdb"
- name: "Local LDAP connection"
  type: "ldap"
  description: "A connection to this ISAMs LDAP."
  locked: false
  properties:
    hostname: ibmsec.ldap.domain
    port: 636
    bind_dn: "cn=root,secAuthority=Default"
    bind_password: !secret default/isva-secrets:ldap_bind_secret
    ssl: true
    ssl_truststore: "lmi_trust_store"
  - name: "SCIM web service connection"
    type: "web_service"
    description: "A connection to this ISAMs SCIM server."
    locked: false
    properties:
      url: https://ibmsec.runtime.svc
      user: !secret default/isva-secrets:runtime_user
      password: !secret default/isva-secrets:runtime_secret
      ssl: true
      key_file: "rt_profile_keys.kdb"
class Server_Connection
class IbmsecVerifyConnection

ci

admin_host: str

The IBM Security Verify administration host to connect to.

authenticators_endpoint: str | None

The versioned endpoint for authenticator requests.

authnmethods_endpoint: str | None

The DEPRECATED versioned endpoint for authentication method requests.

authorize_endpoint: str | None

The versioned endpoint for authorization requests.

client_id: str

The client ID to authenticate to the IBM Security Verify tenant.

client_secret: str

The client secret to authenticate to the IBM Security Verify tenant.

factors_endpoint: str | None

The versioned endpoint for factors requests.

ssl: bool

Controls whether SSL is used to establish the connection.

ssl_key_label: str | None

The name of the key which should be used during mutual authentication with the web server.

ssl_truststore: str | None

The key database to be used as an SSL truststore. This field is required when ssl is true.

user_endpoint: str | None

The versioned endpoint for user requests.

class Java_Database_Connection

jdbc

age_timeout: int | None

Amount of time before a physical connection can be discarded by pool maintenance. A value of -1 disables this timeout. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds. (Default value is -1)

connection_purge_policy: str | None

Specifies which connections to destroy when a stale connection is detected in a pool. Valid values include EntirePool (When a stale connection is detected, all connections in the pool are marked stale, and when no longer in use, are closed.) FailingConnectionOnly (When a stale connection is detected, only the connection which was found to be bad is closed.) ValidateAllConnections (When a stale connection is detected, connections are tested and those found to be bad are closed.) (Default value is EntirePool)

connection_reap_time: str | None

Amount of time between runs of the pool maintenance thread. A value of “-1” disables pool maintenance. Default value is 3m.

connection_timeout: int | None

Amount of time after which a connection request times out. A value of -1 disables this timeout. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds. (Default value is 30s)

connections_per_thread: int | None

Caches the specified number of connections for each thread.

database_name: str | None

The name of the database to connect to. Only applicable for DB2 and PostgreSQL connections, this parameter is required for all DB2 and PostgreSQL connections.

max_connections_per_thread: int | None

Limits the number of open connections on each thread.

max_idle_time: int | None

Amount of time after which an unused or idle connection can be discarded during pool maintenance, if doing so does not reduce the pool below the minimum size. A value of -1 disables this timeout. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds. (Default value is 30m)

max_pool_size: int | None

Maximum number of physical connections for a pool. A value of 0 means unlimited. (Default value is 50)

min_pool_size: int | None

Minimum number of physical connections to maintain in the pool. The pool is not pre-populated. Aged timeout can override the minimum.

password: str

The password used to to authenticate with the database.

port: int

The port that the database is listening on.

server_name: str

The IP address or hostname of the database.

service_name: str | None

The name of the database service to connect to. Only applicable for Oracle connection, this parameter is required for all Oracle connections.

ssl: bool

Controls whether SSL is used to establish the connection.

type: str | None

The Oracle JDBC driver type. Valid types are thin and oci. Only applicable for Oracle connection, this parameter is required for all Oracle connections.

user: str

The user name used to to authenticate with the database.

class LDAPConnection

ldap

class Server
connection: dict

The connection properties. This dictionary uses the properties from LDAPConnection.

order: int

The order of precedence for this server.

bind_dn: str

The distinguished name to use to bind to the LDAP server.

bind_password: str

The password for bindDN to use when binding to the LDAP server.

hostname: str

The IP address or hostname of the LDAP server.

key_file: str

The key database to be used as an SSL truststore.

key_label: str

The name of the key which should be used during mutual authentication with the LDAP server.

port: int

The port that the LDAP server is listening on.

servers: List[Server] | None

Additional LDAP servers for this connection.

ssl: bool

Controls whether SSL is used to establish the connection.

timeout: int | None

Amount of time, in seconds, after which a connection to the LDAP server times out.

class RedisConnection

redis

class Server
hostname: str

The IP address or hostname of the Redis server.

port: str

The port that the Redis server is listening on.

connection_timeout: int | None

Amount of time, in seconds, after which a connection to the Redis server times out.

deployment_model: str

The Redis deployment model. Valid values are standalone and sentinel.

hostname: str | None

The IP address or hostname of the Redis server. This is only required if the deployment_model is set as standalone.

idle_timeout: int | None

Amount of time, in seconds, after which an established connection will be discarded as idle.

io_timeout: int | None

Amount of time, in seconds, after which the connection socket will timeout.

master_name: str

The key used in the redis sentinel node to store the master/slave configuration.

max_idle_size: int | None

The maximum number of idle connections in the pool.

max_pool_size: int | None

Number of connections which will be pooled.

min_pool_size: int | None

The minimum number of idle connections in the pool.

password: str | None

The password used to to authenticate with the Redis server.

port: int

The port that the Redis server is listening on.

servers: List[Server] | None

Additional Redis servers for this connection.

ssl: bool

Controls whether SSL is used to establish the connection.

ssl_key_label: str | None

The key database to be used as an SSL keystore. Only required if ssl is set to true.

ssl_truststore: str | None

The key database to be used as an SSL truststore. Only required if ssl is set to true.

user: str | None

The user name to authenticate to the Redis server.

class SMTPConnection

smtp

hostname: str

The IP address or hostname of the SMTP server.

password: str | None

The password used to to authenticate with the SMTP server.

port: int

The port that the SMTP server is listening on.

ssl: bool

Controls whether SSL is used to establish the connection.

timeout: int | None

Amount of time, in seconds, after which a connection to the SMTP server times out.

user: str | None

The user name to authenticate to the SMTP server.

class VerifyAccessRuntimeConnection

isamruntime

bind_dn: str

The distinguished name to use to bind to the Verify Identity Access Runtime LDAP server.

bind_pwd: str

The password for bindDN to use when binding to the Verify Identity Access Runtime LDAP server.

ssl: bool

Controls whether SSL is used to establish the connection.

ssl_key_label: str | None

The name of the key which should be used during mutual authentication with the Verify Identity Access runtime LDAP server.

ssl_truststore: str | None

The key database to be used as an SSL truststore. This field is required when ssl is true.

class WebServiceConnection

ws

key_file: str | None

The key database to be used as an SSL truststore. This field is required when ssl is true.

key_label: str | None

The name of the key which should be used during mutual authentication with the web server.

password: str

The password used to to authenticate with the web service.

ssl: bool

Controls whether SSL is used to establish the connection.

url: str

The fully qualified URL of the web service endpoint, including the protocol, host/IP, port and path.

user: str

The user name to authenticate to the web service.

description: str | None

A description of the connection.

locked: bool | None

Controls whether the connection is allowed to be deleted. If not present, a default of false will be assumed.

name: str

The name of the connection.

properties: IbmsecVerifyConnection | Java_Database_Connection | RedisConnection | LDAPConnection | SMTPConnection | VerifyAccessRuntimeConnection | WebServiceConnection

Connection specific properties.

type: str

ci, ldap, isamruntime, oracle, db2, soliddb, psotgresql, smtp and ws.

Type:

The type of server connection. Valid types are

connections: List[Server_Connection]

List of server connections to create or update. Properties of individual connections are described in the _Connection subclasses.

Runtime Server Configuration

This property can be used to configure the runtime liberty server. This includes: configuring trace; managing endpoints/interfaces that the runtime server can respond to requests; setting server configuration parameters (such as proxy settings, SSL configuration); and defining users in the runtime user registry.

class src.ibmvia_autoconf.access_control.AAC_Configurator.Runtime_Configuration

Example:

runtime_properties:
  users:
  - name: "easuser"
    password: !secret default/isva-secrets:runtime_password
    groups:
    - "scimAdmin"
    - "fidoAdmin"
  tuning_parameters:
  - name: "https_proxy_host"
    value: "http://my.proxy"
  - name: "https_proxy_port"
    value: "3128"
  endpoints:
  - interface: "1.1"
    address: "192.168.42.102"
    port: 444
    ssl: true
  - interface: "1.2"
    dhcp4: true
    dhcp6: false
    port: 443
    ssl: true
class Endpoint
address: str | None

The static address that the runtime endpoint will listen on.

dhcp4: bool | None

Endpoint should listen on the DHCP IPv4 address for the given interface.

dhcp6: bool | None

Endpoint should listen on the DHCP IPv6 address for the given interface.

interface: str

The interface the runtime endpoint will listen on.

port: int

Port that endpoint will listen on.

ssl: bool

Endpoint should use SSL encryption for connections.

class Group
name: str

Name of the group to create or update.

users: List[str] | None

List of users to add to the group.

class Runtime_Tuning_Parameter
name: str

The tuning parameter to set.

value: str

The new value for the specified parameter.

class User
groups: List[str] | None

A list of groups the new user will belong to.

name: str

Name of the user to create or update.

password: str

The password for the new user. This can contain any ASCII characters.

endpoints: List[Endpoint] | None

List of http(s) endpoints that the AAC/Federation runtime is listenting on.

groups: List[Group] | None

List of groups to add/update in the AAC/Federation runtime user registry

trace: str | None

Set the runtime trace specification in Liberty.

tuning_parameters: List[Runtime_Tuning_Parameter] | None

List of AAC/Federation runtime JVM tuning parameters.

users: List[User] | None

List of users to add/update in the AAC/Federation runtime user registry. Users are created before groups, so if you are creating a user and a group in the same autoconf; then only add you user to the list of users when creating the group.