Application / Server Configuration
The main nevisFIDO configuration is specified in a file in standard YAML format. You find the file in the instance directory: /var/opt/nevisfido/<instance>/conf/nevisfido.yml.
The nevisFIDO component will fail to start if incorrect configuration is provided. Observe the logs to obtain more detailed information regarding the issue. This applies to known configuration properties, unknown properties are simply ignored and do no lead to a startup failure.
Application Configuration
It is possible to replace the configuration by supplying a custom --config location in the RUN_ARGS environment variable in the env.conf file of the instance.
Some property values are expressions that will be replaced. The next list shows the available syntax:
-
${exec:command}Executes the given command and uses its output as the value.
Example:
server.host: ${exec:hostname -f} -
${env:variablename}Uses the value of the specified environment variable.
Example:
server.host: ${env:HOSTNAME}
Server Configuration
The server configuration defines the configuration of the main web server.
-
server.portWeb application port. If not specified, the default value is 8080.
-
server.hostNetwork address to which the server must bind. By default, it binds to all available interfaces (that is, "0.0.0.0").
-
server.protocolEither
httporhttps. It is advisable to always run nevisFIDO inhttpsmode. Refer to theserver.tlssettings for configuring TLS if set tohttps. -
server.connection-timeoutThe time after which idle connections will be terminated. The default value is 30 seconds. If no time unit is provided, seconds will be used.
-
server.max-http-header-sizeMaximum size of the HTTP request header in bytes. The default value is 8192 bytes. Increase this value when clients send large headers, for example large cookies or tokens.
-
server.tls.keystorePath to the keystore that holds the TLS certificate of nevisFIDO.
-
server.tls.keystore-passphrasePassword used to access the keystore and the key. Use the mechanisms described in Application Configuration to avoid providing a plaintext password.
-
server.tls.keystore-typeDefines the type of keystore. It is recommended using a "pkcs12" type of keystore. If not specified, the system will use the default keystore type of the Java Virtual Machine that runs nevisFIDO.
-
server.tls.key-aliasAlias that identifies the key in the keystore.
-
server.tls.client-authControls client authentication (2-way TLS) for the TLS connection. Accepted values:
required- client authentication is mandatory.requested- client authentication is requested but not enforced.disabled- client authentication is not required.
noteThe legacy boolean property
server.tls.require-client-authis deprecated. Useserver.tls.client-authinstead. Migration:require-client-auth: true→client-auth: required;require-client-auth: false→client-auth: requested. -
server.tls.truststorePath to the truststore that holds the TLS certificates (typically a PKCS12 file) that nevisFIDO trusts. These are the certificates presented by the client when doing client authentication.
-
server.tls.truststore-passphrasePassword used to access the truststore contents. Use the mechanisms described in Application Configuration to avoid providing a plaintext password.
-
server.tls.truststore-typeDefines the type of truststore. It is recommended using a "pkcs12" type of keystore. If not specified, the system will use the default keystore type of the Java Virtual Machine that runs nevisFIDO.
-
server.tls.supported-protocolsProvides a list of protocols that are accepted by the client when trying to initiate a connection with TLS. This attribute must be provided as an array. By default only
TLSv1.3is supported.If you require TLSv1.2, set
server.tls.supported-protocolstoTLSv1.2explicitly. When both protocols are configured, nevisFIDO accepts connections using either version. -
server.tls.cipher-suitesProvides a list of ciphers that are accepted by the client when trying to initiate a connection with TLS. This attribute must be provided as an array. The default cipher suites depend on the configured protocol:
For TLSv1.3 (default):
TLS_AES_128_GCM_SHA256TLS_AES_256_GCM_SHA384TLS_CHACHA20_POLY1305_SHA256
For TLSv1.2:
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384TLS_DHE_RSA_WITH_AES_128_GCM_SHA256TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
When both TLSv1.3 and TLSv1.2 are configured, the TLSv1.3 cipher suites are included first, followed by the TLSv1.2 cipher suites.
server:
port: 9443
host: localhost
protocol: https
connection-timeout: 30s
tls:
keystore: conf/nevisfido-server-keystore.p12
keystore-passphrase: password
keystore-type: pkcs12
key-alias: nevisfido
supported-protocols:
- TLSv1.3
cipher-suites:
- TLS_AES_128_GCM_SHA256
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
Management Configuration
Configuration of the liveness and readiness endpoints. For the endpoints, the API versions, and response examples, see Management Endpoints.
-
management.server.portPort where the management server listens. Default:
9089. It must differ fromserver.port. -
management.healthchecks.enabledEnables the liveness and readiness endpoints. Default:
false. -
management.healthchecks.default-api-versionAPI version used if the
api-versionrequest header is missing, empty, or unsupported. Allowed values:1.0,2.0. An invalid value is ignored with a warning. Default:2.0. -
management.healthchecks.ignore-indicatorsChecks to exclude from the readiness result. Default:
mds3,androidAttestationKeyRevocation,fcm. Setting the property replaces the default list. Use an empty list to include all checks. -
management.healthchecks.database.active.timeoutTime limit of the active database check. Allowed range:
1msto less than5s. Default:2s. -
management.healthchecks.database.passive.evidence-max-ageHow long the outcome of a connection pool borrow counts as evidence. Default:
10s. -
management.healthchecks.database.passive.failure-thresholdNumber of consecutive failed borrows that make the readiness
DOWN. Allowed range:1to256. Default:3. -
management.healthchecks.database.passive.pool-wait-thresholdWait time for a pool connection from which the pool counts as exhausted. Default:
5s.
management:
server:
port: 9089
healthchecks:
enabled: true
default-api-version: "2.0"
Credential Repository Configuration
The credential repository holds the registered credentials. nevisFIDO needs access to this repository to be able to perform the following actions:
- Adding credentials.
- Reading credentials.
- Removing credentials.
You specify the configuration of the credential repository with the credential-repository attribute:
-
credential-repositoryThe root node of the credential repository configuration.
-
credential-repository.typeDefines the type of the credential repository. Currently, you can configure two types of credential repositories, the in-memory and the nevisIDM types of credential repository.
In-Memory Credential Repository
In case of an in-memory type of credential repository, the registered credentials are stored in the memory. The registered credentials will be lost when you stop nevisFIDO. This type of credential repository is therefore mainly used for testing purposes.
To define an in-memory type of credential repository, set the value of the type attribute to "in-memory". The in-memory repository does not have additional configuration options.
credential-repository:
type: in-memory
Do not use actively in production setups.
nevisIDM Credential Repository
In case of a nevisIDM type of credential repository, the FIDO UAF credentials, the dispatch targets and the iOS App Attestation data are stored in nevisIDM. nevisFIDO manages them through the dedicated-entity REST API of nevisIDM: FIDO UAF credentials as FIDO authenticators, dispatch targets as Dispatch Target entities, and iOS App Attestation data as the App Attestation of the dispatch target it belongs to.
nevisFIDO no longer reads or writes dispatch targets and iOS App Attestation credentials stored as nevisIDM generic credentials. Before you upgrade nevisFIDO to this release, migrate the existing generic credentials to dedicated entities as described in Migrating Dispatch Target From Generic Credentials to Dedicated Entities. Dispatch targets that were not migrated are not found at runtime, so out-of-band operations can no longer reach the affected devices.
If you select this type of repository, nevisFIDO needs key material to connect to nevisIDM. The connection is based on TLS Client Authentication. This means that both parties require a correctly set up private key and public certificate to be able to trust each other. The public certificate of nevisIDM has to be imported into nevisFIDO’s truststore and vice versa.
nevisFIDO has 60 seconds to establish connections to and execute requests with nevisIDM before a timeout will occur.
To define a nevisIDM type of credential repository, set the value of the type attribute to "nevisidm".
The nevisIDM credential repository has the following additional configuration attributes:
-
rest-urlDefines the URL pointing to the root endpoint of the nevisIDM REST API. For example:
https://nevisidm.siven.ch:8443/nevisidm. Configuring the REST URL is required. -
keystoreDefines the path to the keystore holding the nevisFIDO client certificate. nevisIDM must have a technical user whose certificate credential contains the public key of this nevisFIDO client certificate.
-
keystore-passphraseSets the password of the keystore. It is assumed that this keystore password can be used to access the key. Use the mechanisms described in Application Configuration to avoid providing a plaintext password.
-
keystore-typeDefines the type of keystore. A "pkcs12" type of keystore is recommended. Using the legacy Java key-/truststore "jks" is also possible. If you do not specify this attribute, the system will use the default keystore type of the Java Virtual Machine that runs nevisFIDO.
-
truststorePath to the truststore containing the nevisIDM public key.
-
truststore-passphraseDefines the password used to access the truststore. Use the mechanisms described in Application Configuration to avoid providing a plaintext password.
-
truststore-typeDefines the type of truststore. A "pkcs12" truststore type is recommended. Using the legacy Java key-/truststore "jks" is also possible. If you do not specify this attribute, the system will use the default truststore type of the Java Virtual Machine that runs nevisFIDO.
-
client-idSpecifies the ID of the nevisIDM client that contains the relevant data. Configuring the client ID is required.
-
user-attributeSpecifies how the
usernameprovided by the client applications is mapped to a user in nevisIDM. The user will be looked up in nevisIDM based on the provided information, if not found the operation will be aborted immediately. The allowed values areextId, andloginId. If not defined, theextIdattribute is used as value of the attribute.For UAF the username is provided in the context of the
GetUAFRequest( for registration , authentication and deregistration). For FIDO2, the username is provided in theOptionsRequestfor registration and authentication. -
login-info-update(String, optional, always)Defines which type of operations should update the success/failure authentication count in the credentials stored in nevisIDM.
alwayswill update the counters for both authentication and transaction confirmation operations.authenticationwill update the counters only for authentication operations. Note that technically both authentication and transaction confirmation is an authentication, but transaction confirmation is part of the payload. Therefore the distinction between those two is done by checking the payload.infoVisit successful login tracking and failed login tracking for additional details.
-
credential-cache-enabled(Boolean, opional, true)A request-scoped credential cache for FIDO UAF credentials. By default it is enabled.
-
use-dedicated-entities(removed)This property was removed in the November 2026 release, because nevisFIDO always uses the dedicated-entity REST API of nevisIDM. Remove it from your configuration:
- If it is set to
true, nevisFIDO logs a warning and starts. - If it is set to
false, nevisFIDO logs an error and does not start. Migrate the generic credentials as described in Migrating Dispatch Target From Generic Credentials to Dedicated Entities, then remove the property and start nevisFIDO again.
The nevisAdmin4 property Credential Management API of the nevisFIDO instance pattern, which generated this property, was removed as well.
- If it is set to
-
connection-keepalive(String, optional, 10)Connection keepalive to use when no
Keep-Alivepolicy in the HTTP header is specified. The default value is 10 seconds. If no time unit is provided, seconds will be used. -
connection-timeout(String, optional, 30)The HTTP client connection timeout. The default value is 30 seconds. If no time unit is provided, seconds will be used. The connection timeout defines how long the communication between a client and a server is allowed to take. The property is applied to the following: connecting to the specified url (connection timeout), receiving response from the target (socket timeout).
-
connection-pool-max-total(Integer, optional, 50)The maximum number of total open connections in the connection pool.
-
connection-pool-max-per-route(Integer, optional, 50)The maximum number of connections per route in the connection pool.
-
connection-pool-timeout(String, optional, 0)The HTTP client pool keep-alive timeout. If no time unit is provided, seconds will be used. With the default value of 0 there is no timeout (Infinite). The pool will actively close idle connections when the timeout is reached.
The username mapper is experimental and there are no guarantees that it will be kept in the future.
credential-repository:
type: nevisidm
rest-url: https://nevisauth-fido-test1.zh.nevis-security.com:8443/nevisidm
keystore: /var/opt/nevisfido/default/conf/keystore.p12
keystore-passphrase: password
keystore-type: pkcs12
truststore: /var/opt/nevisfido/default/conf/truststore.p12
truststore-passphrase: password
truststore-type: pkcs12
client-id: 100
user-attribute: loginId
Session Repository Configuration
Sessions managed by nevisFIDO are stored either in the memory or in a (MariaDB) SQL database.
You specify the configuration of the session storage with the session-repository attribute:
-
session-repositoryThe root node of the session repository configuration.
-
session-repository.typeThe type of the session repository. The default value is "in-memory".
In-Memory Session Repository
The in-memory session repository is selected by setting "in-memory" as the repository type. This type of session repository has no other configuration options.
session-repository:
type: in-memory
The in-memory session repository is the default. It will also be selected if the above configuration is omitted.
We recommend only using in-memory for development and testing purposes. Use the SQL session repository for production setups.
The session-repository.type setting also selects the backend that stores request identifiers used for replay protection of signed device requests (for example, dispatch-target modification, device credential, and out-of-band operations). The in-memory backend keeps sessions and this replay-protection state per pod, so they are not shared across nevisFIDO instances. In a Kubernetes multi-pod deployment, replay protection and session lookups would then only work within the pod that handled the original request. Use the SQL session repository in such deployments so that sessions and replay-protection state are shared across all pods.
SQL Session Repository
The SQL session repository is selected by configuring "sql" as the repository type. nevisFIDO comes bundled with MariaDB and PostgreSQL client capability. MariaDB and PostgreSQL are the officially supported SQL storage backend.
The SQL session repository needs a JDBC URL for locating the database, and a user and password for authentication. It is recommended to create a dedicated database to store the nevisFIDO session information.
The database schema is created and migrated with the nevisfido-dbschema image, which contains the Flyway migrations for all nevisFIDO tables. In Kubernetes-based deployments, nevisOperator runs the image for you, or your database administrator runs it as a migration job. For the available approaches and the required database users, see Database Management. The user configured in user only requires SELECT, INSERT, UPDATE, and DELETE access rights on the tables.
The automatic table creation by nevisFIDO (automatic-db-schema-setup, schema-user, and schema-user-password) is deprecated since nevisFIDO 9.2611.0 and is planned for removal in the May 2027 Rolling Release. This follows the move to Kubernetes and SaaS deployments, where the dbschema images manage the database schema, and is in line with the Classic Deployment retirement. The automatic table creation does not apply schema changes to existing tables. Use the nevisfido-dbschema image to create and migrate the database schema, and set automatic-db-schema-setup to false.
The required attributes are:
-
jdbc-urlThe JDBC URL to the database.
Examples (standard):
- jdbc:mariadb://localhost:3306/db?autocommit=true
- jdbc:postgresql://localhost:5432/db
Examples (one-way TLS):
- jdbc:mariadb://server.sieven.ch:3306/db?sslMode=verify-ca
- jdbc:mariadb:sequential//server_1.sieven.ch:3306,server_2.sieven.ch:3306/db?sslMode=verify-ca
- jdbc:postgresql://server.sieven.ch:5432/db?ssl=true&sslmode=verify-ca
For TLS connections, MariaDB uses the sslMode parameter (camelCase) and PostgreSQL uses lowercase sslmode with ssl=true.
For more information visit the official connection parameter documentation for MariaDB and PostgreSQL. For TLS options, see the MariaDB Connector/J TLS documentation and the PostgreSQL JDBC SSL documentation.
-
userThe user name needed to access the database.
-
passwordThe password needed to access the database. Use the mechanisms described in Application Configuration to avoid providing a plaintext password.
-
schema-user(deprecated)Deprecated since nevisFIDO 9.2611.0 and planned for removal in the May 2027 Rolling Release. See SQL Session Repository.
The user name of the user who creates the schema and the tables in the database. If you do not provide a schema user here, the system will use the user specified in the attribute
userto create the schema. However, it is recommended having different users for creating the schema and for accessing the data.
If you do not set the schema-user attribute, do not set the schema-user-password attribute either. Otherwise the system will throw an error. This is because the system takes the user as fallback if no schema-user is provided. If in this case both the password attributes schema-user-password and password are set, there are two passwords available for the user attribute, which is ambiguous.
-
schema-user-password(deprecated)Deprecated since nevisFIDO 9.2611.0 and planned for removal in the May 2027 Rolling Release. See SQL Session Repository.
The password of the
schema-user, that is, the user who creates the schema and the tables in the database. If you do not provide the schema user password, the system takes the password specified in the attributepasswordas fallback. Use the mechanisms described in Application Configuration to avoid providing a plaintext password. -
automatic-db-schema-setup(deprecated)Deprecated since nevisFIDO 9.2611.0 and planned for removal in the May 2027 Rolling Release. See SQL Session Repository.
If set to
true, the tables used to store the session data will be created automatically by nevisFIDO when they are missing. Note that it will not apply patches on existing tables. Set this property tofalsewhen the database schema is managed with the nevisfido-dbschema image. If not specified, the default value istrue. -
connection-timeoutDefines the maximum time that nevisFIDO waits for the connection to receive a response from the Database. Default is 30 seconds.
-
max-connection-lifetimeDefines the maximum time that a database connection remains in the connection pool. Although having a high value improves the performance, it should be lower than the connection idle timeout of the database (parameter * wait_timeout* in MariaDB). If not specified, the default value is 30 minutes. If no time unit is provided, seconds will be used.
-
max-connection-idle-timeThe maximum time (If no time unit is provided, seconds), that an idle connection is kept in the connection pool. (Only applicable if the min and max size of the connection pool is different). Default value is 10 minutes.
-
min-connection-pool-sizeDefines the minimum number of connections to be idle in the connection pool. Default value is 10. For the best performance it is recommended to keep the min and the max value the same so there is no need to ramp up and down connections. Setting the minimum pool size does not affect the maximum pool size, when setting it to a higher value than the default adjust the maximum pool size as well.
-
max-connection-pool-sizeDefines the maximum number of connections allowed in the connection pool. Default value is 10.
session-repository:
type: sql
jdbc-url: 'jdbc:mariadb://localhost:3306/db'
user: data-user
password: secret
automatic-db-schema-setup: false
session-lifetime: 25m