Skip to main content

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.

info

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.

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.port

    Web application port. If not specified, the default value is 8080.

  • server.host

    Network address to which the server must bind. By default, it binds to all available interfaces (that is, "0.0.0.0").

  • server.protocol

    Either http or https. It is advisable to always run nevisFIDO in https mode. Refer to the server.tls settings for configuring TLS if set to https.

  • server.connection-timeout

    The 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.tls.keystore

    Path to the keystore that holds the TLS certificate of nevisFIDO.

  • server.tls.keystore-passphrase

    Password used to access the keystore and the key. Use the mechanisms described in Application Configuration to avoid providing a plaintext password.

  • server.tls.keystore-type

    Defines 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-alias

    Alias that identifies the key in the keystore.

  • server.tls.require-client-auth

    true if client authentication (2-way TLS) is required for the TLS connection, false if no client authentication is required.

  • server.tls.truststore

    Path 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-passphrase

    Password used to access the truststore contents. Use the mechanisms described in Application Configuration to avoid providing a plaintext password.

  • server.tls.truststore-type

    Defines 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-protocols

    Provides 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.2 is supported.

  • server.tls.cipher-suites

    Provides 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 are:

    • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
    • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
    • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
    • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
Server configuration example
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.2
    cipher-suites:
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

Management Configuration​

Configuration of liveness and readiness probes.

The configuration described in this section are experimental and can change in future releases.

  • management.server

    Main node of the management server configuration properties.

  • management.server.port

    Port where the management server listens. Currently this includes the readiness probe.

  • management.healthchecks

    Main node for health probe configurations.

  • management.healthchecks.enabled

    Enables liveness and readiness probes.

Management configuration example
management:
  server:
    port: 9452
  healthchecks:
    enabled: false

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-repository

    The root node of the credential repository configuration.

  • credential-repository.type

    Defines 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.

In-memory credential repository configuration example
credential-repository:
  type: in-memory
caution

Do not use actively in production setups.

nevisIDM Credential Repository​

In case of a nevisIDM type of credential repository, the FIDO UAF credentials are stored in nevisIDM.

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.

tip

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-url

    Defines 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.

  • keystore

    Defines 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-passphrase

    Sets 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-type

    Defines 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.

  • truststore

    Path to the truststore containing the nevisIDM public key.

  • truststore-passphrase

    Defines the password used to access the truststore. Use the mechanisms described in Application Configuration to avoid providing a plaintext password.

  • truststore-type

    Defines 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-id

    Specifies the ID of the nevisIDM client that contains the relevant data. Configuring the client ID is required.

  • user-attribute

    Specifies how the username provided 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 are extId, and loginId. If not defined, the extId attribute 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 the OptionsRequest for registration and authentication.

  • connection-keepalive (String, optional, 10)

    Connection keepalive in seconds to use when no Keep-Alive policy in the HTTP header is specified.

  • connection-timeout (String, optional, 30)

    The HTTP client connection timeout value in seconds. With the default value of 30 seconds. 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 (Integer, optional, 0)

    The HTTP client pool keep-alive timeout value in seconds. With the default value of 0 there is no timeout (Infinite). The pool will actively close idle connections when the timeout is reached.

info

The username mapper is experimental and there are no guarantees that it will be kept in the future.

nevisIDM credential repository configuration example
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-repository

    The root node of the session repository configuration.

  • session-repository.type

    The 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.

In-memory session repository configuration example
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.

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. nevisFIDO will automatically initially generate the required tables in the specified database (no patches are applied later). It is recommended to create a dedicated MariaDB database to store the nevisFIDO session information. The required attributes are:

  • jdbc-url

    The JDBC URL to the database.

info

Examples:

  • jdbc:mariadb://localhost:3306/db?autocommit=true
  • jdbc:postgresql://localhost:5432/db

For more information visit the official connection parameter documentation for MariaDB and PostgreSQL

  • user

    The user name needed to access the database.

  • password

    The password needed to access the database. Use the mechanisms described in Application Configuration to avoid providing a plaintext password.

  • schema-user

    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 user to create the schema. However, it is recommended having different users for creating the schema and for accessing the data.

info

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

    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 attribute password as fallback. Use the mechanisms described in Application Configuration to avoid providing a plaintext password.

  • automatic-db-schema-setup

    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. For non-docker-based setups, those patches has to be manually applied based on the release notes. Set this property to false if the database must be not be set-up automatically. If not specified, the default value is true.

  • connection-timeout

    Defines the maximum time that nevisFIDO waits for the connection to receive a response from the Database. Default is 30 seconds.

  • max-connection-lifetime

    Defines 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-time

    The 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 seconds.

  • min-connection-pool-size

    Defines 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-size

    Defines the maximum number of connections allowed in the connection pool. Default value is 10.

SQL session repository configuration example
session-repository:
  type: sql
  jdbc-url: 'jdbc:mariadb://localhost:3306/db'
  user: data-user
  password: secret
  schema-user: schema-user
  schema-user-password: schema-secret
  automatic-db-schema-setup: true
  session-lifetime: 25m