Welcome to ibmvia-autoconf documentation!

ibmvia-autoconf is an automation layer written on top of pyIVIA. This library should be used to apply YAML configuration files to a Verify Identity Access deployment.

This library is designed to work with both Appliance and Container based deployments, and is not idempotent.

Configuration is supplied in YAML syntax using a well-defined data structure (detailed in this doc).

Installation

You can install ibmvia-autoconf with pip:

$ pip install ibmvia-autoconf

If you require the extra dependencies (for example using K8S secrets to store sensitive properties) you can install the optional targets kubernetes, docker-compose, or all:

$ pip install ibmvia-autoconf[kubernetes]

or

$ pip install ibmvia-autoconf[all]

Architecture

Users should take care to ensure the configuration of these separate features are compatible (eg. conflicting ALC’s in a WebSEAL reverse proxy). Administrators will also have to define the webseal.runtime entry for many configuration options even if the WebSEAL Runtime Component is already configured.

Example configurations can be found in the examples directory with additional documentation in the Examples / Getting Started page.

Strategies on how administrators can attempt idempotency are documented here.

Modules

The configuration process is broken into six modules. Each module is responsible for configuring a subset of Verify Identity Access features. The order of configuration is:

base (Licensing, SSL Databases, Cluster Settings)
appliance (if applicable)
container (if applicable)
federations
webseal
access control

This ordering has been chosen to allow for modules which depend on each-other to be deployed in the correct order.

More complex deployment architectures can be achieved by running sequential config.yaml descriptors.

API Failure Tracking

IBM Verify Identity Access Automated Configurator includes built-in tracking of failed API requests. When enabled (default), the configurator will collect information about any API calls that fail during execution and print a comprehensive summary at the end.

Captures context for each failure:

Module name and operation being performed
Error message from the API response
API endpoint that was called
HTTP status code
Full response content/data
Request payload/parameters sent
Timestamp of the failure
Outputs summary grouped by module
Supports both human-readable and JSON output formats
Can be disabled via environment variable

Example Output (Human-Readable Format)

================================================================================
API FAILURE SUMMARY - 3 Failed Request(s)
================================================================================

Module: access_control (2 failure(s))
--------------------------------------------------------------------------------
  1. Operation: create_policy
    Error: Policy name already exists
    API Endpoint: /iam/access/v8/policies
    Status Code: 409
    Response: {'error': 'DUPLICATE_NAME', 'message': 'Policy name already exists'}
    Request Data: {'name': 'MyPolicy', 'type': 'authorization'}
    Timestamp: 2026-04-02T03:15:00.123Z

  2. Operation: update_pip
    Error: Connection timeout
    API Endpoint: /iam/access/v8/pips/123
    Status Code: 504
    Response: {'error': 'GATEWAY_TIMEOUT'}
    Timestamp: 2026-04-02T03:16:30.456Z

Module: webseal (1 failure(s))
--------------------------------------------------------------------------------
  1. Operation: create_junction
    Error: Backend server unreachable
    API Endpoint: /wga/reverseproxy/junctions
    Status Code: 502
    Response: {'error': 'BAD_GATEWAY', 'backend': 'https://backend.example.com'}
    Request Data: {'junction_point': '/app', 'server': 'backend.example.com'}
    Timestamp: 2026-04-02T03:18:00.012Z

================================================================================

Example Output (JSON Format)

When IVIA_CONFIGURATOR_LOG_FORMAT=json:

{
  "type": "ibmvia-autoconf",
  "host": "ivia-config-5ccc54dcf-nvxf5",
  "timestamp": "2026-04-02T03:18:00.012Z",
  "message": "API Failure Summary - 3 failed request(s)",
  "ibm_threadId": "4150",
  "loglevel": "1",
  "api_failure_summary": {
    "total_failures": 3,
    "by_module": {
      "access_control": 2,
      "webseal": 1
    }
  },
  "failures": [
    {
      "timestamp": "2026-04-02T03:15:00.123Z",
      "module": "access_control",
      "operation": "create_policy",
      "error_message": "Policy name already exists",
      "api_endpoint": "/iam/access/v8/policies",
      "status_code": 409,
      "response_content": {"error": "DUPLICATE_NAME", "message": "Policy name already exists"},
      "request_data": {"name": "MyPolicy", "type": "authorization"}
    },
    {
      "timestamp": "2026-04-02T03:16:30.456Z",
      "module": "access_control",
      "operation": "update_pip",
      "error_message": "Connection timeout",
      "api_endpoint": "/iam/access/v8/pips/123",
      "status_code": 504,
      "response_content": {"error": "GATEWAY_TIMEOUT"},
      "request_data": null
    },
    {
      "timestamp": "2026-04-02T03:18:00.012Z",
      "module": "webseal",
      "operation": "create_junction",
      "error_message": "Backend server unreachable",
      "api_endpoint": "/wga/reverseproxy/junctions",
      "status_code": 502,
      "response_content": {"error": "BAD_GATEWAY", "backend": "https://backend.example.com"},
      "request_data": {"junction_point": "/app", "server": "backend.example.com"}
    }
  ]
}

YAML configuration keywords

Each module expects a YAML object describing the desired configuration state. There are a number of useful features which can be used to make configuration files re-usable and version controlled. There are five keywords which can be used in configuration files:

!include
Used to include a YAML configuration file as the value of the given key. This file can be either an absolute path or relative to the IVIA_CONFIG_BASE environment variable. eg:
container: !include base_config.yaml
webseal: !include webseal.yaml
access_control: !include aac.yaml
!secret
Used to set the value of the given key as a value read from the given Kubernetes Secret Namespace/Name, eg:
admin_password: !secret default/isva-secrets:admin_secret
!secret:tofile
Used to load binary or text files from Kubernetes Secrets. The file content is written to a temporary file Use this for certificates, archives, mapping rules, templates, and any other files that need to be loaded from Kubernetes Secrets. If the namespace is not provided then autoconf assumes it is running in a container (pod) and will use the namespace of the container it is running in.

Example:
lmi_certificate:
  p12: !secret:tofile default/lmi-ssl-certs:server.p12
  password: !secret lmi-ssl-passwords:p12-password
!configmap:tofile
Used to load binary or text files from Kubernetes ConfigMaps. Works identically to !secret:tofile but reads from ConfigMaps instead of Secrets. Use this for non-sensitive configuration files, templates, and scripts. eg:
mapping_rules:
  - type: SAML2
    files:
      - !configmap:tofile default/aac-config:saml_mapping.js
template_files:
  - !configmap:tofile ui-templates:login.zip
!environment:
Used to set the value of the given key as the value read from the given environment variable, eg:
admin_password: !environment IVIA_ADMIN_SECRET

Environment properties

In addition to the supplied YAML configuration, some properties can alternatively be set as environment variables. If these variables are set, they take priority over values set in configuration files.

IVIA_CONFIG_BASE
This variable is the root directory of all configuration files for the given Verify Identity Access Deployment. This can include: YAML configuration files; HTML template pages; JavaScript mapping rules; XML configuration files.

Note

If this environment variable is not set then the user’s $HOME directory is used.
IVIA_CONFIG_YAML
This variable defines the YAML configuration file to deploy. This can be either relative to the IVIA_CONFIG_BASE directory or an absolute file path. If this variable is not defined then the configuration will look for a file called config.yaml in the IVIA_CONFIG_BASE directory.
IVIA_MGMT_BASE_URL
This variable is the URL address that Verify Identity Access Local Management Interface is responding on. This should contain: the https scheme; the domain or IP address; and a port if not the standard (443) port. eg: https://127.0.0.2:9443.
IVIA_MGMT_USER
The user to perform configuration as. This user should have sufficient permissions to configure all of the features in your YAML configuration file. If a username is not supplied then the IVIA_MGMT_PWD value is used as a bearer API access token.
IVIA_MGMT_PWD
The password or API access token required to authenticate.
IVIA_MGMT_OLD_PWD
If a password change is required then this variable defines the password for IVIA_MGMT_USER before the configuration is applied.
IVIA_EXT_USER
If external (federated) authentication to the management interface is configured, this property can be used to define the external user to perform configuration as once the management_authorization feature has been configured.
IVIA_EXT_PWD
If external (federated) authentication to the management interface is configured, this property can be used to define the external password to authenticate with once the management_authorization feature has been configured.
- IVIA_PUBLISH_SNAPSHOT_SLEEP
  The number of seconds to delay after publishing a configuration snapshot. This property can be used to allow time for the configuration to be replicated in the filesystem or for the configuration container to stabilize after publishing a snapshot.
IVIA_KUBERNETES_YAML_CONFIG
This variable defines the Kubernetes cluster configuration file required to run kubectl commands. This configuration file should have sufficient permission in your cluster to restart deployments and pods in the namespace that Verify Identity Access is deployed to. The file path can either be absolute or relative to the IVIA_CONFIG_BASE variable.

Note

This is only applicable for Container deployments using Kubernetes orchestration.
KUBERNETES_CLIENT_SLEEP
The number of seconds to delay after requesting a restart of the runtime containers managed by the automated configuration tool. Use this property to allow time for the runtime containers to fetch the latest snapshot and apply the configuration.
IVIA_DOCKER_COMPOSE_CONFIG
This variable defines the Docker-Compose deployment configuration file required to run docker-compose commands for your Verify Identity Access deployment. This file path can either be absolute or relative to the IVIA_CONFIG_BASE variable.

Note

This is only applicable for Container deployments using Docker-Compose orchestration.
IVIA_CONFIGURATOR_LOG_LEVEL
This variable set the logging level for the autoconf tool. The default log level is INFO. Valid values are DEBUG, INFO, WARNING, ERROR, and CRITICAL.
IVIA_TRACK_API_FAILURES
If set to true, the autoconf tool will track API failures and summarize them before the tool exits. Default is true.
IVIA_CONFIGURATOR_LOG_FORMAT
The format to use for the log messages. Default is %(asctime)s - %(levelname)s - %(message)s”. If the format is set to json then the messages logged will be JSON parsible.
IVIA_TRACK_API_FAILURES
If set to true, the autoconf tool will track API failures and summarize them before the tool exits. Default is true.
IVIA_CONFIGURATOR_LOG_FILE
The path to the log file to write to. If not specified, logs will be written to stdout. This should be a fully qualified path.

Detailed information on configuration object structure can be found in the submodule documentation

Contents: