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.
Note
The accept_eula and complete_setup functions are used internally during first-time setup.
Password Update
Admin Password Configuration
Type: objectThe 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. These properties are overridden by IVIA_MGMT_* environment variables
mgmt_user: admin
mgmt_pwd: S3cr37Pa55w0rd!
mgmt_old_pwd: administrator
Administrator user to run configuration as.
Secret to authenticate as the Administrator user.
Password to update for the Administrator user.
Administrator Configuration
System wide settings such as LMI log file configuration, account management and tuning parameters for the LMI JVM.
admin_cfg:
session_timeout: 7200
sshd_client_alive: 300
console_log_level: AUDIT
accept_client_certs: true
The minimum heap size, in megabytes, for the JVM.
Value must be greater or equal to 1
The minimum heap size, in megabytes, for the JVM.
Value must be greater or equal to 1
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.
Value must be greater or equal to 0 and lesser or equal to 720
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.
Value must be greater or equal to -1 and lesser or equal to 720
The TCP port on which the LMI will listen.
Value must be greater or equal to 1 and lesser or equal to 65535
The SSL port on which the LMI will listen. A default value of 443 is used.
Value must be greater or equal to 1 and lesser or equal to 65535
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.
Value must be greater or equal to 1 and lesser or equal to 65535
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.
Value must be greater or equal to -1
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).
Value must be greater or equal to 0
The minimum number of threads which will handle LMI requests. A default value of 6 is used.
Value must be greater or equal to 1
The maximum number of threads which will handle LMI requests. A default value of 6 is used.
Value must be greater or equal to 1
The maximum number of connections for the connection pool. The default value is 100.
Value must be greater or equal to 1
A boolean value which is used to control whether LMI debugging is enabled or not. By default debugging is disabled.
The console messaging level of the LMI (valid values include INFO, AUDIT, WARNING, ERROR and OFF). A default value of OFF is used.
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=*.
Specifies which secure protocols will be accepted when connecting to the LMI. The supported options include: TLS, TLSv1, TLSv1.1 and TLSv1.2.
List of Enabled TLS protocols for the local management interface. Valid values include TLSv1, TLSv1.1 and TLSv1.2.
No Additional ItemsEach item of this array must be:
Must be one of:
- "TLSv1"
- "TLSv1.1"
- "TLSv1.2"
- "TLSv1.3"
The console messaging level of the LMI (valid values include INFO, AUDIT, WARNING, ERROR and OFF). A default value of OFF is used.
Must be one of:
- "INFO"
- "AUDIT"
- "WARNING"
- "ERROR"
- "OFF"
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.
The maximum number of log files that are retained. The default value is 2.
Value must be greater or equal to 1
The maximum size (in MB) that a log file can grow to before it is rolled over. The default value is 20
Value must be greater or equal to 1
The proxy <host>:<port> to be used for HTTP communication from the LMI. The port component is optional and will default to 80.
Must match regular expression:^[^:]+(:d+)?$
The proxy <host>:<port> to be used for HTTPS communication from the LMI. The port component is optional and will default to 443.
Must match regular expression:^[^:]+(:d+)?$
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.
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.
The template string to use for the LMI access.log file. If not set the access log is disabled (default).
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.
Value must be greater or equal to 0
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.
SSL Certificate Database
X509 Certificates and PCKS12 key-files to be imported into Verify Identity Access SSL databases. Each entry in the list can have four keys: database name; personal certificates; certificates loaded from URL's; and signer certificates. Alternatively a SSL Certifiacte Datbase can be imported from a .kdb and corresponding .sth file. 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.
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
Name of SSL database to configure. If database does not exist it will be created. Either name or kdb_file must be defined.
Path to the .kdb file to import as a SSL database. Required if importing a SSL KDB.
Must match regular expression:.*\.kdb$
Path to the .sth file for the specified kdbfile. Required if kdbfile is set.
Must match regular expression:.*\.sth$
List of file paths for signer certificates (PEM or DER) to import.
No Additional ItemsEach item of this array must be:
Must match regular expression:
.*\.(pem|der|crt|cer)$
List of file paths for personal certificates (PKCS#12) to import.
No Additional ItemsEach item of this array must be:
Optional label to include when importing the certificate. If this is not present the CN X.500 attribute is used.
Path to PKCS12 file to import as a personal certificate/key.
Must match regular expression:.*\.(p12|pfx)$
Optional secret to decrypt personal certificate.
Load X509 certificates from TCPS endpoints.
No Additional ItemsEach item of this array must be:
Domain name or address of web service.
Port Web service is listening on.
Value must be greater or equal to 1 and lesser or equal to 65535
Name of retrieved X509 certificate alias in SSL database.
Administrator Account Management
Administrator accounts, groups for the local management interface. 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.
account_management:
users:
- name: cfgsvc
operation: update
password: StrongPassword
groups:
- aGroup
- anotherGroup
groups:
- name: adminGroup
operation: update
users:
- admin
- anotherUser
Optional list of management users to configure
No Additional ItemsEach item of this array must be:
Operation to perform with user. add | update | delete.
Must be one of:
- "add"
- "update"
- "delete"
Name of the user to create, remove or update.
Password to authenticate as user. Required if creating user.
Optional list of groups to add user to.
No Additional ItemsEach item of this array must be:
Optional list of management groups to configure.
No Additional ItemsEach item of this array must be:
Operation to perform with group. add | update | delete.
Must be one of:
- "add"
- "update"
- "delete"
Name of group to create.
Optional list of users to add to group.
No Additional ItemsEach item of this array must be:
Management Authentication
Configure how users 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.
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
Specifies whether the local user database or the remote LDAP user registry is used for authentication. If set to 'local', then all other fields are ignored.
Must be one of:
- "local"
- "federation"
- "remote"
LDAP specific configuration properties. Only one of LDAP or OIDC should be defined.
Specifies the name of the LDAP server.
Specifies the port over which to communicate with the LDAP server.
Specifies whether SSL is used when the system communicates with the LDAP server.
Specifies the name of the key database file (without any path information). This parameter is required if 'ssl' is 'true'
Specifies the name of the certificate within the Key database that is used if client authentication is requested by the LDAP server.
Specifies the name of the LDAP attribute which holds the supplied authentication user name of the user.
Specifies the name of the LDAP attribute which is used to hold the members of a group.
Specifies the base DN which is used to house all administrative users.
Specifies the DN of the group to which all administrative users must belong.
Specifies whether the LDAP user registry supports anonymous bind. If set to false, 'binddn' and 'bindpassword' are required.
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'
Specifies the password which is associated with the binddn. This parameter is required if anonbind is 'false'.
Specifies whether the capturing of LDAP debugging information is enabled or not.
Specifies whether mapping of the incoming client certificate DN is enabled.
Specifies the javascript script that will map the incoming client certificate DN. Only valid if 'enable_usermapping' is true.
Specifies whether or not users in the LDAP server can log in via SSH using SSH public key authentication. Defaults to false.
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.
OIDC specific configuration properties. Only one of LDAP or OIDC should be defined.
The OIDC Client Identifier.
The OIDC Client Secret.
The OIDC Discovery (well-known) endpoint.
Specifies whether the Public key Code Exchange extension is enforced.
Specifies whether a user must be a member of a particular group to be considered an administrator user.
The OIDC token claim to use as group membership. This claim can either be a String, or a list of Strings.
The name of the group which a user must be a member of to be considered an administrator user.
Specifies the OIDC token claim to use as the username.
The SSL Truststore to verify connections to the OIDC OP.
Specifies whether custom claim to identity mapping is performed using a JavaScript code fragment.
The custom JavaScript code fragment to map an identity token to a username/group membership. Only valid if 'enable_tokenmapping' is 'true'.
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 dependent on one or more of these licenses being applied to a deployment.
activation:
webseal: base_activation_code
access_control: aac_activation_code
federation: fed_activation_code
activation:
trial_license: issued/trial.pem
Trial license file issued from https://isva-trial.verify.ibm.com/
Must match regular expression:.*\.pem$
License code for the WebSEAL Reverse Proxy module.
License code for the Advanced Access Control module.
License for the Federations 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 IBM support.
No Additional ItemsEach item of this array must be:
Name of the Advanced Tuning Parameter.
Value of the Advanced Tuning Parameter.
Optional description of the Advanced Tuning Parameter.
Operation which should be performed on advanced tuning parameter.
Must be one of:
- "add"
- "delete"
- "update"
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.
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.
snapshot: snapshots/isva-2023-02-08.snapshot
Path to the signed snapshot archive file to apply.
Must match regular expression:.*\.snapshot$
Extensions
Extensions are used to install third party applications, such as platform monitoring tools, on a Verify Identity Access deployment.
An extension consists of:
- A signed installation package from IBM Security Verify Identity Access App-Xchange
- Optional configuration properties
- Additional binaries 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.
No Additional ItemsEach item of this array must be:
An extension package to install on Verify Identity Access.
The signed extension file to be installed on Verify Identity Access.
Must match regular expression:.*\.(ext|zip)$
An optional list of third party packages to be uploaded to Verify Identity Access as part of the installation process.
No Additional ItemsEach item of this array must be:
Key-Value properties to give the extension during the installation process. This list of properties will vary with the type of extension being installed.
Additional Properties of any type are allowed.
Type: objectextensions:
- extension: Instana/instana.ext
third_party_packages:
- Instana/agent.rpm
properties:
extId: instanaAgent
instanaAgentKey: api_key_goes_here
instanaHost: ingress-orange-saas.instana.io
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
Remote Syslog
The remote system logging capabilities of Verify Identity Access deployments. Administrators are able to define external servers where logs for Verify Identity Access sub-components should be forwarded to.
No Additional ItemsEach item of this array must be:
The hostname or IP address of the remote syslog server.
The port number on which the remote syslog server is listening.
Value must be greater or equal to 1 and lesser or equal to 65535
Enable debug logging for the syslog forwarder.
The protocol to use for forwarding logs.
Must be one of:
- "tcp"
- "udp"
- "tls"
The format of the syslog messages.
Must be one of:
- "rfc3164"
- "rfc5424"
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'.
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'.
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.
List of permitted peer names for TLS certificate validation.
No Additional ItemsEach item of this array must be:
List of log sources (forwarders) to configure for this syslog server.
No Additional ItemsEach item of this array must be:
Name of the log source/forwarder.
Tag to identify the source in syslog messages.
Syslog facility level.
Must be one of:
- "kern"
- "user"
- "mail"
- "daemon"
- "auth"
- "syslog"
- "lpr"
- "news"
- "uucp"
- "cron"
- "authpriv"
- "ftp"
- "local0"
- "local1"
- "local2"
- "local3"
- "local4"
- "local5"
- "local6"
- "local7"
Minimum severity level to forward.
Must be one of:
- "emerg"
- "alert"
- "crit"
- "err"
- "warning"
- "notice"
- "info"
- "debug"
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
Managment Certificate
Management Interface Certificate Configuration
Type: objectUpdate the Local Management Interface (LMI) SSL certificate and key. This certificate is used to secure HTTPS connections to the management interface.
lmi_certificate:
p12: ssl/lmi_certificate.p12
password: S3cr37Pa55w0rd!
Path to the PKCS12 file containing the LMI certificate and private key.
Must match regular expression:.*\.p12$
Password to decrypt the PKCS12 file.
FIPS Compliance
Verify Identity Access can be configured to FIPS compliance when required. FIPS compliance can only be enabled on new (unconfigured) deployments and should be enabled before any other configuration options are applied.
fips:
fips_enabled: true
tls_v10_enabled: false
tls_v11_enabled: false
Enable FIPS 140-2 Mode.
Allow TLS v1.0 for LMI sessions.
Allow TLS v1.1 for LMI sessions.
Networking
Note
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
Network interfaces can only be updated, they cannot be created.
Configuration for network interfaces, routes, DNS, host file entries, and hostname on IBM Verify Access appliances. 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).
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
Hostname to set for the Verify Identity Access appliance.
Entries to add to an appliance's hosts file.
No Additional ItemsEach item of this array must be:
A host file entry mapping an IP address to hostnames.
IPv4 address to add for hosts.
List of host names or domain names to add.
Must contain a minimum of 1 items
Each item of this array must be:
Optional list of routes to add to an interface.
No Additional ItemsEach item of this array must be:
A static network route configuration.
Enable this route.
Interface this route is attached to.
Optional comment to add to route.
Network address to use for route.
Network gateway to use for route.
Network bitmask or prefix to use for route.
Route metric.
Value must be greater or equal to 0
Route table.
List of properties for attached interfaces.
No Additional ItemsEach item of this array must be:
Network interface configuration.
System assigned label of interface.
Name of the interface.
Comment to add to interface.
Enable this interface.
System assigned vlan ID.
Bonding mode for the interface.
Interface this is bonded to.
IPv4 settings.
DHCP configuration for an interface.
Enable DHCP on this interface.
Use a DHCP address for the Local Management Interface.
Use DHCP to determine the default network route.
Route metric.
Value must be greater or equal to 0
Static IPv4 addresses assigned to an interface.
No Additional ItemsEach item of this array must be:
A static IPv4 address configuration.
IPv4 address to assign to interface.
IPv4 netmask or prefix to assign to address.
IPv4 address to use for broadcasting.
Use this address for the Local Management Interface.
Enable this address.
Domain Name Server settings for appliance.
true if DNS should be auto configured via dhcp.
Name or ID of interface whose dhcp will defined the dns settings.
Primary DNS Server address.
Secondary DNS Server address.
Tertiary DNS Server address.
Comma-separated list of DNS search domains.
Date / Time settings
Configuration for date, time, timezone, and NTP settings on IBM Verify Access appliances. The date and time settings can be synchronized to a external NTP server, or set to a time-zone using canonical names.
date_time:
enable_ntp: true
ntp_servers:
- time.ibm.com
- 192.168.0.1
time_zone: Australia/Brisbane
Enable Network Time Protocol synchronization.
List of hostnames or addresses to use as NTP servers.
No Additional ItemsEach item of this array must be:
The id of the timezone the appliance is operating in.
The current date and time, in the format 'YYYY-MM-DD HH:mm:ss'.
Must match regular expression:^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
Cluster Configuration
Note
PKI required to connect to any servers should be defined in the the ssl_certificates property.
Configuration for high availability clustering; as well as defining external configuration and runtime database connection properties.
cluster:
config_database:
type: postgresql
host: 127.0.10.1
port: 1234
user: database_user
password: database_password
ssl: true
ssl_keystore: lmi_trust_store.kdb
db_name: isva_config
runtime_database:
type: postgresql
host: postgresql
port: 5432
user: postgres
password: database_password or !secret macro
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
Configuration for the config database.
Database type.
Must be one of:
- "postgresql"
- "db2"
- "oracle"
Hostname or address of database.
Port database is listening on.
Value must be greater or equal to 1 and lesser or equal to 65535
Enable SSL encryption of connections.
SSL database to use to verify connections. Only valid if ssl == true.
Username to authenticate to database as.
Password to authenticate as username.
Name of the database instance to use.
Database type specific configuration.
Additional Properties of any type are allowed.
Type: objectConfiguration for Verify Identity Access High Availability cluster nodes.
Signature file generated by the primary master; used to add nodes to the cluster.
Verify Identity Access appliance designated as the primary master node.
Verify Identity Access appliance designated as the secondary master node.
Verify Identity Access appliance designated as nodes.
No Additional ItemsEach item of this array must be:
Verify Identity Access appliance designated as the restricted nodes.
No Additional ItemsEach item of this array must be:
Configuration for the Verify Identity Access Distributed Session Cache.
A flag indicating whether clients that are external to the cluster will need to use the DSC.
The port over which DSC communication will take place. This parameter is required if external_clients is set to true.
Value must be greater or equal to 1 and lesser or equal to 65535
A flag indicating whether or not SSL should be used when communicating with the DSC. This parameter is required if external_clients is set to true.
The keyfile that will house the SSL certificates used by the DSC. This parameter is required if use_ssl is set to true.
The name of the SSL certificate that will be presented to clients. This parameter is optional and can only be set if ssl_keyfile is set.
Comma separated list of SSL ciphers permitted for use in TLS connections to the DSC. Valid values include: "RSAWITHSHA224", "RSAWITHSHA256", "RSAWITHSHA384", "RSAWITHSHA512", "ECDSAWITHSHA224", "ECDSAWITHSHA256", "ECDSAWITHSHA384", and "ECDSAWITHSHA512".
Comma separated list of TLS 1.2 cipher specs permitted for use in TLS connections to the DSC.
Comma separated list of TLS 1.3 cipher specs permitted for use in TLS connections to the DSC.
The number of worker threads that will be used.
The maximum lifetime of sessions within the DSC.
The maximum number of sessions to return when a "listSessions" request is made to the DSC. Note this may have an impact on performance.
When a client is shut down we give the client a grace period (in seconds) to restart and register an interest in a session again before we remove the session from the session cache. This will give the client a chance to restart without losing sessions from the server. The value specified here should be similar to the idle timeout value for the session.
The maximum length of time that a connection from a client can remain idle before it is closed by the server. A value of 0 indicates that connections will not be reused. The default value is 0.
Managed Containers
The managed containers feature allows administrators to deploy IBM containerized products to IBM Verify Identity Access appliances. This is useful for administrators with hardware based appliances, allowing them to deploy a greater range of IBM products with their existing hardware.
managed_containers:
volumes:
- name: iag-config
archive: iag.zip
images:
- icr.io/isva/verify-access-oidc-provider:23.03
- icr.io/ibmappgateway/ibm-application-gateway:22.07.0
registries:
- host: icr.io
proxy:
host: proxy.ibm.com
port: 3128
deployments:
- name: IAG Deployment
image: icr.io/ibmappgateway/ibm-application-gateway:22.07.0
type: ibm-application-gateway
ports:
- name: https
value: 192.168.42.102:30443
volumes:
- name: config
value: iag-config
env:
- name: LOG_FORMAT
value: JSON
List of volumes to be created or updated.
No Additional ItemsEach item of this array must be:
A container volume configuration.
Name of volume to be created/updated.
Zip archive of volume contents.
List of image to be pulled. This should include registry and tag information, eg. 'icr.io/isva/verify-access-oidc-provider:23.03'
No Additional ItemsEach item of this array must be:
List of container registry authentication/proxy configuration to apply.
No Additional ItemsEach item of this array must be:
Container registry configuration.
Domain or IP address of container registry.
User to authenticate to container registry as.
Secret to authenticate to the container registry as user.
Proxy configuration for pulling images.
Host name or address of proxy.
Port request should be proxied to.
Value must be greater or equal to 1 and lesser or equal to 65535
Username to (basic) authenticate to the proxy with.
Secret to (basic) authenticate to the proxy with.
TCP schema to communicate with proxy. Default is 'http://'.
Must be one of:
- "http://"
- "https://"
Path to a X509 Certificate bundle to use as the Certificate Authority when pulling images from this registry.
List of managed container deployments to create.
No Additional ItemsEach item of this array must be:
A managed container deployment configuration.
Name of the container deployment.
Container image to use.
Container deployment metadata type.
Mapping between container ports and host ports.
No Additional ItemsEach item of this array must be:
Port mapping configuration.
Name of the Metadata port mapping being forwarded to the host appliance.
Host port to map to. This can optionally include an interface address, eg. '192.168.42.201:30443'.
Container volume mount properties.
No Additional ItemsEach item of this array must be:
Volume mount configuration.
Name of Metadata volume mount point.
Name or ID of the volume being mounted.
Container environment variable properties.
No Additional ItemsEach item of this array must be:
Environment variable configuration.
Name of environment variable to create.
Value of environment variable.
Container logfile rollover properties.
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.
Value must be greater or equal to 1
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.
Value must be greater or equal to 1
An optional command from the metadata document to run instead of the container entrypoint.
An optional list of arguments to pass to the specified command.
No Additional ItemsEach item of this array must be:
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
Configuration for federation access policies that define JavaScript-based policy rules. 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
Each item of this array must be:
A federation access policy with JavaScript content.
A unique name for the access policy. Maximum of 256 bytes.
Must be at most 256 characters long
System default type for each access policy. For example, 'JavaScript'.
A grouping of related access polices. For example, category 'OAUTH' identifies all the rules associated with the OAUTH flow. Maximum 256 bytes.
Must be one of:
- "InfoMap"
- "AuthSVC"
- "OAUTH"
- "OTP"
- "OIDC"
- "SAML2_0"
A file with the JavaScript content of the access policy. Path can be absolute or relative to IVIACONFIGBASE environment variable.
access_policies:
- name: MyNewAccessPolicy
type: JavaScript
policy_file: path/to/policy.file
category: OTP
Attribute Sources
Identity attribute sources for enriching and generating federated identities.
No Additional ItemsEach item of this array must be:
An attribute source defining where an attribute value originates.
The friendly name of the source attribute. It must be unique.
The type of the attribute source.
Must be one of:
- "credential"
- "value"
- "ldap"
The value of the source attribute. For credential type: The name of a credential attribute from the authenticated context which contains the value. For value type: The plain text to be used as the source attribute value. For LDAP type: The name of the LDAP attribute to be used.
The properties associated with an attribute source.
No Additional ItemsEach item of this array must be:
A property for an attribute source.
The property key. Valid fields for LDAP include 'serverConnection', 'scope', 'selector', 'searchFilter', 'baseDN'.
The property value.
attribute_sources:
- name: username
type: credential
value: PrincipalName
properties:
- key: searchFilter
value: (&(ObjectClass=inetOrgPerson)(memberOf=dc=ibm,dc=com))
Advanced Configuration Properties
Advanced Configuration Parameters define system wide properties for authentication and authorization components. The list of available properties is dependent on the target version of Verify Identity Access being configured. Administrators are able to use either the Verify Identity Access assigned identifier or the name of the property.
No Additional ItemsEach item of this array must be:
An advanced configuration property with its value.
The Verify Identity Access assigned property id. Either the property ID or name must be defined.
The name of the advanced configuration property. Either the property ID or name must be defined.
The updated value of the advanced configuration property.
advanced_configuration:
- name: attributeCollection.authenticationContextAttributes
value: resource,action,ac.uuid,header:userAgent,urn:ibm:demo:transferamount
- name: mmfa.transactionArchival.maxPendingPerUser
value: '1'
HTTP Template Files
Upload 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 /.
Each item of this array must be:
File path to an HTML template file or ZIP archive containing multiple templates.
template_files:
- aac/isva_template_files.zip
- login.html
- 2fa.html
JavaScript Mapping Rules
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.
Configuration for uploading JavaScript mapping rules used in authentication and authorization flows. These rules are typically used to implement custom business logic for a particular integration requirement.
No Additional ItemsEach item of this array must be:
A mapping rule configuration specifying the type and files to upload.
Type of JavaScript rule to create.
Must be one of:
- "InfoMap"
- "AuthSVC"
- "FIDO2"
- "OAUTH"
- "OTP"
- "OIDC"
- "SAML2_0"
List of files or directories to upload as JavaScript mapping rules. Path to files can be relative to the IVIACONFIGBASE property or fully-qualified file paths.
Must contain a minimum of 1 items
Each item of this array must be:
File path to a JavaScript mapping rule file.
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/add_user_mmfa.js
- type: FIDO2
files:
- mediator.js
Point Of Contact Profile
The point of contact profile is used to control how the runtime server communicates with the point of contact server (usually WebSEAL).
Point of Contact Profiles Configuration
Type: objectConfiguration for Point of Contact (PoC) profiles that define callback modules for federation authentication flows.
point_of_contact:
active_profile: MyPoCProfile
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'
List of point of contact profiles to configure.
No Additional ItemsEach item of this array must be:
A Point of Contact profile defining callback modules for federation flows.
A meaningful name to identify this point of contact profile.
A description of the point of contact profile.
An array of callbacks for authentication.
No Additional ItemsEach item of this array must be:
A callback module configuration for a specific federation flow step.
A number reflects the position in the callbacks array.
Value must be greater or equal to 0
The module ID referenced in the callback. It must be one of the supported module IDs.
The parameters used by the callback.
No Additional ItemsEach item of this array must be:
A parameter for a Point of Contact callback.
The name of the parameter.
The value of the parameter.
An array of callbacks for sign in.
No Additional ItemsEach item of this array must be:
A callback module configuration for a specific federation flow step.
Same definition as profiles_items_authenticate_callbacks_itemsAn array of callbacks for local identity.
No Additional ItemsEach item of this array must be:
A callback module configuration for a specific federation flow step.
Same definition as profiles_items_authenticate_callbacks_itemsAn array of callbacks for sign out.
No Additional ItemsEach item of this array must be:
A callback module configuration for a specific federation flow step.
Same definition as profiles_items_authenticate_callbacks_itemsAn array of callbacks for authentication policy.
No Additional ItemsEach item of this array must be:
A callback module configuration for a specific federation flow step.
Same definition as profiles_items_authenticate_callbacks_itemsThe name of the Point of Contact profile which should be the active profile. Only one profile can be active at a time.
Server Connections
Configuration for external server connections used by Access Control and Federation components. Server connections are used to connect to third party infrastructure such as LDAP registries, email servers, SMS servers, ect.
No Additional ItemsEach item of this array must be:
A server connection configuration.
The name of the connection.
A description of the connection.
The type of server connection.
Must be one of:
- "ci"
- "ldap"
- "isamruntime"
- "jdbc"
- "redis"
- "smtp"
- "ws"
Controls whether the connection is allowed to be deleted.
Connection specific properties. The structure depends on the connection type.
Connection properties for IBM Security Verify (Cloud Identity) - type: ci
The IBM Security Verify administration host to connect to.
The client ID to authenticate to the IBM Security Verify tenant.
The client secret to authenticate to the IBM Security Verify tenant.
Controls whether SSL is used to establish the connection.
The key database to be used as an SSL truststore. This field is required when ssl is true.
The name of the key which should be used during mutual authentication with the web server.
The versioned endpoint for user requests.
The versioned endpoint for authenticator requests.
The DEPRECATED versioned endpoint for authentication method requests.
The versioned endpoint for factors requests.
Connection properties for LDAP server - type: ldap
The IP address or hostname of the LDAP server.
The port that the LDAP server is listening on.
Value must be greater or equal to 1 and lesser or equal to 65535
The distinguished name to use to bind to the LDAP server.
The password for bindDN to use when binding to the LDAP server.
Controls whether SSL is used to establish the connection.
The key database to be used as an SSL truststore.
The name of the key which should be used during mutual authentication with the LDAP server.
Amount of time, in seconds, after which a connection to the LDAP server times out.
Value must be greater or equal to 1
Additional LDAP servers for this connection.
No Additional ItemsEach item of this array must be:
Additional LDAP server configuration.
The order of precedence for this server.
Value must be greater or equal to 1
The connection properties. This uses the same properties as LDAPConnection.
Connection properties for Verify Access Runtime LDAP - type: isamruntime
The distinguished name to use to bind to the Verify Identity Access Runtime LDAP server.
The password for bindDN to use when binding to the Verify Identity Access Runtime LDAP server.
Controls whether SSL is used to establish the connection.
The key database to be used as an SSL truststore. This field is required when ssl is true.
The name of the key which should be used during mutual authentication with the Verify Identity Access runtime LDAP server.
Connection properties for JDBC database - type: jdbc
The IP address or hostname of the database.
The port that the database is listening on.
Value must be greater or equal to 1 and lesser or equal to 65535
Controls whether SSL is used to establish the connection.
The user name used to authenticate with the database.
The password used to authenticate with the database.
The Oracle JDBC driver type. Only applicable for Oracle connection.
Must be one of:
- "thin"
- "oci"
The name of the database service to connect to. Only applicable for Oracle connection.
The name of the database to connect to. Only applicable for DB2 and PostgreSQL connections.
Amount of time before a physical connection can be discarded by pool maintenance. A value of -1 disables this timeout.
Amount of time after which a connection request times out. A value of -1 disables this timeout.
Limits the number of open connections on each thread.
Value must be greater or equal to 0
Amount of time after which an unused or idle connection can be discarded during pool maintenance.
Maximum number of physical connections for a pool. A value of 0 means unlimited.
Value must be greater or equal to 0
Minimum number of physical connections to maintain in the pool.
Value must be greater or equal to 0
Caches the specified number of connections for each thread.
Value must be greater or equal to 0
Specifies which connections to destroy when a stale connection is detected in a pool.
Must be one of:
- "EntirePool"
- "FailingConnectionOnly"
- "ValidateAllConnections"
Amount of time between runs of the pool maintenance thread. A value of -1 disables pool maintenance.
Connection properties for Redis server - type: redis
The Redis deployment model.
Must be one of:
- "standalone"
- "sentinel"
The key used in the redis sentinel node to store the master/slave configuration.
The IP address or hostname of the Redis server. This is only required if the deployment_model is set as standalone.
The port that the Redis server is listening on.
Value must be greater or equal to 1 and lesser or equal to 65535
The user name to authenticate to the Redis server.
The password used to authenticate with the Redis server.
Controls whether SSL is used to establish the connection.
The key database to be used as an SSL truststore. Only required if ssl is set to true.
The key database to be used as an SSL keystore. Only required if ssl is set to true.
Amount of time, in seconds, after which a connection to the Redis server times out.
Value must be greater or equal to 1
Amount of time, in seconds, after which an established connection will be discarded as idle.
Value must be greater or equal to 1
Number of connections which will be pooled.
Value must be greater or equal to 1
The minimum number of idle connections in the pool.
Value must be greater or equal to 0
The maximum number of idle connections in the pool.
Value must be greater or equal to 0
Amount of time, in seconds, after which the connection socket will timeout.
Value must be greater or equal to 1
Additional Redis servers for this connection.
No Additional ItemsEach item of this array must be:
Additional Redis server configuration.
The IP address or hostname of the Redis server.
The port that the Redis server is listening on.
Connection properties for SMTP server - type: smtp
The IP address or hostname of the SMTP server.
The port that the SMTP server is listening on.
Value must be greater or equal to 1 and lesser or equal to 65535
The user name to authenticate to the SMTP server.
The password used to authenticate with the SMTP server.
Controls whether SSL is used to establish the connection.
Amount of time, in seconds, after which a connection to the SMTP server times out.
Value must be greater or equal to 1
Connection properties for web service - type: ws
The fully qualified URL of the web service endpoint, including the protocol, host/IP, port and path.
The user name to authenticate to the web service.
The password used to authenticate with the web service.
Controls whether SSL is used to establish the connection.
The key database to be used as an SSL truststore. This field is required when ssl is true.
The name of the key which should be used during mutual authentication with the web server.
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: https://my.verify.tenant
ci_client_id: abcd1234ABCD
ci_client_secret: abcd1234ABCD
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: bind password
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: runtime_user
password: runtime_secret
ssl: true
key_file: rt_profile_keys.kdb
Runtime Server Configuration
Configuration for the Access Control and Federation runtime environment. Configuration options includes: configuring trace; managing endpoints and interfaces that the runtime server listens on; setting server configuration parameters (such as proxy settings, SSL configuration); and defining users and groups in the runtime user registry.
runtime_properties:
users:
- name: easuser
password: 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
List of users to add/update in the AAC/Federation runtime user registry. Users are created before groups.
No Additional ItemsEach item of this array must be:
A runtime user account.
Name of the user to create or update.
The password for the new user. This can contain any ASCII characters.
A list of groups the new user will belong to.
No Additional ItemsEach item of this array must be:
List of groups to add/update in the AAC/Federation runtime user registry.
No Additional ItemsEach item of this array must be:
A runtime user group.
Name of the group to create or update.
List of users to add to the group.
No Additional ItemsEach item of this array must be:
List of AAC/Federation runtime JVM tuning parameters.
No Additional ItemsEach item of this array must be:
A JVM tuning parameter for the runtime.
The tuning parameter to set.
The new value for the specified parameter.
List of http(s) endpoints that the AAC/Federation runtime is listening on.
No Additional ItemsEach item of this array must be:
An HTTP/HTTPS endpoint configuration for the runtime.
The interface the runtime endpoint will listen on.
The static address that the runtime endpoint will listen on.
Endpoint should listen on the DHCP IPv4 address for the given interface.
Endpoint should listen on the DHCP IPv6 address for the given interface.
Port that endpoint will listen on.
Value must be greater or equal to 1 and lesser or equal to 65535
Endpoint should use SSL encryption for connections.
Set the runtime trace specification in Liberty.