Advanced database configuration

Configuring the OneSpan Authentication Server database connection

Custom database configuration

You can use a custom database configuration and provide it to the OneSpan Authentication Server container by mounting the ODBC data source configuration file (/etc/odbc.ini). If you use Oracle Database 19, a volume mount to /usr/lib/oracle/19.17/client64/network/admin/tnsnames.ora is required.

When you mount a custom /etc/odbc.ini file, the specified database driver name must match the one provided in the container's ODBC driver configuration file (/etc/odbcinst.ini). You can verify this with the following command:

docker run --rm onespan_ias_<db_type>:<release_version> cat /etc/odbcinst.ini

Replace the following:

• db_type. The database type of the active OneSpan Authentication Server instance. This is usually a substring of the image name. Possible values: maria, mssql, oracle.
• release_version. The specific version of the images distributed in the package, e.g. 3.27.0.1234.

You can use the IASDB_DSN environment variable to set the DSN that should be used by the OneSpan Authentication Server images. By default, the DSN is iasdb (see OneSpan Authentication Server).

Encrypted communication

When you configure TLS/SSL between the OneSpan Authentication Server container and the database, the following volume mounts may be required:

• Database client certificate, key, and root certificate (e.g. for MariaDB)
• Client certificate wallet and the sqlnet.ora file (for Oracle Database)

MariaDB with TLS/SSL

The following is a partial example of a OneSpan Authentication Server service configuration (docker-compose.yml) when using TLS/SSL to secure database connections:

# IAS service connecting to a local MariaDB instance via TLS/SSL, as created
# as part of the basic OAS ISO installation.

ias-maria:
  image: onespan_ias_maria:<release_version>
  container_name: ias-maria

  environment:
    - IASDB_SERVICE_NAME=db
    - IASDB_SERVICE_PORT=3306
    - IASDB_DSN=IAS embedded database
    - ...

  secrets:
    - ...

  volumes:
    - /etc/odbc.ini:/etc/odbc.ini
    - /etc/vasco/ias/cert/client-cert.pem:/etc/vasco/ias/cert/client-cert.pem
    - /etc/vasco/ias/cert/client-key.pem:/etc/vasco/ias/cert/client-key.pem
    - /etc/vasco/ias/cert/ca-cert.pem:/etc/vasco/ias/cert/ca-cert.pem
    - ...

  ...

If you use Oracle Database, ensure the following:

• The mounted wallet was not created with auto login enabled (e.g. with the ‑auto_login_local parameter set for orapki or an equivalent tool).
• The wallet path specified in sqlnet.ora corresponds to the wallet mount location inside the container.
• The file permissions set on the wallet files are sufficient to be readable for the OneSpan Authentication Server container user.

Oracle Database with TLS/SSL

The following is a partial example of an Oracle Database service configuration (docker-compose.yml) when using TLS/SSL to secure database connections:

# IAS service connecting to a local Oracle Database instance via TLS/SSL,
# where the mounted sqlnet.ora file specifies /tmp/wallet as the wallet
# directory in the WALLET_LOCATION setting and the odbc.ini file defines the
# iasdb DNS, removing the need to override the IASDB_DSN value.

ias-oracle:
  image: onespan_ias_oracle:<release_version>
  container_name: ias-oracle

  environment:
    - IASDB_SERVICE_NAME=ol8-19.localdomain
    - IASDB_SERVICE_PORT=1521
    - CARG_IASDB_ORACLE_SID_TYPE=SID
    - CARG_IASDB_ORACLE_SID=cdb1
    - TNS_ADMIN=/tmp/tnsadmin
    - ...

  secrets:
    - ...

  volumes:
    - /etc/odbc.ini:/etc/odbc.ini
    - ./network/tnsnames.ora:/tmp/tnsadmin/tnsnames.ora
    - ./network/sqlnet.ora:/tmp/tnsadmin/sqlnet.ora
    - ./wallet/ewallet.p12:/tmp/wallet/ewallet.p12
    - ./wallet/cwallet.sso:/tmp/wallet/cwallet.sso
    - ...

    # the wallet and the *ora file mounts can be simplified in this case to:
    # - ./network:/tmp/tnsadmin
    # - ./wallet:/tmp/wallet

  extra_hosts:
    - "ol8-19.localdomain:<oracle_host_ip>"
    - ...

Replace the following:

• oracle_host_ip. The IP address of the server that runs the Oracle Database.

Performing a database upgrade

The OneSpan Authentication Server containers perform database schema verification checks when they start and issue errors when the checks fail. Running the container with the environment variable CARG_IAS_UPGRADE_MODE=true set, will cause the container to attempt a database upgrade and exit upon successful upgrade completion or failure. After a successful database upgrade, a new OneSpan Authentication Server container can be successfully started without CARG_IAS_UPGRADE_MODE set.

Database upgrade with custom database configuration

The following is a partial example of a service configuration (docker-compose.yml) that performs a database upgrade and start a OneSpan Authentication Server instance with a custom database configuration:

services:
  upgrade:
    image: onespan_ias_maria:<release_version>
    container_name: upgrade

    environment:
      - IASDB_SERVICE_NAME=db
      - IASDB_SERVICE_PORT=3306
      - IASDB_DSN=IAS embedded database
      - CARG_IAS_UPGRADE_MODE=true

    secrets:
      - source: ias_admin_username
        target: onespan.com/admin_username
      - source: ias_admin_password
        target: onespan.com/admin_password
      - source: db_admin_username
        target: onespan.com/db_username
      - source: db_admin_password
        target: onespan.com/db_password

    volumes:
      - /etc/odbc.ini:/etc/odbc.ini
      - /etc/vasco/ias/cert/client-cert.pem:/etc/vasco/ias/cert/client-cert.pem
      - /etc/vasco/ias/cert/client-key.pem:/etc/vasco/ias/cert/client-key.pem
      - /etc/vasco/ias/cert/ca-cert.pem:/etc/vasco/ias/cert/ca-cert.pem

  ias:
    image: onespan_ias_maria:<release_version>
    container_name: ias

    environment:
      - IASDB_SERVICE_NAME=db
      - IASDB_SERVICE_PORT=3306
      - IASDB_DSN=IAS embedded database

    secrets:
      - source: ias_admin_username
        target: onespan.com/admin_username
      - source: ias_admin_password
        target: onespan.com/admin_password
      - source: db_admin_username
        target: onespan.com/db_username
      - source: db_admin_password
        target: onespan.com/db_password
      - ...

    volumes:
      - /etc/odbc.ini:/etc/odbc.ini
      - /etc/vasco/ias/cert/client-cert.pem:/etc/vasco/ias/cert/client-cert.pem
      - /etc/vasco/ias/cert/client-key.pem:/etc/vasco/ias/cert/client-key.pem
      - /etc/vasco/ias/cert/ca-cert.pem:/etc/vasco/ias/cert/ca-cert.pem
      - ...

    depends_on:
      upgrade:
        condition: service_completed_successfully

Performing a data migration

To perform a data migration from an existing OneSpan Authentication Server deployment using the Data Migration Tool (DMT), you can start the OneSpan Authentication Server container in migration mode. To do so, set the data attribute of the /VASCO/Server-Config/OperationMode element in the mounted OneSpan Authentication Server configuration file template (identikeyconfig.tmpl) to 2.

For more information about using DMT refer to the Data Migration Tool Administrator Guide.