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
andOFF
). A default value ofOFF
is used.
- enabled_server_protocols: int | None
TLS
,TLSv1
,TLSv1.1
andTLSv1.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
andTLSv1.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 to80
.
- 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 to443
.
- 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 is5
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 of30
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
andOFF
). A default value ofOFF
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
orkdb_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 ifkdb_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 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
andbind_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
istrue
- 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
istrue
.
- 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
andremote
.
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.
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
andlocal7
.
- 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
anddebug
.
- 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
andrfc-5424
. Default value isrfc-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
andtls
.
- server: str
The IP address or host name of 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.
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.
- comment: str
Comment to add to interface.
- enabled: str
Enable this interface.
- 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.
- hostname: str | None
Hostname to set for the Verify Identity Access appliance.
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.
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
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.
- 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
andSAML2_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
istrue
.
- 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 as30s
. 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 isEntirePool
)
- 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 as30s
. You can include multiple values in a single entry. For example,1m30s
is equivalent to 90 seconds. (Default value is30s
)
- 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 as30s
. You can include multiple values in a single entry. For example,1m30s
is equivalent to 90 seconds. (Default value is30m
)
- 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
andoci
. 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.
- 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
andsentinel
.
- hostname: str | None
The IP address or hostname of the Redis server. This is only required if the
deployment_model
is set asstandalone
.
- 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.
- 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 totrue
.
- ssl_truststore: str | None
The key database to be used as an SSL truststore. Only required if
ssl
is set totrue
.
- 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
istrue
.
- class WebServiceConnection
ws
- key_file: str | None
The key database to be used as an SSL truststore. This field is required when
ssl
istrue
.
- 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
andws
.- 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.