Skip to main content

nevisadmin-plugin-fido2

FIDO2 Authentication​

Use FIDO2 for passwordless authentication.

This step may be assigned for FIDO2 Authenticator in nevisIDM Second-Factor Selection.

Renders a Gui with name fido2_auth.

This Gui name is handled by the default Login Template (in js_end.vm) by including JavaScript. The JavaScript then triggers authentication using the WebAuthn protocol.

You may allow users to opt out by assigning a step to On Cancel.

nevisFIDO FIDO2​

Assign a nevisFIDO FIDO2 Instance.

On Success​

Assign an authentication step to continue with after successful authentication.

On Cancel​

If assigned a button with label 'fido2.cancel.button.label' will be added.

Use to provide an alternative to the user when the user decides to cancel the authentication or the authentication fails and the error cannot be handled.

User Verification​

User verification is a crucial step during WebAuthn authentication process as it confirms that the person attempting to authenticate is indeed the legitimate user.

This setting allows to configure the user verification requirements for authentication.

Allowed values:

  • discouraged
  • preferred
  • required

User Name​

The username is used by nevisFIDO to look up the user in nevisIDM.

Depending on how the nevisFIDO FIDO2 Instance is configured, either the extId or the loginId have to be used.

AuthState Class​

Select one of the available implementations.

When ScriptState is selected, all requests sent by JavaScript are directed towards nevisAuth. The script takes care of the communication with the nevisFIDO component, and thus you can restrict access to nevisFIDO. There is no need to expose any nevisFIDO APIs on the nevisProxy Virtual Host.

When Fido2AuthState is selected, configuration for Fido2AuthState is generated. FIDO2 related requests are sent to nevisFIDO instead. This requires that the following nevisFIDO APIs are exposed on the nevisProxy Virtual Host:

  • /nevisfido/fido2/attestation/options
  • /nevisfido/fido2/assertion/result
  • /nevisfido/fido2/status

The easiest way to ensure this is to add a nevisFIDO FIDO2 REST Service pattern to your project.

It is recommended to select the Fido2AuthState implementation as it is a more pragmatic solution whereas the ScriptState is likely to be decommissioned.

This pattern is experimental and likely to change in future releases.

Authentication Level​

Authentication level that is set on success.

FIDO2 Management Demo​

#DEMO/TESTING ONLY - NOT FOR PRODUCTION USE

Serves a simple HTML page with JavaScript to register a FIDO2 authenticator.

This is a simple and bare-bone example for demonstration and testing purposes and not intended for production use. It works only when the extId is used as username. Provide your own version adapted to your integration scenario.

For instance, use Hosting Service to deploy your HTML and JavaScript on a nevisProxy Virtual Host or Generic Authentication Step when the registration shall be done within an authentication flow.

Visit the official WebAuthn Guide for further information on how to do FIDO2-based registration and authentication.

The nevisFIDO FIDO2 Instance must be exposed on the same Virtual Host using nevisFIDO FIDO2 REST Service pattern.

In the nevisFIDO FIDO2 Instance pattern Relying Party ID and Relying Party Origins must be set correctly, to allow AJAX calls from the JavaScript.

The client certificate used by nevisFIDO FIDO2 Instance must be uploaded as a certificate credential for the nevisfido technical user. This should be done automatically in Kubernetes deployments but best double-check.

The credential type 23 must be allowed in the nevisIDM unit policy so that a FIDO2 Authenticator credential can be created for the authenticated user.

Virtual Host​

Assign a Virtual Host which shall serve as entry point.

Frontend Path​

Enter the path where this example shall be exposed on the nevisProxy Virtual Host.

Authentication Realm​

Optionally assign a realm to protect this application or service.

Additional Settings​

Assign add-on patterns to customize the behaviour of this service.

Example use cases:

  • Authorization Policy to enforce roles or an authentication level.
  • URL Handling to redirect or forward requests.
  • HTTP Header Customization to add, replace, or remove HTTP headers in requests or responses.

FIDO2 Onboarding​

Use for onboarding when the user has no FIDO2 credential in nevisIDM.

This step may be used as a follow-up of Not Found in nevisIDM Second-Factor Selection.

This step renders Guis with name fido2_onboard.

This Gui name is handled by the default Login Template (in js_end.vm) by including JavaScript files:

  • base64.js
  • fido2_utils.js
  • fido2_onboard.js

The JavaScript triggers device onboarding using the WebAuthn protocol when the Continue or Try Again button is clicked.

These buttons have a special name onclick which is handled in the logrend template by adding onClick.

You may allow users to opt out by assigning a step to On Cancel.

nevisFIDO FIDO2​

Assign a nevisFIDO FIDO2 Instance.

On Success​

Assign an authentication step to continue with after successful FIDO2 onboarding.

On Unsupported​

Assign a step to continue with when the browser does not support FIDO2 WebAuthn.

On Cancel​

If assigned a skip button will be added.

Use to provide an alternative to the user.

The button is defined by the label info.signup.passwordless.skip and looks like a link.

Translations for this label must include a button with name cancel-bottom. Example:

<button name="cancel-bottom" type="submit" value="true" class="btn btn-link link-primary">Skip for now</button>

User Name​

The username is used by nevisFIDO to look up the user in nevisIDM.

Depending on how the nevisFIDO FIDO2 Instance is configured, either the extId or the loginId have to be used.

Display Name​

Enter a 1 line Groovy statement to determine the displayName included in the call to the Registration Options Service.

The statement must produce a String.

The displayName is required by nevisFIDO and may be shown to the user by some devices.

Examples:

"${session['ch.nevis.idm.User.firstName']}_${session['ch.nevis.idm.User.name']}"

Authenticator Type​

Describes the authenticators' attachment modalities.

Allowed values:

  • any - does not set a specific value accepting the standard's default
  • platform - indicates a platform authenticator, such as Windows Hello
  • cross-platform - indicates a roaming authenticator, such as a security key

Resident Key​

WebAuthn enables high assurance multi-factor authentication with a passwordless login experience. One of the things that enables this is what is called Discoverable Credentials, also referred to as resident keys. This property specifies the extent to which the Relying Party desires to create a client-side discoverable credential.

Allowed values:

  • unspecified
  • discouraged
  • preferred
  • required

User Verification​

User verification is a crucial step during WebAuthn authentication process as it confirms that the person attempting to authenticate is indeed the legitimate user.

This setting allows to configure the user verification requirements for onboarding.

Allowed values:

  • discouraged
  • preferred
  • required

Attestation​

Define the preference for attestation conveyance.

You can configure if you want an attestation statement.

  • none - no attestation statement required.
  • direct - receive an attestation statement as produced by the authenticator.
  • indirect - requests an attestation statement but allows the client to modify what has been received from the authenticator (e.g. for anonymization).

Welcome Screen Button​

Configure to add a dispatcher button to the welcome screen.

The button may have a special Button Name to render in a nice way by a customized Login Template.

For instance, Identity Cloud uses this mechanism to add a button which looks like a back arrow. This button takes the user to a previous step.

This is an advanced setting. Use only when you understand the concept.

Failed Screen Button​

Configure to add a dispatcher button to the failed screen.

The button may have a special Button Name to render in a nice way by a customized Login Template.

For instance, Identity Cloud uses this mechanism to add a button which looks like a back arrow. This button takes the user to a previous step.

This is an advanced setting. Use only when you understand the concept.

Generic nevisFIDO FIDO2 Instance Settings​

Use this add-on pattern to set low-level properties in configuration files of a nevisFIDO FIDO2 Instance.

Java Opts​

Add additional entries to the JAVA_OPTS environment variable.

Use the expression ${instance} for the instance name.

For instance, you may configure nevisFIDO to create a heap dump on out of memory as follows:

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/opt/nevisfido/${instance}/log/

Be aware that this example will not work for Kubernetes as the pod will be automatically restarted on out of memory and the created heap dump files will be lost.

nevisFIDO FIDO2 Database​

Configures nevisFIDO to use a MariaDB database for storing sessions. Assign to nevisFIDO FIDO2 Instance as Database.

When deploying to Kubernetes, the database and connection user will be created automatically. The database schema will be migrated automatically when upgrading Nevis on the next deployment.

In classic VM deployment you have to provide an empty database and a schema user. The schema user is used by nevisFIDO to populate the database during startup.

Setup instructions can be found in the nevisFIDO technical documentation.

Database Type​

Choose between MariaDB and PostgresSQL.

We recommend to use MariaDB as it is supported by all Nevis components that have a database.

Note: PostgresSQL database is only experimental configuration.

Database Host​

Enter the host name of the database service.

The database service must be up when you deploy.

In a classic deployment the Database User and Database Password is used to connect.

In Kubernetes deployment a connection user and password will be generated and the Root Credential will be used to set up the database schema.

Database Name​

Here you can change the name of the database.

The database name only needs to be changed when the database service contains multiple databases.

Root Credential​

Enter the name of a Kubernetes secret which contains the user and password of a database root account.

Required in Kubernetes deployment when Advanced Settings / Database Management is to complete or schema.

This is the default behaviour in Kubernetes.

With complete the secret should contain the following:

username: <root-user
password: <root-password>

If the Database Management is set to schema the root user can be omitted, but the application and schema user has to be specified:

ownerUsername: <some-username>
ownerPassword: <some-password>
appUsername: <some-username>
appPassword: <some-password>

If used with complete the app and owner users will be created with the credentials specified in the secret.

Due to the usage of schemas, it is recommended to create a separate Kubernetes secret for each database pattern with the app and owner credentials when using Oracle or PostgreSQL.

Root Credential Namespace​

Set if the Root Credential is in a different Kubernetes namespace.

Schema User​

The user which will be used to connect to the database and create the schema (tables).

The database must have been created already (CREATE DATABASE) and the user must have CREATE privileges for this database.

Example: schema-user

Schema User Password​

The password of the user on behalf of the schema will be created in the database.

Database User​

Database connection user.

This setting is used in the following cases:

  • Classic deployments (VM)
  • In Kubernetes when 'Database Management' (Advanced Settings) is set to 'disabled'.

Database Password​

Password for the database connection user.

This setting is used in the following cases:

  • Classic deployments (VM)
  • In Kubernetes when 'Database Management' (Advanced Settings) is set to 'disabled'.

Encryption​

Enables SSL/TLS in a specific mode. The following values are supported:

  • disabled: Do not use SSL/TLS (default)
  • trust: Only use SSL/TLS for encryption. Do not perform certificate or hostname verification. This mode is not safe for production applications but still safer than disabled.
  • verify-ca: Use SSL/TLS for encryption and perform certificates verification, but do not perform hostname verification.
  • verify-full: Use SSL/TLS for encryption, certificate verification, and hostname verification.

Trust Store​

Assign a trust store which provides the CA certificate of the DB endpoint.

Key Store​

Define the key store to use for 2-way HTTPs connections for DB endpoint.

This configuration only accept PEM Key Store pattern configuration.

Noted: This is an experimental configuration

Database Management​

The pattern can set up the database, and it's schema when deploying to Kubernetes.

The complete option, on top of handling the schema migration, will do the initial database preparation like creating the actual database or tablespace in case of oracle, as well as creating the required database users.

The schema option will skip the initial preparation and will only take care of the actual schema migration. This requires the schema owner and the application user credentials to be present in the root credential secret. The root user information can be omitted with this option.

You can select disabled here to opt out. In this case you have to create and migrate the database schema yourself.

This feature is set to recommended by default which aims for the most convenient solution based on the deployment type. In case of Kubernetes deployments, it uses complete. In a classical VM deployment, it will use schema if the pattern allows setting Schema User and Schema Password, otherwise it's disabled.

Maximum Connection Lifetime​

Defines the maximum time that a session database connection remains in the connection pool.

Connection Parameters​

Enter parameters for the DB connection string.

The default value will be used only when no parameters are entered.

If you want to keep the default parameters, add them as well.

Enter 1 parameter per line.

Lines will be joined with &.

Examples (from various Nevis components):

pinGlobalTxToPhysicalConnection=1
useMysqlMetadata=true
autocommit=0

Connection URL​

Set only if you have to use a JDBC connection string which the pattern cannot generate.

If the prefix of the connection string works for you and you only have to add or overwrite query parameters, set Connection Parameters instead.

If you have to use this setting, please consult your setup with your integration partner.

In Kubernetes deployments the connection string configured here is used by the component only. It is not used to set up and migrate the database schema.

Thus, this setting should only be used in classic deployments, or when Database Management is disabled.

nevisFIDO FIDO2 Instance​

Sets up a nevisFIDO Instance with support for FIDO2.

Port​

Port the nevisFIDO Instance is listening on.

Status Port​

This port is used to check if the instance is up after deployment.

Instance Name​

Enter the instance name.

If not set, the pattern name will be used as the instance name.

When deploying to Kubernetes, this setting will be ignored and the instance name will be default.

Frontend Key Store​

Assign the Key Store provider for the HTTPs endpoint.

Frontend Trust Store​

Assign the Trust Store provider for the HTTPs endpoint.

SecToken Signer Trust Store​

Assign the Trust Store provider for SecToken verification.

Database​

The database where the nevisFIDO sessions will be stored can be configured here. If no pattern is assigned, the sessions will be stored in memory.

Log Settings​

Assign nevisFIDO Log Settings to change the log configuration.

User Name​

Configure what is expected as username in incoming API calls.

Choose between extId and loginId.

Display Name Source​

Defines the attribute of the user that will be populated into the user.name property in the PublicKeyCredentialCreationOptions object that nevisFIDO sends to the FIDO2 client during the Registration ceremony. Some browsers choose this user.name property to display to the user when they prompt for user interaction (as opposed to user.displayName). Supported values are loginId, displayName, email and username - this latter does not correspond strictly to a nevisIDM user property, but instead is the same username what nevisFIDO received in the ServerPublicKeyCredentialCreationOptionsRequest object.

The default is loginId.

Relying Party Name​

Enter a name for the relying party.

This name is displayed by the user agent when performing a FIDO 2 registration or authentication.

Relying Party ID​

Enter a base domain for all Relying Party Origins.

Example: example.com

Relying Party Origins​

Enter all URLs from where FIDO 2 registration and authentication is invoked.

Example: https://www.example.com

nevisFIDO will use this information to check the Origin header of incoming REST calls.

URLs must be entered without a path.

URLs must have a common base domain which will be used as the ID for the relying party.

For Android Applications using the non-WebauthN standard compliant Origins enter the origin in the format android:apk-key-hash:<your-apk-key-hash>.

nevisIDM​

Assign a nevisIDM Instance or nevisIDM Connector pattern.

Use nevisIDM Connector only when the nevisIDM instance is not setup by the same nevisAdmin 4 project.

When using nevisIDM Connector you have to use non-automatic key management.

Client ID​

Enter the ID of the nevisIDM Client.

Only 1 client is supported.

Key Store​

Assign a key store to be used for the 2-way TLS connection to nevisIDM.

If no pattern is assigned an automatic key store will be generated. This requires automatic key management to be enabled in the inventory. Further, the pattern assigned to nevisIDM must be a nevisIDM Instance which uses an automatic trust store for the Frontend Trust Store.

Note that it is required that the certificate used by nevisFIDO to connect to nevisIDM is uploaded as a certificate credential for the nevisfido technical user. This is done automatically when deploying to Kubernetes and using automatic key management on both sides. In any other case, this step has to be done manually.

Trust Store​

Assign the trust store for validating the nevisIDM endpoint.

The trust store should contain the certificate of the CA that has issued the server certificate.

If no pattern is assigned an automatic trust store will be generated. This requires automatic key management to be enabled in the inventory.

In that case the pattern assigned to nevisIDM must be a nevisIDM Instance pattern which uses an automatic key store for the Frontend Key Store.

Memory Limit​

This setting defines the maximum amount of RAM than can be used by this instance.

VM Deployment​

By default, the Java process will use 1/4 of the available RAM.

Depending on how many instances are deployed to the same target host this may be either too much or too little.

The value configured here will be used for the maximum heap size of the Java process (-Xmx).

Kubernetes Deployment​

In Kubernetes deployment the value configured here will be ignored and the Java process will be configured to use a percentage of the available RAM.

Note that -Xmx is not set to avoid file changes when adapting the limit.

As the docker container runs only 1 process the JVM flags -XX:+UseContainerSupport and -XX:MaxRAMPercentage=80.0 will be applied so that Java process can use up to 80% of the configured limit.

Initial Memory Ratio​

Use the given percentage of Memory Limit for the initial memory usage (-Xms).

This setting applies to classic VM deployments only.

Instance Rename Detection​

During deployment nevisAdmin 4 checks if the instance has been renamed by checking the last metadata file deployed on the target host given the pattern ID.

If instance rename is detected the current instance is stopped.

This check should be disabled if multiple environments are simulated on the same server.

This setting is relevant for classic VM deployment only.

Start Inactive​

In a classic VM deployment the instance is restarted when a configuration file changes that requires a restart. The instance is not restarted when a configuration file changes that does not require a restart.

This setting defines if the instance should also be started when it is down.

This setting applies to classic VM deployment only. In Kubernetes deployment the container pods are always recreated when any configuration file changes.

Check Minimum Version​

Select enabled to perform basic version checks.

In classic VM deployment we run a command on each target host, to check which version of the component is installed.

In Kubernetes deployment we check the version of the docker image instead.

This check can be disabled for testing purposes.

Open Telemetry​

OpenTelemetry is used for several use cases:

  • cross-component tracing in logs
  • exposing metrics

By default, OpenTelemetry is enabled and a Java agent is loaded.

If that Java agent is not present on the machines you are deploying to, then you have to provide it at /opt/agent/opentelemetry-javaagent.jar or select disabled.

Additional Settings​

Assign add-on patterns to customize the configuration of nevisFIDO.

nevisFIDO FIDO2 Log Settings​

Defines log levels and log retention of nevisFIDO. Assign to a nevisFIDO Instance using Log Settings.

Default Log Level​

Change the level of the root logger. This impacts all logging apart from Log Levels.

Note that Syslog appenders have a threshold which ensures that only INFO, WARN, or ERROR messages are forwarded.

Log Levels​

Configure log levels.

In classic deployment nevisAdmin 4 does not restart nevisFIDO if you only change log levels. The log configuration will be reloaded within 60 seconds after deployment.

The category ch.nevis.auth.fido.application.Application will always be generated. If you don't set its level, INFO will be used.

This gives you:

  • log messages during startup and when the startup is done
  • 1 line per incoming request
  • 1 line for each API call towards nevisIDM

Debug incoming requests:

org.springframework.web.filter.CommonsRequestLoggingFilter = DEBUG

Debug the entire component:

ch.nevis.auth.fido = DEBUG

Rotation Type​

Select log rotation type.

Choose between:

  • size - defines the maximum file size before the log files are rolled over
  • time - defines the time span after which logs are rolled over

If you rotate by time we recommend you monitor the disk usage as log files can be huge.

Note: a combination of size and time based log rotation is not supported.

Max Backup Files​

Maximum number of backup files to keep in addition to the current log file. When Rotation Type is time, this property is used as Logback's maxHistory property. This means that logs will be archived for this number of time units where time unit is as defined in Rotation Interval.

Max File Size​

Maximum allowed file size (in bytes) before rolling over.

Suffixes "KB", "MB" and "GB" are allowed. 10KB = 10240 bytes, etc.

Note: not relevant when rotation type is time.

Rotation Interval​

Rotation interval after which log files are rolled over.

This configuration is not used when Rotation Type is set to size.

Choose between:

  • daily - the postfix of rotated files will be .%d{yyyy-MM-dd}
  • hourly - the postfix of rotated files will be .%d{yyyy-MM-dd-HH}

Log Format​

Log4j 2 log format for the default SERVER logs. This pattern is used for non-kubernetes deployments.

Note: not relevant when Log Targets is set to syslog.

Syslog Format​

Log4j 2 log format for the SERVER SYS logs.

Note: not relevant when Log Targets is set to default.

Log Targets​

Select the type of appender.

In Kubernetes the default appender writes to system out so that log messages appear in the docker logs.

Choose between:

  • default - log to default target
  • default + syslog - log to default target and forward to a Syslog server
  • syslog - forward to a Syslog server only

Syslog Host​

Defines where to send logs to via syslog.

This configuration is used only when syslog forwarding is enabled (see Log Targets).

The syslog facility is localhost3 and the threshold is INFO.

nevisFIDO FIDO2 REST Service​

Set up access to a nevisFIDO FIDO2 Instance on a nevisProxy Virtual Host.

This pattern will be adapted depending on the requirements of upcoming FIDO 2 use case patterns.

Virtual Host​

Assign a Virtual Host which shall serve as entry point.

nevisFIDO FIDO2​

Assign a nevisFIDO FIDO2 Instance.

Additional Settings​

Assign add-on patterns to customize the behaviour of this service.

Example use cases:

  • Authorization Policy to enforce roles or an authentication level.
  • URL Handling to redirect or forward requests.
  • HTTP Header Customization to add, replace, or remove HTTP headers in requests or responses.