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.

Configuration Structure

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

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 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.
workflow.enabled	Boolean	true	Enables workflow execution service.
workflow.workers	integer/string	auto	Number of workers for workflow service.
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.
audit.enabled	Boolean	false	Enables audit logging service.
audit.wsEnabled	Boolean	false	Enables WebSocket-based audit streaming to a client.
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

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/