Skip to main content

nevisadmin-plugin-mobile-auth

Generic nevisFIDO UAF Instance Settings​

Use this add-on pattern to customize configuration files of a nevisFIDO UAF 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.

Configuration: nevisfido.yml​

This setting provides a low-level way to add or overwrite configuration in nevisfido.yml.

Enter the configuration as it would appear in the nevisfido.yml using correct indentation.

For now, the only supported case is to add additional entries to the dispatchers block. The setting will be improved in a future release to support additional cases.

Example:

fido-uaf:  
  dispatchers:
  - type: png-qr-code
    registration-redeem-url: http://localhost:9080/nevisfido/token/redeem/registration
    authentication-redeem-url: http://localhost:9080/nevisfido/token/redeem/authentication
    deregistration-redeem-url: http://localhost:9080/nevisfido/token/redeem/deregistration

In-band Mobile Authentication Realm​

Sets up In-Band Authentication to protect REST services.

If you want to protect a web application and use mobile authentication from a web browser, use Out-of-band Mobile Authentication instead.

In a nutshell, the pattern configures Nevis for the following use case:

  1. The user opens the mobile application and accesses a protected resource, for which they have no authorization yet.
  2. The mobile application prompts the user to authenticate.
  3. The mobile app sends a request to /auth/fidouaf to authenticate.
  4. The user is now authenticated, the mobile application is able to access the protected REST service.

Before executing mobile authentication, the user has to register their mobile device. The required APIs can be set up using In-band Mobile Registration Service pattern.

Application Access Tokens​

Tokens assigned here may be created after successful authentication.

To produce and forward a token to an application backend, reference the same token from the application's Additional Settings property.

nevisFIDO​

Assign a nevisFIDO instance. This instance will be responsible for providing the in-band authentication services.

Key Store​

Assign a pattern which provides the key store for nevisAuth to connect to nevisFIDO with client TLS.

Trust Store​

Assign a pattern which provides the trust store for nevisAuth to connect to nevisFIDO.

nevisAuth​

The nevisAuth Instance where the authentication flow will be configured.

Key Store​

Define the key store to use for 2-way HTTPs connections from nevisProxy to nevisAuth.

Trust Store​

Defines the trust store that nevisProxy uses to validate the nevisAuth HTTPs endpoint.

Hostname Validation​

Enable to verify that the hostname on the certificate presented by nevisAuth matches the configured hostname in the nevisAuth Instance or nevisAuth Connector pattern.

Internal SecToken Trust Store​

Defines the trust store nevisProxy uses for validating the signature of the NEVIS SecToken issued by nevisAuth.

Custom Parameters (IdentityCreationFilter)​

Add custom init-param elements to each IdentityCreationFilter generated by this pattern.

Most realms generate only 1 IdentityCreationFilter named Authentication_<name>, which is used to protect the application.

Multi-line values, as required for conditional configuration, can be entered by replacing the line-breaks with \n.

Examples:

KeyValue
BodyReadSize64000
InterceptionRedirectCondition:ENV:HTTP_USER_AGENT:mozilla|Mozilla\ninitial\nnever
ClientCertwant

Custom Parameters (Esauth4ConnectorServlet)​

Add custom init-param elements to the Esauth4ConnectorServlet generated by this pattern.

That servlet is called Connector_<name>.

Multi-line values, as required for conditional configuration, can be entered by replacing the line-breaks with \n.

Examples:

KeyValue
EnablePollTerminatedCallstrue

Login Renderer​

Assign a pattern which defines the login renderer.

In case no pattern is assigned a nevisLogrend instance named default will be created and deployed on the same host as nevisProxy.

Key Store​

Assign a pattern which sets up a key store to use for 2-way HTTPs connections to nevisLogrend.

If no pattern is assigned no key store will be setup and 1-way HTTPs or plain HTTP will be used depending on the connection URL of nevisLogrend.

Trust Store​

If nevisLogrend is used and the connection to nevisLogrend uses HTTPs then a trust store should be configured here.

If no pattern is assigned the nevisAdmin 4 automatic key management will set up a trust store.

Hostname Validation​

Enable to verify that the hostname on the certificate presented by nevisLogRend matches the configured hostname in the nevisLogrend Instance or nevisLogrend Connector pattern.

This setting only applies if nevisLogrend is used in the Login Renderer setting and the connection to nevisLogrend uses HTTPs.

Initial Session Timeout​

Define the idle timeout of the initial session. The user must complete the authentication within this time.

Authenticated Session Timeout​

Define the idle timeout of an authenticated session.

Max Session Lifetime​

Define the maximum lifetime of an authenticated session. The session will be removed after that time even if active.

Update Session Timestamp Interval​

Sets the minimum time interval between two updates of the session timestamp.

If the parameter is set to "0", the system will update the session timestamp each time a request accesses a session.

The Initial Session Timeout is used as Update Session Timestamp Interval if it is shorter than the duration configured here.

In-band Mobile Registration Service​

Provides services for In-Band Registration.

For in-band registration no browser is required. All actions are triggered by the mobile app.

The user typically has to click a registration button in the app to get started. On successful registration, credentials are created on the mobile device and in nevisIDM.

A Generic credential is generated as well which makes the mobile device a dispatch target, to which push notifications can be sent. For more information, see Dispatch Target Management.

For the access app this use case is provided for testing purposes only. However, in-band registration may be used in production when using the mobile SDK.

In-band registration requires non-mobile authentication.

This pattern can generate a simple username and password flow into the assigned realm. There are several limitations with this flow:

  • the flow cannot be adapted.
  • the password must be active and not expired, as there is no support for enforced password change.

For production use cases we recommend to configure your own flow and expose that on a separate path using Standalone Authentication Flow.

Virtual Host​

Assign a Virtual Host which shall serve as entry point.

Authentication Realm​

Assign an In-band Mobile Authentication Realm or Authentication Realm here.

Assignment is required.

The assigned realm will be used to protect the path /nevisfido/uaf/1.1/request/registration/.

If Authentication Service is enabled, a simple authentication flow will be added to this realm.

Application Access Token​

Propagate a token to the backend application. The token informs the application about the authenticated user.

For instance, assign NEVIS SecToken if the application uses Ninja or SAML Token for applications which are able to consume SAML Responses.

nevisFIDO​

Assign a nevisFIDO instance.

This instance will be responsible for providing the device registration services.

Authentication Service​

Convenience feature.

If enabled, an endpoint will be provided at the Authentication Service Path.

The mobile app may use this endpoint to authenticate and obtain a cookie.

With this cookie the registration operation can be initiated.

The flow is described here.

There are several alternatives:

  • use Standalone Authentication Flow to provide an authentication endpoint for this realm using authentication steps.
  • authenticate the registration operation using the Initial Authentication Flow of the assigned Authentication Realm.

Authentication Service Path​

Configure the path of the authentication service.

Mobile Deregistration Service​

Set up processes required for mobile device deregistration.

The services are called by the mobile app, e.g., when you delete your account in the mobile app.

This use cases uses FIDO UAF Credential Deregistration to de-register FIDO credentials.

Virtual Host​

A virtual host assigned will be used to expose the protected services.

Authentication Realm​

To provide the best possible security, the nevisFIDO APIs required for mobile device deregistration may be protected by In-Band Authentication.

Assign an In-band Mobile Authentication Realm here.

Application Access Token​

Assign a NEVIS SecToken pattern.

This pattern must also be assigned to Application Access Tokens in the Authentication Realm.

nevisFIDO​

Assign a nevisFIDO UAF Instance. This instance will be responsible for providing the mobile device deregistration services.

Out-of-band Device Management App​

#DEMO/TESTING ONLY - NOT FOR PRODUCTION USE

Provides a simple self-service application for mobile device management. The application is a single page app (SPA) and will be hosted on the Virtual Host at the Frontend Path.

The SPA is not ready for production use. We recommend to implement your own Web application. At least you have to adapt the HTML, CSS, and JavaScript based on your requirements.

The nevisIDM bootstrap user (or any other user with nevisIdm.Root role) can not be used to test the device management as the nevisfido technical user is not allowed to manage credentials of root users.

The SPA sends the following AJAX calls to render a device list:

1a) Get user attributes: GET /nevisidm/api/principal/v1/me (authentic) 1b) Get generic credentials: GET /nevisidm/api/core/v1/100/users/<userExtId>/generic-credentials/ (authentic)

When you then click "Enroll new device", the following API calls are sent:

2a) Generate QR-Code: POST /nevisfido/token/dispatch/registration (authentic) 2b) Poll for completion: POST /nevisfido/status (public)

Now you can scan the displayed QR code with the mobile app. This leads to the following calls:

3a) POST /nevisfido/token/redeem/registration (authentic) 3b) GET /nevisfido/uaf/1.1/facets (public)

The registration is completed with by the mobile app with:

4a) POST /nevisfido/uaf/1.1/registration/ (authentic)

This pattern does not validate that the required APIs are set up! You must provide these APIs by adding appropriate patterns. For instance, you can use the following patterns:

  • nevisIDM REST Service or nevisIDM Administration GUI (provides 1a, 1b)
  • Out-of-band Mobile Registration Service (provides 2a, 2b, 3a, 3b, 4a)

The same Authentication Realm must be assigned in all these patterns.

Virtual Host​

A virtual host assigned will be used to expose services required for Out-of-band Management Application.

Frontend Path​

The path at which the management app shall be accessible at the frontend.

Resources​

Upload a ZIP to provide your own resources.

By default, the following resources are provided:

  • index.html
  • logo.png

Authentication Realm​

Configure an authentication realm, which will protect the device management application.

Additional Settings​

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

Out-of-band Mobile Authentication​

Sets up Out-of-Band Authentication.

Use as an authentication step in a flow of your Authentication Realm. Typically, this means including this step in the Initial Authentication Flow.

This step can not be used as the first step as the user must be determined before reaching this step. Use any of the following steps in front of this step:

  • nevisIDM User Lookup for passwordless authentication,
  • nevisIDM Password Login when mobile authentication shall be a second factor.

The user must have a registered mobile app.

Depending on what is selected in the Channel drop-down, the user either has to:

  • click a link (shown only on mobile devices),
  • scan a QR-code,
  • or confirm a push notification sent to the mobile app (with optional number matching).

When this step is done (see On Success), the user will be authenticated, and you can finish the authentication flow or do additional steps.

This step must only be used when the user-agent is a Web browser. To protect REST APIs called by a mobile app use In-band Mobile Authentication Realm instead. Such mobile apps typically embed the Nevis Mobile Authentication SDK.

To use this step, the user must have registered a mobile app and further configuration is required for that. The Out-of-band Device Management App provides an example self-admin page for device registration, while the Mobile Device Registration API only exposes the required APIs.

This pattern uses JavaScript (mauth*.js) and other resources, which are included in the default Login Template of the Authentication Realm.

If you are using a custom template you have to ensure that the required resources are used in the same way. Search for mauth in the *.vm files to get started.

Channel​

Select how to transfer information to the mobile application.

Link / QR-Code: User can click a link if they are navigating on the same mobile device as the app resides on. A QR-code is shown as well which can be scanned if the user uses a browser separate from the mobile device the app resides on. The QR-code can also be scanned with the camera app of the mobile device. This option uses mauth_link_qr.js.

Push / QR-Code (in-app): The user receives a push notification on their mobile device. In addition to that, a QR-code is shown which can be scanned instead in case the user does not receive the push notification. This QR-code can be scanned in the mobile app only, scanning the QR-Code using the camera app of the mobile device is not supported. This option uses mauth_push_qr.js.

If you are using a custom login template, add the correct Javascript file and some Velocity template snippets.

Download the default template in your Authentication Realm, unpack the zip, and search for mauth to get started.

Number Matching​

Enable/disable number matching in case of push notifications. If enabled, a 4-digit number will be displayed on the screen that you have to enter on your mobile device.

By default, it is disabled.

For more information, see Number Matching.

Virtual Host​

To complete the authentication, the mobile app will send a request to /nevisfido/token/redeem/authentication.

The domain is coded into the mobile app and has to be communicated when ordering the app.

We recommend to assign the Virtual Host which serves that domain here so that this pattern can generate the required configuration.

The Virtual Host assigned here will also be considered when calculating the Frontend Address in the nevisFIDO UAF Instance.

On Success​

On a successful authentication, the flow will continue with the assigned step.

On Cancel​

Assign an authentication step to continue with when the user clicks cancel.

Use to provide a fallback authentication option.

You can change the text on the cancel button by translating the label mobile_auth.cancel.button.label.

On Client Failure​

When authentication fails due to user behaviour, the authentication flow may continue with assigned step.

The authentication may fail due to the following reasons (non-exhaustive list):

  • A timeout has occurred
  • The authentication itself has failed (for example wrong biometric credential was provided)
  • Client errors (e.g. the authenticator chosen did not comply with the policy)

To handle a failure upon sending a push notification, configure On Push Failure instead.

On Dispatch Failure​

When a failure occurs during dispatching, the authentication flow will continue with the assigned step.

There are several error cases:

  • nevisFIDO is unable to hand out a link or render a QR-code
  • the dispatchTargetId sent by the JavaScript does not exist. For instance, the credential may have been deleted in nevisIDM.

User Name​

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

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

nevisFIDO​

Assign a nevisFIDO UAF Instance pattern. nevisFIDO provides required services for out-of-band authentication.

Key Store​

Assign a key store for the TLS connection to nevisFIDO.

If no pattern is assigned, a key store will be provided by automatic key management.

The client certificate in the key store must be trusted by nevisFIDO.

In case both sides use automatic key management, trust can be established automatically and there is nothing to configure.

However, if you are using a different kind of key store, then you must configure Frontend Trust Store in the associated nevisFIDO UAF Instance.

Trust Store​

The trust store used to establish a connection with the nevisFIDO component.

The trust store must contain the certificate of the CA that has issued the certificated contained in the Key Store of the nevisFIDO UAF Instance.

In case both sides use automatic key management, trust can be established automatically and there is nothing to configure.

Policy​

Enter the name of a policy provided by the assigned nevisFIDO instance.

Read the help of the Policies settings in the nevisFIDO UAF Instance pattern for details.

By default, no policy name is set here and thus the policy default will be used.

You can also enter a nevisAuth or EL expression to determine the policy based on the request or the user session.

Authentication Level​

Set an authentication level to apply when authentication is successful.

The level is relevant only if there are is an Authorization Policy assigned to applications.

Out-of-band Mobile Onboarding​

This pattern provides Out-of-Band Registration for mobile authentication and has to be used as a step in an Authentication Realm.

For instance, this pattern may be part of a self-registration flow which starts at the login screen (use Dispatcher Button pattern to add the button), or is exposed on a separate path (use Standalone Authentication Flow pattern).

Out-of-band registration requires a browser and works as follows:

  1. First a QR code is shown. The page is rendered using the Login Template of your Authentication Realm and required JavaScript to render the QR code.
  2. The user scans the QR code with their mobile device. 2.1. if the QR code is scanned by the camera app, then the user is sent to an HTML page for further installation instruction. 2.2. when the QR code is scanned by the mobile app, the registration continues (step 3).
  3. The mobile app creates a client-side credential.
  4. The mobile app ensures that the required credentials are created in nevisIDM.

Virtual Host​

To complete the authentication, the mobile app will send a request to /nevisfido/token/redeem/authentication.

The domain is coded into the mobile app and has to be communicated when ordering the app.

We recommend to assign the Virtual Host which serves that domain here so that this pattern can generate the required configuration.

The Virtual Host assigned here will also be considered when calculating the Frontend Address in the nevisFIDO UAF Instance.

On Success​

On a successful authentication, the flow will continue with the assigned step.

On Cancel​

Assign an authentication step to continue with when the user clicks cancel.

Use to provide a fallback authentication option.

You can change the text on the cancel button by translating the label mobile_auth.cancel.button.label.

User Name​

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

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

nevisFIDO​

Assign a nevisFIDO UAF Instance pattern. nevisFIDO provides required services for out-of-band authentication.

Key Store​

Assign a key store for the TLS connection to nevisFIDO.

If no pattern is assigned, a key store will be provided by automatic key management.

The client certificate in the key store must be trusted by nevisFIDO.

In case both sides use automatic key management, trust can be established automatically and there is nothing to configure.

However, if you are using a different kind of key store, then you must configure Frontend Trust Store in the associated nevisFIDO UAF Instance.

Trust Store​

The trust store used to establish a connection with the nevisFIDO component.

The trust store must contain the certificate of the CA that has issued the certificated contained in the Key Store of the nevisFIDO UAF Instance.

In case both sides use automatic key management, trust can be established automatically and there is nothing to configure.

Policy​

Enter the name of a policy provided by the assigned nevisFIDO instance.

Read the help of the Policies settings in the nevisFIDO UAF Instance pattern for details.

By default, no policy name is set here and thus the policy default will be used.

You can also enter a nevisAuth or EL expression to determine the policy based on the request or the user session.

Profile ID Source​

Enter a variable expression for the profile ID.

The default works when this step is a follow-up of nevisIDM Password Login or nevisIDM User Lookup.

Out-of-band Mobile Registration Service​

Provides services for Out-of-Band Registration.

The following paths will be exposed:

  • /nevisfido/token/dispatch/registration
  • /nevisfido/token/redeem/registration
  • /nevisfido/uaf/1.1/facets
  • /nevisfido/uaf/1.1/registration/
  • /nevisfido/status

Out-of-band registration requires a browser and works as follows:

  1. The user accesses a Web application which generates a QR code.
  2. The user scans the QR code with the mobile app.
  3. The mobile app creates a client-side credential.
  4. The mobile app calls services provided by this pattern to establish a FIDO UAF credential in nevisIDM.

Alongside the FIDO UAF credential a Generic credential is generated which makes the mobile device a dispatch target, to which push notifications can be sent. For more information, see Dispatch Target Management.

The Web application, which is responsible for QR code generation, is not provided by Nevis. However, you can use the 'Out-of-band Device Management App' pattern to test out-of-band registration.

Virtual Host​

Assign the Virtual Host which serves the domain where the nevisFIDO services shall be exposed so that this pattern can generate the required configuration.

The domain is coded into the mobile app and has to be communicated when ordering the app.

The Virtual Host assigned here will also be considered when calculating the Frontend Address in the nevisFIDO UAF Instance.

Authentication Realm​

Assign an Authentication Realm to protect the APIs for out-of-band registration.

When the APIs are called by a protected application which is exposed / running on nevisProxy, then you should assign the same realm here.

Application Access Token​

Propagate a token to the backend application. The token informs the application about the authenticated user.

For instance, assign NEVIS SecToken if the application uses Ninja or SAML Token for applications which are able to consume SAML Responses.

nevisFIDO​

Assign a nevisFIDO instance.

This instance will be responsible for providing the device registration services.

Transaction Confirmation​

Sets up services for Out-of-band Transaction Confirmation.

Third-party clients can initiate a transaction confirmation and mobile clients complete the process.

The limit for the transaction message is 2000 characters.

Virtual Host​

Assign a Virtual Host to expose the transaction confirmation services.

The following public endpoints can be invoked:

  • /nevisfido/token/dispatch/authentication
  • /nevisfido/status
  • /nevisfido/token/redeem/authentication
  • /nevisfido/uaf/1.1/facets
  • /nevisfido/uaf/1.1/authentication

nevisFIDO​

Assign a nevisFIDO UAF Instance. This instance will provide the transaction confirmation services.

Usernameless Out-of-band Mobile Authentication​

Sets up Out-of-Band Usernameless Authentication.

Use as an authentication step in your Authentication Realm.

This step can be used as the first step as no username has to be entered. Instead, a QR code and a link will be shown.

If you want to show a welcome screen, assign another step in front of this step.

The user must have a registered mobile app and has to scan the QR code to authenticate. If the user is on a mobile device, they can click the link instead.

The Out-of-band Device Management App pattern provides an example self-admin page for app registration, while the Mobile Device Registration API only exposes the required APIs.

When this step is done (see On Success), the user will be authenticated, and you can finish the authentication flow or do additional steps.

This step must only be used when the user-agent is a Web browser.

To protect APIs called by a mobile app use In-band Mobile Authentication Realm instead. Your mobile app should use the Nevis Mobile Authentication SDK.

This pattern uses a JavaScript file (mauth_usernameless.js) and other resources, which are included in the default Login Template of the Authentication Realm.

If you are using a custom template you have to ensure that the required resources are used in the same way. Search for mauth_usernameless in the *.vm files to get started.

Virtual Host​

To complete the authentication, the mobile app will send a request to /nevisfido/token/redeem/authentication.

The domain is coded into the mobile app and has to be communicated when ordering the app.

We recommend to assign the Virtual Host which serves that domain here so that this pattern can generate the required configuration.

The Virtual Host assigned here will also be considered when calculating the Frontend Address in the nevisFIDO UAF Instance.

On Success​

On a successful authentication, the flow will continue with the assigned step.

On Cancel​

Assign an authentication step to continue with when the user clicks cancel.

Use to provide a fallback authentication option.

You can change the text on the cancel button by translating the label mobile_auth.cancel.button.label.

nevisFIDO​

Assign a nevisFIDO UAF Instance pattern. nevisFIDO provides required services for out-of-band authentication.

Key Store​

Assign a key store for the TLS connection to nevisFIDO.

If no pattern is assigned, a key store will be provided by automatic key management.

The client certificate in the key store must be trusted by nevisFIDO.

In case both sides use automatic key management, trust can be established automatically and there is nothing to configure.

However, if you are using a different kind of key store, then you must configure Frontend Trust Store in the associated nevisFIDO UAF Instance.

Trust Store​

The trust store used to establish a connection with the nevisFIDO component.

The trust store must contain the certificate of the CA that has issued the certificated contained in the Key Store of the nevisFIDO UAF Instance.

In case both sides use automatic key management, trust can be established automatically and there is nothing to configure.

Policy​

Enter the name of a policy provided by the assigned nevisFIDO instance.

Read the help of the Policies settings in the nevisFIDO UAF Instance pattern for details.

By default, no policy name is set here and thus the policy default will be used.

You can also enter a nevisAuth or EL expression to determine the policy based on the request or the user session.

Authentication Level​

Set an authentication level to apply when authentication is successful.

The level is relevant only if there are is an Authorization Policy assigned to applications.

nevisFIDO UAF Connector​

Use to connect to an existing nevisFIDO UAF instance.

Use the pattern only when the instance is not set up by the project.

Ensure that the SecToken trust store of the instance allows the SecToken signers used in this project.

Connection URL(s)​

Enter URL(s) to connect to your nevisFIDO instance.

The path must be omitted.

Only scheme https:// is allowed.

The scheme is optional which means that you can enter simple host:port pairs (1 per line).

Kubernetes​

This setting is used when deploying to Kubernetes only.

Choose between:

  • disabled: instance running on a VM.

  • same_namespace: service running in the same cluster and namespace.

  • other_namespace: service running in the same cluster but in another namespace.

  • other_cluster: service running in another cluster.

Namespace​

Enter the Kubernetes namespace.

Configuration is required when Kubernetes is set to other_namespace.

nevisFIDO UAF Database​

Configures nevisFIDO to use a MariaDB database for storing sessions. Assign to nevisFIDO UAF 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.

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.

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.

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 UAF Instance​

Represents a nevisFIDO instance which has been set up for FIDO UAF use cases.

Further information about nevisFIDO can be found in the nevisFIDO Technical Documentation.

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.

Log Settings​

Assign nevisFIDO Log Settings to change the log configuration.

Frontend Address​

Enter the address of the Virtual Host where the services of this instance are exposed.

Enter the address without any path component.

Example:

https://example.com

If no address is provided, the pattern tries to automatically determine a value based on the Virtual Host patterns, that are associated with this instance through patterns for out-of-band use-cases.

The entered value is used to calculate:

The dispatch payload informs the mobile device where to access nevisFIDO for the following use cases:

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.

Facets​

Facets are defined by the FIDO UAF specification as follows:

An (application) facet is how an application is implemented on various platforms.
For example the application MyBank may have an Android app, an iOS app, and a Web app. 
These are all facets of the MyBank application.

The facets configured here correspond to the definition above.

Note that the default value of this field represents the facets required for nevisFIDO to be able to work with the integration flavor of the Access App or the debug flavor of the Nevis Mobile Authentication SDK.

If you're using a custom app based on the release flavor of the Nevis Mobile Authentication SDK or a production flavor of the Nevis Access App, these values will need to be updated.

Refer to the Access App or SDK documentation for details.

Policies​

A FIDO UAF Policy defines which authenticators can be used during registration or authentication.

Each configuration file has to contain exactly 1 policy, as a JSON object.

A policy contains a list of allowed and/or disallowed AAIDs, pointing to specific authenticator implementations.

The policy for a certain operation can be specified in the context of the GetUafRequest object.

Example Javascript snippet for a registration operation with pin_only policy:

const getUafRequest = {
    op: "Reg",
    context: JSON.stringify({username: userExtId, policy: "pin_only"})
}

Given a policy in the GetUafRequest context, nevisFIDO looks for a .json file with the same name.

There must be at least one file named default.json which serves as default policy. This policy will be used when no policy is specified in the GetUafRequest context.

The following policies are included by default:

  • default: allows to execute registration or authentication with all authenticators supported by Nevis.
  • pin_only: allows only the PIN authenticators.
  • biometrics_only: allows only biometric authenticators.

Note that the default policies are supported in combination with the Nevis Access App.

If you're using a custom app based on the Nevis Mobile Authentication SDK, you may have to upload your own policy configuration.

Metadata​

The FIDO UAF specification describes metadata as follows:

It is assumed that FIDO Server has access to a list of all supported authenticators and their corresponding Metadata. Authenticator metadata contains information such as:

* Supported Registration and Authentication Schemes
* Authentication Factor, Installation type, supported content-types and other supplementary information, etc.

To make a decision about which authenticators are appropriate for a specific transaction, FIDO Server looks up the list of authenticator metadata by AAID and retrieves the required information from it.

The nevisFIDO server ignores any authenticators and halts all operations in relation to them, which do not have metadata data entries accessible for the server.

Note that the default value of this field represents the metadata required for nevisFIDO to be able to work with the NEVIS Access App. If you're using a custom app based on the NEVIS Mobile Authentication SDK or a customized Whitelabel Access App, these values will need to be updated.

Firebase Configuration​

For sending push notifications, nevisFIDO needs to access Firebase, which is a push messaging service. For that, it requires an account and its corresponding credential.

Please visit the Firebase Console, create a project and download the service-account.json file. Please upload this file here.

Note that this file contains a private key, that gives access to your project's Firebase services. Keep it confidential at all times, and never store it in a public repository. Be aware that anybody who has access to this property, also has access to the file itself.

Firebase Proxy Address​

The URL of the HTTP/HTTPS proxy used by nevisFIDO to access the Firebase Cloud Messaging service.

Note: The FCM dispatcher requires outbound access to the Google API service, specifically https://oauth2.googleapis.com for authentication and https://fcm.googleapis.com for accessing the FCM HTTP API. In case proxies and/or company firewalls are in place the connectivity to these Google services must be ensured.

Choose between:

  • Deep Link: configures nevisFIDO to use a deep link (recommended).
  • Custom URI: configures nevisFIDO to use a custom URI link.
  • undefined: this pattern won't generate any link dispatcher configuration.

Deep links are harder to set up but more recommended as they offer a better user experience.

Nevis recommends using Custom URI links in mobile only scenarios only. The end-user is always expected to click a link on the same phone as the Access App is running on.

Note: the selected type here and the corresponding URI/URL must be communicated when Ordering an Access App.

Further information about deep links and custom URI links can be found in the related settings.

Deep links use the standard https:// scheme.

Enter a complete URL here.

We recommend to add a path component as otherwise / will be used and there often is no appropriate content on the root location.

Note that Apple requires the link to point to another domain. You can use any web server or Nevis as the target.

When the user clicks the link, the OS of the mobile device will first try to download an app link file from a /.well-known/ path on that domain.

You can configure Deep Link Host and Deep Link App Files to host these files.

The app link file is used by the OS to determine if a mobile app shall be opened, handing over the current URL.

If no mobile app can be determined, the deep link will be opened in the browser instead. Examples:

  • user does not have the app installed
  • no rule in the /.well-known/apple-app-site-association file applies to the path

Because of these error cases, there should be content on the deep link URL.

We recommend to create a page that informs the user how to install the mobile app. You can use the Hosting Service pattern to host this page on the Deep Link Host.

If you have uploaded any Deep Link App Files, then assign a Virtual Host.

The files will be hosted with a base path of /.well-known/.

The domain of the Deep Link must point to this Virtual Host.

If the user does not have the mobile app installed, the Deep Link will be opened in the browser instead.

Upload resources required for deep links.

Installation Page​

You can upload the HTML page that your Deep Link points to.

This page is shown only when the mobile app is not installed and should provide installation instructions.

You can also upload static resources (e.g. CSS and images) used by this page.

Uploaded files will be hosted at the root location (/) of the Deep Link Host.

If you want to host them on a sub-path, use the Hosting Service pattern instead.

App link files are JSON files which provide information about the mobile app. Apple and Google use different terms, and expect different filenames and contents.

iOS​

The file must be named apple-app-site-assocation without any extension and will be hosted at /.well-known/apple-app-site-association.

The file must be created manually and match the following structure:

{
  "applinks": {
    "details": [{
      "paths": [
        "*"
      ],
      "appID": "<TeamID>.<bundleID>"
    }],
    "apps": []
  }
}

appID: refers to the app. It consists of two components as follows: <TeamID>.<bundleID>, for details or about how to obtain it, see Apple documentation about Universal Links.

deep-link-base-path: The path configured here is the one supported in the deep links. Make sure the path used in the Deep Link corresponds to this value.

When the mobile app is installed or updated, iOS fetches this file from the server and stores it for later, to verify the paths in deep links the user clicks on.

For more information, visit Universal Links.

Android​

The file must be named assetlinks.json with the extension and will be hosted at /.well-known/assetlinks.json.

The file can be generated with the Statement List Generator using the following information:

  • Hosting site domain: enter the domain used in the Deep Link. It should point to the assigned Deep Link Host.
  • App package name: enter the package name of your app. If you are using a NEVIS branded Access App, that would be ch.nevis.security.accessapp.
  • App package fingerprint (SHA256): enter the fingerprint of the certificate your app has been signed with.

For more information, visit Android App Links.

Note that certain Chinese browsers do not support Android App Links: 360, QQ, UC.

Custom URI links will open the mobile app directly.

The scheme must be registered for the mobile app.

See Link Structure for Custom URIs for details.

If the mobile app is not installed an error will occur.

Example:

myaccessapp://x-callback-url/authenticate

nevisIDM​

For user and credential management, nevisFIDO needs nevisIDM.

Assign a nevisIDM Instance or nevisIDM Connector here.

This connection uses Client TLS and the trust is not built up automatically.

Client ID​

Enter the ID of the nevisIDM Client.

Only 1 client is supported.

Key Store​

The key nevisFIDO uses to connect to nevisIDM Instance. Important to note that the certificate that belongs to this key must exist in nevisIDM as the certificate credential of the nevisfido technical user.

Trust Store​

The trust store nevisFIDO uses to connect to nevisIDM Instance.

In-band Registration Timeout​

The maximum time that the mobile client has to complete the FIDO registration, after it has contacted nevisFIDO.

This timeout is relevant in registration use-cases, such as:

In-band Authentication Timeout​

The maximum time the mobile client has to complete the FIDO authentication operation, after it has contacted nevisFIDO.

This timeout is relevant in the authentication use-cases, such as:

Out-of-band Registration Timeout​

The maximum time that the mobile client has to contact nevisFIDO, once the registration token has been dispatched.

This timeout is relevant in the Out-of-Band Registration use-case.

Out-of-band Authentication Timeout​

The maximum time that the mobile client has to contact nevisFIDO, once the authentication token has been dispatched.

This timeout is relevant in Out-of-Band Authentication.

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.

User Name​

Configure what is expected as username in incoming API calls.

Choose between extId and loginId.

Deregistration Authorization​

TODO

Additional Settings​

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

nevisFIDO UAF Log Settings​

Defines log levels and log retention of nevisFIDO. Assign to a nevisFIDO UAF 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.