IDV Configuration

The IDV Platform configuration is managed via a single config.yaml file.

It is the preferred and central approach to define service behavior, integrations, storage options, and internal scheduling.

Structure

└── mode
└── fernetKey
└── baseUrl
└── identifier
└── metrics
└── logging
└── storage
└── mobile
└── smtp
└── oauth2
└── faceSearch
└── textSearch
└── services
└── mongo
└── messageBroker
└── webApp
└── custom

You can find the example of the configuration file at the bottom of the page.

Basic Parameters

Parameter	Type	Default	Description
`mode`	string	`cluster`	Mode of operation: `cluster` for distributed deployments, `standalone` for local development.
`fernetKey`	string	—	Secret key used for encrypting sensitive data in the database.
`baseUrl`	string	—	Base URL where the service is accessible, used in email templates and redirects.
`identifier`	string	—	Optional server identifier used in sessions.
`custom`	object	—	Arbitrary user-defined configuration values that can be used in templates.

Metrics

This section configures performance and usage metrics collection, including StatsD and database-based storage.

metrics
├── statsd
│   ├── enabled
│   ├── host
│   ├── port
│   └── prefix
└── alerts
    ├── enabled
    └── prometheus
        ├── url
        └── filter
            └── groups

Parameter	Type	Default	Description
`statsd` → `enabled`	boolean	`false`	Whether to enable StatsD for metrics collection.
`statsd` → `host`	string	`localhost`	StatsD server hostname.
`statsd` → `port`	integer	`9125`	StatsD server port.
`statsd` → `prefix`	string	—	Prefix for metrics.
`alerts` → `enabled`	boolean	`false`	Whether to enable access to alerts via the API.
`alerts` → `prometheus` → `url`	string	—	Prometheus server URL for alerts.
`alerts` → `prometheus` → `filter` → `groups`	list[str]	—	Alert groups to filter.

Logging

This section defines the logging behavior, including format, log level, output destinations (console/file), and file management settings.

logging
├── level
├── formatter
├── console
├── file
├── path
├── maxFileSize
└── filesCount

Parameter	Type	Default	Description
`level`	string	`INFO`	Logging level.
`formatter`	string	—	Format for log output.
`console`	boolean	`true`	Whether to enable logging to console.
`file`	boolean	`false`	Whether to enable logging to file.
`path`	string	`"logs"`	Path for storing log files.
`maxFileSize`	string	`1048576`	Maximum size of each log file. Supports floating-point format (for example, "1e6") and memory expressions (for example, "10Mi").
`filesCount`	integer	`10`	Number of log files to retain.

Storage

The storage section defines the main storage backends (for example, S3 or local file system) and specifies bucket paths for storing various data types like sessions, persons, workflows, user files, and localization configs.

storage
├── type
├── s3
│   ├── endpoint
│   ├── accessKey
│   ├── accessSecret
│   ├── region
│   └── secure
├── fs
│   └── path
├── sessions
│   └── location
│       ├── bucket
│       ├── prefix
│       └── folder
├── persons
│   └── location
│       ├── bucket
│       ├── prefix
│       └── folder
├── idags
│   └── location
│       ├── bucket
│       ├── prefix
│       └── folder
├── workflows
│   └── location
│       ├── bucket
│       ├── prefix
│       └── folder
├── userFiles
│   └── location
│       ├── bucket
│       ├── prefix
│       └── folder
├── locales
│   └── location
│       ├── bucket
│       ├── prefix
│       └── folder
└── assets
    └── location
        ├── bucket
        ├── prefix
        └── folder

Parameter	Type	Default	Description
`type`	string	`s3`	Storage backend: `s3` or `fs`.
`s3` → `endpoint`	string	—	S3-compatible endpoint URL.
`s3` → `accessKey`	string	—	Access key for S3.
`s3` → `accessSecret`	string	—	Secret key for S3.
`s3` → `region`	string	`eu-central-1`	Storage region.
`s3` → `secure`	boolean	`true`	Use HTTPS connection.
`fs` → `path`	string	—	Local file system path for data.
`sessions`	object	—	Stores user session data.
`sessions` → `location` → `bucket`	string	—	Bucket name for session data.
`sessions` → `location` → `prefix`	string	—	Path prefix for session data.
`sessions` → `location` → `folder`	string	—	Subfolder for session data.
`persons`	object	—	Stores biometric/person-related files.
`persons` → `location` → `bucket`	string	—	Bucket name for person-related files.
`persons` → `location` → `prefix`	string	—	Path prefix for person-related files.
`persons` → `location` → `folder`	string	—	Subfolder for person-related files.
`idags`	object	—	Stores IDAG files.
`idags` → `location` → `bucket`	string	—	Bucket name for IDAG files.
`idags` → `location` → `prefix`	string	—	Path prefix for IDAG files.
`idags` → `location` → `folder`	string	—	Subfolder for IDAG files.
`workflows`	object	—	Stores predefined scenario workflows.
`workflows` → `location` → `bucket`	string	—	Bucket name for workflows.
`workflows` → `location` → `prefix`	string	—	Path prefix for workflows.
`workflows` → `location` → `folder`	string	—	Subfolder for workflows.
`userFiles`	object	—	Stores uploaded user documents.
`userFiles` → `location` → `bucket`	string	—	Bucket name for user files.
`userFiles` → `location` → `prefix`	string	—	Path prefix for user files.
`userFiles` → `location` → `folder`	string	—	Subfolder for user files.
`locales`	object	—	Stores localization files for translation.
`locales` → `location` → `bucket`	string	—	Bucket name for localization files.
`locales` → `location` → `prefix`	string	—	Path prefix for localization files.
`locales` → `location` → `folder`	string	—	Subfolder for localization files.
`assets`	object	—	Stores asset files.
`assets` → `location` → `bucket`	string	—	Bucket name for asset files.
`assets` → `location` → `prefix`	string	—	Path prefix for asset files.
`assets` → `location` → `folder`	string	—	Subfolder for asset files.

Mobile

The mobile section defines identifiers and security hashes for the Android and Apple apps to verify and link official mobile clients.

mobile
├── android
│   ├── bundleId
│   └── sha256
│       ├── \[0]
│       ├── \[1]
│       └── \[2]
└── apple
│   ├── appId
│   ├── bundleId

Mobile Parameters

Parameter	Type	Default	Description
`android` → `bundleId`	string	—	Android application ID.
`android` → `sha256`	list	—	App certificate fingerprints for security.
`apple` → `appId`	string	—	Apple app ID.
`apple` → `bundleId`	string	—	Apple bundle ID.

SMTP

The smtp section configures email delivery settings such as SMTP host, port, credentials, and TLS for sending system emails (for example, verifications or alerts).

smtp
├── enabled
├── host
├── port
├── username
├── password
└── tls

Parameter	Type	Default	Description
`enabled`	boolean	`true`	Whether to enable sending emails.
`host`	string	—	SMTP server host.
`port`	integer	`587`	SMTP server port.
`username`	string	—	Credentials for SMTP authentication.
`password`	string	—	Credentials for SMTP authentication.
`tls`	boolean	`false`	Whether to enable TLS encryption.

OAuth2

The oauth2 section defines external OAuth 2.0 identity providers (for example, Google, Microsoft, Cognito) for user authentication, with roles, scopes, and endpoint URLs.

Before configuring OAuth2, obtain credentials (client ID and secret) from your provider, for example in the Google API Console. You will also need provider-specific endpoint URLs.

oauth2
├── enabled
├── accessTokenTtl
└── providers
    ├── [0]
    │   ├── name
    │   ├── type
    │   ├── clientId
    │   ├── secret
    │   ├── scope
    │   ├── defaultRoles
    │   ├── defaultGroups
    │   └── urls
    │       ├── jwk
    │       ├── authorize
    │       ├── token
    │       ├── refresh
    │       └── revoke
    └── [1]
        └── (same structure as above)

Parameter	Type	Default	Description
`enabled`	boolean	`false`	Enables OAuth2 authentication. If `false`, OAuth2 will not work.
`accessTokenTtl`	int	`3600`	Time-to-live of the access token in seconds.
`providers`	list	empty list	List of provider configurations.
`providers` → `name`	string	—	Unique name of the provider. Becomes part of the callback URL.
`providers` → `type`	string	—	Provider type: `google`, `microsoft`, or `cognito`.
`providers` → `clientId`	string	—	Client ID obtained from the provider. Used to identify the platform.
`providers` → `secret`	string	—	Client secret obtained from the provider. Used to authenticate the platform.
`providers` → `scope`	string	—	Space-separated list of requested permissions (for example, `openid email profile`).
`providers` → `defaultRoles`	list	—	Roles assigned to new users.
`providers` → `defaultGroups`	list	—	Groups assigned to new users. Groups that don’t exist will be created automatically.
`providers` → `urls` → `jwk`	string	—	JSON Web Key Set (JWKS) endpoint. Returns the public keys used by the provider to sign tokens. The platform uses these to verify token integrity.
`providers` → `urls` → `authorize`	string	—	Authorization endpoint. Users are redirected here to log in and grant consent.
`providers` → `urls` → `token`	string	—	Token endpoint. Used to exchange an authorization code for an access token (and refresh token).
`providers` → `urls` → `refresh`	string	—	Refresh token endpoint. Used to obtain a new access token using a valid refresh token. Often the same as the `token` endpoint.
`providers` → `urls` → `revoke`	string	—	Token revocation endpoint. Allows invalidating access or refresh tokens before expiry.

faceSearch

Enables facial recognition and search capabilities using a vector database (for example, OpenSearch), with thresholds and matching parameters.

faceSearch
├── enabled
├── limit
├── threshold
└── database
    ├── type
    ├── opensearch
    │   ├── host
    │   ├── port
    │   ├── useSsl
    │   ├── verifyCerts
    │   ├── username
    │   ├── password
    │   ├── dimension
    │   ├── indexName
    │   └── awsAuth
    │       ├── enabled
    │       └── region
    └── atlas
        └── dimension

Parameter	Type	Default	Description
`enabled`	boolean	`false`	Whether to enable facial recognition search.
`limit`	integer	`1000`	Max number of search results.
`threshold`	float	`0.75`	Similarity threshold.
`database` → `type`	string	`opensearch`	Database type: `opensearch` or `atlas`.
`database` → `opensearch` → `host`	string	—	Hostname of OpenSearch.
`database` → `opensearch` → `port`	integer	`9200`	Port for OpenSearch.
`database` → `opensearch` → `useSsl`	boolean	`false`	Use SSL connection.
`database` → `opensearch` → `verifyCerts`	boolean	`false`	Whether to enable SSL certificates verification.
`database` → `opensearch` → `username`	string	—	Username.
`database` → `opensearch` → `password`	string	—	Password.
`database` → `opensearch` → `dimension`	integer	`512`	Feature vector size.
`database` → `opensearch` → `indexName`	string	—	Index used for face vectors.
`database` → `opensearch` → `awsAuth` → `enabled`	boolean	`false`	Whether to use AWS authentication when connecting to the OpenSearch service.
`database` → `opensearch` → `awsAuth` → `region`	string	—	AWS region (for example, `us-east-1`).
`database` → `atlas` → `dimension`	integer	`512`	Feature vector size for Atlas.

textSearch

Enables full-text search capabilities using a search database, for example, OpenSearch.

textSearch
├── enabled
├── limit
└── database
    ├── type
    ├── opensearch
    │   ├── host
    │   ├── port
    │   ├── useSsl
    │   ├── verifyCerts
    │   ├── username
    │   └── password
    └── atlas

Parameter	Type	Default	Description
`enabled`	boolean	`false`	Whether to enable text search.
`limit`	integer	`1000`	Max number of search results.
`database` → `type`	string	`opensearch`	Database type: `opensearch` or `atlas`.
`database` → `opensearch` → `host`	string	—	Hostname of OpenSearch.
`database` → `opensearch` → `port`	integer	`9200`	Port for OpenSearch.
`database` → `opensearch` → `useSsl`	boolean	`false`	Use SSL connection.
`database` → `opensearch` → `verifyCerts`	boolean	`false`	Whether to enable SSL certificates verification.
`database` → `opensearch` → `username`	string	—	OpenSearch Username.
`database` → `opensearch` → `password`	string	—	OpenSearch Password.

services

Toggles key microservices like API, audit logging, scheduler, workflow engine, and third-party integrations, such as docreader, faceapi.

services
├── api
│   ├── enabled
│   ├── port
│   ├── host
│   └── workers
├── audit
│   ├── enabled
│   └── wsEnabled
├── scheduler
│   ├── enabled
│   └── jobs
│       ├── expireSessions
│       │   └── cron
│       ├── reloadWorkflows
│       │   └── cron
│       ├── cleanSessions
│       │   ├── cron
│       │   └── keepFor
│       ├── expireDeviceLogs
│       │   ├── cron
│       │   └── keepFor
│       ├── reloadLocales
│       │   └── cron
│       └── cronWorkflow
│           └── cron
├── workflow
│   ├── enabled
│   └── workers
├── analytics
│   ├── enabled
│   └── connectionString
├── docreader
│   ├── enabled
│   ├── prefix
│   └── url
├── faceapi
│   ├── enabled
│   ├── prefix
│   └── url
└── indexer
    ├── enabled
    ├── timeout
    └── maxBatchSize

Service	Type	Default	Description
`api` → `enabled`	boolean	`true`	Whether to enable the main HTTP API service.
`api` → `port`	integer	`8000`	TCP port for API server.
`api` → `host`	string	`0.0.0.0`	Network interface or IP for API binding.
`api` → `workers`	integer/string	`auto`	Number of workers handling API requests.
`audit` → `enabled`	boolean	`false`	Enables audit logging service.
`audit` → `wsEnabled`	boolean	`false`	Enables WebSocket-based audit streaming to a client.
`scheduler` → `enabled`	boolean	`true`	Enables the scheduler service for background jobs.
`scheduler` → `jobs` → `expireSessions` → `cron`	string (cron)	—	Frequency for expiring inactive sessions.
`scheduler` → `jobs` → `reloadWorkflows` → `cron`	string (cron)	—	Frequency for reloading workflow definitions.
`scheduler` → `jobs` → `cleanSessions` → `cron`	string (cron)	—	Frequency for cleaning expired sessions.
`scheduler` → `jobs` → `cleanSessions` → `keepFor`	string (duration)	—	Retention period for session data (for example, `1w`).
`scheduler` → `jobs` → `expireDeviceLogs` → `cron`	string (cron)	—	Frequency for expiring device logs.
`scheduler` → `jobs` → `expireDeviceLogs` → `keepFor`	string (duration)	—	Retention period for device logs.
`scheduler` → `jobs` → `reloadLocales` → `cron`	string (cron)	—	Frequency for reloading localization files.
`scheduler` → `jobs` → `cronWorkflow` → `cron`	string (cron)	—	Frequency for cron workflows.
`workflow` → `enabled`	boolean	`true`	Enables workflow execution service.
`workflow` → `workers`	integer/string	`auto`	Number of workers for workflow service.
`analytics` → `enabled`	boolean	`false`	Enables analytics service.
`analytics` → `connectionString`	string	—	Connection string for analytics database.
`docreader` → `enabled`	boolean	`false`	Enables DocReader SDK integration.
`docreader` → `prefix`	string	—	URL path prefix for DocReader.
`docreader` → `url`	string	—	Internal URL of DocReader service.
`faceapi` → `enabled`	boolean	`false`	Enables FaceAPI integration.
`faceapi` → `prefix`	string	—	URL path prefix for FaceAPI.
`faceapi` → `url`	string	—	Internal URL of FaceAPI service.
`indexer` → `enabled`	boolean	`false`	Enables indexer service.
`indexer` → `timeout`	integer	`60`	Time to wait between two batches of indexer operations.
`indexer` → `maxBatchSize`	integer	`1000`	Maximum batch size for indexer.

mongo

Defines the MongoDB connection URL used to store and access application data.

mongo
└── url

Parameter	Type	Default	Description
`url`	string	`mongodb://localhost:27017/idv`	MongoDB connection string.

messageBroker

Defines message broker (for example, RabbitMQ) connection URL used for event-driven communication between services.

messageBroker
└── url

Parameter	Type	Default	Description
`url`	string	`amqp://admin:admin@localhost:5672/`	AMQP Message Broker connection string.

webApp

Controls the embedded IDV Portal application.

webApp
└── enabled

Parameter	Type	Default	Description
`enabled`	boolean	`true`	Whether to serve IDV Portal application.

Config File Example

config.yaml
mode: cluster
fernetKey: "z82-gpAZjBkCmwE8GJjB-Lt5kJZi9ARAI2uXTRGtEfQ="
identifier: "PQT"
baseUrl: "https://dev-idv.regulaforensics.com"

custom:
  someExternalServiceBaseUrl: https://example.com/api/

metrics:
  statsd:
    enabled: true
    host: statsd
    port: 9125
    prefix: "idv"

logging:
  level: INFO
  formatter: "%(asctime)s.%(msecs)03d - %(name)s - %(levelname)s - %(message)s"
  console: true
  file: false
  path: "/var/log"
  maxFileSize: 1.048576e7
  filesCount: 10

storage:
  type: s3
  s3:
    endpoint: http://minio:9000
    accessKey: "minioadmin"
    accessSecret: "minioadmin"
    region: "master"
    secure: false

  fs:
    path: /var/idv/data

  sessions:
    location:
      bucket: "coordinator"
      prefix: "sessions"
      folder: ""

  persons:
    location:
      bucket: "coordinator"
      prefix: "persons"
      folder: "person_files"

  idags:
    location:
      bucket: "coordinator"
      prefix: "idags"
      folder: "idag_data"

  workflows:
    location:
      bucket: "coordinator"
      prefix: "workflows"
      folder: ""

  userFiles:
    location:
      bucket: "coordinator"
      prefix: "files"
      folder: "user_files"

  locales:
    location:
      bucket: "coordinator"
      prefix: "localization"
      folder: "config"

  assets:
    location:
      bucket: "coordinator"
      prefix: "assets"
      folder: "assets_data"

mobile:
  android:
    bundleId: com.regula.app.idv
    sha256:
    - 60:92:AB:C1:E3:F1:53:5D:94:A8:CA:E5:40:85:8C:9B:3F:4A:30:99:44:88:08:1A:11:94:A0:71:6F:34:90:51
    - ED:88:29:A8:4C:7B:5B:C9:2B:5C:31:75:41:C5:F7:C4:0D:8E:A4:71:C8:86:60:E5:9E:B2:C5:CB:85:F8:C2:C4
    - 14:66:5E:B5:46:C6:0E:54:92:AA:80:85:DF:E4:6E:A4:9A:9B:B7:B5:EB:67:AD:EF:0F:AE:E2:D4:79:6C:74:7F
  apple:
    appId: "6737484022"
    bundleId: H6WR54S268.com.regula.app.idv

smtp:
  enabled: true
  host: <smtp server>
  port: 587
  username: <user name>
  password: <password>
  tls: true

oauth2:
  enabled: true
  accessTokenTtl: 3600
  providers:
    - name: google
      type: google
      clientId: "<app_id>.apps.googleusercontent.com"
      secret: "<client_secret>"
      scope: "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile"
      defaultRoles: ["demo"]
      defaultGroups: ["Demo", "Users"]
      urls:
        jwk: "https://www.googleapis.com/oauth2/v3/certs"
        authorize: "https://accounts.google.com/o/oauth2/auth"
        token: "https://accounts.google.com/o/oauth2/token"
        refresh: "https://accounts.google.com/o/oauth2/token"
        revoke: "https://accounts.google.com/o/oauth2/revoke"

    - name: azure
      type: microsoft
      clientId: "<app_id>"
      secret: "<client_secret>"
      scope: "email openid profile User.Read"
      defaultRoles: ["admin"]
      defaultGroups: []
      urls:
        jwk: "https://login.microsoftonline.com/<tenant_id>/discovery/v2.0/keys"
        authorize: "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/authorize"
        token: "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token"
        refresh: "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token"
        revoke: "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/revoke"

    - name: cognito
      type: cognito
      clientId: "<app_id>"
      secret: "<client_secret>"
      scope: "openid email profile"
      defaultRoles: ["user"]
      defaultGroups: ["CognitoUsers"]
      urls:
        jwk: "https://cognito-idp.<region>.amazonaws.com/<user_pool_id>/.well-known/jwks.json"
        authorize: "https://<domain>.auth.<region>.amazoncognito.com/oauth2/authorize"
        token: "https://<domain>.auth.<region>.amazoncognito.com/oauth2/token"
        refresh: "https://<domain>.auth.<region>.amazoncognito.com/oauth2/token"
        revoke: "https://<domain>.auth.<region>.amazoncognito.com/oauth2/revoke"

faceSearch:
  enabled: true
  limit: 1000
  threshold: 0.75
  database:
    type: opensearch
    opensearch:
      host: "opensearch"
      port: 9200
      useSsl: false
      verifyCerts: false
      username: "admin"
      password: ""
      dimension: 512
      indexName: "hnsw"
      awsAuth:
        enabled: false
        region: ""
        accessKey: ""
        secretKey: ""


textSearch:
  enabled: true
  limit: 1000
  database:
    type: opensearch
    opensearch:
      host: "opensearch"
      port: 9200
      useSsl: false
      verifyCerts: false
      username: admin
      password: ""
      awsAuth:
        enabled: false
        region: ""
        accessKey: ""
        secretKey: ""
  atlas:
    dimension: 512


services:
  api:
    enabled: true
    port: 8000
    host: "0.0.0.0"
    workers: auto

  analytics:
    enabled: true
    connectionString: http://username:password@db-host:8123/idv

  audit:
    enabled: true
    wsEnabled: true

  scheduler:
    enabled: true
    jobs:
      expireSessions:
        cron: "*/10 * * * * *"
      reloadWorkflows:
        cron: "*/5 * * * * *"
      cleanSessions:
        cron: "*/30 * * * * *"
        keepFor: "1w" # 5s, 10m, 15w, 1y, 1w, 30d, 1h, 2m, 3s
      expireDeviceLogs:
        cron: "*/5 * * * *"
        keepFor: "30d"
      reloadLocales:
        cron: "*/15 * * * * *"
      cronWorkflow:
        cron: "*/30 * * * * *"

  workflow:
    enabled: true
    workers: auto

  docreader:
    enabled: true
    prefix: drapi
    url: "http://docreader.docreader.svc.cluster.local:80"

  faceapi:
    enabled: true
    prefix: faceapi
    url: "http://faceapi.faceapi.svc.cluster.local:80"

  indexer:
    enabled: true
    timeout: 60
    maxBatchSize: 1000

webApp:
  enabled: true

mongo:
  url: mongodb://mongo-username:mongo-password@mongodb:27017/idv?tlsInsecure=true&directConnection=true

messageBroker:
  url: amqp://admin:admin@localhost:5672/