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.