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

SLA / First steps

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

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

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

Password update

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

class src.ibmvia_autoconf.configure.IVIA_Configurator.Admin_Password

Example:

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

Note

These properties are overridden by IVIA_MGMT_* environment variables

mgmt_old_pwd: str: Password to update for the Administrator user.

mgmt_pwd: str: Secret to authenticate as the Administrator user.

mgmt_user: str: Administrator user to run configuration as.

Administrator Configuration

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

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

class src.ibmvia_autoconf.configure.IVIA_Configurator.Admin_Config

Examples:

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

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

accept_client_certs: bool | None: A boolean value which is used to control whether SSL client certificates are accepted by the local management interface. By default SSL client certificates are accepted.

access_log_fmt: str | None: The template string to use for the LMI access.log file. If not set the access log is disabled (default).

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

enabled_server_protocols: int | None

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

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

enabled_tls: List[str] | None: List of Enabled TLS protocols for the local management interface. Valid values include TLSv1, TLSv1.1 and TLSv1.2.

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

http_port: int | None: The TCP port on which the LMI will listen.

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

https_port: int | None: The SSL port on which the LMI will listen. A default value of 443 is used.

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

lmi_debugging_enabled: bool | None: A boolean value which is used to control whether LMI debugging is enabled or not. By default debugging is disabled.

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

log_max_files: int | None: The maximum number of log files that are retained. The default value is 2.

log_max_size: int | None: The maximum size (in MB) that a log file can grow to before it is rolled over. The default value is 20

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

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

max_heap_size: int | None: The minimum heap size, in megabytes, for the JVM.

max_pool_size: int | None: The maximum number of connections for the connection pool. The default value is 100.

max_threads: int | None: The maximum number of threads which will handle LMI requests. A default value of 6 is used.

min_heap_size: int | None: The minimum heap size, in megabytes, for the JVM.

min_threads: int | None: The minimum number of threads which will handle LMI requests. A default value of 6 is used.

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

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

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

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

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

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

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

SSL Certificate database

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

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

class src.ibmvia_autoconf.configure.IVIA_Configurator.SSL_Certificates

Example:

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

class Load_Certificate

label: str: Name of retrieved X509 certificate alias in SSL database.

port: int: Port Web service is listening on.

server: str: Domain name or address of web service.

class Personal_Certificate

path: str: Path to file to import as a personal certificate.

secret: str | None: Optional secret to decrypt personal certificate.

kdb_file: str | None: Path to the .kdb file to import as a SSL database. Required if importing a SSL KDB.

load_certificates: List[Load_Certificate] | None: Load X509 certificates from a TCPS endpoints.

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

personal_certificates: List[Personal_Certificate] | None: List of file paths for personal certificates (PKCS#12) to import.

signer_certificates: List[str] | None: List of file paths for signer certificates (PEM or DER) to import.

stash_file: str | None: Path to the .sth file for the specified kdb_file. Required if kdb_file is set.

Administrator Account Management

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

class src.ibmvia_autoconf.configure.IVIA_Configurator.Account_Management

Example:

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

class Management_Group

Note

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

id: str: Name of group to create.

operation: str: Operation to perform with group. add | update | delete.

users: List[str] | None: Optional list of users to add to group.

class Management_User

groups: List[str] | None: Optional list of groups to add user to.

name: str: Name of the user to create, remove or update.

operation: str: Operation to perform with user. add | update | delete.

password: str | None: Password to authenticate as user. Required if creating user.

groups: List[Management_Group] | None: Optional list of management groups to configure.

users: List[Management_User] | None: Optional list of management users to configure

Management Authorization

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

class src.ibmvia_autoconf.configure.IVIA_Configurator.Management_Authorization

Example:

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

class Role

class Feature

access: str: Access to grant to feature. r | w.

name: str: Name of feature.

class Group

name: str: name of group.

type: str: Type of group. local | remote.

class User

name: str: Name of user

type: str: Type of user. local | remote.

features: List[Feature]: List of features to authorize users / groups for.

groups: List[Group] | None: Optional list of groups to add to role.

name: str: Name of role.

operation: str: Operation to perform on authorization role. add | remove | update.

users: List[User] | None: Optional list of users to add to role.

authorization_enforcement: bool: Enable role based authorization for this deployment.

roles: List[Role] | None: Optional list of roles to modify for role based authorization.

Management Authentication

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

class src.ibmvia_autoconf.configure.IVIA_Configurator.Management_Authentication

Example:

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

class LDAP

admin_group_dn: str: Specifies the DN of the group to which all administrative users must belong.

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

base_dn: str: Specifies the base DN which is used to house all administrative users.

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

bind_password: str | None: Specifies the password which is associated with the bind_dn. This parameter is required if anon_bind is false.

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

debug: bool: Specifies whether the capturing of LDAP debugging information is enabled or not.

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

enable_usermapping: bool: Specifies whether mapping of the incoming client certificate DN is enabled.

group_member_attribute: str: Specifies the name of the LDAP attribute which is used to hold the members of a group.

host: str: Specifies the name of the LDAP server.

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

port: str: Specifies the port over which to communicate with the LDAP server.

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

ssl: bool: Specifies whether SSL is used when the system communicates with the LDAP server.

user_attribute: str: Specifies the name of the LDAP attribute which holds the supplied authentication user name of the user.

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

class OIDC

admin_group: str | None: The name of the group which a user must be a member of to be considered an administrator user. The default value is adminGroup.

client_id: str: The OIDC Client Identifier.

client_secret: str: The OIDC Client Secret.

discovery_endpoint: str: The OIDC Discovery (well-known) endpoint.

enable_admin_group: bool: Specifies whether a user must be a member of a particular group to be considered an administrator user.

enable_pkce: bool: Specifies whether the Public key Code Exchange extension is enforced.

enable_tokenmapping: bool: Specifies whether custom claim to identity mapping is performed using a JavaScript code fragment.

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

keystore: str | None: The SSL Truststore to verify connections the the OIDC OP. The default value if lmi_trust_store.

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

user_claim: str | None: Specifies the OIDC token claim to use as the username. The default value is sub.

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

ldap: LDAP | None: LDAP specific configuration properties. Only one of LDAP or OIDC should be defined

oidc: OIDC | None: OIDC specific configuration properties. Only one of LDAP or OIDC should be defined

Module Activation

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

class src.ibmvia_autoconf.configure.IVIA_Configurator.Module_Activations

Example:

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


activation:
  trial_license: issued/trial.pem

access_control: str | None: License code for the Advanced Access Control module.

federation: str | None: License for the Federations module.

trial_license: str | None

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

Type:: Trial license file issued from https

webseal: str | None: License code for the WebSEAL Reverse Proxy module.

Advanced tuning parameters

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

class src.ibmvia_autoconf.configure.IVIA_Configurator.Advanced_Tuning_Parameter

Example:

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

description: str | None: optional description of the Advanced Tuning Parameter.

name: str: Name of the Advanced Tuning Parameter.

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

value: str: Value of the Advanced Tuning Parameter.

Configuration Snapshots

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

class src.ibmvia_autoconf.configure.IVIA_Configurator.Snapshot

Example:

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

snapshot: str: Path to signed snapshot archive file.

Extensions

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

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

class src.ibmvia_autoconf.configure.IVIA_Configurator.Extensions

Example:

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

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

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

third_party_packages: str | None: An optional list of third party packages to be uploaded to Verify Identity Access as part of the installation process.

Remote Syslog

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

class src.ibmvia_autoconf.configure.IVIA_Configurator.Remote_Syslog

Example:

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

class Forwarder

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

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

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

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

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

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

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

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

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

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

port: int: The port on which the remote syslog server is listening.

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

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

sources: List[Forwarder]: The source of the log file entries which will be sent to the remote syslog server.