Container Configuration
This module contains documentation for system level configuration applicable for Container based Verify Identity Access
deployments. Container configuration is defined under the container top level key. At a minimum an administrator
should define the mgmt_base_url, mgmt_user and mgmt_pwd keys (or define the applicable
environment variables). These keys should be defiend at the top level of the configuration file.
Example
mgmt_base_url: "https://127.0.0.1:9443"
mgmt_user: "admin"
mgmt_pwd: "Passw0rd"
container:
admin_cfg:
session_timeout: 720
account_management:
users:
- name: "cfgsvc"
operation: "update"
password: !secrets/isva-secrets:cfgsvc-passwd
management_authorization:
authorization_enforcement: True
roles:
- operation: update
name: "Configuration Service"
users:
- name: "cfgsvc"
type: "local"
features:
- name: "shared_volume"
access: "w"
ssl_certificates:
- name: "lmi_trust_store"
signer_certificates:
- "postgres.crt"
- "ldap.crt"
- name: "rt_profile_keys"
signer_certificates:
- "postgres.crt"
cluster:
host: "postgresql"
port: 5432
type: "Postgresql"
user: "postgres"
password: !secrets/isva-secrets:postgres-passwd
ssl: True
db_name: "isva"
Container specific configuration
This section covers the Container specific configuration of Verify Identity Access deployments. Typically this involves setting an external HVDB connection; and enabling the management authorization feature to permit a service account to publish configuration snapshots which can be subsequently fetched by other containers in` the deployment.
Managing Container Deployments
Kubernetes / OpenShift
If Verify Identity Access is deployed with Kubernetes, then kubectl cli tool can be used to promote a configuration snapshot. There are
two ways to do this: One, use Kubernetes to restart the deployments; Two, use the automated service from the legacy
“all-in-one” container. It is recommended to use Kubernetes to rollout restarts to deployments where possible.
The kubectl rollout restart command can be used to restart reverse proxy, runtime and DSC deployments. The configurator
can use deployment names to request a restart of all of the pods associated with a deployment. If this functionality is
used then the user running the Kubernetes commands must have sufficient privilege to restart the containers. An example
of a deployment configuration is:
container:
k8s_deployments:
namespace: "default"
configuration:
- "isamconfig"
webseal:
- "isamwrp_1"
- "isamwrp_2"
runtime:
- "isamruntime"
dsc:
- "isamdsc_1"
- "isamdsc_2"
Docker-Compose
If Verify Identity Access is deployed with Docker-Compose, then docker-compose cli tool can be used to manage runtime
containers when a snapshot needs to be promoted. The configurator can use the compose service names to request a restart
of runtime containers. If this functionality is used then the user running the configurator should have sufficient
privilege to restart docker containers.
An example of a compose deployment configuration is:
container:
compose_services:
- "isvawrprp1"
- "isvaruntime"
docker_compose_yaml: "iamlab/docker-compose.yaml"
Database and Distribued Session Cache Configuration
Configuration for config and runtime database connections; and distributed session cache settings in container deployments.
cluster:
runtime_database:
type: postgresql
host: postgresql
port: 5432
ssl: true
ssl_keystore: rt_profile_keys
user: postgres
password: Passw0rd
db_name: isva
cluster:
config_database:
type: postgresql
host: postgresql
port: 5432
ssl: true
ssl_keystore: rt_profile_keys
user: postgres
password: Passw0rd
db_name: config
runtime_database:
type: postgresql
host: postgresql
port: 5432
ssl: true
ssl_keystore: rt_profile_keys
user: postgres
password: Passw0rd
db_name: hvdb
Configuration for the config database.
Database type.
Must be one of:
- "postgresql"
- "db2"
- "oracle"
- "mssql"
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 the distributed session cache runtime containers.
The length of time (in seconds) that a client (aka WebSEAL) has to reconnect before sessions owned by that client are discarded.
Value must be greater or equal to 0
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.
Value must be greater or equal to 0
The maximum lifetime (in seconds) of any session stored by the DSC.
Value must be greater or equal to 1
The port number on which the DSC will listen for requests.
Value must be greater or equal to 1 and lesser or equal to 65535
The port number on which the DSC will listen for replication requests.
Value must be greater or equal to 1 and lesser or equal to 65535
The comma separated list of permitted SSL algorithms for TLS connections to the DSC.
The comma separated list of permitted TLS 1.2 cipher specs for established TLS connections to the DSC.
The comma separated list of permitted TLS 1.3 cipher specs for established TLS connections to the DSC.
The number of worker threads allocated to processing requests.
Value must be greater or equal to 1
The external connection data for each instance of the DSC. This corresponds to the IP address and ports to which clients will connect. Up to 4 servers may be defined (primary, secondary, tertiary and quaternary). The role of the server will be determined by the order of elements within the servers array.
Must contain a minimum of 1 items
Must contain a maximum of 4 items
Each item of this array must be:
A Distributed Session Cache server configuration.
The name/IP address over which clients can connect to the DSC.
The port which can be used by clients to connect to the DSC for session requests.
Value must be greater or equal to 1 and lesser or equal to 65535
The port which can be used by the DSC to replicate data to a replication DSC.
Value must be greater or equal to 1 and lesser or equal to 65535
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 Items