Configuration Patterns Reference

This page lists all configuration patterns that are available in nevisAdmin 4. For each pattern, you find a detailed description, complete with information about each field you can set for the pattern. The text content is a copy of the pattern help texts that appear on the nevisAdmin 4 interface.

Use the right sidebar to browse the patterns in alphabetical order, or your browser's Find function to search for specific terms, pattern categories or plugins.

Access Restriction

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Sets up a filter in nevisProxy to block or filter incoming requests based on the source IP of the request.

The pattern can be assigned to applications or an entire Virtual Host using Additional Settings.

Blocked requests are responded to with HTTP error code 403.

To produce a nice looking error page, ensure that you have configured an error page for 403 on the Virtual Host or use the HTTP Error Handling pattern on the same location.

Listing Type

Indicates if Source IPs should be used as blacklist or whitelist.

• blacklist: Access from all configured Source IPs is denied. All other IPs are allowed.
• whitelist: Access is allowed only for IPs in the Source IPs list. All other IPs are blocked.

Source IPs

List of client source IPs which shall be allowed. You may include entire range of IPs by separating two IPs with -. If there is load-balancer in front of nevisProxy please configure it to preserve the client source IP. IPv6 is not supported here.

Examples:

• 10.0.0.1: specific IP address
• 192.168.0.0-192.168.0.255: range of IP addresses
• 0.0.0.0-255.255.255.255: all IP addresses

Source IP HTTP-Header

Optional setting used to specify HTTP header that contains the users IP. Otherwise, a default environment variable from nevisProxy is used.

Examples:

• X-Forwarded-For

Country database

IP geolocation database file for country filtering.

Currently only the mmdb format (MaxMind Database) is supported. This is a binary file format.

Rules

Defines what action should be taken for a specified country.

Possible actions are:

• allow: Requests are let through
• log: A log entry is made for each request from the specified country
• block: Blocks requests from a country

Default Action

Defines the action taken either when no country rules were matched or the IP of a request does not have an associated country in the database.

Possible actions are:

• allow: Requests are let through
• log: A log entry is made for each request
• block: Blocks requests

Apply only to sub-paths

Set to apply this pattern on some sub-paths only.

Sub-paths must be relative (e.g. not starting with /) and will be appended to the frontend path(s) of the virtual host (/) or applications this pattern is assigned to.

Sub-paths ending with / are treated as a prefix, otherwise an exact filter-mapping will be created.

The following table provides examples to illustrate the behaviour:

Frontend Path	Sub-Path	Effective Filter Mapping
/	secure/	/secure/*
/	accounts	/accounts
/	api/secure/	/api/secure/*
/	api/accounts	/api/accounts
/app/	secure/	/app/secure/*
/app/	accounts	/app/accounts
/app/	api/secure/	/app/api/secure/*
/app/	api/accounts	/app/api/accounts

Allow Override

By default, access restriction rules apply to all sub-locations.

For instance, when you assign an Access Restriction pattern to a Virtual Host all applications on this virtual host will be affected.

To replace the rules defined on a parent location select enabled on all Access Restriction patterns in the hierarchy.

If disabled is selected anywhere in the hierarchy the rules are considered additional.

Technical Details:

This feature is implemented using a nevisProxy LuaFilter. Mapped filters are inherited to sub-locations unless an exclude-url-regex is defined.

By selecting enabled the generator is informed that the mapped filter has the purpose access restriction. The generator then ensures that an exclude-url-regex entry is generated when a filter with the same purpose is mapped to a sub-location.

Access Token Consumer

#Federation #Authentication #Experimental

Plugin: nevisadmin-plugin-oauth

This step can validate access tokens issued by an OAuth 2.0 Authorization Server / OpenID Provider.

You can use this step in the Initial Authentication Flow of a Authentication Realm to provide a simple resource server for REST services.

The access token has to be sent as Bearer token in the Authorization header.

The content of the token will be stored in the session.

No authentication decision is taken! You have to use the session variables in a subsequent step to authenticate the user.

For instance, you may use a nevisIDM User Lookup step to search for a user in nevisIDM.

When the access token is invalid a 403 forbidden will be returned.

This pattern is experimental as there are several limitations. For instance, it is assumed that the authorization server is running Nevis and is set up by a OAuth 2.0 Authorization Server / OpenID Provider pattern which is part of this project. Thus, there are cases where this pattern cannot be used yet. These limitations may be addressed in a future release.

On Success

Assign a step to continue with after successfully validating the token.

On Missing Token

Assign a step to continue with when no token was sent.

If nothing is assigned then authentication will fail with an error.

OAuth 2.0 Authorization Server / OpenID Provider

Assign the OAuth 2.0 Authorization Server / OpenID Provider which has issued the access token.

Note that this step works in combination with Nevis OAuth 2.0 Authorization Server / OpenID Provider only and the other pattern has to be in the same project.

ActiveMQ Client Configuration

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisdetect

Using the pattern, you can connect to an external ActiveMQ service using TLS/SSL.

Message Broker URL

Set the URL for the ActiveMQ message broker. Example:

ssl://my-message-broker:61616

Advanced Session Upgrade

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Serves as entry point for an authentication process which may be executed on demand.

Assign the pattern to a Authentication Realm using the reference On Demand. An entry point for the configured Authentication Level is added to the nevisAuth configuration.

The process is triggered by services by assigning an Authorization Policy pattern using Additional Settings which set the required Authentication Level.

Authentication Level

Define the authentication level that this flow produces on successful execution.

The step assigned to On Entry (or a subsequent step) must achieve at least this level.

Custom Condition

Enter a custom nevisAuth or EL expression.

If set the Authentication Level will not be used.

The step assigned to On Entry will be executed when the expression evaluates to true.

On Entry

Point to the first step of the authentication process.

Apple Login Step

#Federation #Authentication #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

Setup social login, using Apple as OpenID Connect provider.

Client ID

ClientID is Identifier provided by Apple when you register Apple as IdP service.

Client Secret

The Client Secret is a JWT token generated by using a private key provided by Apple. Please follow the instructions here.

You can generate the client secret by yourself and configure it here, or upload the Private Key to generate the client secret automatically. Only private key or client secret can be use at the time

Return Path

The callback URI to go to after a successful login with Apple.

This will create an endpoint in your host config.

The URL will be a combination of the Frontend Address of the Virtual Host and the value configured here. For example, let's assume that you have configured:

• Return Path: /oidc/apple/
• Frontend Address: https://nevis.net

Then the URL will be https://nevis.net/oidc/apple/.

Use the exact: prefix to use the given path as-is. Without this prefix a normal mapping with /* will be generated and thus sub-paths will be accessible as well.

Scope(s)

Select the requested scopes for getting user information from Apple.

The default is email and thus minimal information will be returned.

The scope openid will always be added as Apple uses OpenID Connect.

Virtual Host

Assign a Virtual Host which shall serve as entry point for the callback from social login provider.

In case your host has

• 1 address, that address will be used
• many addresses with
  • 1 https, and many http, the https will be used without warning
  • mix between http and https, the 1st https will be used with warning
  • single scheme (http or https only) the 1st address will be used with warning

E.g.

http://nevis.net
http://nevis-security.net
https://nevis.net
https://nevis-security.net

The https://nevis.net will be used as the host for Apple callback

On Success

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

In case you change this to your custom step(s), you can assign pattern Social Login Final Step as the last step of the Authentication process to redirect back to original URL.

On Failure

The step that will be executed if the authentication fails. If no step is configured here the process ends with AUTH_ERROR.

In case you change this to your custom step(s), you can assign pattern Social Login Final Failure Step as the last step of the Authentication process to redirect back to original URL.

Private Key

Private key provided by Apple. Find out more here.

If you upload your private key here and set the Issuer, the pattern will automatically generate the Client Secret.

If you do not want to configure your private key, you have to set the Client Secret instead.

Issuer

The issuer registered claim identifies the principal that issued the client secret. Since the client secret belongs to your developer team, use your 10-character Team ID associated with your developer account. Find out more here.

nevisIDM

Choose which nevisIDM instance you want to store the user's information after logged in with social login provider.

Client External ID

The ExtId of the client in nevisIDM that will be used to store the user

On User Not Found

Configure the authentication flow to be executed when no user was found and the email provided by social account does not exist. The authentication flow must contain the Social Login Create User pattern if a new user shall be created.

Note: Please select scope email and profile for getting user's information from social account.

On User Found

Configure the Authentication Flow in case no user with Subject/ID from social account was found but email does exist in nevisIDM. The Authentication Flow must contain:

• Social Login Link User pattern to link an existing user in IDM with Subject/ID of social account.
• Social Login Done to end the social login flow after some other action(s).

Note: Please select scope email and profile for getting user's information from social account.

Claims Request

The claims request parameter. This value is expected to be formatted in JSON and does not accept trailing spaces nor tabs.

User ID Field

Logged userId will automatically get from social account. But you can change the userId by using this field.

Additional Auth Request Parameters

Arbitrary additional request parameters used in the authentication request. The property supports variable substitution.

Example:

[paramName]=[paramValue]

Button Label

Enter the text that should be displayed for the end-user on the social login button, and provide translations for this label on the Authentication Realms.

Authentication Cloud Login

#Authentication Cloud #Authentication #Experimental

Plugin: nevisadmin-plugin-authcloud

Connects to the Nevis Authentication Cloud.

This step adds mobile authentication to your authentication flow.

You need an access app use this step.

The user must be registered in your Authentication Cloud instance. You can use the Authentication Cloud Onboarding pattern for that.

When the user exists, login confirmation is requested. By default, a push notification is sent to trigger the Nevis Access App.

However, you can also show a QR code instead (see Authentication Type).

If the user is not registered or has no active authenticator, the On User Not Exists exit will be taken and no screen will be shown.

Your authentication flow should include any of the following patterns in front of this pattern:

• nevisIDM Password Login: use when mobile authentication shall be a second factor
• nevisIDM User Lookup: use for passwordless login

nevisAuth will connect to your Authentication Cloud instance using TLS and thus the CA certificate of the endpoint needs to be trusted.

If you get an unable to find valid certification path to requested target error in the nevisAuth log, then you have to import the CA certificate of the Authentication Cloud endpoint into the Default Backend Trust Store of the nevisAuth Instance.

Authentication Type

Choose between:

• QR code / deep link: renders a QR code which should be scanned or shows a deep link
• push / deep link: sends a push notification to the user which tells them to check the access app or shows a deep link.

The first option is used for non-mobile browsers. The deep link is shown when using a browser on a mobile.

On Success

Assign a step to execute after successful authentication.

If no step is configured, the flow ends and an authenticated session will be established.

This requires that the session contains an authenticated user.

A simple way to ensure that is to include nevisIDM User Lookup or nevisIDM Password Login steps in your flow.

On User Not Exists

Assign an authentication step to continue with when the user does not exist or has no active authenticator.

If no step is assigned here the authentication flow will fail for such users.

On Abort

Assign a step to continue with when the user has aborted in the mobile app or a timeout occurred.

On Failure

Assign a step to continue with when the operation has failed due to unknown reasons.

For instance, you may assign the following steps:

• User Information: show an error message and terminate the authentication flow.
• nevisIDM Second Factor Selection: select an alternative second factor for authentication.

Instance

Instead of uploading an access-key.json, you can enter the name of your Authentication Cloud instance here.

Access Key

Instead of uploading an access-key.json, you can enter the access key of your Authentication Cloud instance here.

Access Key File

Upload the access-keys.json of your Authentication Cloud instance.

The file contains the instance name and an access key.

You can download this file from the NEVIS Authentication Cloud Console.

Check Integrate Authentication Cloud with nevisAdmin 4 for setup instructions.

On Skip

Assign a step to continue with when the user clicks the skip button.

A skip button will be added to the authentication screen.

Skip Element Type

The type of element which allows the user to skip this step.

The element is usually a button but may also be changed to an info text. As info elements may contain HTML you can display a link that behaves like a button.

Skip Label

Label to display on the element which allows the user to skip.

The element is usually a button but this can be changed by setting Skip Type.

Title

Enter a label to use for the title.

You can use a different standard label (e.g. title.login) or invent your own.

Translations for custom labels can be defined in the Authentication Realm / GUI Rendering / Translations.

The default label title.authcloud has the following translations:

• en: Authenticate with Access App
• de: Mit Access-App anmelden
• fr: S'authentifier avec l'application Access
• it: Autenticazione con l'app Access

Deep Link Label

Label to display on the element which allows the user to use the deep link to log in.

The element is usually a button.

Username Prefix

Optional prefix which will be added to the Authentication Cloud username.

WARNING: Changing this option means that all existing users will have to register their Access Apps again.

The Authentication Cloud username consists of the user ID and the optional Username Prefix.

The user ID is looked up from the following sources:

• session variable ch.adnovum.nevisidm.user.extId
• request field userId

Hash Username

Enable to use a hash (MD5) for the Authentication Cloud username.

WARNING: Changing this option means that all existing users will have to register their Access Apps again.

There are 2 motivations for enabling this feature:

• the Authentication Cloud username is limited to 50 characters. Hashing makes it shorter.
• you avoid storing sensitive user information in the Authentication Cloud instance.

Proxy Server

If you have to go through a forward proxy for the outbound connection to firebase enter the hostname:port here.

At the moment only HTTP proxy is supported.

Authentication Cloud Lookup

#Authentication Cloud #Authentication #Experimental

Plugin: nevisadmin-plugin-authcloud

Connects to the Nevis Authentication Cloud.

Use this step to check if the user is active in your Authentication Cloud instance.

When the user exists and has an active authenticator, the On User Exists exit will be taken.

On User Exists

Assign an authentication step to continue with when the user exists and has an active authenticator.

On User Not Exists

Assign an authentication step to continue with when the user does not exist or has no active authenticator.

On Failure

Assign a step to continue with when the operation has failed due to unknown reasons.

For instance, you may assign the following steps:

• User Information: show an error message and terminate the authentication flow.
• nevisIDM Second Factor Selection: select an alternative second factor for authentication.

Instance

Instead of uploading an access-key.json, you can enter the name of your Authentication Cloud instance here.

Access Key

Instead of uploading an access-key.json, you can enter the access key of your Authentication Cloud instance here.

Access Key File

Upload the access-keys.json of your Authentication Cloud instance.

The file contains the instance name and an access key.

You can download this file from the NEVIS Authentication Cloud Console.

Check Integrate Authentication Cloud with nevisAdmin 4 for setup instructions.

Username Prefix

Optional prefix which will be added to the Authentication Cloud username.

WARNING: Changing this option means that all existing users will have to register their Access Apps again.

The Authentication Cloud username consists of the user ID and the optional Username Prefix.

The user ID is looked up from the following sources:

• session variable ch.adnovum.nevisidm.user.extId
• request field userId

Hash Username

Enable to use a hash (MD5) for the Authentication Cloud username.

WARNING: Changing this option means that all existing users will have to register their Access Apps again.

There are 2 motivations for enabling this feature:

• the Authentication Cloud username is limited to 50 characters. Hashing makes it shorter.
• you avoid storing sensitive user information in the Authentication Cloud instance.

Proxy Server

If you have to go through a forward proxy for the outbound connection to firebase enter the hostname:port here.

At the moment only HTTP proxy is supported.

Authentication Cloud Onboarding

#Authentication Cloud #Onboarding #Experimental

Plugin: nevisadmin-plugin-authcloud

Connects to the Nevis Authentication Cloud.

This step can be used to enroll users.

You need an access app use this step.

A QR code is shown which has be scanned with the app.

If the user is already registered and has an active authenticator, the On User Exists exit will be taken and no screen will be shown.

Your flow should include any of the following patterns in front of this pattern:

• nevisIDM Password Login: use when Auth Cloud shall be used as second factor
• nevisIDM User Lookup: use for passwordless login

nevisAuth will connect to your Authentication Cloud instance using TLS and thus the CA certificate of the endpoint needs to be trusted.

If you get an unable to find valid certification path to requested target error in the nevisAuth log, then you have to import the CA certificate of the Authentication Cloud endpoint into the Default Backend Trust Store of the nevisAuth Instance.

On Success

Assign a step to execute after successful onboarding.

If no step is configured, the flow ends and an authenticated session will be established.

This requires that the session contains an authenticated user.

A simple way to ensure that is to include nevisIDM User Lookup or nevisIDM Password Login steps in your flow.

On User Exists

Assign an authentication step to continue with when the user exists and has an active authenticator.

If no step is assigned here the authentication flow will fail for such users.

On Abort

Assign a step to continue with when the user has aborted in the mobile app or a timeout occurred.

On Failure

Assign a step to continue with when the operation has failed due to unknown reasons.

For instance, you may assign the following steps:

• User Information: show an error message and terminate the authentication flow.
• nevisIDM Second Factor Selection: select an alternative second factor for authentication.

Instance

Instead of uploading an access-key.json, you can enter the name of your Authentication Cloud instance here.

Access Key

Instead of uploading an access-key.json, you can enter the access key of your Authentication Cloud instance here.

Access Key File

Upload the access-keys.json of your Authentication Cloud instance.

The file contains the instance name and an access key.

You can download this file from the NEVIS Authentication Cloud Console.

Check Integrate Authentication Cloud with nevisAdmin 4 for setup instructions.

On Skip

Assign a step to continue with when the user clicks the skip button.

A skip button will be added to the authentication screen.

Skip Element Type

The type of element which allows the user to skip this step.

The element is usually a button but may also be changed to an info text. As info elements may contain HTML you can display a link that behaves like a button.

Skip Label

Label to display on the element which allows the user to skip.

The element is usually a button but this can be changed by setting Skip Type.

Title

Enter a label to use for the title.

You can use a different standard label (e.g. title.login) or invent your own.

Translations for custom labels can be defined in the Authentication Realm / GUI Rendering / Translations.

The default label title.authcloud has the following translations:

• en: Authenticate with Access App
• de: Mit Access-App anmelden
• fr: S'authentifier avec l'application Access
• it: Autenticazione con l'app Access

Deep Link Label

Label to display on the element which allows the user to use the deep link to onboard.

The element is usually a button.

Username Prefix

Optional prefix which will be added to the Authentication Cloud username.

WARNING: Changing this option means that all existing users will have to register their Access Apps again.

The Authentication Cloud username consists of the user ID and the optional Username Prefix.

The user ID is looked up from the following sources:

• session variable ch.adnovum.nevisidm.user.extId
• request field userId

Hash Username

Enable to use a hash (MD5) for the Authentication Cloud username.

WARNING: Changing this option means that all existing users will have to register their Access Apps again.

There are 2 motivations for enabling this feature:

• the Authentication Cloud username is limited to 50 characters. Hashing makes it shorter.
• you avoid storing sensitive user information in the Authentication Cloud instance.

Proxy Server

If you have to go through a forward proxy for the outbound connection to firebase enter the hostname:port here.

At the moment only HTTP proxy is supported.

Onboarding Screen Button

Adds another button to the onboarding screen.

The button may have a special Button Name set to render it in a nice way using 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.

Authentication Done

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Completes an authentication flow.

The pattern may only be used as the last step within an authentication flow.

Use as explicit follow-up for patterns such as Generic Authentication Step and User Information which do not add follow-up steps automatically.

Authentication Failed

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Shows a GUI with the error message error_99. When the GUI is shown, the session is terminated.

If HTTP Error Code is configured and the configured code is handled on the nevisProxy Virtual Host then the GUI is not shown, and a static error page is presented instead.

The pattern may only be used as the last step within an authentication flow.

Use as explicit follow-up for patterns such as Generic Authentication Step and User Information which do not add follow-up steps automatically.

HTTP Error Code

Enter a status code for error page produced by nevisAuth. If not set the status code will be 200.

Note that the error page from nevisAuth will not be shown, when error handling is applied by nevisProxy.

nevisProxy replaces the body of the HTTP response, when there is a page for this status code, uploaded to Hosted Resources of the Virtual Host, or to a HTTP Error Handling pattern.

Authentication Realm

#Authentication #Realms

Plugin: nevisadmin-plugin-nevisauth

This pattern defines how to authenticate access to applications.

You can assign this pattern to your applications as Authentication Realm, or expose it as a SAML IDP or OAuth 2.0 Authorization Server / OpenID Provider.

Examples how to authenticate your users can be found in the Concept & Configuration Guide.

The authentication processes are provided by a nevisAuth Instance which has to be assigned. For rendering the pages during authentication, nevisLogrend is used.

Initial Authentication Flow

The initial authentication flow starts with the authentication step assigned here. To create a multi-step flow, you can reference further steps from within the first assigned step.

The initial authentication flow is applied on first access, when the client does not have an authenticated session.

Every time a step within the flow executes successfully, the authentication level defined in that step is added to the authenticated session.

Session Upgrade Flows

Applications may be configured to trigger a session upgrade flow.

Here you assign the authentication steps which provide these session upgrade flows. This mechanism also works when the realm is accessed via a SAML IDP.

The process of selecting and executing a flow is as follows:

An application's Authorization Policy specifies the required authentication level (2-9) which is needed to access the application. (Level 1 is not allowed here, as the session has at least level 1 after the user successfully completes the initial authentication flow.)

Every time the user accesses the application, the policy is enforced as follows:

• If the authentication level of the current session is lower than the level required by the policy, nevisAuth is invoked to execute a session upgrade flow - the one which provides the required level.

• Only if the flow runs through successfully, the level reached is stored in the session and access is granted.

• If the level of the session equals, or is higher than the required level, access is granted immediately.

• Authentication steps assigned here are executed only if the required level (by policy) exactly matches the provided value in its Authentication Level property. For example, if level 3 is required, the authentication step directly providing that level is started.

It is possible, in a multi-step flow, that the required authentication is reached only after the second step or later. In this case, assign Advanced Session Upgrade as the first step. In this step, you declare the level that should ultimately be reached by the flow. The engine can then match the required level to the one provided by the flow, even if it is not provided by the first authentication step in the flow.

When no flow can be determined the Default Session Upgrade Flow will be used instead.

Default Session Upgrade Flow

Assign an authentication step which should be invoked when a session upgrade is triggered and none of the Session Upgrade Flows can be applied.

Logout Flow

The default logout flow works as follows:

• the user accesses a protected application URL with query parameter logout, for instance /myapp/?logout
• any active session for this realm is terminated
• an HTML page is displayed that informs the user and allows to log in again on the same URL

To replace this behavior, assign a logout step here.

Note: to expose the logout function to the user, the web page(s) of backend applications should to be customized. Supported approaches are:

• Adapt the backend application: add a button or link that requests a URL ending with ?logout.

Note that when this realm is used as a SAML IDP then the logout flow cannot be customized. The only thing you can do is to assign a Logout pattern and configure a custom Redirect. This is the location the user is redirect to after the SAML logout flow is done.

Application Access Tokens

Tokens assigned here may be created after successful completion of the Initial Authentication Flow.

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

nevisAuth

Assign a nevisAuth Instance pattern.

Key Store

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

If no pattern is assigned automatic key management will provide the required key material. This requires that the nevisAuth Instance is part of this project and also uses automatic key management.

Automatic key management should be used for test setups only.

Trust Store

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

If no pattern is assigned automatic key management is used to provide the trust store. This requires that the nevisAuth Instance is part of this project and also uses automatic key management.

Automatic key management should be used for test setups only.

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.

If no pattern is assigned automatic key management is asked to provide the trust store. This requires that the nevisAuth Instance is part of this project and also uses automatic key management.

Automatic key management should be used for test setups only.

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:

Key	Value
BodyReadSize	64000
InterceptionRedirect	Condition:ENV:HTTP_USER_AGENT:mozilla|Mozilla\ninitial\nnever
ClientCert	want

Custom Parameters (SecurityRoleFilter)

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

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

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:

Key	Value
EnablePollTerminatedCalls	true

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.

Login Template

Customize the rendering of login pages.

Download the default template to get started.

nevisLogrend: Simple Mode

Point your browser to a protected application to have a look at the login page. Download any resources (e.g. images, CSS) that you want to adapt. Then upload the changed files here.

To change the outer HTML upload a file named template.html. Here is a simple example:

<!DOCTYPE html>
<html lang="${lang.code}">
  <head>
    <title>${label.title}</title>
    <link href="${resources}/bootstrap.min.css" rel="stylesheet" type="text/css">
    <link href="${resources}/default.css" rel="stylesheet" type="text/css" media="all">
  </head>
  <body>
    <header id="header" class="container-fluid">
      <img class="logo center-block" src="${resources}/example.svg" alt="NEVIS Security Suite">
    </header>
    <main id="content" class="container">
      ${form}
    </main>
  </body>
</html>

Please also upload file resources referenced by your template (e.g. images, CSS, Javascript). Use this when you reference additional files, or if you want to override the default files provided.

The template must contain ${form} and may contain additional expressions.

Expression	Description
${form}	generated login form (required)
${lang.switch}	language switcher component
${lang.code}	current language code (i.e. EN, DE)
${label.title}	a human-readable title
${label.myLabel}	a custom text which must be defined via Custom Translations
${resources}	path to static resources (e.g. CSS, images, Javascript)

Some resources (i.e. bootstrap.min.css, default.css) are provided out of the box because they are required by the default template. Feel free to use them.

nevisLogrend: Expert Mode

Expert users may upload Velocity templates and resources to nevisLogrend.

Zip files will be extracted into the nevisLogrend application:

/var/opt/nevislogrend/<instance>/data/applications/<realm>

Flat files will be added to the following subdirectories:

• webdata/template: Velocity templates (*.vm)
• webdata/resources: additional resources (e.g. images, CSS)

nevisProxy: Simple Template

nevisProxy provides a simple login page renderer which can be used instead of nevisLogrend. See Login Renderer for details.

For each enabled language (e.g. en) upload a file named <lang>_template.html. The template must contain the placeholder NEVIS_AUTH_FORM.

If your templates require additional resources (e.g. CSS, images) upload them as Hosted Resources on the nevisProxy virtual host.

Login Template Mode

Choose between two options:

• additive: files uploaded as Login Template will be added on top of the default. Use this option when you want to add or replace files, but don't want to upload an entire template. There will be less work when you upgrade.

• complete: only the files uploaded as Login Template will be deployed. Use this option when you want to provide the entire template.

Translations

Labels are used to show text in the language of the user.

Which labels are used depends on the assigned steps. Click Download Default Labels to retrieve the used labels and their translations.

Here you can overwrite the defaults and add your own translations or even add new labels, which may be required when using a Custom Login Template or Generic Authentication Step.

Upload 1 file per language code. The file name should be labels_<code>.properties. Check Languages on the nevisAuth Instance for enabled language codes.

The uploaded files must be UTF-8 encoded or special characters must be HTML encoded.

If you want to reuse existing text_<code>.properties and LitDict_<code>.properties files, you have to merge them first, or set Translations Mode to separate.

By default, the patterns add several default labels and the labels configured here are added on top. This is convenient as you only have to define labels that you want to add or overwrite. However, this way you cannot remove labels. If you want to do that you have to set Default Translations to disabled and then only the uploaded labels will be used.

The default login template uses the following labels:

• title - used as browser page title
• language.<code> - used by language switch component

The default logout process of nevisAuth (which will be applied when no step is assigned to Logout) has a confirmation GUI which uses the following labels:

• logout.label - header of the logout confirmation GUI
• logout.text - text shown to the user
• continue.button.label - label on the confirmation button

Translations Mode

Choose between:

• combined - upload 1 file per language code named labels_<code>.properties. The labels will be added to both nevisAuth and nevisLogrend. Alternatively, you can upload a zip file called labels.zip containing these properties files.

• separate - select only when you need different labels in nevisAuth and nevisLogrend. The files must be called LitDict_<code>.properties for nevisAuth and text_<code>.properties for nevisLogrend. Alternatively, you may upload zip file called LitDict.zip and text.zip containing these properties files.

Default Translations

Choose between:

• enabled - add default translations for labels which are commonly used (e.g. title or language labels in nevisLogrend, error labels in nevisAuth) and which are required by the realm patterns (e.g. assigned authentication steps).

• disabled - select to only add what has been uploaded via Translations. Note that if Translations are incomplete users may encounter untranslated labels.

nevisLogrend default.properties

Add or overwrite properties in the default.properties of the nevisLogrend application.

Use only when there is no high-level setting. We recommend to not overwrite any language related properties, as the languages should be in sync with nevisAuth. You can configure the languages on the nevisAuth Instance.

Requires that nevisLogrend is used for GUI rendering. Check the help of Login Renderer for details.

Session Tracking

Choose between:

• COOKIE: issue a session cookie.
• AUTHORIZATION_HEADER: track the session based on the value of the Authorization header.
• CUSTOM: track the session based on custom configuration. It generates an empty session filter which has to be replaced (see below).
• disabled: disable session tracking.

CUSTOM session tracking

Given a pattern name of SSO, the following empty filter will be generated:

    <filter>
        <filter-name>SessionHandler_SSO</filter-name>
        <filter-class>__REPLACE_USING_GENERIC__</filter-class>
    </filter>

For the filter-class, a placeholder (REPLACE_USING_GENERIC) will be used and that placeholder has to be overwritten.

Another pattern must complete the session filter. For example, use Generic Virtual Host Context pattern with the following Filters and Mappings configuration:

<filter>
    <filter-name>SessionHandler_SSO_RealmName</filter-name>
    <filter-class>ch::nevis::nevisproxy::filter::session::SessionManagementFilter</filter-class>
    <init-param>
        <param-name>Identification</param-name>
        <param-value>CUSTOM</param-value>
    </init-param>
    <init-param>
        <param-name>Custom.RequiredIdentifiers</param-name>
        <param-value>HEADER:Authorization</param-value>
    </init-param>       
    <init-param>
        <param-name>Servlet</param-name>
        <param-value>LocalSessionStoreServlet</param-value>
    </init-param>
</filter>

Session Cookie Name

Each realm has its own session cookie. By default, this cookie will be called Session_<pattern-name>

Set this optional property to use a different name (e.g. ProxySession).

Note that each realm has its own session. However, if the same cookie name is configured for multiple realms running on the same host the sessions will be cleaned up together when the first session expires.

Session Cookie Same Site

In February 2020 Chrome 80 has been released which treats cookies without SameSite flag as Lax.

This change can break cross-domain use cases (e.g. SAML).

Thus, it is recommended to select None here.

If None is selected, and you have to support older browsers also check Cookie Same Site Relaxation.

If you do not expect any requests from other domains, you may also go for Lax or Strict as this increases security.

Session Cookie Same Site Relaxation (Experimental)

Some older browsers treat cookies with SameSite=None as Strict.

See this example bug report for Safari:

Bug 198181 - Cookies with SameSite=None or SameSite=invalid treated as Strict

Enable this feature to map a filter to the root location /* which evaluates the User-Agent request header to remove SameSite=None for browsers which are known to be affected.

Session Validation

A newline separated list of rules declaring attributes that must not change in the same session. A rule has the following syntax:

AUTH|ENV|CONST|PARAM|HEADER:<name of the attribute>:block|invalidate

• block: the request will be blocked and 403 (Forbidden) will be returned
• invalidate: the session will be invalidated and a new one will be created

nevisProxy Conditions are supported. See nevisProxy reference guide for details.

For instance, use the following configuration to terminate the session if the source IP changes:

ENV:REMOTE_ADDR:invalidate

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.

Language Cookie Name

Enter a name of the cookie that nevisLogrend issues to remember the language of the user.

The same name will also be used in nevisAuth to determine the language.

Note that the language cookie name is an instance global configuration in nevisAuth. Enter the same value for all realms associated with the same nevisAuth instance.

Language Cookie Domain

Enter a domain for the cookie that nevisLogrend issues to remember the language of the user.

This setting should only be used when you want to issue a wildcard cookie to share the language with other sub-domains (e.g. across multiple Virtual Host).

For instance, if you enter .example.com then the cookie will also be sent to subdomain.example.com.

Reset Authentication Condition

In some setups it is required to adapt the resetAuthenticationCondition of the Domain. You can configure a nevisAuth or EL expression here.

If the expression evaluates to true then the authentication flow is reset and the request is dispatched from the beginning.

Authorization Policy

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Assign the pattern to an application to enforce a session upgrade (stepup).

Define the session upgrade process in the realm used for initial authentication.

If the realm is a SAML Service Provider Realm, define the upgrade flow in the realm assigned to the SAML Identity Provider.

Required Roles

Optional setting to enforce authorization.

Callers need any of the specified roles to access.

Required roles defined for an application can be overridden for a sub-path by combining several Authorization Policy patterns for this application. Required roles can also be inherited between patterns. See Required Roles Mode for details.

This setting requires assigning an Authentication Realm on the application pattern.

Usage examples:

• Enforce required roles for an application: use an Authorization Policy pattern with the Required Roles to enforce and link it to the application via Additional Settings;
• Enforce required roles for some sub-paths of an application: use an Authorization Policy pattern with the Required Roles to enforce and Apply only to sub-paths set to the paths to protect. Link the pattern to the application via Additional Settings;
• Enforce some main required roles for an application and some specific required roles for some sub-paths: use two Authorization Policy patterns, one with the main Required Roles and no sub-path, and one with the specific Required Roles and Apply only to sub-paths set to the paths where the specific required roles should apply. Link both patterns to the application via Additional Settings.
• Enforce some main required roles for an application and disable them for some sub-paths: use two Authorization Policy patterns, one with the main Required Roles and no sub-path, and one with no Required Roles and Apply only to sub-paths set to the paths where no required roles should be enforced. Link both patterns to the application via Additional Settings.
• Enforce some required roles for an application and add some forbidden roles for some sub-paths: use two Authorization Policy patterns, one with the Required Roles for the application, Required Roles Mode set to self-contained, and no sub-path, and the other pattern with no Required Roles, Required Roles Mode set to inherited, the Forbidden Roles for the subpaths, Forbidden Roles Mode set to self-contained, and Apply only to sub-paths set to the paths where the forbidden roles should be enforced. Link both patterns to the application via Additional Settings.

Forbidden Roles

Optional setting to enforce authorization.

Callers must not have any of the specified roles to access.

Forbidden roles defined for an application can be overridden for a sub-path by combining several Authorization Policy patterns for this application. Forbidden roles can also be inherited between patterns. See Forbidden Roles Mode for details.

This setting requires assigning an Authentication Realm on the application pattern.

Usage examples:

• Enforce forbidden roles for an application: use an Authorization Policy pattern with the Forbidden Roles to enforce and link it to the application via Additional Settings;
• Enforce forbidden roles for some sub-paths of an application: use an Authorization Policy pattern with the Forbidden Roles to enforce and Apply only to sub-paths set to the paths to protect. Link the pattern to the application via Additional Settings;
• Enforce some main forbidden roles for an application and some specific forbidden roles for some sub-paths: use two Authorization Policy patterns, one with the main Forbidden Roles and no sub-path, and one with the specific Forbidden Roles and Apply only to sub-paths set to the paths where the specific forbidden roles should apply. Link both patterns to the application via Additional Settings.
• Enforce some main forbidden roles for an application and disable them for some sub-paths: use two Authorization Policy patterns, one with the main Forbidden Roles and no sub-path, and one with no Forbidden Roles and Apply only to sub-paths set to the paths where no forbidden roles should be enforced. Link both patterns to the application via Additional Settings.
• Enforce some forbidden roles for an application and add an authentication level for some sub-paths: use two Authorization Policy patterns, one with the Forbidden Roles for the application, Forbidden Roles Mode set to self-contained, and no sub-path, and the other pattern with no Forbidden Roles, Forbidden Roles Mode set to inherited, the Authentication Level for the subpaths, Authentication Level Mode set to self-contained, and Apply only to sub-paths set to the paths where the authentication level should be enforced. Link both patterns to the application via Additional Settings.

Authentication Level

The Authentication Level defines the strength of authentication. Enter a number between 2 and 9 (including).

If the session is not yet at the configured level a session upgrade will be performed.

Level 1 is the weakest possible authentication. By definition this level is reached by the initial authentication flow, e.g. set by a username / password authentication step (e.g. LDAP Login).

Level 2 is the default level set by steps which do second factor authentication (e.g. Test TAN).

Levels 3 to 9 are not used by default. These levels may be used for additional session upgrade processes.

For the session upgrade to succeed there must be a step which set at least this level. This step must be assigned to Session Upgrade Flow(s) in the Authentication Realm pattern.

In case the upgrade flow consists of multiple steps and the level should be reached by a subsequent step assign the Advanced Session Upgrade pattern instead.

The authentication level defined for an application can be overridden for a sub-path by combining several Authorization Policy patterns for this application. The authentication level can also be inherited between patterns. See Authentication Level Mode for details.

This setting requires assigning an Authentication Realm on the application pattern.

Usage examples:

• Enforce an authentication level for an application: use an Authorization Policy pattern with the Authentication Level to enforce and link it to the application via Additional Settings;
• Enforce an authentication level for some sub-paths of an application: use an Authorization Policy pattern with the Authentication Level to enforce and Apply only to sub-paths set to the paths to protect. Link the pattern to the application via Additional Settings;
• Enforce some main authentication level for an application and some specific authentication level for some sub-paths: use two Authorization Policy patterns, one with the main Authentication Level and no sub-path, and one with the specific Authentication Level and Apply only to sub-paths set to the paths where the specific authentication level should apply. Link both patterns to the application via Additional Settings.
• Enforce some main authentication level for an application and disable them for some sub-paths: use two Authorization Policy patterns, one with the main Authentication Level and no sub-path, and one with no Authentication Level and Apply only to sub-paths set to the paths where no authentication level should be enforced. Link both patterns to the application via Additional Settings.
• Enforce an authentication level for an application and add some required roles for some sub-paths: use two Authorization Policy patterns, one with the Authentication Level for the application, Authentication Level Mode set to self-contained, and no sub-path, and the other pattern with no Authentication Level, Authentication Level Mode set to inherited, the Required Roles for the subpaths, Required Roles Mode set to self-contained, and Apply only to sub-paths set to the paths where the required roles should be enforced. Link both patterns to the application via Additional Settings.

Apply only to sub-paths

Set to apply this pattern on some sub-paths only.

Sub-paths must be relative (e.g. not starting with /) and will be appended to the frontend path(s) of the virtual host (/) or applications this pattern is assigned to.

Sub-paths ending with / are treated as a prefix, otherwise an exact filter-mapping will be created.

The following table provides examples to illustrate the behaviour:

Frontend Path	Sub-Path	Effective Filter Mapping
/	secure/	/secure/*
/	accounts	/accounts
/	api/secure/	/api/secure/*
/	api/accounts	/api/accounts
/app/	secure/	/app/secure/*
/app/	accounts	/app/accounts
/app/	api/secure/	/app/api/secure/*
/app/	api/accounts	/app/api/accounts

Required Roles Mode

The Required Roles Mode defines which Required Roles are set for the current paths.

When combining several Authorization Policy patterns for an application, this setting allow inheriting the Required Roles from a more general pattern.

Choose one of:

• self-contained: The Required Roles defined in this pattern are applied to the current paths. They override any Required Roles set on parents paths. If no Required Roles are set in the current pattern, no required roles will be enforced for the current paths.
• inherited: The Required Roles in this pattern is not used. Use this setting if you have another Authorization Policy pattern applied to a parent path to inherit the configuration from. For the Required Roles to be inherited from a particular parent, this setting has to be set to default (self-contained) in the parent pattern (otherwise you may inherit a value from a grandparent).

Forbidden Roles Mode

The Forbidden Roles Mode defines which Forbidden Roles are set for the current paths.

When combining several Authorization Policy patterns for an application, this setting allow inheriting the Forbidden Roles from a more general pattern.

Choose one of:

• self-contained: The Forbidden Roles defined in this pattern are applied to the current paths. They override any Forbidden Roles set on parent paths. If no Forbidden Roles are set in the current pattern, no forbidden roles will be enforced for the current paths.
• inherited: The Forbidden Roles in this pattern is not used. Use this setting if you have another Authorization Policy pattern applied to a parent path to inherit the configuration from. For the Forbidden Roles to be inherited from a particular parent, this setting has to be set to default (self-contained) in the parent pattern (otherwise you may inherit a value from a grandparent).

Authentication Level Mode

The Authentication Level Mode defines which Authentication Level is set for the current paths.

When combining several Authorization Policy patterns for an application, this setting allow inheriting the Authorization Level from a more general pattern.

Choose one of:

• self-contained: The Authentication Level defined in this pattern is applied to the current paths. They override any Authentication Level set on parent paths. If no Authentication Level is set in the current pattern, no authentication level will be enforced for the current paths.
• inherited: The Authentication Level in this pattern is not used. Use this setting if you have another Authorization Policy pattern applied to a parent path to inherit the configuration from. For the Authentication Level to be inherited from a particular parent, this setting has to be set to default (self-contained) in the parent pattern (otherwise you may inherit a value from a grandparent).

Automatic Key Store

#Key Management

Plugin: nevisadmin-plugin-nevisproxy

Sets up a key store managed by nevisAdmin 4.

In classic deployment the private key is generated during deployment by running a command on the target host.

nevisAdmin then downloads the CSR and issues a certificate, which is deployed to the target host.

In Kubernetes deployment a custom resource definition (CRD) is generated and sent to the Nevis Operator running in the cluster.

Set the inventory variable __nevisadmin_pki_automatic_allowed_mode to restrict the allowed modes:

• any (default) - assignment of key management patterns is optional.
• explicit - assign patterns where-ever a key store or trust store is required.

This example illustrates how the key store looks on the target system:

[root@nevis /]# ls -l /var/opt/keys/own/<name>/
total 40
-rw-r----- 1 root nvbgroup 1103 Dec  1 07:05 ca-chain.pem
-rw-r----- 1 root nvbgroup 1013 Dec  1 07:05 cert.pem
-rw-r----- 1 root nvbgroup  887 Dec  1 07:05 csr.pem
-rwxr-x--- 1 root nvbgroup   40 Dec  1 07:05 keypass
-rw-r----- 1 root nvbgroup 1675 Dec  1 07:05 key_pkcs1.pem
-rw-r----- 1 root nvbgroup 1704 Dec  1 07:05 key.pem
-rw-r----- 1 root nvbgroup  451 Dec  1 07:05 key_pub.pem
-rw-r----- 1 root nvbgroup 2053 Dec  1 07:05 keystore.jks
-rw-r----- 1 root nvbgroup 2309 Dec  1 07:05 keystore.p12
-rw-r----- 1 root nvbgroup 2688 Dec  1 07:05 keystore.pem

Owner(s)

Select an instance pattern which defines the target hosts of this Automatic Key Store. This setting is required only when this pattern is assigned to an Automatic Trust Store.

Automatic Trust Store

#Key Management

Plugin: nevisadmin-plugin-nevisproxy

Sets up a trust store managed by nevisAdmin 4.

In classic deployment the certificates of trusted key stores are deployed to the target host.

In Kubernetes deployment a custom resource definition (CRD) is generated instead and sent to the Nevis Operator running in the cluster.

Set the inventory variable __nevisadmin_pki_automatic_allowed_mode to restrict the allowed modes:

• any (default) - assignment of key management patterns is optional.
• explicit - assign patterns where-ever a key store or trust store is required.

This example illustrates how the trust store looks on the target system:

[root@nevis /]# ls -l /var/opt/keys/trust/<name>/
total 16
-rwxr-x--- 1 root nvbgroup   16 Dec  1 07:05 keypass
-rw-r----- 1 root nvbgroup 1656 Dec  1 07:05 truststore.jks
-rw-r----- 1 root nvbgroup 2042 Dec  1 07:05 truststore.p12
-rw-r----- 1 root nvbgroup 2116 Dec  1 07:05 truststore.pem

Trusted Key Store

Assign one or multiple Automatic Key Store patterns to establish a trust relation.

Additional Trusted Certificates

Upload additional trusted certificates in PEM format.

The content of all files will be concatenated and added to the truststore.* files generated by this pattern.

You can make this a variable and upload the files in the inventory using the Attach files function.

Azure Service Bus

#Identity Management #Add-ons #Experimental

Plugin: nevisadmin-plugin-nevisidm

Configures a nevisIDM Instance to publish events into Azure Service Bus queues.

Queues can be reused, for example for handling time-based and other failures, Dead Letter Queue and Expiry Queue pointed to the same Remote Queue with the same AzureServiceBusRemoteQueue pattern.

Remote Provisioning Queue

Remote Azure Service Bus Queue to which provisioning messages should be sent.

Remote Expiry Queue

Remote Azure Service Bus Queue to which Expiry messages should be sent.

Messages in Expiry Queue are those messages which validTo time has passed without successful receive action and without failing for other reason. For further reference check NevisIdm Technical documentation > Configuration > Components > Provisioning module > Provisioning providers.

Remote Dead Letter Queue

Remote Azure Service Bus Queue to which Dead Letter messages should be sent.

Dead letter messages are those messages which are not in the expiryQueue and their delivery was unsuccessful. For further reference check NevisIdm Technical documentation > Configuration > Components > Provisioning module > Provisioning providers.

Trust Store

Assign a trust store which provides the Microsoft Azure TLS Issuing CA 01 certificate.

You can access the Host name with your browser by adding https:// in front, download the CA certificate, and then use a PEM Trust Store to provide it.

Azure Service Bus Remote Queue

#Identity Management #Add-ons #Experimental

Plugin: nevisadmin-plugin-nevisidm

Configures an Azure Service Bus connection-string for Azure Service Bus pattern to use.

Host Name

Enter the complete Host name of the Service Bus as shown in the Azure portal.

Example: my-service-bus-name.servicebus.windows.net

Shared Access Policy

Enter the Policy that shall be used to connect.

Also known as: SAS Policy, Shared access policy

Primary Key

Enter the Primary Key of the Policy as shown in the Azure portal.

Queue

Enter the name of a queue.

BehavioSec Risk Plugin

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisdetect

The pattern configures BehavioSec risk scores to be integrated with nevisDetect.

For more information, see BehavioSec Developer Docs.

URL

Service URL used to connect to the BehavioSec service from the plugin. For example: https://mycompany.behaviosec.com/BehavioSenseAPI/

Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

Proxy

Outbound proxy, optional

Web App URL

BehavioSec Dashboard URL

Fraudulent Flags

List of BehavioSec report flag names. Please add each entry line-by-line.

If any of these flags contains true value in the report, the request is marked as fraudulent and the request fails.

If the field remains empty, the items marked with (*) will be part of the default configuration.

Potential flag names (as of 5.4):

• advancedUser (*)
• autoModel
• coached (*)
• deviceChanged (*)
• deviceIdShared (*)
• deviceIntegrity (*)
• diError (*)
• drFlag (*)
• finalized
• ipChanged (*)
• ipShared (*)
• isDataCorrupted (*)
• isBot (*)
• isDuplicate (*)
• isOneHand
• isRemoteAccess (*)
• isReplay (*)
• isSessionCorrupted (*)
• isWhitelisted
• locationMismatch (*)
• newCountry (*)
• newsubprofile
• numpadAnomaly (*)
• numpadUsed
• numrowUsed
• ohFlag (*)
• otjsError (*)
• pdError (*)
• pnFlag (*)
• pocAnomaly (*)
• pocUsed
• tabAnomaly (*)
• tabUsed
• travelTooFast (*)
• uiConfidenceFlag (*)
• uiScoreFlag (*)

Flag / Description Mappings

List of BehavioSec report flag names with their description name in the following format: <flagName>=<descriptionName>. Please add each entry line-by-line.

If any of these flags contain true value in the report, it will be added to the respective header field along with the mapped description value.

To delete a default mapping, omit the description field's name: <flagName>=. If the flag is part of the default mapping, it will be overwritten, otherwise added.

Default combined values (flag name/description name):

• advancedUser/advancedUserScore
• deviceChanged/deviceDesc
• deviceIntegrity/deviceIntegrityDesc
• diError/diDesc
• finalized/finalizeTimestamp
• isBot/botDesc
• isDuplicate/duplicateDesc
• isRemoteAccess/raDesc
• isReplay/replayDesc
• isSessionCorrupted/isSessionCorruptedDesc
• locationMismatch/locationMismatchDesc
• newCountry/ipCountry
• numpadUsed/numpadRatio
• otjsError/otjsDesc
• pdError/pdDesc
• pocUsed/pocRatio
• tabUsed/tabRatio
• travelTooFast/travelTooFastDesc
• uiConfidenceFlag/uiConfidence
• uiScoreFlag/uiScore

CSRF Protection Settings

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Customize CSRF protection for an application, for example, Web Application.

You can assign the pattern to Virtual Host patterns as well, to configure CSRF protection for all applications on this host.

SameSite Cookie (Experimental)

Set to lax to issue a separate cookie with the SameSite flag set to lax. In this configuration, links and redirects from other domains are allowed, while CSRF-prone requests (e.g. POST) should be prevented by the browser.

Set to off to not send an additional cookie. There are several reasons why this feature may be disabled:

• Not all browsers support the SameSite flag and behave incorrectly by never sending the cookie. Older versions of IE and Windows may be affected.

• The SameSite flag breaks SAML use cases when POST binding is used. SP-initiated authentication does work with NEVIS but all other SAML process (e.g. logout) will fail.

Header-based Check

CSRF protection can be obstructive for some cross-domain use cases (e.g. federation or providing a public REST API).

Allowed Domains

CSRF protection can be obstructive for cross-domain use cases (e.g. federation or providing a public REST API).

Enter domains which should be excluded from header-based CSRF protection. There is no support for wildcards, pre- or postfix notations (sub-domains must be listed individually).

Example:

www.adnovum.ch 
adnovum.ch

Cookie Customization

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Configure whether cookies are to be returned to the caller or stored in the user session.

You may also assign the pattern to multiple applications, and set Shared Protected Cookies to share cookies between applications.

Note that cookie sharing is supported only for applications using the same session in nevisProxy, that is, applications protected by the same authentication realm.

The default cookie handling differs based on the type of application:

Type	Behaviour
Web Application (with authentication)	Cookies are stored.
Web Application (public)	Cookies are allowed to passthrough.
REST API	Cookies are dropped.
SOAP Service	Cookies are dropped.

Client Cookies

Cookies listed here will be allowed to pass through.

Use for cookies which should be returned to the caller (e.g. browser).

Regular expressions are supported.

Example:

• LANG.*

Shared Protected Cookies

Cookies listed here will be stored in nevisProxy and shared between all applications which have this pattern assigned.

Note that storing cookies requires a user session. Thus, we recommend to not use this feature for applications which are supposed to be stateless and public.

Regular expressions are supported.

Note that cookies matching ^Marker_.*$ will never be stored as a corresponding allow rule is generated to support Session Expiration features of the SAML SP Realm.

Example:

• LANG.*

Protected Cookies

Cookies listed here will be stored in nevisProxy.

However, cookies marked as Client Cookies in any Cookie Customization pattern assigned to the same application will still be allowed to pass through!

Storing cookies requires a user session. Thus, we recommend to not use this feature for stateless or public applications!

Incoming cookies with the same name will be blocked.

Regular expressions are supported.

Example:

• .*SESSION.*

Cookie Conflict Resolution

When multiple Cookie Customization patterns are used it happen that a certain cookie is defined as both a Client Cookie and as a Shared Protected Cookie for the same application.

By default, this conflict is resolved by allowing the cookie to pass-through, treating it as a Client Cookie.

This behaviour is usually more robust but less secure as the cookie will be accessible in the browser.

Select protect to threat the cookie as a Shared Protected Cookie instead.

Custom Input Field

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

A field to ask the user for some input and store the input in a variable.

Use the variable in subsequent authentication steps.

Label

Enter a text or litdict key to be displayed as label in front of the input field.

Variable Name

Enter <scope>:<name> of the variable which shall be set.

The following scopes are supported:

• inargs
• notes
• sess or session

For instance, enter notes:loginid to prefill the login form which is produced by the nevisIDM Password Login pattern.

Optional

Input into the field is optional or mandatory.

Choose between:

• optional - No input is required to the field.
• mandatory - Input is required to the field.

Custom Risk Score Weight Configuration

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisadapt

Use the pattern for custom risk score weight configuration. Every weight must be between 0 and 1 inclusive. The higher the value the more impact the component has on the aggregate score. Set the weight to 0 to disregard the analyzer completely. Default values are the same as for Balanced configuration.

Geolocation Weight

Configuration of the risk score weight for the geolocation analyzer's risk score.

IP Weight

Configuration of the risk score weight for the ip analyzer's risk score.

IP Reputation Weight

Configuration of the risk score weight for the ip reputation analyzer's risk score.

IP Velocity Weight

Configuration of the risk score weight for the ip velocity analyzer's risk score.

Suspicious Country Weight

Configuration of the risk score weight for the suspicious country analyzer's risk score.

Device Cookie Weight

Configuration of the risk score weight for the device cookie analyzer's risk score.

Fingerprint Weight

Configuration of the risk score weight for the fingerprint analyzer's risk score.

Default Service

#Applications #Experimental

Plugin: nevisadmin-plugin-nevisproxy

Makes the configured Frontend Path(s) accessible on the assigned Virtual Host(s) by mapping a DefaultServlet.

You can decorate the paths by assigning Additional Settings, for example, to provide custom services using nevisProxy filters.

Note that if your request passes through the entire filter chain without being responded or redirected an error code 404 is returned.

The pattern is only to be used when there is no pattern for your use case. Whenever possible, use the following patterns instead:

• Web Application, REST Service, SOAP Service: to make a backend application accessible
• Standalone Authentication Flow: to provide an entry point for flows implemented in nevisAuth
• Hosting Service: to host static resources

Virtual Host(s)

Assign a Virtual Host which shall serve as entry point.

Frontend Path(s)

The path(s) which shall be accessible on the assigned Virtual Host(s).

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.

Dispatcher Button

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

Adds a button to an authentication GUI which takes the user to another step.

Label

Enter the label which shall be used for this button.

The label should be added to the Translations of the realm.

On Click

Assign an authentication step to continue with when the button is clicked.

Name

Enter a name to use for the GuiElem.

Configuration is optional but may be required when the button is rendered differently based on the name.

If missing, the sanitized name of the pattern will be used.

Value

Enter a value to use for the GuiElem.

Configure only when you need a different value.

Dispatcher Step

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Dispatch to other authentication steps based on nevisAuth expressions.

Condition(s)

Configure conditions.

The first column gives your condition a name. The name must be unique and must be used in Transition(s).

In the second column enter an expression. This may be a nevisAuth expression (${...}) or EL expression (#{...}). See nevisAuth Technical Documentation for information about the expression syntax.

In EL expressions it is possible to reference variables from the inventory, an example can be found below.

All conditions will be evaluated and thus multiple conditions may apply. In this case the combination of conditions in must be configured in Transition(s).

Examples:

Key	Value
pwreset	${request:currentResource:/pwreset:true}
sp	${sess:ch.nevis.auth.saml.request.issuer:^SP$:true}
mfa	#{${var.mtanEnabled} or ${var.oathEnabled}}

Transition(s)

Define how to dispatch based on conditions.

In the first column enter the transition. A transition may be:

• a condition name
• a comma-separated list of conditions

All conditions in the transition must match in order for the transition to be applicable. The most specific transition is chosen.

In the second column enter the position. Position refers to the list of Conditional Step(s). The first step has position 1.

Examples:

Transition	Position
pwreset	1
pwreset,mfa	2

Conditional Step(s)

Assign the steps to be used for Transition(s).

Default Step

Assign the step to continue with if no transition matches.

Email Input Field

#Authentication

Plugin: nevisadmin-plugin-nevisauth

An input field for an email address. A basic syntax check will be performed.

The entered value will be stored in a session variable. Use the variable in subsequent authentication steps.

Label

Enter a text or litdict key to be displayed as label in front of the input field.

Variable Name

Enter <scope>:<name> of the variable which shall be set.

The following scopes are supported:

• inargs
• notes
• sess or session

For instance, enter notes:loginid to prefill the login form which is produced by the nevisIDM Password Login pattern.

Email Validation

Customize the email validation regular expression.

The regular expression will be used in a Groovy script and thus the \ character will be escaped in the generated script.

Optional

Input into the field is optional or mandatory.

Choose between:

• optional - No input is required to the field.
• mandatory - Input is required to the field.

Email TAN (eTAN)

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Use to send TAN codes to users via email.

You can use this pattern for email validation or authentication.

The pattern works out-of-the-box as an On Success for nevisIDM Password Login.

If you have a different flow, you may have to adapt the Recipient to consume the email from a different variable.

To configure the message template sent to the user, translate the label etan.message.template.

On Success

Configure the step to execute after successful authentication. If no step is configured here the process ends and the user will be authenticated.

On Failure

Assign the step to execute in case no TAN code can be sent or all attempts had been exhausted.

The step will be executed in the following cases:

• the Recipient could not be determined
• all attempts had been exhausted and the user has failed to authenticate

If no step is assigned then the authentication flow will be terminated and an error GUI with label error_99 (System Problems) will be shown.

Buttons

Assign a Dispatcher Button to add a button which points to a different authentication step.

SMTP Server

The connection provider for the sending the email code.

Choose between Sendgrid SMTP and a Generic SMTP patterns.

Sender

Sender email address.

Recipient

Enter a nevisAuth or EL expression for the recipient.

You have to ensure that this expression always resolves. There will be a system error if the expression does not produce an email address.

Examples:

${sess:ch.nevis.idm.User.email}

Max Retries

The maximum attempts for each code.

When this threshold is reached, the behaviour depends on Max Regenerations.

As long as Max Regenerations is not exhausted, a new code will be generated and sent to the user.

Once Max Regenerations is reached as well, the On Failure exit will be taken.

Max Regenerations

The maximum number of times a new code can be generated.

If the value is 1 or greater, a resend button will be added to the screen. The button is shown only when there are still resends left.

When you configure 0 there will only be 1 code and thus there will be no resend button. Note that when Max Retries is reached, a new code will be generated and sent automatically.

TAN Format

The format of the TAN sent to the user. For instance, with 5 digits, the generated TAN will always consist of 5 numerical digits (e.g. 12345).

Testing Mode

When testing mode is enabled the TAN code is always AAAAA.

Thus, you can test the flow more easily during integration.

No email will be sent and thus no SMTP Server needs to be assigned.

Authentication Level

Set an authentication level if authentication of this step is successful. The level is relevant only if there are is an Authorization Policy assigned to applications.

GUI Name

Change the name of the Gui element.

Change this only if you need the Gui name your login template to render the screen differently.

Gui Title

Change the Gui title.

We recommend to enter a label here and provide translations for this label in the Authentication Realm.

FIDO2 Authentication

#FIDO2 #Authentication #Experimental

Plugin: nevisadmin-plugin-fido2

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

#FIDO2 #Testing #Experimental

Plugin: nevisadmin-plugin-fido2

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

#FIDO2 #Authentication #Experimental

Plugin: nevisadmin-plugin-fido2

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.

Facebook Login Step

#Federation #Authentication #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

Set up social login, using Facebook as OpenID Connect provider.

Client ID

ClientID is App ID provided by Facebook when you register Facebook as IdP service.

Client Secret

Client Secret is App Secret provided by Facebook when you register Facebook as IdP service.

Return Path

The callback URI to go to after a successful login with Facebook.

This will create an endpoint in your host config.

The URL will be a combination of the Frontend Address of the Virtual Host and the value configured here. For example, let's assume that you have configured:

• Return Path: /oidc/facebook/
• Frontend Address: https://nevis.net

Then the URL will be https://nevis.net/oidc/facebook/.

Use the exact: prefix to use the given path as-is. Without this prefix a normal mapping with /* will be generated and thus sub-paths will be accessible as well.

Scope(s)

Select the request scopes for getting user information from Facebook.

The default is email and thus minimal information will be returned.

Select public_profile to return additional user information.

Scope offline_access is not supported as Facebook has removed this scope.

Virtual Host

Assign a Virtual Host which shall serve as entry point for the callback from social login provider.

In case your host has

• 1 address, that address will be used
• many addresses with
  • 1 https, and many http, the https will be used without warning
  • mix between http and https, the 1st https will be used with warning
  • single scheme (http or https only) the 1st address will be used with warning

E.g.

http://nevis.net
http://nevis-security.net
https://nevis.net
https://nevis-security.net

The https://nevis.net will be used as the host for Apple callback

On Success

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

In case you change this to your custom step(s), you can assign pattern Social Login Final Step as the last step of the Authentication process to redirect back to original URL.

On Failure

The step that will be executed if the authentication fails. If no step is configured here the process ends with AUTH_ERROR.

In case you change this to your custom step(s), you can assign pattern Social Login Final Failure Step as the last step of the Authentication process to redirect back to original URL.

nevisIDM

Choose which nevisIDM instance you want to store the user's information after logged in with social login provider.

Client External ID

The ExtId of the client in nevisIDM that will be used to store the user

On User Not Found

Configure the authentication flow to be executed when no user was found and the email provided by social account does not exist. The authentication flow must contain the Social Login Create User pattern if a new user shall be created.

Note: Please select scope email and profile for getting user's information from social account.

On User Found

Configure the Authentication Flow in case no user with Subject/ID from social account was found but email does exist in nevisIDM. The Authentication Flow must contain:

• Social Login Link User pattern to link an existing user in IDM with Subject/ID of social account.
• Social Login Done to end the social login flow after some other action(s).

Note: Please select scope email and profile for getting user's information from social account.

Claims Request

The claims request parameter. This value is expected to be formatted in JSON and does not accept trailing spaces nor tabs.

User ID Field

Logged userId will automatically get from social account. But you can change the userId by using this field.

Additional Auth Request Parameters

Arbitrary additional request parameters used in the authentication request. The property supports variable substitution.

Example:

[paramName]=[paramValue]

Button Label

Enter the text that should be displayed for the end-user on the social login button, and provide translations for this label on the Authentication Realms.

Generic Application Settings

#Application Protection #Generic

Plugin: nevisadmin-plugin-nevisproxy

Customize the web.xml configuration for an application using XML constructs as described in the nevisProxy Technical Documentation.

Use as add-on for Web Application, SOAP Service, or REST Service.

The following expressions may be used for all applications:

• ${name}: sanitized name of the pattern
• ${service.name}: the name of the application
• ${service.id}: the unique ID of the application
• ${host.key}: use as EntryPointID when adding a custom IdentityCreationFilter (advanced use case)

For applications with only 1 Frontend Path:

• ${service.path}: the frontend path of the application, excluding trailing slash / and asterisk *
• ${service.mapping}: the url-pattern calculated for the frontend path of the application

In case an Authentication Realm is assigned:

• ${realm.name}: name of the realm (use for StateKey / DelegateSource)
• ${auth.connector}: name of the Esauth4ConnectorServlet (use for AuthenticationServlet)
• ${logrend.renderer}: name of the LoginRendererServlet
• ${logrend.connector}: name of the Http(s)ConnectorServlet for nevisLogrend (if nevisLogrend is used)

When defining filters it is recommended to set Filter Mappings to automatic. This way the filters are mapped to all frontend paths of the application.

Filters and Mappings

Configure filters and their mappings using the XML syntax described in the nevisProxy Technical Documentation.

Filters that have the same name as other filters (even those defined by other patterns) will be combined: the init-param sets will be merged where possible. Direct contradictions are interpreted as validation failures.

Example 1: Create (or patch) a filter with a fixed name

<filter>
   <filter-name>SomeName</filter-name>
   <filter-class>ch::nevis::isiweb4::filter::SomeClass</filter-class>
   <init-param>
      <param-name>...</param-name>
      <param-value>...</param-value>
   </init-param>
</filter>

Example 2: Create (or patch) a filter using an application-specific name

<filter>
   <filter-name>SomeName_${service.name}</filter-name>
   <filter-class>ch::nevis::isiweb4::filter::SomeClass</filter-class>
   ...
</filter>

Example 3: Map a filter to a sub-path of the assigned application(s). This example works for applications which have 1 frontend path only.

<filter-mapping>
   <filter-name>SomeFilter</filter-name>
   <url-pattern>${service.path}/custom/*</url-pattern>
</filter-mapping>

Example 4: Use multi-value expressions

Multi-value expressions replicate an entire line for each associated value.

Use the expressions *{service.path} and *{service.mapping} to generate filters which must contain the frontend paths of all assigned applications.

The following snippet is not complete but should illustrate the concept:

<filter>
    <filter-name>FormSigning</filter-name> 
    <filter-class>ch::nevis::isiweb4::filter::validation::EncryptionFilter</filter-class>
    <init-param>
        <param-name>EntryURL</param-name>
        <param-value>
            *{service.path}/
        </param-value>
    </init-param>
    ...
</filter>

Filter Mappings

Choose between:

• manual (default): only the filter-mapping elements which have been configured via Filters and Mappings will be added.
• automatic: filters configured via Filters and Mappings will be mapped to all Frontend Paths of the application.
• both: like automatic but additional filter-mapping elements are allowed as well.

Filter Phase

When adding filter-mapping elements, a phase must be defined.

The phase defines where the filter-mapping is placed in the web.xml and ensures that filters are applied in the right order, relative to other phases.

The order within a certain phase is undefined as it must not matter.

The order for requests is START to END and END to START for responses.

This setting applies to all filter-mapping elements.

The filter-mapping elements may be provided via Filters and Servlets, or created automatically (see Filter Mappings for details).

Choose from the following filter phases:

• START: applied as early as possible for requests and as late as possible for responses.
• BEFORE_SANITATION: applied before filters which validate the request (e.g. Mod Security).
• SANITATION: used for security. This is the first phase which allows accessing the session for applications protected by a realm.
• AFTER_SANITATION: your request has passed security checks.
• BEFORE_AUTHENTICATION: applied just before authentication.
• AUTHENTICATION: used by the filter which connects to nevisAuth for applications which are protected by an Authentication Realm.
• AFTER_AUTHENTICATION: the request has level 1 authentication. Used by Authorization Policy for Authentication Level stepup.
• BEFORE_AUTHORIZATION: choose this phase to do preprocessing before authorization.
• AUTHORIZATION: used by Authorization Policy for Required Roles check.
• AFTER_AUTHORIZATION: used by patterns assigned as Application Access Token to applications.
• END: applied as late as possible for requests and as early as possible for responses.

This setting is ignored when you patch a filter generated by another pattern (e.g. by adding, overwriting, or removing an init-param element) but don't create any filter-mapping element.

Servlets and Mappings

Configure servlet and/or servlet-mapping elements using the XML constructs described in the nevisProxy Technical Documentation.

You may add new elements or customize elements provided by other patterns.

• Reference a servlet by setting servlet-name. Use Connector_${service.name}for the servlet which connects to the backend application.
• Reference a servlet-mapping by setting url-pattern.

In Kubernetes side-by-side deployment a postfix is added to service names. Use the expression ${service.postfix} connecting to a service deployed against the same inventory.

Example 1: Add or overwrite an init-param:

Enable load-balancing when there are multiple backend servers.

<servlet>
  <servlet-name>Connector_${service.name}</servlet-name>
  <init-param>
    <param-name>LoadBalancing</param-name>
    <param-value>true</param-value>
  </init-param>
</servlet>

Instruct nevisProxy to a add Content-Type header when missing.

<servlet>
  <servlet-name>Connector_${service.name}</servlet-name>
  <init-param>
    <param-name>ProxyPolicy</param-name>
    <param-value>mime-completion</param-value>
  </init-param>
</servlet>

Example 2: Remove an init-param (no param-value provided):

<servlet>
  <servlet-name>Connector_${service.name}</servlet-name>
  <init-param>
    <param-name>CookieManager</param-name>
  </init-param>
</servlet>

Example 3: Change the servlet-mapping for an application to use a different servlet by changing servlet-name.

<servlet>
   <servlet-name>Connector_Conditional_${service.name}</servlet-name>
   <servlet-class>ch::nevis::isiweb4::servlet::mapping::ServletMappingServlet</servlet-class>
   ...
</servlet>
<servlet-mapping>
   <servlet-name>Connector_Conditional_${service.name}</servlet-name>
   <url-pattern>${service.path}/*</url-pattern>
</servlet-mapping>

Removing servlet or servlet-mapping elements is not supported.

Template Parameters

Define Template Parameters.

Examples:

backend-host: backend.siven.ch

These parameters can be used in:

• Servlets and Mappings
• Filters and Mappings

The expression formats are:

${param.<name>}:

• name found: parameter value is used.
• name missing: expression is not replaced.

${param.<name>:<default value>}:

• name found: parameter value is used.
• name missing: default value will be used.

In <default value> the character } must be escaped as \}.

Remove Filter Mappings

Remove <filter-mapping> elements generated by other patterns.

The syntax is a map of <filter-name>:<url-pattern>, according to elements from the web.xml.

In the <filter-name> the expressions ${service.name} and ${realm.name} may be used.

For applications which have only 1 frontend path you may use ${service.mapping} instead of <url-pattern>.

Examples:

ModSecurity_${service.name}:${service.mapping}
Authentication_${realm.name}:${service.mapping}

Generic Authentication Realm

#Authentication #Realms

Plugin: nevisadmin-plugin-nevisauth

Create a realm by providing the entire configuration as XML. We recommend you use the higher level Authentication Realm instead.

Token patterns, for example, Nevis SecToken and JWT Token, are not supported.

To issue a token, add the required AuthState, for example, TokenAssemblerState, to the authentication flow, and assign a HTTP Header Customization pattern to the application to ensure that the token is sent to the backend.

There are several ways to trigger a stepup:

• use Authorization Policy to demand an Authentication Level
• use Generic Application Settings to map a SecurityRoleFilter which has DynamicRoleAcquire set to true

For rendering login pages during authentication the nevisLogrend component is used. nevisLogrend is deployed on the same hosts as nevisProxy.

Configuration

Upload an XML file containing AuthState elements.

Upload of a complete esauth4.xml is not supported.

The Domain element is optional.

• If missing the element will be created. The Entry methods authenticate and stepup will be set to the first provided AuthState. The method logout is not set and thus the nevisAuth default behaviour applies.

• If provided the Domain must come before all AuthState elements. The attributes name and default are not supported and should be omitted. Attributes are sorted by name. The Entry elements are sorted by method.

The AuthState linked to stepup should be able to dispatch the request. For instance, you may have assigned an Authorization Policy to your application(s) and thus you need a state which decides based on the request variable requiredRoles.

The following example dispatches level 2 into an AuthState named TAN which provides authentication via mTAN:

<AuthState name="EntryDispatcher" class="ch.nevis.esauth.auth.states.standard.ConditionalDispatcherState" final="false">
    <ResultCond name="nomatch" next="Authentication_Done"/>
    <ResultCond name="level2" next="TAN"/> <!-- TAN state is expecetd to set authLevel="2" -->
    <Response value="AUTH_ERROR">
        <Arg name="ch.nevis.isiweb4.response.status" value="403"/>
    </Response>
    <property name="condition:level2" value="${request:requiredRoles:^2.*$:true}"/>
</AuthState>

The following expressions are supported:

• ${instance}: name of the nevisAuth instance
• ${request_url}: generates a nevisAuth expression which returns the URL of the current request
• ${realm}: name of the Realm (see below)
• ${keystore}: name of the KeyStore element provided by this pattern. Assign a pattern to Key Objects to add a KeyObject into this KeyStore.

The name of AuthState elements is prefixed with the sanitized name of the Realm (referred to as ${realm}).

The realm prefix must be added when using propertyRef to reference AuthStates generated by other patterns (e.g. <propertyRef name="${realm}_SomeState"/>).

An exception is the AuthState which defines the nevisIDM connection (as generated by nevisIdm Password Login or nevisIDM Connector for Generic Authentication). Here the propertyRef must be defined as follows:

<propertyRef name="nevisIDM_Connector"/>

This pattern does not validate that labels are translated. Translations can be provided on the Authentication Realm pattern.

Template Parameters

Define Template Parameters.

Examples:

smtp: smtp.siven.ch
sender: [email protected]

These parameters can be used in your Configuration.

The expression formats are:

${param.<name>}:

• name found: parameter value is used.
• name missing: expression is not replaced.

${param.<name>:<default value>}:

• name found: parameter value is used.
• name missing: default value will be used.

In <default value> the character } must be escaped as \}.

Resources

In case your AuthState elements require additional configuration files or scripts upload them here.

Files uploaded here will be deployed into the conf directory of the nevisAuth instance.

Key Objects

Assign patterns to add KeyObject elements to the KeyStore provided by this pattern.

nevisAuth

Assign a nevisAuth Instance pattern.

Key Store

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

If no pattern is assigned automatic key management will provide the required key material. This requires that the nevisAuth Instance is part of this project and also uses automatic key management.

Automatic key management should be used for test setups only.

Trust Store

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

If no pattern is assigned automatic key management is used to provide the trust store. This requires that the nevisAuth Instance is part of this project and also uses automatic key management.

Automatic key management should be used for test setups only.

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.

If no pattern is assigned automatic key management is asked to provide the trust store. This requires that the nevisAuth Instance is part of this project and also uses automatic key management.

Automatic key management should be used for test setups only.

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:

Key	Value
BodyReadSize	64000
InterceptionRedirect	Condition:ENV:HTTP_USER_AGENT:mozilla|Mozilla\ninitial\nnever
ClientCert	want

Custom Parameters (SecurityRoleFilter)

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

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

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:

Key	Value
EnablePollTerminatedCalls	true

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.

Login Template

Customize the rendering of login pages.

Download the default template to get started.

nevisLogrend: Simple Mode

Point your browser to a protected application to have a look at the login page. Download any resources (e.g. images, CSS) that you want to adapt. Then upload the changed files here.

To change the outer HTML upload a file named template.html. Here is a simple example:

<!DOCTYPE html>
<html lang="${lang.code}">
  <head>
    <title>${label.title}</title>
    <link href="${resources}/bootstrap.min.css" rel="stylesheet" type="text/css">
    <link href="${resources}/default.css" rel="stylesheet" type="text/css" media="all">
  </head>
  <body>
    <header id="header" class="container-fluid">
      <img class="logo center-block" src="${resources}/example.svg" alt="NEVIS Security Suite">
    </header>
    <main id="content" class="container">
      ${form}
    </main>
  </body>
</html>

Please also upload file resources referenced by your template (e.g. images, CSS, Javascript). Use this when you reference additional files, or if you want to override the default files provided.

The template must contain ${form} and may contain additional expressions.

Expression	Description
${form}	generated login form (required)
${lang.switch}	language switcher component
${lang.code}	current language code (i.e. EN, DE)
${label.title}	a human-readable title
${label.myLabel}	a custom text which must be defined via Custom Translations
${resources}	path to static resources (e.g. CSS, images, Javascript)

Some resources (i.e. bootstrap.min.css, default.css) are provided out of the box because they are required by the default template. Feel free to use them.

nevisLogrend: Expert Mode

Expert users may upload Velocity templates and resources to nevisLogrend.

Zip files will be extracted into the nevisLogrend application:

/var/opt/nevislogrend/<instance>/data/applications/<realm>

Flat files will be added to the following subdirectories:

• webdata/template: Velocity templates (*.vm)
• webdata/resources: additional resources (e.g. images, CSS)

nevisProxy: Simple Template

nevisProxy provides a simple login page renderer which can be used instead of nevisLogrend. See Login Renderer for details.

For each enabled language (e.g. en) upload a file named <lang>_template.html. The template must contain the placeholder NEVIS_AUTH_FORM.

If your templates require additional resources (e.g. CSS, images) upload them as Hosted Resources on the nevisProxy virtual host.

Login Template Mode

Choose between two options:

• additive: files uploaded as Login Template will be added on top of the default. Use this option when you want to add or replace files, but don't want to upload an entire template. There will be less work when you upgrade.

• complete: only the files uploaded as Login Template will be deployed. Use this option when you want to provide the entire template.

Translations

Labels are used to provide human-readable text in the language of the user.

The language is extracted from the Accept-Language header and the default login page template has a language selection.

Which labels are used depends on the assigned steps. Click Download Default Labels to retrieve the labels used and their translations.

Here you can overwrite the defaults and add your own translations or even introduce new labels which may be required when using a Custom Login Template or Generic Authentication Step patterns.

The name of uploaded files must end with the language code. As the format is compatible you may upload existing text_<code>.properties files of nevisLogrend or LitDict_<code>.properties of nevisAuth.

The encoding of uploaded files does not matter as long as all translations are HTML encoded.

The default login template uses the following labels:

• title - used as browser page title
• language.<code> - used by language switch component

The default logout process of nevisAuth (which will be applied when no step is assigned to Logout) produces a confirmation GUI which requires the following labels:

• logout.label - header of the logout confirmation GUI
• logout.text - text shown to the user
• continue.button.label - label on the confirmation button

Translations Mode

Choose between:

• combined - upload 1 file per language code named labels_<code>.properties. The labels will be added to both nevisAuth and nevisLogrend. Alternatively, you can upload a zip file called labels.zip containing these properties files.

• separate - select only when you need different labels in nevisAuth and nevisLogrend. The files must be called LitDict_<code>.properties for nevisAuth and text_<code>.properties for nevisLogrend. Alternatively, you may upload zip file called LitDict.zip and text.zip containing these properties files.

Default Translations

Choose between:

• enabled - add default translations for labels which are commonly used (e.g. title or language labels in nevisLogrend, error labels in nevisAuth) and which are required by the realm patterns (e.g. assigned authentication steps).

• disabled - select to only add what has been uploaded via Translations. Note that if Translations are incomplete users may encounter untranslated labels.

nevisLogrend default.properties

Add or overwrite properties in the default.properties of the nevisLogrend application.

Use only when there is no high-level setting. We recommend to not overwrite any language related properties, as the languages should be in sync with nevisAuth. You can configure the languages on the nevisAuth Instance.

Requires that nevisLogrend is used for GUI rendering. Check the help of Login Renderer for details.

Session Tracking

Choose between:

• COOKIE: issue a session cookie.
• AUTHORIZATION_HEADER: track the session based on the value of the Authorization header.
• CUSTOM: track the session based on custom configuration. It generates an empty session filter which has to be replaced (see below).
• disabled: disable session tracking.

CUSTOM session tracking

Given a pattern name of SSO, the following empty filter will be generated:

    <filter>
        <filter-name>SessionHandler_SSO</filter-name>
        <filter-class>__REPLACE_USING_GENERIC__</filter-class>
    </filter>

For the filter-class, a placeholder (REPLACE_USING_GENERIC) will be used and that placeholder has to be overwritten.

Another pattern must complete the session filter. For example, use Generic Virtual Host Context pattern with the following Filters and Mappings configuration:

<filter>
    <filter-name>SessionHandler_SSO_RealmName</filter-name>
    <filter-class>ch::nevis::nevisproxy::filter::session::SessionManagementFilter</filter-class>
    <init-param>
        <param-name>Identification</param-name>
        <param-value>CUSTOM</param-value>
    </init-param>
    <init-param>
        <param-name>Custom.RequiredIdentifiers</param-name>
        <param-value>HEADER:Authorization</param-value>
    </init-param>       
    <init-param>
        <param-name>Servlet</param-name>
        <param-value>LocalSessionStoreServlet</param-value>
    </init-param>
</filter>

Session Cookie Name

Each realm has its own session cookie. By default, this cookie will be called Session_<pattern-name>

Set this optional property to use a different name (e.g. ProxySession).

Note that each realm has its own session. However, if the same cookie name is configured for multiple realms running on the same host the sessions will be cleaned up together when the first session expires.

Session Cookie Same Site

In February 2020 Chrome 80 has been released which treats cookies without SameSite flag as Lax.

This change can break cross-domain use cases (e.g. SAML).

Thus, it is recommended to select None here.

If None is selected, and you have to support older browsers also check Cookie Same Site Relaxation.

If you do not expect any requests from other domains, you may also go for Lax or Strict as this increases security.

Session Cookie Same Site Relaxation (Experimental)

Some older browsers treat cookies with SameSite=None as Strict.

See this example bug report for Safari:

Bug 198181 - Cookies with SameSite=None or SameSite=invalid treated as Strict

Enable this feature to map a filter to the root location /* which evaluates the User-Agent request header to remove SameSite=None for browsers which are known to be affected.

Session Validation

A newline separated list of rules declaring attributes that must not change in the same session. A rule has the following syntax:

AUTH|ENV|CONST|PARAM|HEADER:<name of the attribute>:block|invalidate

• block: the request will be blocked and 403 (Forbidden) will be returned
• invalidate: the session will be invalidated and a new one will be created

nevisProxy Conditions are supported. See nevisProxy reference guide for details.

For instance, use the following configuration to terminate the session if the source IP changes:

ENV:REMOTE_ADDR:invalidate

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.

Custom Dependencies

In case your AuthState elements use custom classes upload the required JAR file(s) here.

Files uploaded here will be deployed into the lib directory of the nevisAuth instance.

Generic Authentication Service

#Authentication #Realms

Plugin: nevisadmin-plugin-nevisauth

Defines an authentication service which is exposed on the given Frontend Path on the assigned Virtual Host.

Requests received on this path are forwarded to nevisAuth.

Use to import an existing configuration.

We recommend you implement complex self-service and registration processes in a dedicated application, for example, using the SOAP or REST API of nevisIDM.

The pattern can also provide authentication for applications exposed on nevisProxy, see Generic Authentication Realm for details.

Virtual Host

Assign a Virtual Host which shall serve as entry point for this authentication service.

Frontend Path

Define a path to be mapped on the assigned virtual host.

Requests sent to this path will be forwarded to nevisAuth so that they can be handled by this authentication service.

Configuration

Enter AuthState elements as XML.

The Domain element is optional.

• If missing the element will be created. The Entry methods authenticate and stepup will be set to the first provided AuthState. The method logout is not set and thus the nevisAuth default behaviour applies.

• If provided the Domain must come before all AuthState elements. The attributes name and default are not supported and should be omitted. Attributes are sorted by name. The Entry elements are sorted by method.

The AuthState linked to stepup should be able to dispatch the request. For instance, you may have assigned an Authorization Policy to your application(s) and thus you need a state which decides based on the request variable requiredRoles.

The following example dispatches level 2 into an AuthState named TAN which provides authentication via mTAN:

<AuthState name="EntryDispatcher" class="ch.nevis.esauth.auth.states.standard.ConditionalDispatcherState" final="false">
    <ResultCond name="nomatch" next="Authentication_Done"/>
    <ResultCond name="level2" next="TAN"/> <!-- TAN state is expected to set authLevel="2" -->
    <Response value="AUTH_ERROR">
        <Arg name="ch.nevis.isiweb4.response.status" value="403"/>
    </Response>
    <property name="condition:level2" value="${request:requiredRoles:^2.*$:true}"/>
</AuthState>

The following expressions are supported:

• ${instance}: name of the nevisAuth instance
• ${request_url}: generates a nevisAuth expression which returns the URL of the current request
• ${realm}: name of the Realm (see below)
• ${service_url}: generates a nevisAuth expression which evaluates to true for requests received on the configured Frontend Path
• ${service.postfix}: in Kubernetes side-by-side deployment a postfix is added to service names. Use this expression when connecting to a service deployed against the same inventory.
• ${keystore}: name of the KeyStore element provided by this pattern. Assign a pattern to Key Objects to add a KeyObject into this KeyStore.

The name of AuthState elements is prefixed with the sanitized name of the Realm (referred to as ${realm}).

The realm prefix must be added when using propertyRef to reference AuthStates generated by other patterns (e.g. <propertyRef name="${realm}_SomeState"/>).

An exception is the AuthState which defines the nevisIDM connection (as generated by nevisIdm Password Login or nevisIDM Connector for Generic Authentication). Here the propertyRef must be defined as follows:

<propertyRef name="nevisIDM_Connector"/>

This pattern does not validate that labels are translated. Translations can be provided on the Authentication Realm pattern.

Template Parameters

Define Template Parameters.

Examples:

smtp: smtp.siven.ch
sender: [email protected]

These parameters can be used in your Configuration.

The expression formats are:

${param.<name>}:

• name found: parameter value is used.
• name missing: expression is not replaced.

${param.<name>:<default value>}:

• name found: parameter value is used.
• name missing: default value will be used.

In <default value> the character } must be escaped as \}.

Resources

In case your AuthState elements require additional configuration files or scripts upload them here.

Files uploaded here will be deployed into the conf directory of the nevisAuth instance.

Key Objects

Assign patterns to add KeyObject elements to the KeyStore provided by this pattern.

nevisAuth

Assign a nevisAuth Instance pattern.

Key Store

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

If no pattern is assigned automatic key management will provide the required key material. This requires that the nevisAuth Instance is part of this project and also uses automatic key management.

Automatic key management should be used for test setups only.

Trust Store

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

If no pattern is assigned automatic key management is used to provide the trust store. This requires that the nevisAuth Instance is part of this project and also uses automatic key management.

Automatic key management should be used for test setups only.

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.

If no pattern is assigned automatic key management is asked to provide the trust store. This requires that the nevisAuth Instance is part of this project and also uses automatic key management.

Automatic key management should be used for test setups only.

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:

Key	Value
BodyReadSize	64000
InterceptionRedirect	Condition:ENV:HTTP_USER_AGENT:mozilla|Mozilla\ninitial\nnever
ClientCert	want

Custom Parameters (SecurityRoleFilter)

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

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

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:

Key	Value
EnablePollTerminatedCalls	true

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.

Login Template

Customize the rendering of login pages.

Download the default template to get started.

nevisLogrend: Simple Mode

Point your browser to a protected application to have a look at the login page. Download any resources (e.g. images, CSS) that you want to adapt. Then upload the changed files here.

To change the outer HTML upload a file named template.html. Here is a simple example:

<!DOCTYPE html>
<html lang="${lang.code}">
  <head>
    <title>${label.title}</title>
    <link href="${resources}/bootstrap.min.css" rel="stylesheet" type="text/css">
    <link href="${resources}/default.css" rel="stylesheet" type="text/css" media="all">
  </head>
  <body>
    <header id="header" class="container-fluid">
      <img class="logo center-block" src="${resources}/example.svg" alt="NEVIS Security Suite">
    </header>
    <main id="content" class="container">
      ${form}
    </main>
  </body>
</html>

Please also upload file resources referenced by your template (e.g. images, CSS, Javascript). Use this when you reference additional files, or if you want to override the default files provided.

The template must contain ${form} and may contain additional expressions.

Expression	Description
${form}	generated login form (required)
${lang.switch}	language switcher component
${lang.code}	current language code (i.e. EN, DE)
${label.title}	a human-readable title
${label.myLabel}	a custom text which must be defined via Custom Translations
${resources}	path to static resources (e.g. CSS, images, Javascript)

Some resources (i.e. bootstrap.min.css, default.css) are provided out of the box because they are required by the default template. Feel free to use them.

nevisLogrend: Expert Mode

Expert users may upload Velocity templates and resources to nevisLogrend.

Zip files will be extracted into the nevisLogrend application:

/var/opt/nevislogrend/<instance>/data/applications/<realm>

Flat files will be added to the following subdirectories:

• webdata/template: Velocity templates (*.vm)
• webdata/resources: additional resources (e.g. images, CSS)

nevisProxy: Simple Template

nevisProxy provides a simple login page renderer which can be used instead of nevisLogrend. See Login Renderer for details.

For each enabled language (e.g. en) upload a file named <lang>_template.html. The template must contain the placeholder NEVIS_AUTH_FORM.

If your templates require additional resources (e.g. CSS, images) upload them as Hosted Resources on the nevisProxy virtual host.

Login Template Mode

Choose between two options:

• additive: files uploaded as Login Template will be added on top of the default. Use this option when you want to add or replace files, but don't want to upload an entire template. There will be less work when you upgrade.

• complete: only the files uploaded as Login Template will be deployed. Use this option when you want to provide the entire template.

Translations

Labels are used to provide human-readable text in the language of the user.

The language is extracted from the Accept-Language header and the default login page template has a language selection.

Which labels are used depends on the assigned steps. Click Download Default Labels to retrieve the labels used and their translations.

Here you can overwrite the defaults and add your own translations or even introduce new labels which may be required when using a Custom Login Template or Generic Authentication Step patterns.

The name of uploaded files must end with the language code. As the format is compatible you may upload existing text_<code>.properties files of nevisLogrend or LitDict_<code>.properties of nevisAuth.

The encoding of uploaded files does not matter as long as all translations are HTML encoded.

The default login template uses the following labels:

• title - used as browser page title
• language.<code> - used by language switch component

The default logout process of nevisAuth (which will be applied when no step is assigned to Logout) produces a confirmation GUI which requires the following labels:

• logout.label - header of the logout confirmation GUI
• logout.text - text shown to the user
• continue.button.label - label on the confirmation button

Translations Mode

Choose between:

• combined - upload 1 file per language code named labels_<code>.properties. The labels will be added to both nevisAuth and nevisLogrend. Alternatively, you can upload a zip file called labels.zip containing these properties files.

• separate - select only when you need different labels in nevisAuth and nevisLogrend. The files must be called LitDict_<code>.properties for nevisAuth and text_<code>.properties for nevisLogrend. Alternatively, you may upload zip file called LitDict.zip and text.zip containing these properties files.

Default Translations

Choose between:

• enabled - add default translations for labels which are commonly used (e.g. title or language labels in nevisLogrend, error labels in nevisAuth) and which are required by the realm patterns (e.g. assigned authentication steps).

• disabled - select to only add what has been uploaded via Translations. Note that if Translations are incomplete users may encounter untranslated labels.

nevisLogrend default.properties

Add or overwrite properties in the default.properties of the nevisLogrend application.

Use only when there is no high-level setting. We recommend to not overwrite any language related properties, as the languages should be in sync with nevisAuth. You can configure the languages on the nevisAuth Instance.

Requires that nevisLogrend is used for GUI rendering. Check the help of Login Renderer for details.

Session Tracking

Choose between:

• COOKIE: issue a session cookie.
• AUTHORIZATION_HEADER: track the session based on the value of the Authorization header.
• CUSTOM: track the session based on custom configuration. It generates an empty session filter which has to be replaced (see below).
• disabled: disable session tracking.

CUSTOM session tracking

Given a pattern name of SSO, the following empty filter will be generated:

    <filter>
        <filter-name>SessionHandler_SSO</filter-name>
        <filter-class>__REPLACE_USING_GENERIC__</filter-class>
    </filter>

For the filter-class, a placeholder (REPLACE_USING_GENERIC) will be used and that placeholder has to be overwritten.

Another pattern must complete the session filter. For example, use Generic Virtual Host Context pattern with the following Filters and Mappings configuration:

<filter>
    <filter-name>SessionHandler_SSO_RealmName</filter-name>
    <filter-class>ch::nevis::nevisproxy::filter::session::SessionManagementFilter</filter-class>
    <init-param>
        <param-name>Identification</param-name>
        <param-value>CUSTOM</param-value>
    </init-param>
    <init-param>
        <param-name>Custom.RequiredIdentifiers</param-name>
        <param-value>HEADER:Authorization</param-value>
    </init-param>       
    <init-param>
        <param-name>Servlet</param-name>
        <param-value>LocalSessionStoreServlet</param-value>
    </init-param>
</filter>

Session Cookie Name

Each realm has its own session cookie. By default, this cookie will be called Session_<pattern-name>

Set this optional property to use a different name (e.g. ProxySession).

Note that each realm has its own session. However, if the same cookie name is configured for multiple realms running on the same host the sessions will be cleaned up together when the first session expires.

Session Cookie Same Site

In February 2020 Chrome 80 has been released which treats cookies without SameSite flag as Lax.

This change can break cross-domain use cases (e.g. SAML).

Thus, it is recommended to select None here.

If None is selected, and you have to support older browsers also check Cookie Same Site Relaxation.

If you do not expect any requests from other domains, you may also go for Lax or Strict as this increases security.

Session Cookie Same Site Relaxation (Experimental)

Some older browsers treat cookies with SameSite=None as Strict.

See this example bug report for Safari:

Bug 198181 - Cookies with SameSite=None or SameSite=invalid treated as Strict

Enable this feature to map a filter to the root location /* which evaluates the User-Agent request header to remove SameSite=None for browsers which are known to be affected.

Session Validation

A newline separated list of rules declaring attributes that must not change in the same session. A rule has the following syntax:

AUTH|ENV|CONST|PARAM|HEADER:<name of the attribute>:block|invalidate

• block: the request will be blocked and 403 (Forbidden) will be returned
• invalidate: the session will be invalidated and a new one will be created

nevisProxy Conditions are supported. See nevisProxy reference guide for details.

For instance, use the following configuration to terminate the session if the source IP changes:

ENV:REMOTE_ADDR:invalidate

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.

Custom Dependencies

In case your AuthState elements use custom classes upload the required JAR file(s) here.

Files uploaded here will be deployed into the lib directory of the nevisAuth instance.

Frontend Path Settings

Assign add-on patterns to customize the Frontend Path.

Generic Authentication Step

#Authentication #Generic

Plugin: nevisadmin-plugin-nevisauth

Define an authentication step using XML elements as described in the nevisAuth reference guide.

An authentication step consists of one or multiple AuthState elements which belong together, for example, username / password login against LDAP with enforced password change.

Configuration

Upload an XML file containing AuthState elements.

Example to illustrate the syntax:

<AuthState 
  name="${state.entry}"
  class="ch.nevis.esauth.auth.states.standard.ThrottleSessionsState"
  final="false">
  <ResultCond name="ok" next="${state.done}" />
  <Response value="AUTH_ERROR">
    <Gui name="AuthErrorDialog"/>
  </Response>
  <property name="queryValue" value="${request:userId}" />
</AuthState>

See Standard authentication AuthStates and plug-ins for further examples.

The following expressions may be used:

• ${instance}: name of the nevisAuth instance.
• ${request_url}: generates a nevisAuth expression which returns the URL of the current request
• ${realm}: name of the Realm (see below)
• ${state.entry}: use as name to mark the first AuthState.
• ${state.done}: use as next in ResultCond elements to exit this step and continue with On Success.
• ${state.failed}: use as next in ResultCond elements to exit this step and continue with On Failure.
• ${state.exit.<index>}: use as next in ResultCond elements to exit this step and continue with an Additional Follow-up Step(s). The index starts with 1.
• ${state.level}: must be used if an Authentication Level has been defined. Use as authLevel on ResultCond elements which point to ${state.done}.
• ${keystore}: name of the KeyStore element provided by this pattern. Assign a pattern to Key Objects to add a KeyObject into this KeyStore.
• ${service.postfix}: in Kubernetes side-by-side deployment a postfix is added to service names. Use this expression when connecting to a service deployed against the same inventory.
• ${var.<name>}: insert the scalar variable <name>. This is an alternative to using Template Parameters.

The name of AuthState elements is prefixed with the sanitized name of the Realm (referred to as ${realm}).

The realm prefix must be added when using propertyRef to reference AuthStates generated by other patterns (e.g. <propertyRef name="${realm}_SomeState"/>).

An exception is the add-on pattern nevisIDM Connector for Generic Authentication which does not set a prefix. Here the propertyRef must be defined as follows:

<propertyRef name="nevisIDM_Connector"/>

This pattern does not validate that labels are translated. Translations can be provided on the Authentication Realm pattern.

Template Parameters

Define Template Parameters.

The syntax is a multi-line String containing a YAML map (key-value pairs). Example:

smtp: smtp.siven.ch
sender: [email protected]
doctype: "<!DOCTYPE html>"
counter: 1

As shown in the example above, double quotes " need to be put around the value if the value contains special characters.

Parameters can be used in:

• AuthState(s): direct input
• AuthState(s): as file

The expression formats are:

${param.<name>}:

• name found: parameter value is used.
• name missing: expression is not replaced.

${param.<name>:<default value>}:

• name found: parameter value is used.
• name missing: default value will be used.

In <default value> the character } must be escaped as \}.

On Success

Use ${state.done} to continue with the assigned step.

If no step is assigned and ${state.done} is found an AuthState named <Realm>_Prepare_Done will be used instead.

On Failure

Use ${state.failed} to continue with the assigned step.

If no step is assigned and ${state.failed} is used an AuthState named <Realm>_Authentication_Failed is generated.

Custom Follow-up Steps

Assign follow-up steps.

The order of steps is relevant. The first step in this list has index 1.

You may reference a step in the configuration via the expression ${state.exit.<index>}.

Entry AuthState

Define the name of the first AuthState.

If not set the sanitized name of the pattern will be used.

The XML must contain an AuthState which has this name set, or one that uses the expression ${state.entry} for the name.

Authentication Level

Optionally define an authentication level which will be set if the user has passed this step successfully.

Resources

Upload additional configuration files or scripts required by your AuthState configuration. Uploaded files will be deployed into the conf directory of the nevisAuth instance.

Key Objects

This pattern adds a XML element KeyStore to esauth4.xml.

Each pattern referenced here creates an additional KeyObject which will be added to this KeyStore as a child element.

Generic Deployment

#Instances

Plugin: nevisadmin-plugin-base

Use the advanced pattern for the following use cases:

• Deploy files and scripts for your own custom component or application.
• Modify remote system configuration files.
• Patch files generated by other nevisAdmin 4 patterns (not recommended).

The pattern cannot be used when deploying to Kubernetes.

Note that the third option is not recommended. Instead, please explore the various Generic patterns which can configure many low-level options. If you cannot find a solution, please open a Nevis Support ticket. Support may be able to provide an alternative, or can create a product improvement request.

Path

Absolute path of a directory on the target host(s) where the files will be deployed to. The command will run from the same path.

nevisAppliance targets only: if the files must be persisted across reboots, use a file name or path listed in the /etc/rwdisk.conf file on the nevisAppliance target host.

The path must not point into a directory (potentially) managed by a nevisAdmin 4 Instance Pattern. Thus, it is not possible to directly overwrite files generated by other patterns. See Command and Command: Execution File Triggers for an alternative solution to overcome this limitation.

Allowed Paths:

• /tmp/generic-deployment
• /var/opt/<directory>

Example:

• /tmp/generic-deployment/patch01/

Path: Delete Unknown Files

If enabled, all files in the directory (Path property) that are not specified under Files are deleted.

If you enable this property your files must be in one of the following directories or subdirectories:

• /var/opt
• /tmp
• /home

Files

Upload the files which will be copied into the Path.

To upload files into subdirectories within Path, add a single .zip file with files and directories. Unpacked files will have Owner and Group applied. Note: If multiple files are uploaded, any .zip file is deployed as is, without being extracted.

It is not supported to overwrite files generated by other patterns. See also Path above.

Template Parameters

Define Template Parameters.

Examples:

smtp: smtp.siven.ch
sender: [email protected]

These parameters can be used in:

• uploaded files matching an expression specified in the Template Files property
• the value of the Path property
• the value of the Command property

The expression formats are:

${param.<name>}:

• name found: parameter value is used.
• name missing: expression is not replaced.

${param.<name>:<default value>}:

• name found: parameter value is used.
• name missing: default value will be used.

In <default value> the character } must be escaped as \}.

Template Files

Expressions matching files in which to replace parameters.

If a single .zip file is unpacked, it is scanned for matching files as well.

Possible values are exact file names or file endings.

Example:

• my_script.sh
• *.txt
• *.properties

Owner

Owner of the directory at specified path. All files and subdirectories will have the same owner.

Group

Owner of the directory at path. All files and subdirectories will have the same owner.

Permissions: Owner

Read-write permissions for specified owner of the directory. All files and subdirectories (including unpacked from single .zip) will have the same permissions. The executable bit will be set automatically for readable directories and for readable Executable Files.

Permissions: Group

Read-write permissions for specified group of the directory. All files and subdirectories (including unpacked from single .zip) will have the same permissions. The executable bit will be set automatically for readable directories and for readable Executable Files.

Permissions: Other

Read-write permissions for all users of the directory. All files and subdirectories (including unpacked from single .zip) will have the same permissions. The executable bit will be set automatically for readable directories and for readable Executable Files.

Executable Files

Expression to select files which shall have the executable flag. Add exact file names or *.<ending>.

Example:

• myScript.sh
• *.py

Command

Bash shell expression which will be executed from the working directory Path as the deployment user (__connection_user variable in the inventory).

Example:

• ./my_script.sh

The command will run depending on the Command: Execution setting: always or conditional (e.g. onFileChange). Note that with the onFileChange setting, the command is not automatically executed if you change it here.

Tip: Instead of specifying your shell instruction(s) here, add them as a separate script file into Files. For example, if the file name is my_script.sh, enter ./my_script.sh as the Command. This way, the script will be re-executed each time you upload an updated script file and deploy the project (if onFileChange command execution is configured below).

Command: Execution Phase

Defines when the command is executed. The files are always copied during the CONFIGURE phase.

Phases:

• CONFIGURE: Command runs after files have been uploaded, but before NEVIS instances are (re)started. Use e.g. when patching a NEVIS instance configuration file.
• ACTIVATE: Command runs when instances are (re)started. Use when deploying files or commands that are independent of NEVIS instances.

Command: Execution

Defines when or how often the command is executed.

Possible values are:

• always: Execution during each deployment.
• onFileChange: Executed if an uploaded file under the specified Path has changed.
• onFileTriggers: Executed if a file that is listed under Command: Execution File Triggers has changed.
• onFileChange + onFileTriggers: Combining both options above.

Command: Execution File Triggers

Files deployed by other nevisAdmin 4 patterns that, when changed, trigger the script to be executed, even if the script and files itself do not change.

Example:

• /var/opt/nevisproxy/my_proxy/conf/navajo.xml

Hint: This is useful for patching e.g. navajo.xml after generation. Note that during the next deployment, it will be reverted (if the nevisProxy Instance pattern is deployed as well) and then patching will happen again.

Generic nevisAdapt Instance Settings

#User Behavior Analytics #Experimental #Add-ons

Plugin: nevisadmin-plugin-nevisadapt

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

Java Opts

Add additional entries to the JAVA_OPTS environment variable.

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

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/opt/nevisadapt/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.

Generic nevisAuth Instance Settings

#Authentication #Add-ons

Plugin: nevisadmin-plugin-nevisauth

Use this add-on pattern to set low-level properties in configuration files of a nevisAuth 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 nevisAuth to create a heap dump on out of memory as follows:

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/opt/nevisauth/${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.

Environment Variables

Add additional environment variables to the nevisAuth env.conf.

The standard environment variables RTENV_SECURITY_CHECK and JAVA_OPTS will always be present in env.conf and can't be overwritten using this setting.

Generic nevisAuth REST Service

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Configures a nevisAuth REST service using the XML syntax described in the nevisAuth Technical Documentation.

The service is not exposed on a nevisProxy Virtual Host, it is accessible on the assigned nevisAuth only.

The XML attribute path defines which requests are handled.

nevisAuth

Assign a nevisAuth Instance.

Configuration

As an alternative to direct configuration you can upload a file which contains the XML.

The file should contain RESTService elements only.

Uploading a complete esauth4.xml is not supported.

Template Parameters

Define Template Parameters.

Examples:

smtp: smtp.siven.ch
sender: [email protected]

These parameters can be used in your Configuration.

The expression formats are:

${param.<name>}:

• name found: parameter value is used.
• name missing: expression is not replaced.

${param.<name>:<default value>}:

• name found: parameter value is used.
• name missing: default value will be used.

In <default value> the character } must be escaped as \}.

Generic nevisAuth Web Service

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Configures a nevisAuth Web service using the XML syntax described in the nevisAuth Technical Documentation.

The service is not exposed on a nevisProxy Virtual Host, it is accessible on the assigned nevisAuth only.

The XML attribute uri defines which requests are handled.

nevisAuth

Assign a nevisAuth Instance.

Configuration

The file should contain WebService elements only.

Uploading a complete esauth4.xml is not supported.

Template Parameters

Define Template Parameters.

Examples:

smtp: smtp.siven.ch
sender: [email protected]

These parameters can be used in your Configuration.

The expression formats are:

${param.<name>}:

• name found: parameter value is used.
• name missing: expression is not replaced.

${param.<name>:<default value>}:

• name found: parameter value is used.
• name missing: default value will be used.

In <default value> the character } must be escaped as \}.

Generic nevisDetect Instance Settings

#User Behavior Analytics #Experimental #Add-ons

Plugin: nevisadmin-plugin-nevisdetect

Use this add-on pattern to set low-level properties in configuration files of a nevisDetect 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 nevisDetect to create a heap dump on out of memory as follows:

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/opt/nevisdetect/${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.

Generic nevisFIDO FIDO2 Instance Settings

#FIDO2 #Add-ons

Plugin: nevisadmin-plugin-fido2

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.

Generic nevisFIDO UAF Instance Settings

#Mobile Authentication #Authentication #Add-ons #Experimental

Plugin: nevisadmin-plugin-nevisfido

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.

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

Generic nevisIDM Instance Settings

#Identity Management #Add-ons

Plugin: nevisadmin-plugin-nevisidm

Use the add-on pattern to set low-level properties in configuration files of an nevisIDM Instance.

nevisIDM Properties

Add properties for nevisidm-prod.properties. See nevisIDM Reference Guide (chapter Configuration files) for details.

Java Opts

Add additional entries to the JAVA_OPTS environment variable.

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

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

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/opt/nevisidm/${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.

Generic nevisLogrend Instance Settings

#Authentication #Add-ons

Plugin: nevisadmin-plugin-nevisauth

Use the add-on pattern to set low-level properties in configuration files of a nevisLogrend 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 nevisLogrend to create a heap dump on out of memory as follows:

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/opt/nevislogrend/${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.

Generic nevisMeta Instance Settings

#Federation #Add-ons

Plugin: nevisadmin-plugin-nevismeta

Use this add-on pattern to set low-level properties in configuration files of a nevisMeta 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 nevisMeta to create a heap dump on out of memory as follows:

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/opt/nevismeta/${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.

Generic nevisProxy Instance Settings

#Application Protection #Generic

Plugin: nevisadmin-plugin-nevisproxy

You can assign the pattern to a nevisProxy Instance using Additional Settings.

Use to customize the main configuration files of the nevisProxy instance, including:

• navajo.xml
• bc.properties

To configure logging, use nevisProxy Log Settings instead.

Configuration: navajo.xml

Customize the Navajo servlet container configuration (navajo.xml) using XML constructs described in the nevisProxy Technical Documentation.

The root element <Service> must be provided.

Examples:

Increase number of parallel requests (worker threads):

<Service>
    <Server MaxClients="1000"/>
</Service>

Increase the maximum allowed request body size:

<Service>
    <Server LimitRequestBody="10485760"/>
</Service>

Set a Context attribute for some.domain.com:

<Service>
    <Engine>
        <Host name="some.domain.com">
            <Context additionalStatusCodes="207,210,242,422,423,424,449,456,540,541,543,544,545,456,549,552,560" />
        </Host>
    </Engine>
</Service>

Overrule the allowed HTTP methods for some.domain.com:

<Service>
    <Engine>
        <Host name="some.domain.com">
            <Context allowedMethods="ALL-HTTP" />
        </Host>
    </Engine>
</Service>

Overrule the server aliases for some.domain.com:

<Service>
    <Connector name="some.domain.com" port="*" serverAlias="*.domain.com">
    </Connector>
</Service>

It is possible to use the following placeholders:

• ${instance.id}: unique ID of the nevisProxy Instance pattern
• ${instance.name}: name of the nevisProxy instance. For instance, use /var/opt/nevisproxy/${instance.name} to refer to the instance directory.

Limitations:

• customizing Navajo elements is not supported
• customizing Host (or its child elements) requires name

Configuration: bc.properties

Customize the low-level configuration (bc.properties) using properties described in the nevisProxy Technical Documentation.

For instance, when request validation is enabled this requires a buffer and this buffer has to be big enough to store the entire request.

The following example increases the maximum size of the request buffer to 10 MB:

ch.nevis.navajo.request.BufferSize=10485760

You also may have to increase the maximum allowed request size. See Configuration: navajo.xml for an example.

Note that increased buffer sizes may lead to increased demand of RAM and disk space.

When the required buffer exceeds ch.nevis.navajo.request.MemBufferSize then nevisProxy will buffer to disk instead.

The demand caused by request buffers can be estimated as follows:

• RAM: MaxClients * ch.nevis.navajo.request.MemBufferSize
• disk: MaxClients * ch.nevis.navajo.request.BufferSize

See Configuration: navajo.xml for a description of MaxClients.

Template Parameters

Define Template Parameters.

Examples:

backend-host: backend.siven.ch

These parameters can be used in:

• Configuration: navajo.xml
• Configuration: bc.properties

The expression formats are:

${param.<name>}:

• name found: parameter value is used.
• name missing: expression is not replaced.

${param.<name>:<default value>}:

• name found: parameter value is used.
• name missing: default value will be used.

In <default value> the character } must be escaped as \}.

Generic QoS Configuration (mod_qos)

#Application Protection #Generic

Plugin: nevisadmin-plugin-nevisproxy

Assign the pattern to a Virtual Host using Additional Settings.

Use to configure mod_qos in case the standard configuration is not sufficient.

mod_qos is quite powerful, and can cover may use cases. See mod_qos documentation for further information.

The mod_qos directives are not validated.

The directives are applied using an ApacheConfigFilter (named Qos), which is added to the web.xml of the Virtual Host.

Server Directives

Server level directives can be entered here.

These directives apply to the entire nevisProxy Instance which means that other Virtual Host patterns may be affected.

Examples:

QS_ClientEventBlockCount 200 300
QS_SetEnvIf NAVAJO_HTTPSESS_CREATED !QSNOT QS_Block=yes
QS_SrvMaxConnClose 85%
QS_SrvMaxConnPerIP 75
QS_SrvMinDataRate 75 300 250

Host Directives

Host level directives can be entered here.

Generic SMTP

#Authentication #Connector

Plugin: nevisadmin-plugin-nevisauth

Set up the connection to a generic SMTP server for sending emails. Assign the pattern to Email TAN (eTAN) as SMTP Server.

SMTP Protocol

Select the protocol of the SMTP server.

SMTPS is usually mentioned as the TLS secured SMTP protocol.

SMTP Server

Enter host:port of the SMTP server.

SMTP User

If a username is required at the SMTP server enter it here.

SMTP Password

If a password is required at the SMTP server enter it here.

Generic Social Login Step

#Federation #Authentication #OAuth #OpenID Connect #Experimental

Plugin: nevisadmin-plugin-oauth

Use to set up a generic social login, either using OAuth2 or OpenID Connect.

Provider Type

The provider type of the social account: either OpenID Connect or OAuth2.

Client ID

The identifier provided by the social account when you register with it as the IdP service.

Client Secret

The secret of the client ID that has been set in the OAuth/OpenID Connect configuration of the social account.

Return Path

The callback URI to go to after a successful login with the social account.

This will create an endpoint in your host config.

The URL will be a combination of the Frontend Address of the Virtual Host and the value configured here. For example, let's assume that you have configured:

• Return Path: /oidc/app/
• Frontend Address: https://nevis.net

Then the URL will be https://nevis.net/oidc/app/.

Use the exact: prefix to use the given path as-is. Without this prefix a normal mapping with /* will be generated and thus sub-paths will be accessible as well.

Scope(s)

The request scope(s) for getting the user information from the social account. The default value is email.

The scope openid will be added automatically if providerType is set to OpenID Connect.

Scope offline_access for generate refresh token.

Virtual Host

Assign a Virtual Host which shall serve as entry point for the callback from social login provider.

In case your host has

• 1 address, that address will be used
• many addresses with
  • 1 https, and many http, the https will be used without warning
  • mix between http and https, the 1st https will be used with warning
  • single scheme (http or https only) the 1st address will be used with warning

E.g.

http://nevis.net
http://nevis-security.net
https://nevis.net
https://nevis-security.net

The https://nevis.net will be used as the host for Apple callback

On Success

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

In case you change this to your custom step(s), you can assign pattern Social Login Final Step as the last step of the Authentication process to redirect back to original URL.

On Failure

The step that will be executed if the authentication fails. If no step is configured here the process ends with AUTH_ERROR.

In case you change this to your custom step(s), you can assign pattern Social Login Final Failure Step as the last step of the Authentication process to redirect back to original URL.

Client Secret Method

The method used for authenticating the client. It can be either Basic Authentication or POST. The default value is Basic Authentication.

Response Mode

The mode used for the responses of the server. It can be either Query or Form POST. The default value is Query.

Provider Endpoint

The provider endpoint that contains the configuration of the OpenID Connect server. It's required when providerType has the value OpenID Connect.

Authorization Endpoint

The authorization endpoint of the OAuth2 provider.

Required when Provider Type is set to OAuth2.

Token Endpoint

The token endpoint of the OAuth2 server. It's required when providerType has the value OAuth2.

User Information Endpoint

The user information endpoint of the OAuth2 server. It's required when providerType has the value OAuth2.

nevisIDM

Choose which nevisIDM instance you want to store the user's information after logged in with social login provider.

Client External ID

The ExtId of the client in nevisIDM that will be used to store the user.

On User Not Found

Configure the authentication flow to be executed when no user was found and the email provided by social account does not exist. The authentication flow must contain the Social Login Create User pattern if a new user shall be created.

Note: Please select scope email and profile for getting user's information from social account.

On User Found

Configure the Authentication Flow in case no user with Subject/ID from social account was found but email does exist in nevisIDM. The Authentication Flow must contain:

• Social Login Link User pattern to link an existing user in IDM with Subject/ID of social account.
• Social Login Done to end the social login flow after some other action(s).

Note: Please select scope email and profile for getting user's information from social account.

First Name Claim

The claim that contains the first name of the logged-in user in the social account. The default value is given_name.

Second Name Claim

The claim that contains the second name of the logged-in user in the social account. The default value is family_name.

Email Claim

The claim that contains the e-mail of the logged-in user in the social account. The default value is email.

Subject Claim

The claim that contains the subject of the logged-in user in the social account. The default value is sub.

Claims Request

The claims request parameter. This value is expected to be formatted in JSON and does not accept trailing spaces nor tabs.

User ID Field

Logged userId will automatically get from social account. But you can change the userId by using this field.

Additional Auth Request Parameters

Arbitrary additional request parameters used in the authentication request. The property supports variable substitution.

Example:

[paramName]=[paramValue]

Button Label

The text that should be displayed for the end-user on the social login button, and provide translations for this label on the Authentication Realms.

Button CSS class

The css class that apply for the social login button. Ensure that the Login Template used in your realm pattern includes a CSS file which defines the CSS class.

Button Logo Path

The path to logo file of the social login provider. This path is the path of logo file which you which uploaded at Login template in Realm pattern. E.g:

In the zip file the icon with path /webdata/resources/icons/icon.csv, the input is /icons/icon.csv

Generic Third-Party Authentication Realm

#Authentication #Realms #Experimental

Plugin: nevisadmin-plugin-nevisauth

Assign the pattern to applications as Authentication Realm to enforce authentication using a third-party authentication service.

Integration of a third-party authentication service usually consists of several steps:

• Configure an Authentication Filter which is mapped to applications to enforce authentication. The filter is expected to either trigger a redirect to a different path or perform a side-call.
• Provide a template for the Roles Filter. The template is used to generate a filter in case an Authorization Policy is assigned to an application.

Limitations of the pattern:

• No support for session upgrades. In combination with nevisAuth you can demand a minimum Authentication Level for an application. If the session is not yet at the desired level then a session upgrade is performed.
• No automatic support for sharing cookies between applications and the authentication service. However, you can configure this manually by configuring an Authentication Application and assigning a Cookie Customization pattern to Protected Application Settings and Authentication Application Settings.

Authentication Filter

Define the filter that shall be application to applications to enforce authentication.

The following variables may be used:

• ${realm.id} - unique ID of this realm pattern
• ${realm.name} - name of this realm pattern
• ${auth.servlet} - name of the servlet of the Authentication Application. May be used to perform a side-call.

Roles Filter

Define the filter that shall be application to applications to enforce the presence of certain roles.

The following expressions may be used:

• ${realm.id} - unique ID of this realm pattern
• ${realm.name} - name of this realm pattern
• ${auth.servlet} - name of the servlet of the Authentication Application. May be used to perform a side-call.
• ${filter.name} - a proposed filter name calculated from the required roles
• *{roles} - duplicates the entire line once for each role

Protected Application Settings

Assign add-on patterns to customize the behaviour of applications protected by this realm.

A common case for redirect-based authentication is to assign a Cookie Customization here and to Authentication Application Settings to share cookies between applications and the authentication application.

Authentication Application

Optionally assign an application which provides the authentication service and shall be exposed on the same virtual host as the applications.

Not required for federation-based authentication where the authentication service is hosted on another domain.

Additional Settings

Assign add-on patterns to customize the behaviour of the Authentication Application.

Assigning these add-ons here may be more appropriate to have the complete authentication logic concentrated here.

Session Tracking

Choose between:

• COOKIE: issue a session cookie.
• AUTHORIZATION_HEADER: track the session based on the value of the Authorization header.
• CUSTOM: track the session based on custom configuration. It generates an empty session filter which has to be replaced (see below).
• disabled: disable session tracking.

CUSTOM session tracking

Given a pattern name of SSO, the following empty filter will be generated:

    <filter>
        <filter-name>SessionHandler_SSO</filter-name>
        <filter-class>__REPLACE_USING_GENERIC__</filter-class>
    </filter>

For the filter-class, a placeholder (REPLACE_USING_GENERIC) will be used and that placeholder has to be overwritten.

Another pattern must complete the session filter. For example, use Generic Virtual Host Context pattern with the following Filters and Mappings configuration:

<filter>
    <filter-name>SessionHandler_SSO_RealmName</filter-name>
    <filter-class>ch::nevis::nevisproxy::filter::session::SessionManagementFilter</filter-class>
    <init-param>
        <param-name>Identification</param-name>
        <param-value>CUSTOM</param-value>
    </init-param>
    <init-param>
        <param-name>Custom.RequiredIdentifiers</param-name>
        <param-value>HEADER:Authorization</param-value>
    </init-param>
    <init-param>
        <param-name>Servlet</param-name>
        <param-value>LocalSessionStoreServlet</param-value>
    </init-param>
</filter>

Session Cookie Name

By default, the session cookie will be called Session_<pattern-name>

Set this optional property to use a different name (e.g. ProxySession).

If the same name is configured for multiple realms on the same host then the sessions will be cleaned up together when the first session expires.

Session Cookie Same Site

In February 2020 Chrome 80 has been released which treats cookies without SameSite flag as Lax.

This change can break cross-domain use cases (e.g. SAML).

Thus, it is recommended to select None here.

If None is selected, and you have to support older browsers also check Cookie Same Site Relaxation.

If you do not expect any requests from other domains, you may also go for Lax or Strict as this increases security.

Session Cookie Same Site Relaxation (Experimental)

Some older browsers treat cookies with SameSite=None as Strict.

See this example bug report for Safari:

Bug 198181 - Cookies with SameSite=None or SameSite=invalid treated as Strict

Enable this feature to map a filter to the root location /* which evaluates the User-Agent request header to remove SameSite=None for browsers which are known to be affected.

Session Validation

A newline separated list of rules declaring attributes that must not change in the same session. A rule has the following syntax:

ENV|CONST|PARAM|HEADER:<name of the attribute>:block|invalidate

• block: the request will be blocked and 403 (Forbidden) will be returned
• invalidate: the session will be invalidated and a new one will be created

nevisProxy Conditions are supported. See nevisProxy reference guide for details.

For instance, use the following configuration to terminate the session if the source IP changes:

ENV:REMOTE_ADDR:invalidate

Initial Session Timeout

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

Authenticated Session Timeout

Defines the idle timeout of a nevisProxy session.

A nevisProxy session will be created only if required (e.g. to store application cookies).

Please set the timeout as low as possible to not increase the risk of session exhaustion attacks.

Max Session Lifetime

Define the maximum lifetime of a nevisProxy 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.

Generic Virtual Host Settings

#Application Protection #Generic #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Customize the web.xml configuration using XML constructs as described in the nevisProxy Technical Documentation.

Use as add-on for the Virtual Host pattern. The following expressions are supported:

• ${name}: sanitized name of the pattern
• ${service.name}: the name of the virtual host
• ${service.id}: the unique ID of the virtual host
• ${service.path}: the base path of the virtual host (empty String)
• ${service.mapping}: the url-pattern for the virtual host /*

Filters and Mappings

Configure filters and their mappings using the XML syntax described in the nevisProxy Technical Documentation.

Filters that have the same name as other filters (even those defined by other patterns) will be combined: the init-param sets will be merged where possible. Direct contradictions are interpreted as validation failures.

Example 1: Create (or patch) a filter with a fixed name

<filter>
   <filter-name>SomeName</filter-name>
   <filter-class>ch::nevis::isiweb4::filter::SomeClass</filter-class>
   <init-param>
      <param-name>...</param-name>
      <param-value>...</param-value>
   </init-param>
</filter>

Example 2: Create (or patch) a filter using an application-specific name

<filter>
   <filter-name>SomeName_${service.name}</filter-name>
   <filter-class>ch::nevis::isiweb4::filter::SomeClass</filter-class>
   ...
</filter>

Example 3: Map a filter to a sub-path of the assigned application(s). This example works for applications which have 1 frontend path only.

<filter-mapping>
   <filter-name>SomeFilter</filter-name>
   <url-pattern>${service.path}/custom/*</url-pattern>
</filter-mapping>

Example 4: Use multi-value expressions

Multi-value expressions replicate an entire line for each associated value.

Use the expressions *{service.path} and *{service.mapping} to generate filters which must contain the frontend paths of all assigned applications.

The following snippet is not complete but should illustrate the concept:

<filter>
    <filter-name>FormSigning</filter-name> 
    <filter-class>ch::nevis::isiweb4::filter::validation::EncryptionFilter</filter-class>
    <init-param>
        <param-name>EntryURL</param-name>
        <param-value>
            *{service.path}/
        </param-value>
    </init-param>
    ...
</filter>

Filter Mappings

Choose between:

• manual (default): only the filter-mapping elements which have been configured via Filters and Mappings will be added.
• automatic: filters configured via Filters and Mappings will be mapped to /*.
• both: like automatic but additional filter-mapping elements are allowed as well.

Filter Phase

When adding filter-mapping elements, a phase must be defined.

The phase defines where the filter-mapping is placed in the web.xml and ensures that filters are applied in the right order, relative to other phases.

The order within a certain phase is undefined as it must not matter.

The order for requests is START to END and END to START for responses.

This setting applies to all filter-mapping elements.

The filter-mapping elements may be provided via Filters and Servlets, or created automatically (see Filter Mappings for details).

Choose from the following filter phases:

• START: applied as early as possible for requests and as late as possible for responses.
• BEFORE_SANITATION: applied before filters which validate the request (e.g. Mod Security).
• SANITATION: used for security. This is the first phase which allows accessing the session for applications protected by a realm.
• AFTER_SANITATION: your request has passed security checks.
• BEFORE_AUTHENTICATION: applied just before authentication.
• AUTHENTICATION: used by the filter which connects to nevisAuth for applications which are protected by an Authentication Realm.
• AFTER_AUTHENTICATION: the request has level 1 authentication. Used by Authorization Policy for Authentication Level stepup.
• BEFORE_AUTHORIZATION: choose this phase to do preprocessing before authorization.
• AUTHORIZATION: used by Authorization Policy for Required Roles check.
• AFTER_AUTHORIZATION: used by patterns assigned as Application Access Token to applications.
• END: applied as late as possible for requests and as early as possible for responses.

This setting is ignored when you patch a filter generated by another pattern (e.g. by adding, overwriting, or removing an init-param element) but don't create any filter-mapping element.

Servlets and Mappings

Configure servlet and/or servlet-mapping elements using the XML constructs described in the nevisProxy Technical Documentation.

You can also customize elements which have been generated by other patterns. Elements can be referenced as follows:

• servlet: servlet-name
• servlet-mapping: url-pattern

In Kubernetes side-by-side deployment a postfix is added to service names. Use the expression ${service.postfix} connecting to a service deployed against the same inventory.

Example 1: Add or overwrite an init-param for an existing servlet:

<servlet>
  <servlet-name>Hosting_Default</servlet-name>
  <init-param>
    <param-name>NoMatchFile</param-name>
    <param-value>/index.html</param-value>
  </init-param>
</servlet>

Example 2: Remove a servlet-mapping:

<servlet-mapping>
    <url-pattern>/app/*</url-pattern>
</servlet-mapping>

Here we left out the servlet-name to tell the pattern to remove the servlet-mapping for the given url-pattern.

Note that the mapping of the hosted resources is an exception and cannot be removed this way (see the property Hosted resources of the Virtual Host pattern for more information).

Removing a servlet element is not supported.

Template Parameters

Define Template Parameters.

Examples:

backend-host: backend.siven.ch

These parameters can be used in:

• Servlets and Mappings
• Filters and Mappings

The expression formats are:

${param.<name>}:

• name found: parameter value is used.
• name missing: expression is not replaced.

${param.<name>:<default value>}:

• name found: parameter value is used.
• name missing: default value will be used.

In <default value> the character } must be escaped as \}.

Remove Filter Mappings

Remove <filter-mapping> elements generated by other patterns.

This is an advanced configuration. Use only when you want to remove a <filter-mapping> but keep the <filter> element, e.g. to map it on a sub-location.

The syntax is a map of <filter-name>:<url-pattern>, according to values from the web.xml.

For instance, the following would remove the ErrorHandler_Default from /*:

ErrorHandler_Default:/*

Mime-Mappings

Set or replace mime-mapping elements.

Examples:

<mime-mapping>
    <extension>svg</extension>
    <mime-type>image/svg+xml</mime-type>
</mime-mapping>

The mime-mapping elements affect the entire Virtual Host and are used use to determine the Content-Type for responses.

nevisProxy always sets a Content-Type header for static resources served by the Virtual Host.

Further, nevisProxy can add a Content-Type header for resources served by applications. To enable this advanced feature assign Generic Application Settings to the application and set the parameter ProxyPolicy to mime-completion.

Google Login Step

#Federation #Authentication #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

Set up social login, using Google as OpenID Connect provider.

Client ID

ClientID is Client ID provided by Google when you create a OAUTH 2.0 credential in Google.

Client Secret

Client Secret is Client Secret provided by Google when you create a OAUTH 2.0 credential in Google.

Return Path

The callback URI to go to after a successful login with Google.

This will create an endpoint in your host config.

The URL will be a combination of the Frontend Address of the Virtual Host and the value configured here. For example, let's assume that you have configured:

• Return Path: /oidc/google/
• Frontend Address: https://nevis.net

Then the URL will be https://nevis.net/oidc/google/.

Use the exact: prefix to use the given path as-is. Without this prefix a normal mapping with /* will be generated and thus sub-paths will be accessible as well.

Virtual Host

Assign a Virtual Host which shall serve as entry point for the callback from social login provider.

In case your host has

• 1 address, that address will be used
• many addresses with
  • 1 https, and many http, the https will be used without warning
  • mix between http and https, the 1st https will be used with warning
  • single scheme (http or https only) the 1st address will be used with warning

E.g.

http://nevis.net
http://nevis-security.net
https://nevis.net
https://nevis-security.net

The https://nevis.net will be used as the host for Apple callback

Scope(s)

Select the request scope(s) for getting user information from Google. Default scopes is email.

Scope openid will be added automatically because Google is implement based on OpenID protocol.

Scope offline_access for generate refresh token. This scope will transfer to access_type=offline request parameter for matching with Google spec

On Success

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

In case you change this to your custom step(s), you can assign pattern Social Login Final Step as the last step of the Authentication process to redirect back to original URL.

On Failure

The step that will be executed if the authentication fails. If no step is configured here the process ends with AUTH_ERROR.

In case you change this to your custom step(s), you can assign pattern Social Login Final Failure Step as the last step of the Authentication process to redirect back to original URL.

nevisIDM

Choose which nevisIDM instance you want to store the user's information after logged in with social login provider.

Client External ID

The ExtId of the client in nevisIDM that will be used to store the user

On User Not Found

Configure the authentication flow to be executed when no user was found and the email provided by social account does not exist. The authentication flow must contain the Social Login Create User pattern if a new user shall be created.

Note: Please select scope email and profile for getting user's information from social account.

On User Found

Configure the Authentication Flow in case no user with Subject/ID from social account was found but email does exist in nevisIDM. The Authentication Flow must contain:

• Social Login Link User pattern to link an existing user in IDM with Subject/ID of social account.
• Social Login Done to end the social login flow after some other action(s).

Note: Please select scope email and profile for getting user's information from social account.

Claims Request

The claims request parameter. This value is expected to be formatted in JSON and does not accept trailing spaces nor tabs.

User ID Field

Logged userId will automatically get from social account. But you can change the userId by using this field.

Additional Auth Request Parameters

Arbitrary additional request parameters used in the authentication request. The property supports variable substitution.

Example:

[paramName]=[paramValue]

Button Label

Enter the text that should be displayed for the end-user on the social login button, and provide translations for this label on the Authentication Realms.

Groovy Script Step

#Authentication #Generic

Plugin: nevisadmin-plugin-nevisauth

This step generates a nevisAuth ch.nevis.esauth.auth.states.scripting.ScriptState.

The GUI descriptor cannot be customized, unless you overwrite the response template in the Groovy script.

If script execution fails HTTP error code 403 is returned, and the session will be terminated using AUTH_ERROR.

Groovy Script

Upload the Groovy script as a file.

Further information can be found in the nevisAuth Technical Documentation:

• ScriptState
• Writing scripts in Groovy

Use the expression ${service.postfix} to refer to Kubernetes services deployed by this nevisAdmin 4 project.

The expression can always be used as it produces an empty String when the deployment is not a Kubernetes side-by-side deployment.

For instance, the following snippet declares a URL which points to the REST API of a nevisIDM Instance that has been deployed as a Kubernetes service called idm:

def url = "https://idm${service.postfix}:8989/nevisidm/api"

You may use var expressions to insert values from inventory variables at generation time. For instance, use ${var.<name>} to insert a variable called <name>.

If the variable is a scalar, the value will be returned as-is. If the variable is a sequence, a Groovy list will be returned (start: [, end: ], separator: ,, String quote: ").

If your Groovy script fails to validate, see Script Validation.

Script Parameters

Set parameters for your Groovy script.

Enter the name of the parameter as Key.

The Value can be either:

1. constant String value
2. nevisAuth expression (${...:...})
3. an EL expression (#{...})
4. a reference to an inventory variable (${var.<name>}). Such expressions are resolved during generation.

Parameters can then be used inside the Groovy script via the parameters map.

Example usage:

parameters.get('backend-url')

Script Validation

Choose between:

• enabled - parse the Groovy script and run against mock objects.
• parse-only - only parse the Groovy script.
• disabled - the script is not validated.

The validation is not feature complete and thus there may false negatives.

For instance, import statements can make the validation fail as the corresponding classes are usually not on the nevisAdmin 4 classpath. This case is quite common and thus failed imports will be reported as info issues to not block deployment.

If your Groovy script produces warning or error issues but is working inside nevisAuth please select disabled and provide the script to Nevis Security so that we can improve the validation.

When set to enabled the following mock objects will be used for validation:

Map<String, String> parameters
Map<String, Object> inctx
Properties inargs
Map<String, Object> session
Properties outargs
Properties notes
Request request
Response response
Tracer LOG

On Success

Assign an authentication step which shall be executed when the Groovy script sets the result ok.

response.setResult('ok')

If no step is assigned a default state will be added.

On Failure

Assign an authentication step which shall be executed when the Groovy script sets the result error.

response.setResult('error')

If no step is assigned a default state will be added.

Custom Follow-up Step(s)

Assign follow-up steps.

For each step a transition (called ResultCond in esauth4.xml) is added. The name of the transition depends on the position in the list.

For instance, if 2 steps are assigned the following transitions will be added:

• exit.1
• exit.2

The Groovy script may trigger a certain transition by calling the method response.setResult handing over the name of the transition.

Example:

response.setResult('exit.1')

Custom Class Path

Set the classPath attribute of the AuthState element.

Lines will be joined with :. Enter 1 path per line.

When set, the classLoadStrategy attribute will be set to PARENT_LAST.

Log Category

Use a different category for logging in your Groovy script.

Response Type

Choose between:

• AUTH_ERROR: terminates the session.
• AUTH_CONTINUE: use to produce a response and continue with this state on next request.

Error Status Code

Set the status code for responses when the Response Type is set to AUTH_ERROR.

The default of 403 is backward compatible.

Note that we generally use 403 for unhandled error cases in authentication step patterns. This is to avoid exposing the information that a certain case is not properly handled.

Depending on your case, a 500 or 400 may be a more appropriate choice.

Gui Elements

Add Gui elements to the Response.

For each line 1 Gui element will be generated.

Most authentication states have only 1 Gui element.

The format is key-value pairs. The key is used as name. The value is optional and used as label.

For instance, the line auth:title.login will produce the following Gui element:

<Gui name="auth" label="title.login"/>

Configuration of GuiElem elements is not supported. You have to create them dynamically in your script.

Here is an example how to render a certain Gui and add GuiElem elements:

response.setGuiName('login')
response.addInfoGuiField('info', 'info.login', null)

HTTP Error Handling

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Use the pattern to handle HTTP error codes.

You can use the pattern as an add-on for Virtual Host or any backend application, for example, Web Application, REST Service, or SOAP Service.

Error Pages

Upload HTML error pages, JSON error pages and associated resources here.

Pages must be named like the error code they are used for (e.g. 500.html). You can use the same page for multiple status code (e.g. 401,403,500-599.html).

By default, the error pages are deployed to /errorpages/<name> but you can set a different location via the property Base Path (see Advanced Settings).

In your error pages we recommend to use relative links to include resources. You may also include resources deployed on the virtual host via Hosted Resources.

The following placeholders are supported:

• TRANSFER_ID for the unique ID of the request (e.g. c0a80e52-5d04-11ac0500-16906714eee-00000003)
• TIMESTAMP to show a timestamp (e.g. Tue, 19 Feb 2019 15:48:02 GMT)

Blocked Status Codes

Hide certain HTTP status code(s) by returning 200 OK instead (by using the reset-status-code action).

By default, the status code is not changed as it can be useful for technical clients.

The response body will still be replaced.

You may also enter:

• ranges of status codes (e.g. 500-599),
• lists (e.g. 403,500)
• combination thereof (e.g. 403,500-599).

Redirect Status Code Mapping

Redirect to a given location instead of rewriting the response body.

Locations can be entered as:

• URLs (starting with http:// or https://)
• paths (starting with /)

Internal and external locations are supported.

Examples:

404,500-599 -> /some/super/redirect/
403 -> https://www.google.com

Keep Header Status Codes

By default, HTTP headers are dropped when an error code is handled.

This avoids information leakage but can lead to session loss in some cases.

For instance, the nevisProxy session will be lost when all of the following holds:

• this pattern is configured to handle code 502.
• the application is unreachable (502 is produced).
• the nevisProxy session cookie is renegotiated (Set-Cookie header is set).
• user refreshes the page after the error page is shown.

To overcome this limitation you may enter 502 here.

Note that we are investigating additional measures and may adapt this property in future releases.

Overwrite Status Codes

Overwrite certain HTTP status code(s) by returning with the defined status code instead.

If for an error code both Blocked Status Code and Overwrite Status Code is configured, the Blocked Status Code will take precedent.

Examples:

404,406-499 -> 401
405 -> 200

Mode

Enable or disable the error handling.

When set to disabled, all settings except Apply only to sub-paths are ignored. Use this setting in combination with Apply only to sub-paths to disable the error handling for some sub-paths only.

Usage examples (valid for Virtual Hosts and backend applications):

• Disable the error handling: use an Error Handler pattern with Mode set to disabled and link it to the target pattern via Additional Settings;
• Disable the error handling for some sub-paths: use an Error Handler pattern with Mode set to disabled and Apply only to sub-paths set to the paths where no error handling should occur, and link it to the target pattern via Additional Settings;
• Define a customised error handling and disable it for some sub-paths: use two Error Handler patterns, one with the custom settings, and one with Mode set to disabled and Apply only to sub-paths set to the paths where no error handling should occur. Link both of them to the target pattern via Additional Settings.

Apply only to sub-paths

Set to apply the error handling on some sub-paths only.

Sub-paths must be relative (e.g. not starting with /) and will be appended to the frontend path(s) of the virtual host (/) or applications this pattern is assigned to.

Sub-paths ending with / are treated as a prefix, otherwise an exact filter-mapping will be created.

The following table provides examples to illustrate the behaviour:

Frontend Path	Sub-Path	Effective Filter Mapping
/	secure/	/secure/*
/	accounts	/accounts
/	api/secure/	/api/secure/*
/	api/accounts	/api/accounts
/app/	secure/	/app/secure/*
/app/	accounts	/app/accounts
/app/	api/secure/	/app/api/secure/*
/app/	api/accounts	/app/api/accounts

Content-Type Mode

The Content-Type Mode allows enabling or disabling the error handling depending on the Content-Type header of the backend response. Use this setting in combination with the Content-Types setting.

Choose one of:

• None: The error handling settings are applied to all backend responses.
• Enabled: The error handling settings are enabled only for the backend responses with a Content-Type header included in the Content-Types setting. Backend responses with other Content-Types are propagated to the client.
• Disabled: The error handling settings are disabled for the backend responses with a Content-Type header included in the Content-Types setting. These responses are propagated to the client. The error handling settings are applied to backend responses with other Content-Type headers.

Content-Types

The Content-Types configures the Content-Type headers for which the Content-Type Mode setting is applied. Enter one value per line.

Use this setting in combination with the Content-Type Mode setting.

Base Path

By default, the error pages are deployed to /errorpages/<name> but you can set a different location here.

Keep Security Headers

Configure the name of special response headers which should be kept, regardless of the header action of the matching rule. Useful for keeping the security response headers for the error pages.

Default:

Strict-Transport-Security
X-Content-Type-Options
Referrer-Policy

HTTP Header Customization

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Use to add, overwrite, or remove HTTP headers in requests or responses.

You can use the pattern as add-on for Virtual Host or applications, for example, Web Application, REST Service, or SOAP Service.

The following expressions may be used:

• ${client.ip} - IP address of the caller
• ${request.id} - unique ID of this request
• ${request.header.<name>} - value of a request header (only for requests)
• ${env.<name>} - Apache ENV variables
• ${auth.<name>} - access to the AUTH scope (only for requests, requires an Authentication Realm and the Filter Phase is to be set to AFTER_AUTHENTICATION or END)

Add / Overwrite Headers

Adds/overwrites HTTP headers in requests.

The syntax is: <header name>:<value>

Examples:

X-Forwarded-For: ${client.ip}
User-ID: ${auth.user.auth.UserId}

Note: change the Filter Phase to replace headers early / late.

In order to use the ${exec: ...} syntax of nevisProxy for passwords, use an inventory secret to skip the validation of the value.

Basic Auth User

Enter the basic auth user or an expression of the format <source>:<parameter>.

For the <source> you may use:

• AUTH: outargs returned by nevisAuth.
• CONST: constant strings.
• ENV: Apache environment variables.
• PARAM: values from a request body as provided by a ParameterFilter.
• HEADER: request headers.

Basic Auth Password

Enter the basic auth password or an expression of the format <source>:<parameter>.

For the <source> you may use:

• AUTH: outargs returned by nevisAuth.
• CONST: constant strings.
• ENV: Apache environment variables.
• PARAM: values from a request body as provided by a ParameterFilter.
• HEADER: request headers.

Remove Headers

Removes HTTP headers from requests.

The syntax is: <header name>

Examples:

User-Agent

Note: change the Filter Phase to remove headers early / late.

Filter Phase

• BEFORE_SANITIATION - manipulate request headers early to hide them from validation and authentication.
• AFTER_AUTHENTICATION - the original values are subject to validation and can be accessed in the authentication flow. The header manipulation is applied afterwards to affect the application only.
• END - manipulate request headers late, just before the request is forwarded to the application.

Add / Overwrite Headers

Adds/overwrites HTTP headers in responses.

The syntax is: <header name>:<value>

Force browser to use HTTPS only (1 day expiration):

Strict-Transport-Security: max-age=86400

Ensure pages are not cached:

Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0

Headers set by Apache (e.g. Server) cannot be overwritten.

Note: change the Filter Phase to set headers early / late.

Remove Headers

Removes HTTP headers from responses.

The syntax is: <header name>

Examples:

X-Content-Type-Options

Headers set by Apache cannot be removed:

• Server

Note: change the Filter Phase to remove headers early / late.

Filter Phase

• BEFORE_SANITIATION - manipulate request headers late to also cover any headers set by nevisProxy.
• AFTER_AUTHENTICATION - default behaviour which should work in most cases.
• END - manipulate response headers early hiding them from other nevisProxy filters which operate on responses.

Add / Overwrite Headers Condition

Set to do the header customization only if the given condition applies.

The condition is checked for Add / Overwrite Headers on requests and on responses.

You can use the expressions mentioned above.

Syntax:

${expression} == value

Examples:

${request.header.Content-Type} == application/x-www-form-urlencoded

Apply only to sub-paths

Set to apply the header customization on some sub-paths only.

Sub-paths must be relative (e.g. not starting with /) and will be appended to the frontend path(s) of the virtual host (/) or applications this pattern is assigned to.

Sub-paths ending with / are treated as a prefix, otherwise an exact filter-mapping will be created.

The following table illustrates the behaviour:

Frontend Path	Sub-Path	Effective Filter Mapping
/	secure/	/secure/*
/	accounts	/accounts
/	api/secure/	/api/secure/*
/	api/accounts	/api/accounts
/app/	secure/	/app/secure/*
/app/	accounts	/app/accounts
/app/	api/secure/	/app/api/secure/*
/app/	api/accounts	/app/api/accounts

Hosting Service

#Application Protection #Applications

Plugin: nevisadmin-plugin-nevisproxy

Use the pattern to host static pages and related resources.

For instance, you can use this pattern to host HTML or a single-page application (SPA).

Further, you can provide CSS, images, and Javascript for error pages uploaded by a HTTP Error Handling pattern.

The pattern generates configuration for the nevisProxy ch::nevis::nevisproxy::servlet::file::FileReaderServlet.

Virtual Host

Assign a Virtual Host which shall serve as entry point.

Frontend Path

The path at which the resources shall be accessible at the frontend. You may use / to deploy root content.

Resources

Upload your resources here.

All files will be deployed in the same directory. Please use standard extensions (e.g. .css, .png, .html, .htm) only.

If you want to use subdirectories please upload a .zip file instead. The content of the .zip file will be unpacked.

Default File

Defines a default file which will be returned when there is no other matching file.

Authentication Realm

Optionally assign a realm to protect this application or service.

Rewrite Rules

Rewrite rules for serving files.

This can be useful if a file should be served under a different name, or to map extensions to file names.

Examples:

Source	Destination
/static/picture	/static/picture.jpg

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.

ICAP Scanning

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

The pattern configures a filter in nevisProxy to forward incoming requests to an ICAP server, for example, ClamAV. A typical use case is virus scanning for file uploads.

ICAP Server URLs

URL(s) of the ICAP server(s). Each URL must have the same path.

Example: icap://my-clamav-server1/avscan

Content-Type Restriction

Optional property to restrict scanning to a certain Content-Type (regular expression is supported here).

Example: application/.*

Apply only to sub-paths

Set to apply the ICAP scanning on some sub-paths only.

Sub-paths must be relative (e.g. not starting with /) and will be appended to the frontend path(s) of the virtual host (/) or applications this pattern is assigned to.

Sub-paths ending with / are treated as a prefix, otherwise an exact filter-mapping will be created.

The following table provides examples to illustrate the behaviour:

Frontend Path	Sub-Path	Effective Filter Mapping
/	secure/	/secure/*
/	accounts	/accounts
/	api/secure/	/api/secure/*
/	api/accounts	/api/accounts
/app/	secure/	/app/secure/*
/app/	accounts	/app/accounts
/app/	api/secure/	/app/api/secure/*
/app/	api/accounts	/app/api/accounts

In-band Mobile Authentication Realm

#Mobile Authentication #Authentication #Realms

Plugin: nevisadmin-plugin-nevisfido

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:

Key	Value
BodyReadSize	64000
InterceptionRedirect	Condition:ENV:HTTP_USER_AGENT:mozilla|Mozilla\ninitial\nnever
ClientCert	want

Custom Parameters (SecurityRoleFilter)

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

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

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:

Key	Value
EnablePollTerminatedCalls	true

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

#Mobile Authentication #Authentication

Plugin: nevisadmin-plugin-nevisfido

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.

JSON Response Step

#Authentication #Generic #Experimental

Plugin: nevisadmin-plugin-nevisauth

A simple step that returns a JSON response.

JSON Response

Enter the JSON response.

Response Type

Use AUTH_CONTINUE to keep the current session and stay in state. If and when the next request comes in, the On Continue exit will be taken.

Use AUTH_DONE to finish the current flow and establish an authenticated session.

In a classic reverse proxy scenario, the request will continue in the filter chain in nevisProxy, towards the calculated servlet. If the servlet points to an application the request will be forwarded.

Note that in some authentication scenarios (e.g. federation), there is no backend and thus a 404 error may occur, unless the AUTH_DONE is handled.

For instance, there are certain AuthState classes that handle AUTH_DONE to fulfill their use case. A prime example is the AuthorizationServer which is set up by the OAuth 2.0 Authorization Server / OpenID Connect Provider pattern. This one handles AUTH_DONE by completing the OAuth flow.

Use AUTH_ERROR to terminate the flow, removing the session. Note that this type may also be used for successful execution, to remove the session.

On Continue

This exit will be taken when Response Type is set to AUTH_CONTINUE and the next request is received.

Status Code

Enter an appropriate status code for the HTTP response. If not set the code will be set based on the selected Response Type:

• AUTH_ERROR: 401
• AUTH_DONE: 200

Parameters

Define Parameters to be used in the JSON Response.

Examples:

backend-host: backend.siven.ch

The expression formats are:

${param.<name>}:

• name found: parameter value is used.
• name missing: expression is not replaced.

${param.<name>:<default value>}:

• name found: parameter value is used.
• name missing: default value will be used.

In <default value> the character } must be escaped as \}.

JWT Access Restriction

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Sets up a filter in nevisProxy to verify the JWT of incoming requests.

A request will be allowed to pass through if it contains a valid JWT, in every other case (e.g. failed to verify, expired or token not present), the request will be blocked. Blocked requests are responded to with HTTP error code 403

The pattern can be assigned to applications or an entire Virtual Host using Additional Settings. .

HTTP Header

By default, the JWT will be extracted from the Bearer type Authorization request header:

Authorization: Bearer <token>

Optionally, this behavior can be overwritten by this property by specifying a request header from where the token should be extracted, for example if the token is sent like:

CustomAuthHeader: <token>

Then configure CustomAuthHeader for this property.

Algorithm

The algorithm used to sign and verify the JWT.

Supported algorithms are:

• RS256
• RS384
• RS512 (default)

Public Key

The public key corresponding to the private key which was used to sign the JWT.

JWT Token

#Authentication #Tokens #Add-ons

Plugin: nevisadmin-plugin-nevisauth

Assign to a realm using Application Access Tokens to allow the realm to produce a JWT token.

To issue a JWT token and propagate it to applications you also have to assign the pattern to the corresponding Web Application, REST Service, or SOAP Service using Application Access Token.

The JWT token is sent in an HTTP header (default: Authorization) in the format Bearer <token>.

Token Type

The following types of JWT token are supported:

• JWS: JSON Web Signature - using HS256 or HS512 algorithm
• JWE: JSON Web Encryption - using RSA-OAEP-256 and A256GCM algorithm

Note: in case asymmetric encryption is used, the x5t#S256 Certificate thumbprint header parameter will automatically be added according to RFC 7515.

Token Algorithm

The following algorithms of JWT token are supported:

• HS256 or HS512: compatible with JWS token type
• RSA-OAEP-256: compatible with JWE token type

Secret

Enter a shared secret to be used for symmetric algorithms.

This is required for JWS because of the HS256 algorithm.

Signer Key Store

A Key Store is required when an asymmetric algorithm is used.

This is required for JWE because of the RSA-OAEP-256 algorithm.

Issuer

The issuer (iss) is an optional claim which may be checked by applications receiving this token.

Subject

Enter a nevisAuth expression for the claim sub. The default refers to the ID of the authenticated user.

Audience

The audience (aud) is an optional claim which may be checked by applications receiving this token.

User Attributes

Add custom claims to the JWT token.

Values can be static, nevisAuth expressions (${...}) or EL expressions (#{...}).

Examples:

Claim	Expression
email	${sess:user.email}

Key Identifier

The kid (key ID) Header Parameter is a hint indicating which key was used to secure the JWS. This parameter allows originators to explicitly signal a change of key to recipients.

When used with a JWK, the kid value is used to match a JWK kid parameter value.

For reference, please consult RFC 7515.

Header

When this pattern is assigned to an application, the JWT token will be added to all requests which are forwarded to that application.

Here you can define the name of the HTTP header which should contain the token.

Custom Properties

Set low-level properties for the JWTToken AuthState.

Java Observability Settings

#Add-ons #Experimental

Plugin: nevisadmin-plugin-base

Sets up observability for Java-based Nevis components.

You can choose between OpenTelemetry and Application Insights.

This pattern adds a Java agent to integrate with either system.

Agent Type

Choose agent type:

• OpenTelemetry to integrate with self-hosted observability stack or with an OpenTelemetry compatible cloud provider.
• Application Insights to integrate with Azure Application Insights.

Agent Library Path

Path to the selected agent's library that is available locally to the deployed application.

Agent Configuration

Configuration file of the selected agent.

Use ${...} expressions to refer parameter values. Default parameters:

• ${name}: component name
• ${instance}: instance name
• ${version}: version
• ${service.name}: service name (kubernetes deployment)

Sample configuration for OpenTelemetry:

otel.service.name = ${service.name}
otel.resource.attributes = service.version=${version}
otel.exporter.otlp.protocol = http/protobuf
otel.exporter.otlp.traces.protocol = http/protobuf
otel.exporter.otlp.traces.endpoint = ${tracesEndpoint}
otel.exporter.otlp.metrics.protocol = http/protobuf
otel.exporter.otlp.metrics.endpoint = ${metricsEndpoint}
otel.exporter.otlp.metrics.temporality.preference = cumulative
otel.exporter.otlp.logs.protocol = http/protobuf
otel.exporter.otlp.logs.endpoint = ${logsEndpoint}

Sample configuration for Application Insights:

{
  "connectionString": "${connectionString}",
  "role": {
    "name": "${service.name}"
  },
  "customDimensions": {
    "service.version": "${version}"
  },
  "sampling": {
    "percentage": 100
  },
  "instrumentation": {
    "logging": {
      "level": "OFF"
    }
  }
}

Configuration Parameters

Provide parameters for your configuration file.

Examples:

connectionString = InstrumentationKey=00000000-0000-0000-0000-000000000000

tracesEndpoint = https://otel-collector:4318/v1/traces
metricsEndpoint = https://otel-collector:4318/v1/metrics
logsEndpoint = https://otel-collector:4318/v1/logs

Deployment Environment

Select a value for the OpenTelemetry deployment.environment attribute.

Choose between:

• production: example value used in OpenTelemetry documentation
• staging: example value used in OpenTelemetry documentation
• testing
• development

If nothing is selected, then this attribute will not be set.

In case the attribute is set in the Agent Configuration as well, the configuration provided here wins.

You may use this attribute for filtering, e.g. to separate information from prod and test for metrics and traces.

Kerberos Login

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

The Kerberos Login configures Kerberos authentication based on the simple and protected GSS-API negotiation mechanism (SPNEGO) for nevisAuth.

Kerberos Realms

Enter the allowed Kerberos realms (AD domains).

Example:

• SIVEN.CH

In case multiple values have to be configured you can define which Keytab File or Keytab File Path
to use by referencing its file name.

Example:

• SIVEN.CH -> kerberos_ch.keytab
• SIVEN.DE -> kerberos_de.keytab

Frontend Addresses

Enter the Frontend Addresses of the nevisProxy Virtual Host patterns for which this pattern provides authentication.

Example:

• www.siven.ch

In case multiple values are configured you can define which Keytab File or Keytab File Path to use by referencing its file name.

Example:

• www.siven.ch -> kerberos_ch.keytab
• www.siven.de -> kerberos_de.keytab

Keytab File Path

Enter the path of the Kerberos keytab file.

The path must exist on the target host(s) of the nevisAuth Instance.

This configuration is ignored when keytab file(s) are uploaded via Keytab File.

In complex setups with multiple Kerberos Realms and/or Frontend Addresses you may want to enter multiple keytab file paths.

Keytab File

Upload the Kerberos keytab file.

nevisAuth uses this file to validate Kerberos tokens sent by browsers.

Please check the nevisAuth Technical Documentation on how to create the keytab file.

The keytab file will be deployed to the conf directory of the nevisAuth instance.

For a more secure and environment-specific configuration you have the following alternatives:

• create a variable and upload the keytab file in the inventory
• set Keytab File Path instead of uploading the file and deploy the file by other means

In complex setups with multiple Kerberos Realms and/or Frontend Addresses you may have to upload multiple keytab files.

Authentication Level

Authentication level that is set on success.

Limit Session Lifetime

If set to true then the lifetime of the underlying Kerberos service ticket used by the client during the SPNEGO negotiation will be considered when determining the lifetime of Nevis session. In this case the expiration time of Nevis session cannot be longer than the expiration time of the Kerberos service ticket.

Default is false.

On Success

Configure the step to execute after successful authentication. If no step is configured here the process ends and the user will be authenticated.

On Failure

Assign authentication step that is processed if Kerberos authentication fails.

If no step is assigned an AuthState Authentication_Failed will be created automatically.

Kerberos Login (Deprecated)

#Authentication

Plugin: nevisadmin-plugin-nevisauth

The Kerberos Login configures Kerberos authentication based on the simple and protected GSS-API negotiation mechanism (SPNEGO) for nevisAuth.

Kerberos Realms

Enter the allowed Kerberos realms (AD domains).

Example:

• SIVEN.CH

In case multiple values have to be configured you can define which Keytab File or Keytab File Path
to use by referencing its file name.

Example:

• SIVEN.CH -> kerberos_ch.keytab
• SIVEN.DE -> kerberos_de.keytab

Frontend Addresses

Enter the Frontend Addresses of the nevisProxy Virtual Host patterns for which this pattern provides authentication.

Example:

• www.siven.ch

In case multiple values are configured you can define which Keytab File or Keytab File Path to use by referencing its file name.

Example:

• www.siven.ch -> kerberos_ch.keytab
• www.siven.de -> kerberos_de.keytab

Keytab File Path

Enter the path of the Kerberos keytab file.

The path must exist on the target host(s) of the nevisAuth Instance.

This configuration is ignored when keytab file(s) are uploaded via Keytab File.

In complex setups with multiple Kerberos Realms and/or Frontend Addresses you may want to enter multiple keytab file paths.

Keytab File

Upload the Kerberos keytab file.

nevisAuth uses this file to validate Kerberos tokens sent by browsers.

Please check the nevisAuth Technical Documentation on how to create the keytab file.

The keytab file will be deployed to the conf directory of the nevisAuth instance.

For a more secure and environment-specific configuration you have the following alternatives:

• create a variable and upload the keytab file in the inventory
• set Keytab File Path instead of uploading the file and deploy the file by other means

In complex setups with multiple Kerberos Realms and/or Frontend Addresses you may have to upload multiple keytab files.

Authentication Level

Authentication level that is set on success.

On Success

Configure the step to execute after successful authentication. If no step is configured here the process ends and the user will be authenticated.

On Failure

Assign authentication step that is processed if Kerberos authentication fails.

If no step is assigned an AuthState Authentication_Failed will be created automatically.

LDAP Login

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Username / password login for LDAP.

For Web Application, an initial redirect (to ?login) is performed and a login GUI is shown.

Basic authentication may be used to call a REST or SOAP service.

Double-check the URL you are calling as nevisProxy responds with a redirect if no servlet could be found otherwise (trailingSlashRedirect).

LDAP Endpoints

Configure the LDAP endpoint. The URL must start with ldap:// or ldaps://

In case of ldaps:// you may have to import the certificate of the CA which has issued the certificate of the LDAP server into the Backend Trust Store on the nevisAuth Instance.

Connection Username

User to connect with. This user is part of the LDAP connection url.

Example:

• CN=admin,O=company,C=ch

Connection Password

Password of the connection user. The user is part of the LDAP connection url.

Example:

• secret://Ll41Zsw54rmeNi2ZeoZD
• verySecretPassword

See the nevisAuth Reference Guide UseridPasswordAuthenticateState for more details on how to use obfuscated password.

Base DN

Specifies the directory subtree where all users are located.

Example:

• ou=people,o=company,c=ch

Search In Subtree

If disabled all the users to authenticate must be in the same directory node, specified in the properties Base DN and User Attribute. In this case nevisAuth uses the user's account to authenticate against the LDAP directory.

If enabled a search query for the user is performed, with the specified Base DN.

User Attribute

Specifies the attribute in the LDAP directory that should match the users login-ID input.

Examples:

• uid
• cn

Directory Type

Configure the type of LDAP directory.

LDAP Attribute Mappings

Defines mappings from LDAP attributes to delegate names. The specified LDAP attributes are queried and set as output arguments with the specified output argument name.

• <attribute-name-in-directory>:<output-argument-name>
• <attribute-name-in-directory>

Examples:

• givenName
• mail:email
• telephoneNumber:user.mobile

On Success

Configure the step to execute after successful authentication. If no step is assigned, the process ends and the user will be authenticated.

On User Not Found

Assign an authentication step to be invoked if the user could not be found.

For instance, you may use this setting to chain multiple LDAP Login patterns, e.g. to lookup users based on a different User Attribute or in separate LDAP Endpoints.

The following notes will also be set and may be shown if the next state renders a GUI:

lasterror                 = 1
lasterrorinfo             = authentication failed, invalid input
lastresult                = usernotfound

On Invalid Password (Fallback)

Assign an authentication step to be processed if the user is found but the password is incorrect.

Use for custom reporting or error handling.

If no step is assigned the GUI is displayed again and an error message will be shown.

This setting is experimental and may be adapted in future releases.

On Password Expired

Assign a pattern which defines the step that is executed when the user must change his password.

If no pattern is assigned the next AuthState is Authentication_Failed which terminates the authentication process.

On Failure

Assign an authentication step that is processed if LDAP authentication fails with an technical error, or if the user is not unique.

If no step is assigned an AuthState Authentication_Failed will be created automatically.

User Filter

Enter an LDAP Filter.

Use when the user has to be determined with custom criteria. When configured this is used instead of User Attribute.

Example:

(|(${notes:userid}=cn)(${notes:userid}=mail))

For debugging the authentication set the log level of JNDI to DEBUG.

Authentication Level

Set an authentication level if authentication of this step is successful.

Custom Properties

Set custom properties for the UseridPasswordAuthenticateState.

Examples:

searchSizeLimit = 512

Logout

#Authentication

Plugin: nevisadmin-plugin-nevisauth

A logout can be triggered by sending a request with query parameter logout to a protected location. For example: /my-app/?logout

The default flow renders a GUI with a message and a submit button. On submit the user is redirected to the same URL with the query parameter logout removed. This leads to re-authentication. The logout flow cannot be aborted.

Note that in Chrome the logout GUI may NOT be shown because some versions sends multiple GET requests.

Use this pattern to customize the logout flow by showing a different message or redirecting to a different URL (in this case the GUI will not be shown).

Note that if the application is protected by a SAML SP Realm the logout process is managed by the IDP. Thus, the pattern is to be assigned to the realm of the IDP instead.

Logout Behaviour

• gui - shows a logout GUI. On submit the user is redirected to the same URL with the query parameter logout removed.
• redirect - does not show a GUI. The user is immediately redirected to the given URL or path.

Custom Label

Enter a label for the message that shall be presented to the user. This is used when Logout Behaviour is set to gui.

Redirect

Enter a URL or path to redirect to after logout.

Lua HTTP Processing

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Sets up a filter in nevisProxy which evaluates a Lua script.

The filter class is ch::nevis::isiweb4::filter::lua::LuaFilter.

Assign this pattern to your applications to perform complex request or response processing tasks.

Lua Script

Upload a Lua script which should be invoked for requests and / or responses. The script has to contain one or multiple of the following Lua functions:

• function inputHeader(request, response) - called once per request
• function input(request, response, chunk) - called once per request body chunk
• function outputHeader(request, response) - called once per response
• function output(request, response, chunk) - called once per response body chunk

The uploaded script will be deployed to the nevisProxy host in sub-directory WEB-INF using the name of this pattern for the file name to ensure that the file name is unique.

Here is an example Lua script which replaces sensitive information in response bodies:

local buf = {}
function output(request, response, chunk)
  if chunk ~= nil then
    table.insert(buf, chunk)
    return nil
  else
    return string.gsub(table.concat(buf), "some-sensitive-data", "*****");
  end
end  

The following expressions can be used anywhere within the script:

• ${name} - sanitized name of this pattern
• ${host} - name of the Virtual Host directory
• ${instance} - name of the nevisProxy Instance directory

Lua Libraries

Upload addtional Lua libraries to be used within the Lua Script.

Uploaded files will be deployed to the following directory:

/var/opt/nevisproxy/${instance}/${host}/WEB-INF/lib/${name}/"

The Lua script must patch package.path so that the Lua libraries can be used.

For instance, add the following line at the beginning of the script:

package.path = package.path .. ";/var/opt/nevisproxy/${instance}/${host}/WEB-INF/lib/${name}/?.lua"

Filter Phase

Defines the position of the filter-mapping for this Lua filter. Which position to choose depends on your use case.

For requests filters will be invoked from START to END. For responses filters will be invoked from END to START.

Choose from the following filter phases:

• START: applied as early as possible for requests and as late as possible for responses.
• BEFORE_SANITATION: applied before filters which validate the request (e.g. Mod Security).
• SANITATION: used for security. This is the first phase which allows accessing the session for applications protected by a realm.
• AFTER_SANITATION: your request has passed security checks.
• BEFORE_AUTHENTICATION: applied just before authentication.
• AUTHENTICATION: used by the filter which connects to nevisAuth for applications which are protected by an Authentication Realm.
• AFTER_AUTHENTICATION: the request has level 1 authentication. Used by Authorization Policy for Authentication Level stepup.
• BEFORE_AUTHORIZATION: choose this phase to do preprocessing before authorization.
• AUTHORIZATION: used by Authorization Policy for Required Roles check.
• AFTER_AUTHORIZATION: used by patterns assigned as Application Access Token to applications.
• END: applied as late as possible for requests and as early as possible for responses.

Script Parameters

Parameters defined here can be used inside the Lua script.

The name of each parameter must start with param_. This limitation may be lifted in a future release.

The value will be trimmed.

Set this property if you need a different value depending on the inventory.

1. click var to use a nevisAdmin 4 variable for the entire setting:
   • Enter a good name for the variable as the default may be quite verbose.
   • Enter some sample values to document the variable in the project.
2. add the nevisAdmin 4 variable to your inventories:
   • See below for an example which illustrates the syntax.

Example inventory variable:

vars:
  example-variable:
    param_example_string: "on"
    param_example_numeric: 60

It is sometimes required to quote values. In the example above, the value on would be converted to a boolean value if it weren't for the double quotes ". When unsure, always put double quotes around the value.

Apply only to sub-paths

Set to apply this pattern on some sub-paths only.

Sub-paths must be relative (e.g. not starting with /) and will be appended to the frontend path(s) of the virtual host (/) or applications this pattern is assigned to.

Sub-paths ending with / are treated as a prefix, otherwise an exact filter-mapping will be created.

The following table provides examples to illustrate the behaviour:

Frontend Path	Sub-Path	Effective Filter Mapping
/	secure/	/secure/*
/	accounts	/accounts
/	api/secure/	/api/secure/*
/	api/accounts	/api/accounts
/app/	secure/	/app/secure/*
/app/	accounts	/app/accounts
/app/	api/secure/	/app/api/secure/*
/app/	api/accounts	/app/api/accounts

Maintenance Page

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Shows a static maintenance page if the current date and time is within a certain interval.

Technical note: nevisProxy uses system calls to determine the current time in UTC. To check if UTC time is correct, run date -u on the nevisProxy host.

You can assign the pattern using Additional Settings to applications, or an entire Virtual Host.

Show Maintenance Page

Allows to easily enable / disable the maintenance with being forced to set a time window.

Start

Enter the start date and time of the maintenance window.

• format: yyyy-mm-dd HH:mm (24 hours)
• timezone: UTC (not your local time)
• example: 2020-05-20 15:00

End

Enter the end date and time of the maintenance window.

• format: yyyy-mm-dd HH:mm (24 hours)
• timezone: UTC (not your local time)
• example: 2020-05-20 15:00

Maintenance Page

The page must contain two meta-tags which define the maintenance interval and will be patched during generation.

Example:

<head>
  <meta name="maintenance-start" content="${maintenance-start-value}">
  <meta name="maintenance-end" content="${maintenance-end-value}">
</head>

If the date and time on the target host are within this interval, the maintenance page will be shown. See also the introduction help text above.

Status Code

The status code of the response with the maintenance page.

By default, the response is sent with status code 503 for Service Unavailable.

Base Path

Enter the base path under which the maintenance page will be hosted.

You usually don't have to change this configuration, unless the path clashes with any other hosted resources.

By default, /maintenance/ is used.

Update Interval

Enter the time interval between checks of the maintenance page.

• In normal mode, the system checks the maintenance page for updates when a request comes in, if the configured interval has passed since the last check.
• In maintenance mode, the system ignores the UpdateInterval and fetches the maintenance page on each request.

Microsoft Login Step

#Federation #Authentication #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

Set up social login, using Microsoft as OpenID Connect provider.

Client ID

ClientID is Application (client) ID provided by Microsoft when you create an Application Microsoft.

Client Secret

Client Secret is Client Secret provided by Microsoft when you create an Application Credentials & Secrets in Microsoft.

Return Path

The callback URI to go to after a successful login with Microsoft.

This will create an endpoint in your host config.

The URL will be a combination of the Frontend Address of the Virtual Host and the value configured here. For example, let's assume that you have configured:

• Return Path: /oidc/microsoft/
• Frontend Address: https://nevis.net

Then the URL will be https://nevis.net/oidc/microsoft/.

Use the exact: prefix to use the given path as-is. Without this prefix a normal mapping with /* will be generated and thus sub-paths will be accessible as well.

Scope(s)

Select the request scope(s) for getting user information from Microsoft. Default scopes is email.

Scope openid will be added automatically because Microsoft is implement based on OpenID protocol.

Scope offline_access for generate refresh token.

Virtual Host

Assign a Virtual Host which shall serve as entry point for the callback from social login provider.

In case your host has

• 1 address, that address will be used
• many addresses with
  • 1 https, and many http, the https will be used without warning
  • mix between http and https, the 1st https will be used with warning
  • single scheme (http or https only) the 1st address will be used with warning

E.g.

http://nevis.net
http://nevis-security.net
https://nevis.net
https://nevis-security.net

The https://nevis.net will be used as the host for Apple callback

On Success

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

In case you change this to your custom step(s), you can assign pattern Social Login Final Step as the last step of the Authentication process to redirect back to original URL.

On Failure

The step that will be executed if the authentication fails. If no step is configured here the process ends with AUTH_ERROR.

In case you change this to your custom step(s), you can assign pattern Social Login Final Failure Step as the last step of the Authentication process to redirect back to original URL.

nevisIDM

Choose which nevisIDM instance you want to store the user's information after logged in with social login provider.

Client External ID

The ExtId of the client in nevisIDM that will be used to store the user

On User Not Found

Configure the authentication flow to be executed when no user was found and the email provided by social account does not exist. The authentication flow must contain the Social Login Create User pattern if a new user shall be created.

Note: Please select scope email and profile for getting user's information from social account.

On User Found

Configure the Authentication Flow in case no user with Subject/ID from social account was found but email does exist in nevisIDM. The Authentication Flow must contain:

• Social Login Link User pattern to link an existing user in IDM with Subject/ID of social account.
• Social Login Done to end the social login flow after some other action(s).

Note: Please select scope email and profile for getting user's information from social account.

Application Type

The application type that you choose when you create your application in Microsoft. We are supporting 3 types

• common
• organizations
• consumers

Please follow this document to select your application type correctly

Tenant ID

Enter the Tenant ID of your Azure Active Directory.

This setting is used when Application Type is set to organizations.

Check Microsoft documentation on How to find your Azure Active Directory tenant ID.

Claims Request

The claims request parameter. This value is expected to be formatted in JSON and does not accept trailing spaces nor tabs.

User ID Field

Logged userId will automatically get from social account. But you can change the userId by using this field.

Additional Auth Request Parameters

Arbitrary additional request parameters used in the authentication request. The property supports variable substitution.

Example:

[paramName]=[paramValue]

Button Label

Enter a label for the social login button.

Translations for this label can be configured in the Authentication Realm pattern.

Mobile Deregistration Service

#Mobile Authentication #Authentication

Plugin: nevisadmin-plugin-nevisfido

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.

Mobile TAN (mTAN)

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Use to send a TAN code to the user using SMS, for example, for second factor authentication.

The pattern works out-of-the-box as On Success for nevisIDM Password Login, in case the mobile is stored on the user.

In case users may have multiple mobiles and the mobile is stored in a mobile credential, add the nevisIDM Second Factor Selection in front of this step.

To configure the message template sent to the user, translate the label mtan.message.template.

On Success

Configure the step to execute after successful authentication. If no step is configured here the process ends and the user will be authenticated.

On Failure

Assign the step to execute in case no mTAN can be sent or all attempts had been exhausted.

The step will be executed in the following cases:

• there is no session variable (user.mobile or sess:ch.nevis.idm.User.mobile) which contains the mobile number of the user
• the mobile number cannot be converted into a format supported by the Connection Provider
• all attempts had been exhausted and the user has failed to authenticate

If no step is assigned then the authentication flow will be terminated and an error GUI with label error_99 (System Problems) will be shown.

Buttons

Assign a Dispatcher Button to add a button which points to a different authentication step.

SMS Provider

The connection provider for the TAN transmission. Currently the only supported connection provider is a SwissPhone SMS Gateway.

Max Retries

The maximum attempts for each code.

When this threshold is reached, the behaviour depends on Max Regenerations.

As long as Max Regenerations is not exhausted, a new code will be generated and sent to the user.

Once Max Regenerations is reached as well, the On Failure exit will be taken.

Max Regenerations

The maximum number of times a new code can be generated.

If the value is 1 or greater, a resend button will be added to the screen. The button is shown only when there are still resends left.

When you configure 0 there will only be 1 code and thus there will be no resend button. Note that when Max Retries is reached, a new code will be generated and sent automatically.

TAN Format

The format of the TAN sent to the user. For instance, with 5 digits, the generated TAN will always consist of 5 numerical digits (e.g. 12345).

Testing Mode

Enables "Testing Mode". The TAN challenge is AAAAA.

When testing mode is enabled, the TAN challenge is constant and might not be sent over the linked connection.

Each connection pattern decides individually how it behaves with respect to "Testing Mode".

For instance, the SwissPhone Connection does not sent a message to the gateway when "Testing Mode" is enabled.

Authentication Level

Set an authentication level if authentication of this step is successful. The level is relevant only if there are is an Authorization Policy assigned to applications.

GUI Name

Change the name of the Gui element.

Change this only if you need the Gui name your login template to render the screen differently.

Gui Title

Change the Gui title.

We recommend to enter a label here and provide translations for this label in the Authentication Realm.

nevisAdapt Analyzer Configuration

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisadapt

Pattern to configure individual settings for the NevisAdapt analyzer.

The NevisAdapt analyzer is a powerful tool to detect and prevent fraud in your application during authentication.
It uses a combination of device, fingerprint, and geo/ip analysis to detect suspicious attempts.

Disabling analyzer submodules will reduce the accuracy of the fraud detection, resulting in lower risk scores. Disabling all modules will result in the default login flow being "On Untrained User".

We discourage disabling submodules unless you have a specific use case for it.

Device Analyzer

Device Analyzer is a global setting, disabling this means that the device analyzer will not be used to calculate risk scores. This will result in a lower risk score for all users.

If you wish to disable, consider disabling all other submodules as well.

Shared Device Analyzer

Used to disable the shared device analyzer. This means that the shared device analyzer will not be used to calculate risk scores.

Device Cookie Analyzer

Used to disable Device Cookie creation.

Fingerprint Analyzer

Fingerprint Analyzer is a global setting, disabling this means that the device analyzer will not be used to calculate risk scores. This will result in a lower risk score for all users.

If you wish to disable, consider disabling all other submodules as well.

Browser-Type Fingerprint Analyzer

Used to disable Browser Finger creation and analysis.

Device-Type Fingerprint Analyzer

Used to disable Device Finger creation and analysis.

Geo/IP Analyzer

Geo/IP Analyzer is a global setting, disabling this means that the device analyzer will not be used to calculate risk scores. This will result in a lower risk score for all users.

If you wish to disable, consider disabling all other submodules as well.

Suspicious Country Analyzer

Used to disable suspicious country analysis. Use with caution.

IP Analyzer

Used to disable IpAddress analysis. If you wish to disable filtering for private address, the configuration can be found at nevisAdapt Instance / IP Geolocation.

If you wish to disable this setting also consider disabling the IP Geolocation settings as well in the nevisAdapt Instance / IP Geolocation configuration and the nevisAdapt Instance / IP Reputation configuration.

Geo Analyzer

Used to disable GeoLocation analysis. If you wish to disable this setting also consider disabling the IP Geolocation settings as well in the nevisAdapt Instance / IP Geolocation configuration and the nevisAdapt Instance / IP Reputation configuration.

nevisAdapt Authentication Connector

#User Behavior Analytics #Connector #Experimental

Plugin: nevisadmin-plugin-nevisadapt

Using the pattern, you can integrate nevisAdapt as an authentication step in nevisAuth. Depending on the risk score, a different AuthState can follow this step.

nevisAdapt

Reference for the nevisAdapt service to calculate risk scores during authentication.

On Success

Set the step to continue with on successful authentication.

On Failure

Set the step to continue with in case of error. If nothing is set, the authentication fails.

On Timeout

Set the step to continue with in case the authentication attempt runs into a timeout.

Risk Profile configuration: Setting this step is optional, but the highest available from High and Medium step will replace it.

Risk Event configuration: Setting this step is mandatory.

On Untrained User

Set the step to continue with in case the user is untrained.

Risk Profile configuration: Setting this step is optional, but the highest available from High and Medium step will replace it.

Risk Event configuration: Setting this step is mandatory.

On Medium Risk

Will be considered only if Profile is set to either balanced, strict or custom.

Set the step to continue with if the calculated risk score exceeds the Medium threshold.

In case it remains unset:

1. On High Risk becomes mandatory
2. Applies the same next step as On Success

On High Risk

Will be considered only if Profile is set to either balanced, strict or custom.

Set the step to continue with if the calculated risk score exceeds the High threshold.

In case it remains unset:

1. On Medium Risk becomes mandatory
2. Applies the same next step as On Medium Risk

On Logout Done

Optional. Reference for the next step in the logout authentication flow. If missing, this is the last step and the result will be AUTH_DONE.

Key Store

The key store used by this pattern to establish a connection with the nevisAdapt component. For a client TLS connection, this key store should be trusted by the nevisAdapt Instance. If no pattern is assigned here automatic key management will provide the key store.

Trust Store

The trust store used by this pattern to establish a connection with the nevisAdapt component. This trust store must trust the nevisAdapt Instance's key store. Please reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin automatic key management.

Medium Risk Threshold

Will be considered only if Profile is set to either balanced, strict or custom.

Set the risk score threshold [0...1] for medium threat.

High Risk Threshold

Will be considered only if Profile is set to either balanced, strict or custom.

Set the risk score threshold [0...1] for high threat.

Profile

The profile used during processing the results of the analysis done by the nevisAdapt service.

There are 2 ways to react on the returned values:

• React on the returned events directly
• React based on the calculated weighted sum of the risk scores

Supported values are:

• balanced - balanced risk profile
• strict - strict risk profile with higher weights
• custom - to define own weights for the risk profile
• events - react on the returned events instead of the risk scores

You can find more information about the Risk profiles in the documentation.

Custom Risk Score Weight Configuration

Custom risk score weight configuration for the calculation. Set the weights to be considered for each risk score analyzer.

Analyzer list:

• Suspicious country
• Device cookie
• Fingerprint
• IP
• IP location
• IP velocity
• IP reputation

Suspicious Events Configuration

Will be considered only if Profile is set to events.

Select which events to react on. The events are identified and returned by the nevisAdapt service and the first event combination that they match successfully will determine the next step in the authentication flow. No further entries of this list will be considered.

One event combination entry consists of the following properties:

• Risk Events: set of suspicious event(s) to match against
• Minimum Match Count: minimum number of events to consider the matching valid (all by default). They have to be present in the service response to classify the entire combination as matching.
• Authentication Step: next authentication step if the matching is valid

Complete example with full ruleset:

Combination 1:

• Risk Events: [ 'ip-reputation-blacklisted', 'suspicious-country' ]
• Minimum Match Count: 1
• Authentication Step: Authentication Fails

This combination will match successfully if any of the two selected events are being reported by the nevisAdapt service. If this is the case, neither Combination 2 or 3 will be checked as the authentication fails immediately.

Combination 2:

• Risk Events: [ 'unknown-device', 'unknown-country', 'unknown-fingerprint' ]
• Minimum Match Count: 2
• Authentication Step: mTAN

This combination will match successfully if any 2 of the three selected events are being reported by the nevisAdapt service. If this is the case, Combination 3 will not be checked and the next authentication step will be mTAN.

Combination 3:

• Risk Events: [ 'unknown-country', 'high-ip-velocity' ]
• Minimum Match Count: all
• Authentication Step: email

This combination will match successfully only if both events were reported by the nevisAdapt service. If this is the case, a notification email will be sent to the user.

Otherwise, authentication succeeds without any further complication.

Cookie Domain

If unset, the cookie will not be scoped to subdomains. Set this value to a specific domain to include more than one hostname.

Example: The user wants to login through example.com

If no value is given, the cookie will be effective for requests with the following addresses:

• https://example.com/one/two/three...

If the value is actually set as example.com, the cookie will be effective for requests against subdomains as well:

• https://shopping.example.com/one...
• https://account.example.com/two...
• https://example.com/three...

FingerprintJS version

This configuration option gives the administrator the ability to ensure backwards compatibility in case so far V2 fingerprints have been in use.

• V2 - to ensure backward compatibility, FingerprintJS V2 will be used
• V3 - default option, uses FingerprintJS V3

Pass-through Mode

The passthrough mode disables the nevisAdapt validation. All analysers are still executed and results (risks/active sessions) are persisted.

When enabled, all risks follow the On Success step. High and Medium risk actions are ignored.

This mode is useful for data gathering and troubleshooting.

nevisAdapt Database

#Database #User Behavior Analytics

Plugin: nevisadmin-plugin-nevisadapt

Configures nevisAdapt to use a MariaDB database. Assign to nevisAdapt 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 deployments a database including tables must be set up before deployment.

Setup instructions can be found in the nevisAdapt technical documentation. See Database setup for details.

If you want to use an Oracle database you have to set Custom Connection URL, instead of using the high-level settings, and upload the JDBC Driver.

Database Type

Choose between MariaDB and Oracle 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.

Database User

Provide the DB user name here.

Database Password

Provide the DB password here.

TLS Encryption

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

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

Trust Store

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

JDBC Driver

Due to licensing, nevisAdapt cannot ship the JDBC driver to connect to Oracle databases, Therefore, those who want to use an Oracle database need to obtain and provide the Oracle JDBC driver on their own.

The .jar files can be downloaded from Oracle

Uploading any other .jar files containing JDBC drivers is possible as well.

Volume Claim

Due to licensing restrictions, we cannot ship any Oracle dependencies.

If you are using an Oracle database, are deploying to Kubernetes, and Database Management is enabled (complete or schema), then you have to provide a Kubernetes volume containing an Oracle driver and client.

For more information, see Preparing Oracle Volume.

Enter the name of that volume here.

The volume will be mounted in the nevisadapt-dbschema image to set up and patch the database schema.

The volume will be mounted in the nevisadapt image to connect to the database. Because of that, there is no need to upload a JDBC Driver.

Data Tablespace

Name of the data tablespace for the oracle database used for the Kubernetes migration. It's recommended to keep the default value unless the pattern is used with an existing database that has a different one.

Application Role

Name of the application role for the oracle database used for the Kubernetes migration. It's recommended to keep the default value unless the pattern is used with an existing database that has a different one.

Owner Role

Name of the owner role for the oracle database used for the Kubernetes migration. It's recommended to keep the default value unless the pattern is used with an existing database that has a different one.

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.

Flyway License Key

Please provide a licence key in case you would use the Flyway Teams Edition.

This is recommended only in case you would use an old database version (more than 5 years old). If you do not provide a licence key, the Flyway Community Edition will be used by default.

For more information about Flyway editions please visit this page Flyway.

Datasource Configuration Method

Select which method of generation should be applied when configuring the Hikari datasource for the database connection.

Possible options:

• recommended: the default option, this sets up three explicit values:
  • Maximum session lifetime: 300s
  • Session idle timeout: 100s
  • Maximum pool size: 50
• custom: specify values in the next text area, separate keys and values with =.
  • The valid keys can be found at HikariCP - GitHub.
• unmodified: this configuration doesn't generate anything, leaving all default configurations coming from the library in effect.

Datasource Configuration Values

Specify custom values for Hikari datasource configuration. Separate keys and values with =. The valid keys can be found at HikariCP - GitHub.

Example to set the same as if selecting recommended:

maxLifetime=300000
idleTimeout=100000
maximumPoolSize=50

Connection Parameters

Enter parameters for the DB connection string.

Enter 1 parameter per line.

Lines will be joined with &.

The default is:

useMysqlMetadata=true

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

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

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.

nevisAdapt Event

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisadapt

Configure how to react on nevisAdapt events.

Risk Events

Select at least one event for the combination to react on:

• unknown-device : this is the first time for this device cookie
• unknown-country : this is the first time for this geolocation (country)
• unknown-fingerprint : this is the first time for this browser fingerprint
• suspicious-country : the login request came from a prohibited country
• high-ip-velocity : the current geolocation is physically too far to be reachable since the last login
• ip-reputation-blacklisted : the login request came from an IP address with low reputation

For technical details check Event-based configuration.

Minimum Match Count

Specify the minimum number of matching risk events to continue with Authentication Step. Picking a number that exceeds the size of selected Risk Events will set all during generation.

Authentication Step

Select which authentication step to continue with in case at least Minimum Match Count out of the selection provided in Risk Events are present in the report coming from the nevisAdapt service.

nevisAdapt Feedback Configuration

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisadapt

Pattern to configure details for the feedback feature.

nevisAuth Instance

Add nevisAuth Instance reference pattern(s) to enable session termination in connected components. If the session store is shared, it is enough to add one instance per database.

Please make sure that all involved nevisAuth Instances have ManagementService enabled. Add or extend a Generic nevisAuth REST Service for each with the following configuration:

<RESTService name="ManagementService" class="ch.nevis.esauth.rest.service.session.ManagementService" />

nevisProxy Instance

Reference for the nevisProxy instance to set up frontend addresses.

Feedback Token Encryption Key

Enter a 256-bit encryption key represented in Base64.

To generate a new random key, you may run the following console command:

openssl rand -base64 32

Regular expression for valid values: [a-zA-Z0-9+/]{43}=

Example: fq7J7E1xVFNHcEJ2MSQojLibKOQOMIlp2qXVqvv5y9w=

Feedback Token Behavior

The authentication step is able to generate a short-term feedback token if there are suspicious circumstances around the authentication attempt.

The registered user receives a URL in a notification email (in a notification step if configured), following that link within the token's lifetime would perform the configured task:

• disabled - no token will be generated
• session - following the link distrusts the suspicious session (even retroactively)
• device - following the link distrusts the suspicious session and all other sessions associated with the same device
• all - following the link removes all sessions and observations for the user

All options apart from disabled require access to SessionManagement API in all involved nevisAuth Instance.

In case of all, please set Enable Indexing value to on for all involved nevisAuth Instance.

Feedback Token Lifetime

Set the maximum lifetime for the feedback token.

Feedback Redirect URL

Provide a URL to redirect to after sending a report by pressing the feedback link in the notification. This can either be a base homepage or a more security-oriented one (for example page for password reset).

If it remains unset, a basic informative text is displayed about the report instead of a redirect.

nevisAdapt Instance

#User Behavior Analytics #Instances #Experimental

Plugin: nevisadmin-plugin-nevisadapt

This pattern sets up a nevisAdapt instance.

For details check the nevisAdapt Documentation.

nevisAdapt implements adaptive, context-aware, and continuous authentication based on multiple attributes, like device information or geolocation. Together, these multiple attributes create a unique, digital user footprint.

In case of multi-host deployment, up to one nevisAdapt is supported per isolating line.

TCP Service Port

Enter the port on which nevisAdapt will listen.

Database

Add a database connection reference pattern.

Required properties to be set in the connector pattern are as follows:

• JDBC Driver (Oracle or MariaDB)
• JDBC URL
• DB user/password

Log Settings

Assign nevisAdapt Log Settings to change the log configuration.

Frontend Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Frontend Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

SecToken Signer Trust Store

Assign the Trust Store provider for verifying the NEVIS SecToken. If no pattern is assigned the signer key will be provided by the nevisAdmin 4 PKI.

Client Authentication

Setting for 2-way TLS on the nevisAdapt HTTPs endpoint. There are 3 options will affect the callers (e.g. nevisProxy or technical clients accessing nevisAdapt REST APIs)

• required: Callers must present a client certificate.
• requested: Callers can present a client certificate.
• disabled: Callers must not use a client certificate.

The Frontend Trust Store must contain the issuing CA.

File Selection

Set a file code only if the provider is IP2LOCATION or MaxMind and also set the access token in that case.

Provide a file code that identifies the database file to be downloaded.

The supported values are:

• upload - no update mechanism will be in place for custom uploads by default. Must be .csv/.CSV, up to 20MB.
• DB1BIN - commercial version, IP-Country
• DB1BINLITE - free version, IP-Country
• DB5BIN - commercial version, IP-Country-City-GPS
• DB5BINLITE - free version, IP-Country-City-GPS
• Geo2-City - MaxMind GeoIP2 City Database
• GeoLite2-City - free version of the MaxMind GeoIP2 City Database

nevisAdapt doesn't provide any access token by default. They have to be generated after registration (in case of the commercial version, purchase).

You can find more information about the supported geolocation databases at the IP2LOCATION and MaxMind websites.

Mapping File Upload

Provide a file attachment for the IP-to-Location service to use.

Please consider uploading the file manually if its size exceeds 20MB, then adjust the path ipToLocationMappingFile in nevisadapt.properties after deployment if needed.

With file upload, only the IP-Country database is supported, with fields listed as follows (CC is the 2-letter country code, no header row):

"IP range min (decimal)","IP range max (decimal)","CC","COUNTRY"

The file must adhere to the following formatting rules: all fields must be separated by commas and surrounded by double-quotes. The IP ranges should not intersect each other. File name must end with either .csv or .CSV.

If IP velocity analysis is required, it is handled through IP2LOCATION updates. No other provider is supported at this point. Please switch to either DB5BIN or DB5LITEBIN.

The IP-mapping file has to be updated regularly for the service to stay relevant.

Uploaded files are not updated by default.

We recommend setting up periodic update of IP geolocation and reputation mappings.

Update Schedule

Pick the update frequency of the IP-to-location database.

Valid values:

• disabled - no update mechanism will be triggered. Not recommended for productive environment.
• hourly
• daily
• weekly
• monthly

When selecting disabled, it's highly recommended having a mechanism in place for keeping the database file up-to-date. We recommend setting up periodic update of IP geolocation and reputation mappings.

Download Token

Provide a secret download token for authentication.

Shared Storage Settings

Configure this to override the default configurations used for the shared storage in Kubernetes deployments. If you would use an existing shared volume please only set the claim name. This storage should support the ReadWriteMany access mode.

For more information regarding persistent volumes in Kubernetes please visit this page

IP Private Network Filter

If your network you are connecting from only contains private network addresses nevisAdapt will filter these addresses out thus not assigning riskscore to GeoIP data from these addresses.

If you wish to disable this feature, you can do so by setting the following.

nevisAdapt.database.ipPrivateNetworkFilter.enabled=false

The default value is true.

IP Private Network Country Code

When selected 'disabled' on IP Private Network Filter, the country code of the IP address is not in the list of private network country codes.

You can also assign a default Geolocation by country code by ISO 3166 alpha-2.

Apache Hostname Verifier

Enabling this option will set an Apache hostname verifier (which also handles certificate checks) instead of the default one.

Default: disabled (backwards compatibility)

Mapping File Upload

Provide a file attachment for the IP reputation service to use.

Please consider uploading the file manually if its size exceeds 20MB, then adjust the path ipReputationMappingFile in nevisadapt.properties after deployment if needed.

Every line should contain a single blacklisted IPv4 range in CIDR format:

A.B.C.D/E or A.B.C.D (A/B/C/D: [0-255]; E: [0-32])

The IP ranges should not intersect each other.

The IP-mapping file has to be updated regularly for the service to stay relevant. We recommend setting up periodic update of IP geolocation and reputation mappings.

Update Schedule

Pick the update frequency of the IP reputation database.

Valid values:

• disabled - no update mechanism will be triggered. Not recommended for productive environment.
• hourly
• daily
• weekly
• monthly

When selecting 'disabled', it's highly recommended having a custom mechanism in place for keeping the database file up-to-date. We recommend setting up periodic update of IP geolocation and reputation mappings.

Update URL

Provide a download URL for the database file. The file is downloaded then moved over to the path defined above.

Apache Hostname Verifier

Enabling this option will set an Apache hostname verifier (which also handles certificate checks) instead of the default one.

Default: disabled (backwards compatibility)

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.

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.

nevisAdapt Observation Configuration

Used to assign a nevisAdapt Observation Cleanup Configuration pattern to configure the time interval for cleaning up observation data.

This is an optional setting. Default values if nothing is set:

• Observation Timeframe: 60d
• Trusted Cleanup Period: 1d
• Untrusted Cleanup Timeframe: 12d

Suspicious Country Code List

Provide a list of two-letter ISO country codes of considerable risk.

Input method 1: Single line - comma-delimited

Input method 2: One country code entry per line

ISO code description can be found at: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

Forward proxy host

Enter the host for the forward proxy if available.

Forward proxy port

Enter the port of the forward proxy if available.

3182

Distrust Feedback Settings

Provide additional settings for defining the details of the distrust session mechanism:

• JWE key to generate new tokens with
• nevisAuth reference to distrust and terminate sessions there as well
• nevisProxy reference to build the distrust feedback URI
• action to take on received token
• token lifetime
• redirect URL after sending the token

Bind Host

Enter a custom host name to listen on.

This setting is relevant in classic VM deployment, when working with multi-homed target hosts.

In Kubernetes the component listens on 0.0.0.0 and thus this setting is discouraged.

Device Cookie Name

Provide a name for the cookie that will be used as the volatile identification for a browser.

Leave this configuration empty if you want to keep the default value of DEVICE_COOKIE.

Additional Settings

Assign an add-on pattern to customize the configuration.

nevisAdapt Analyzer Configuration

Allows you to customize nevisAdapt Analyzer configuration.

nevisAdapt Log Settings

#User Behavior Analytics #Logging

Plugin: nevisadmin-plugin-nevisadapt

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

See nevisAdapt Reference Guide, chapter Logging Configuration for details.

Comprehensive logging guide is found here.

Hint: If you only change log levels nevisAdmin 4 does not restart the component in classic VM deployment. The new log configuration will be reloaded within 60 seconds after deployment.

The default configuration is:

AdaptModules-Generic = INFO
ch.nevis.nevisadapt.util.logging.OpTracer = DEBUG

Examples:

org.springframework.web.filter.CommonsRequestLoggingFilter=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

Logback 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

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

nevisAdapt Observation Cleanup Configuration

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisadapt

Allows customization of the observation cleanup interval.

Observation Timeframe

This value defines the observation lookup period, the cleanup of trusted observations cannot happen sooner than this.

The default value is 60d.

Trusted Cleanup Period

This value indicates the buffer time beyond the base observation timeframe for removing trusted observations.

The default value is 1d.

Untrusted Cleanup Timeframe

nevisAdapt stores session data that was not marked as trusted (e.g.: failed 2FA authentication) for a certain amount of time. This is done to allow staff to investigate the issue and to provide the user with a better experience. However, storing untrusted session data for too long can lead to privacy issues. This pattern describes how to configure the cleanup of untrusted session data.

The default value is 12d.

nevisAdapt REST API

#User Behavior Analytics #Applications #Experimental

Plugin: nevisadmin-plugin-nevisadapt

The pattern exposes the nevisAdapt REST API on a nevisProxy Virtual Host.

The nevisAdapt REST API is available via /nevisadapt/api.

nevisAdapt Instance

Reference to the nevisAdapt Instance pattern.

Trust Store

Assign the trust store for outbound TLS connections.

If no pattern is assigned a trust store will be provided by nevisAdmin 4 automatic key management.

Hostname Validation

Enable to verify that the hostname on the certificate presented by the backend matches the hostname of nevisAdapt Instance

Virtual Host

Assign a Virtual Host which shall serve as entry point.

Authentication Realm

Mandatory setting to enforce authentication.

Application Access Token

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

Please assign a NEVIS SecToken. This is mandatory to have access to the Administration UI.

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.

CSRF Protection

Cross-Site Request Forgery (CSRF) is an attack to force an authenticated user to send unwanted requests.

• off (default) - no CSRF protection. Recommended for applications which may be called from other sites.
• header-based - GET and HEAD requests are allowed (assumption: these methods must not manipulate server-side state). For other requests the Referer and Origin headers must match the Host header.

nevisAdapt Remember Me Step

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisadapt

Using the pattern, you can integrate nevisAdapt as a remember-me service in nevisAuth.

If the provided token is found and still valid, the authentication process is cut shorter.

If no remember-me token is provided or it's no longer valid, the step generates a new one then initiates the original full authentication process. If all the authentication steps complete successfully, nevisAdapt persists the new token so that it can be used for quick entry later. Keep On Success empty in order to shortcut the authentication flow.

CAUTION: if On Success and Original Authentication Flow are set to the same step, it disables the remember-me functionality.

nevisAdapt

Reference for the nevisAdapt service to check for the presence of the provided remember-me token.

On Success

Decides what to do if the remember-me token is present and valid. Leave empty for skipping to the end of the authentication flow immediately.

CAUTION: It will disable the remember-me functionality if you set it to the same step as the Original Authentication Flow.

Original Authentication Flow

Set the first step of the full authentication flow to continue with in case no valid remember-me cookie was found:

• the remember-me cookie is not present in the headers
• the remember-me cookie is present but no longer valid
• the associated user is no longer active
• the browser fingerprint has changed

CAUTION: It will disable the remember-me functionality if you set it to the same step as the On Success.

Key Store

The key store used by this pattern to establish a connection with the nevisAdapt component. For a client TLS connection, this key store should be trusted by the nevisAdapt Instance. If no pattern is assigned here automatic key management will provide the key store.

Trust Store

The trust store used by this pattern to establish a connection with the nevisAdapt component. This trust store must trust the nevisAdapt Instance's key store. Please reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin automatic key management.

FingerprintJS version

This configuration option gives the administrator the ability to ensure backwards compatibility in case so far V2 fingerprints have been in use.

• V2 - to ensure backward compatibility, FingerprintJS V2 will be used
• V3 - default option, uses FingerprintJS V3

nevisAdapt Risk Plugin

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisdetect

The pattern configures nevisAdapt risk scores to be propagated to the nevisDetect backend for further processing.

For more information, see Risk score mapping for nevisAdapt.

nevisAdapt

Pattern reference for the nevisAdapt Instance to connect to.

Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

Propagate NevisAdaptDeviceFingerprint Risk Scores

Risk scores to be delivered to the client in the request headers. This option configures enables device fingerprint risk score to be propagated.

Propagate NevisAdaptDeviceRecognition Risk Scores

Risk scores to be delivered to the client in the request headers. This option configures enables device cookie risk score to be propagated.

Propagate NevisAdaptGeolocation Risk Scores

Risk scores to be delivered to the client in the request headers. This option configures enables geolocation risk score to be propagated.

Custom Properties

Set the value for the following optional parameters if the default ones do not match the requirements:

• cacheDisabled = (default 'false')
• ignoreHttpRequest = (default 'false')
• ignoreTlsObservation = (default 'true')

nevisAuth Audit Channel

#Authentication

Plugin: nevisadmin-plugin-nevisauth

nevisAuth raises events for audit purposes and allows to set up audit channels to handle these events.

Audit channels are Java classed which implement the AuditChannel interface.

Use this pattern to add a custom audit channel to your nevisAuth Instance.

Assign this pattern in your the nevisAuth Log Settings pattern under Audit Channels.

For convenience, the default NevisAuthChannel can be enabled in the nevisAuth Log Settings pattern.

Class

Enter the fully qualified name of your Java class. The class must implement the AuditChannel interface.

The class must be on the classpath of the AuthEngine. You can upload your JAR file in the Classloading tab of the nevisAuth Instance under Custom Dependencies.

Properties

Provide configuration for the audit channel.

For each key-value pair 1 property element will be generated.

nevisAuth Connector

#Authentication #Connector

Plugin: nevisadmin-plugin-nevisauth

Use to connect to an existing nevisAuth instance.

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

Connection URL(s)

Enter hostname:port of the nevisAuth instance.

Languages

Enter the language codes which are enabled in nevisAuth.

This property is considered only if nevisLogrend is generated by nevisAdmin to ensure that nevisLogrend provides support for the same languages.

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.

nevisAuth Database

#Database #Authentication

Plugin: nevisadmin-plugin-nevisauth

Configures nevisAuth to use a MariaDB database for storing sessions and out-of-context data. Assign to a nevisAuth 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 deployments a database including tables for sessions and out-of-context data must be set up manually before deployment. Setup instructions can be found in the nevisAuth technical documentation.

The log category for the session store is RemoteSessionStore.

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.

If not set, the database connection user will be used.

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

Password Type

Choose between:

• automatic: behaves like command when the password starts with /opt/.
• command: use when the input is a command. In esauth4.xml the prefix pipe:// will be added.
• plain: take the password as-is.

TLS Encryption

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

• disabled: Do not use SSL/TLS (default)
• trust: Use SSL/TLS for encrypted transfer. 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 certificate 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.

Synchronize Sessions

Defines when sessions are stored to the remote session store.

• after-successful-authentication

A session is stored to the remote session store once authentication has been completed successfully.

Use this mode when performance is critical, when the authentication flow is stateless (e.g. no GUI is shown), when there is only 1 nevisAuth instance, or in classic VM-based deployment scenarios.

• always

Session are always stored to the remote session store.

This mode requires nevisAuth version 4.28.0.216 or newer.

We recommend this mode when you want to restart nevisAuth without user impact and for deployments to Kubernetes.

Typically, while a user is logging in, multiple requests are sent to nevisAuth.

If you configure multiple replicas of nevisAuth, the Kubernetes service may forward these requests to any of the replicas. By selecting always, you ensure that all replicas can access the user's session during the authentication process.

• recommended (default)

Uses always when deploying to Kubernetes and after-successful-authentication for classic, VM-based deployments.

Custom Attributes

Add or overwrite attributes of the RemoteSessionStore and RemoteOutOfContextDataStore XML elements.

Supported attributes are described in the Nevis documentation:

• RemoteSessionStore
• RemoteOutOfContextDataStore

If you want to set an attribute only on one of the 2 elements use the prefix session: or oocd: as illustrated below.

Examples:

Attribute	Value
syncPullInitial	true
session:reaperThreads	5
session:storeUnauthenticatedSessions	false
oocd:reaperPeriod	120

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.

nevisAuth Instance

#Authentication #Instances

Plugin: nevisadmin-plugin-nevisauth

Represents a nevisAuth instance. The instance is named according to the pattern.

Hint for pattern renaming

When the 'Instance Name' property is not filled, the pattern uses the pattern's name as instance directory at the target host.

To rename the pattern, do the following:

1. Rename the pattern in the GUI.
2. Rename the instance directory and associated systemd files on the deployment hosts.
3. Deploy.

In case step 2 is omitted the old instance is shut down during deployment.

For more information, see technical documentation: User Guide / Configuration Projects / Working with Patterns.

Port

Port the nevisAuth instance is listening on.

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

Add logging configuration for nevisAuth.

Database

By default, nevisAuth stores sessions and out of context data in memory.

In most setups you should use a database instead, and you should assign a nevisAuth Database pattern here.

In memory should be used only when there is only 1 line / pod of nevisAuth, or in a classic deployment where nevisProxy can ensure session-sticky load balancing towards nevisAuth.

Languages

Configure the language codes that shall be supported.

Each language code must be entered on a new line. By default, translations are provided for the following codes:

• en: English
• de: German
• fr: French
• it: Italian

nevisAuth uses the Accept-Language header sent by the browser to determine the user language. In case this header is not available the first configured language code will be used as a default.

Frontend Key Store

Assign the Key Store provider for the HTTPs endpoint. If no pattern is assigned a Key Store will be provided by the nevisAdmin 4 PKI.

Frontend Trust Store

Assign the Trust Store provider for the HTTPs endpoint. If no pattern is assigned the Trust Store will be provided by the nevisAdmin 4 PKI.

Client Authentication

Enable to enforce 2-way TLS on the nevisAuth HTTPs endpoint.

This means that callers (e.g. nevisProxy or technical clients accessing nevisAuth REST APIs) must present a client certificate.

The Frontend Trust Store must contain the issuing CA.

Default Backend Key Store

Assign the Key Store provider for outbound TLS connections. If no pattern is assigned a key store will be provided by the nevisAdmin 4 PKI.

Default Backend Trust Store

Assign the Trust Store provider for outbound TLS connections. If no pattern is assigned a trust store will be provided by nevisAdmin 4 automatic key management.

Internal SecToken Signer Key Store

Assign a key store for signing the internal NEVIS SecToken.

This token is returned to nevisProxy and validated there. It should not be added to calls to applications. If your applications need a NEVIS SecToken, assign a NEVIS SecToken pattern to your applications.

If no pattern is assigned, the signer key material will be provided by automatic key management.

Internal SecToken Signer Trust Store

Assign a trust store to validate the signature of the internal NEVIS SecToken.

This is an advanced setting and it is usually not required to configure this.

If no pattern, an Automatic Key Store pattern, or a PEM Key Store, is assigned to Internal SecToken Signer Key Store, then you do not have to configure this. The configuration of nevisAuth will be generated correctly, based on the deployment type and scaling.

Configuration is required in classic VM deployment, when this instance is deployed to multiple hosts, and the hosts have different key material in the Internal SecToken Signer Key Store.

Session Limit

Defines the maximum number of user sessions than may be created in this nevisAuth instance.

A nevisAuth session requires at least 10kb but the session can be much bigger when a user has many roles or multiple tokens are used.

Worker Threads

Number of threads to process incoming requests.

Custom Dependencies

In case AuthStates uses custom AuthState classes upload the required JAR file(s) here. Files will be deployed into the plugin directory of the nevisAuth instance.

Classpath Prefix

Enter directory paths to be added to the classPath of the AuthEngine.

The paths will be added as a prefix. Entries added by other patterns (e.g. /opt/nevisidmcl/nevisauth/lib or /opt/nevisauth/plugin) are preserved.

This is an advanced setting which should only be used when working with custom AuthState classes.

Startup Delay

Time to wait before checking Kubernetes readiness on startup.

You may have to increase this value if start of the nevisAuth service fails because of a failing readiness check.

Sets initialDelaySeconds of the Kubernetes startup probe.

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.

Line Preference

This setting (together with the inventory) defines the order of nevisAuth endpoints in the connection string from nevisProxy.

nevisAuth stores unauthenticated sessions in memory. In a classic deployment to VMs, even when a nevisAuth MariaDB Remote Session Store is configured, sessions are synced to the DB only after successful authentication. Thus, multi-step login flows require that requests for the same session are routed to the same nevisAuth endpoint.

nevisProxy uses a simple fail-over strategy. The first URL in the connection string for nevisAuth is always used, unless this instance is not available. This strategy works well when:

• there is only 1 nevisProxy instance
• there are 2 lines of nevisProxy but line 1 is active and line 2 is standby
• there is a session-sticky load-balancer in front of nevisProxy is session-sticky

The order of the connection string depends on the inventory. See also: Defining Lines and Fail-over Association

This strategy may fail in active / active setups when line groups are defined in the inventory. In such setups you can set this drop-down to disabled to ensure that the order in the connection string is the same on all nevisProxy lines.

Start Timeout

Enter a timeout to wait for nevisAuth startup.

Set a higher value if nevisAuth takes longer to start.

This setting applies to classic VM-based deployment 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.

Connection Host:Port

Enter the host:port pair(s) which nevisProxy should use to connect to this nevisAuth instance.

This setting is required when the primary names of the nevisAuth hosts are not accessible by nevisProxy, which is sometimes the case in classic VM deployment, when working with multi-homed target hosts.

The server certificate provided by the Frontend Key Store must be valid for all provided hosts names.

Bind Host:Port

Enter a custom host name to listen on.

This setting is relevant in classic VM deployment, when working with multi-homed target hosts.

In Kubernetes nevisAuth listens on 0.0.0.0 and thus this setting is discouraged.

Propagate Session

Define the value of the AuthEngine attribute propagateSession.

• enabled: true is set which makes nevisAuth return the user's session to nevisProxy on AUTH_DONE.
• disabled: false is set - nevisAuth does not return the session.

It is generally recommended to disable this feature and thus we plan to change the default to disabled in a future release.

Session Index

Enables session indexing.

WARNING: Other patterns, such as nevisAdapt Instance may overrule this configuration.

This is required by ThrottleSessionsState.

Set Session Index Attribute if you need to index a non-default attribute.

Session Index Attribute

Enter the name of a session variable for the session index.

Differing Resource Startover

Define the value of the AuthEngine attribute differingResourceStartover.

• enabled: true is set.
• disabled: false is set.

Do not change this unless you know what you are doing.

ID Pregenerate

Define the value of the idPregenerate attribute.

• enabled: true is set.
• disabled: false is set.

Do not change this unless you know what you are doing.

Server Configuration

Set Server Configuration properties (nevisauth.yml).

Examples:

server.max-http-header-size: 16384

Custom Resources

Upload additional resources required by your configuration.

Uploaded files will be deployed into the conf folder of the nevisAuth instance.

Shared Groovy Scripts

Upload shared Groovy scripts used in your authentication steps.

You can use the expression ${var.<name>} inside your scripts to refer to an inventory variable.

How the value of a variable is generated into the script depends on the variable content:

Scalar variables will be generated as-is. This means the variable expression has to be within a Java String (') or a Groovy GString (").

YAML variables of type sequence will be generated as a Groovy list.

For instance, let's assume you have the following variable in your inventory:

my-sequence-var:
  - some-entry
  - another-entry

In your script you may use the expression as follows:

def myList = ${var.my-sequence-var}

The following will be generated:

def myList = ["some-entry", "another-entry"]

Inventory variables containing a YAML mapping are not supported yet.

Uploaded files will be deployed to the conf/groovy folder of the nevisAuth instance.

Additional Settings

Assign an add-on pattern to customize the configuration of nevisAuth.

nevisAuth KeyObject

#Authentication #Key Management

Plugin: nevisadmin-plugin-nevisauth

Generates a KeyObject element for nevisAuth.

A KeyObject element can be used as key store or trust store.

These elements are used in various cases and are typically referenced by an AuthState.

The structure of KeyObject elements is explained in the Certificate validation section of the technical documentation of nevisAuth.

Assign this pattern to a Generic Authentication Step to add the KeyObject to your nevisAuth configuration.

The sanitized name of the Generic Authentication Step is used as name of the KeyStore parent element.

KeyObject ID

Set the attribute id of the KeyObject element.

The id must be unique within the nevisAuth instance. If not set the sanitized name of this pattern will be used.

KeyStore Name

Define the name of the parent KeyStore element.

You can enter the name of a KeyStore element generated by another pattern, or enter a new name.

If not configured, the name of the KeyStore depends on where this nevisAuth KeyObject pattern is assigned:

• Generic Authentication Realm: sanitized name of the realm pattern.
• Generic Authentication Step: sanitized name of the step pattern.
• nevisAuth Instance: the name AddonKeyStore.

Note that the nevisAuth configuration always contains a KeyStore element with name DefaultKeyStore. This KeyStore is typically used as a container for signer key material.

Type

Select key store when a private key is needed. Select trust store for providing trusted certificate (e.g. for signature validation).

Key Store

Reference a key store provider pattern or leave empty to let nevisAdmin establish a key store. This reference property is considered when type key store is selected.

Trust Store

Reference a trust store provider pattern or leave empty to let nevisAdmin establish a trust store. This reference property is considered when type trust store is selected.

Revocation

Define the revocation attribute of the KeyObject.

You can enter a path or URL of the certificate revocation list or the URL to the OCSP service.

See Generic key material configuration attributes for examples.

Custom Properties

Add property child elements to the KeyObject element.

nevisAuth Log Settings

#Authentication #Logging

Plugin: nevisadmin-plugin-nevisauth

Configure log levels and retention of nevisAuth logs.

Assign to a nevisAuth Instance via Log Settings.

In classic VM deployment nevisAdmin 4 does not restart the nevisAuth instance when only log configuration is changed. New log configuration is reloaded within 60 seconds after deployment.

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

Set log levels.

The default is:

Category	Level
EsAuthStart	INFO
org.apache.catalina.loader.WebappClassLoader	FATAL
org.apache.catalina.startup.HostConfig	ERROR

The default gives you log messages during startup but is rather silent during runtime.

A good setting for troubleshooting is:

Category	Level
AuthEngine	INFO
Vars	INFO

When using nevisAuth Database with MariaDB the category org.mariadb.jdbc can be set. The levels behave as follows:

• ERROR: log connection errors
• WARNING: log query errors
• DEBUG: log queries
• TRACE: log all exchanges with server

Check the documentation for other important trace groups.

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

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.

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.

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.

Hidden Variables

Enter variables that should be hidden in logs.

The special option auto hides the following variables:

• variables used for GUI elements of type pw-text
• dyncert.key
• connection.HttpHeader.Authorization
• client_secret

The wildcard * may be appended (but not prepended). This way, every variable that starts with a certain string will be hidden from the log. For instance, passw* will hide password and passwd.

Regex Filter

If set, messages for esauth4sv.log which match the given regular expression won't be logged.

The regular expression must match the entire line. For instance, you may use the following format to match some text:

.*some text.*

Audit Log

Configure audit logging of nevisAuth.

Select enabled to use the default audit channel implementation provided by the NevisAuditChannel class.

If you want to use your own channel, you have to assign Audit Channels and select one of the following options here:

• enabled: use you own channel in addition to the NevisAuditChannel.
• custom: use only own channel.

Log Format

Log4j 2 log format for the AUDIT logs.

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

Syslog Format

Log4j 2 log format for the AUDIT SYS logs.

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

Audit Channels

Assign nevisAuth Audit Channel patterns to use your own channel implementations.

Event Log

Enable event logging capability of nevisAuth.

Log Format

Log4j 2 log format for the EVENTS logs.

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

Syslog Format

Log4j 2 log format for the EVENTS SYS logs.

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

Custom Log Fields

Set to add additional fields to the nevisAuth events log.

Enter field names (with optional format JSON) to nevisAuth expressions.

Examples:

Field	Expression
unitDisplayName	${sess:ch.nevis.idm.User.unit.displayName}
unitHierarchy:JSON	${StringUtils.strip(sess['ch.nevis.idm.User.unit.hname'].replace('/',','),',')}

Based on this CustomField elements with name, value, and optional attribute format, are created in esauth4.xml.

Log Targets

Select the type of log4j appender.

This property is relevant for classic VM deployments only.

In Kubernetes the main logs are written to system out so that log messages appear in the docker logs.

Choose between:

• default - log to a file
• default + syslog - log to a file 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.

nevisAuth Radius Facade

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

The pattern sets up a Radius facade which acts as entry point for an Authentication Realm.

See the following chapters in the nevisAuth technical documentation to understand how the Radius facade works:

• Radius facade
• Configuring the RADIUS facade

There are some limitations:

• The Radius UDP ports are not configurable.
• The pattern does not validate whether you have defined an appropriate response for each step in your authentication flow. You have to configure Custom Radius Responses if your flow requires user interaction apart from simple username and password authentication.

For testing the Radius facade on a Linux server, use Radtest.

Authentication Realm

Assign a nevisAuth Realm which shall be exposed via Radius.

Radius Secret

Enter a secret to be used for this facade and all Radius clients.

Request Attribute Mappings

Define how attributes from Radius requests are mapped to input arguments (inargs) for nevisAuth.

There are some well-known input arguments which you may have to provide:

• isiwebuserid - entered user name
• isiwebpasswd - entered password
• mtanresponse - used in mobile TAN patterns

Examples:

Radius Attribute	Input
User-Name	isiwebuserid
User-Password	isiwebpasswd, mtanresponse
State	sessionid

Depending on your authentication flow it may be required to provide additional input arguments.

Additional Radius Responses

Configure additional Radius responses depending on your authentication flow.

For instance, configure Access-Challenge responses if your authentication flow is interactive.

Response rules configured here are evaluated first. You can therefore overrule the default rules added by this pattern.

No configuration may be required for basic username / password login as username and password can be sent by the Radius client in the initial Access-Request message.

nevisAuth Radius Response

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

Use in nevisAuth Radius Facade to declare Additional Radius Responses.

The nevisAuth Radius Facade pattern adds basic response rules for nevisAuth AUTH_DONE and AUTH_ERROR responses out-of-the-box.

However, explicit configuration is required if your Radius clients require additional attributes to be returned, or your authentication flow consists of steps which require user interaction.

Radius Response Type

The Radius message type.

For instance, use Access-Challenge to prompt the user for input.

Condition

An expression which defines when this response is generated.

For instance, use ${response:status:0} to return this Radius response for all AUTH_CONTINUE responses. Likewise, you can use 1 for AUTH_DONE and 2 for AUTH_ERROR responses.

In complex authentication flows consisting of multiple steps it can be tricky to find a good expression which matches for one step only. Please contact your integration partner if you need support.

Radius Attributes

Adds additional attributes to this Radius response.

Which attributes are required depends on the Radius Response Type.

For instance, in an Access-Challenge it is often required to add a Reply-Message which can be shown to the user. Also a State must be added some that the authentication can continue.

You may use expressions for the attribute value. For instance, use a ${litdict: expression to return a translated text.

Examples:

Prompt: No-Echo
Reply-Message: ${litdict:mtan.prompt}
State: ${sess:Id}

nevisDataPorter Instance

#Instances

Plugin: nevisadmin-plugin-nevisdp

The pattern represents a nevisDataPorter instance. The instance is named according to the pattern.

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.

Configuration

The dataporter.xml must be uploaded here.

Click Download Configuration Template to get started.

Log Settings

Add logging configuration for nevisDataPorter.

Key Store

Assign a key store which shall be used for outbound (2-way) TLS connections to nevisIDM. If no pattern is assigned no key store will be generated.

For nevisDataPorter to use the key store, the following expressions should be used inside the dataporter.xml file:

${idm.keystore}
${idm.keystore.password}

Example configuration:

<object type="NevisIDMConnectionPool" name="adminService">
    <dp:paraVal name="endpoint" value="${cfg.idmEndpoint}"/>
    <dp:paraVal name="loginMode" value="proxyCert"/>
    <dp:paraMap name="sslSettings">
        <value name="javax.net.ssl.keyStore" value="${idm.keystore}"/>
        <value name="javax.net.ssl.keyStorePassword" value="${idm.keystore.password}"/>
        ...
    </dp:paraMap>
</object>

Trust Store

Assign a trust store which shall be used for outbound TLS connections to nevisIDM. If no pattern is assigned no trust store will be generated.

For nevisDataPorter to use the trust store, the following expressions should be used inside the dataporter.xml file:

${idm.truststore}
${idm.truststore.password}

Example configuration:

<object type="NevisIDMConnectionPool" name="adminService">
    <dp:paraVal name="endpoint" value="${cfg.idmEndpoint}"/>
    <dp:paraVal name="loginMode" value="proxyCert"/>
    <dp:paraMap name="sslSettings">
        <value name="javax.net.ssl.trustStore" value="${idm.truststore}"/>
        <value name="javax.net.ssl.trustStorePassword" value="${idm.truststore.password}"/>
        ...
    </dp:paraMap>
</object>

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.

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.

Custom JAR Files

Upload custom JAR files to handle specialized logic.

Custom Resources Base Directory

Configure the base directory for uploaded Custom Resources.

Enter a path relative to the instance directory, such as conf or import.

Absolute paths and nested paths are not supported.

Custom Resources

Upload additional resources here.

For instance, you may upload files used by your data sources in the Configuration.

nevisAdmin generation time expressions (e.g. ${var.name}) are not supported here.

nevisDataPorter Log Settings

#Logging

Plugin: nevisadmin-plugin-nevisdp

The pattern defines log levels and log retention of nevisDataPorter. Assign to a nevisDataPorter 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.

See nevisDataPorter Technical Documentation, chapter Logging, tracing, debugging, and profiling for details.

Hint: If you only change log levels nevisAdmin 4 does not restart the component in classic VM deployment. The new log configuration will be reloaded within 60 seconds after deployment.

The default configuration is:

dataporter = INFO

Examples:

dataporter.config=INFO
dataporter.statistics=INFO

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.

This configuration applies to non-Kubernetes deployment only.

Max File Size

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

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

This configuration applies to non-Kubernetes deployment only.

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.

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.

Regex Filter

If set, messages for dataporter.log which match the given regular expression won't be logged.

The regular expression must match the entire line. For instance, you may use the following format to match some text:

.*some text.*

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.

nevisDetect Admin Instance

#User Behavior Analytics #Instances #Experimental

Plugin: nevisadmin-plugin-nevisdetect

Using the pattern, you can set up the administration service for nevisDetect.

TCP Service Port

Enter the port on which nevisDetect Admin service will listen.

nevisDetect Message Queue

Add references (at least one) for the patterns configuring Java Messaging Service. In case of Kubernetes deployment, only one configuration is allowed.

Two different options are allowed at this time:

• nevisDetect Message Queue Instance - deployment pattern for a dedicated MQ component
• ActiveMQ Client Configuration - connect to an external ActiveMQ service via SSL

WARNING: In case of Kubernetes deployment, only ActiveMQ Client Configuration is supported.

Log Settings

Assign nevisDetect Log Settings to change the log configuration.

Frontend Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Frontend Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

SecToken Signer Trust Store

Assign the Trust Store provider for verifying the NEVIS SecToken. If no pattern is assigned the signer key will be provided by the nevisAdmin 4 PKI.

Message Queue Client Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Message Queue Client Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

Client Authentication

Setting for 2-way TLS on the nevisAdapt HTTPs endpoint. There are 3 options will affect the callers (e.g. nevisProxy or technical clients accessing nevisAdapt REST APIs)

• required: Callers must present a client certificate.
• requested: Callers can present a client certificate.
• disabled: Callers must not use a client certificate.

The Frontend Trust Store must contain the issuing CA.

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.

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.

Bind Host

Enter a custom host name to listen on.

This setting is relevant in classic VM deployment, when working with multi-homed target hosts.

In Kubernetes the component listens on 0.0.0.0 and thus this setting is discouraged.

Additional Settings

Assign an add-on pattern to customize the configuration.

nevisDetect Administration GUI

#User Behavior Analytics #Applications #Experimental

Plugin: nevisadmin-plugin-nevisdetect

The pattern exposes the nevisDetect Frontend GUIs on a nevisProxy Virtual Host.

The Administration GUI is available on /nevisdetect/admin.

nevisDetect Admin

Reference for the pattern with the details of the web application.

Supported patterns:

• nevisDetect Admin Instance

Trust Store

Assign the trust store for outbound TLS connections.

If no pattern is assigned a trust store will be provided by nevisAdmin 4 automatic key management.

Hostname Validation

Enable to verify that the hostname on the certificate presented by the backend matches the hostname of nevisDetect Admin

Virtual Host

Assign a Virtual Host which shall serve as entry point.

Authentication Realm

Mandatory setting to enforce authentication.

Application Access Token

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

Please assign a NEVIS SecToken. This is mandatory to have access to the Administration UI.

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.

nevisDetect Authentication Connector

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisdetect

Using the pattern, you can integrate nevisDetect as an authentication step in nevisAuth.

It is required to send the authentication requests to nevisDetect for analysis, and set the device recognition cookie for nevisAdapt.

nevisDetect Core

Pattern reference for the nevisDetect Core Instance to connect to.

nevisAdapt

Optional pattern reference for the nevisAdapt Instance to help configure the device cookie name.

On Success

Set the step to continue with on successful authentication.

On Failure

Set the step to continue with in case of error. If nothing is set, the authentication fails.

Message Queue Client Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Message Queue Client Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

Cookie Domain

If unset, the cookie will not be scoped to subdomains. Set this value to a specific domain to include more than one hostname.

Example: The user wants to login through example.com

If no value is given, the cookie will be effective for requests with the following addresses:

• https://example.com/one/two/three...

If the value is actually set as example.com, the cookie will be effective for requests against subdomains as well:

• https://shopping.example.com/one...
• https://account.example.com/two...
• https://example.com/three...

nevisDetect Core Instance

#User Behavior Analytics #Instances #Experimental

Plugin: nevisadmin-plugin-nevisdetect

Using the pattern, you can set up the plugin administration for nevisDetect.

TCP Service Port

Enter the port on which nevisDetect Core will listen.

nevisDetect Persistency

Add reference for a nevisDetect Persistency Instance pattern.

nevisDetect Message Queue

Add reference for the pattern providing Java Messaging Service.

Two different options are allowed at this time:

• nevisDetect Message Queue Instance - deployment pattern for a dedicated MQ component
• ActiveMQ Client Configuration - connect to an external ActiveMQ service via SSL

WARNING: In case of Kubernetes deployment, only ActiveMQ Client Configuration is supported.

Risk Plugins

List of Risk Plugins that are loaded by this nevisDetect Core component

Log Settings

Assign nevisDetect Log Settings to change the log configuration.

Frontend Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Frontend Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

Message Queue Client Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Message Queue Client Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

Client Authentication

Setting for 2-way TLS on the nevisAdapt HTTPs endpoint. There are 3 options will affect the callers (e.g. nevisProxy or technical clients accessing nevisAdapt REST APIs)

• required: Callers must present a client certificate.
• requested: Callers can present a client certificate.
• disabled: Callers must not use a client certificate.

The Frontend Trust Store must contain the issuing CA.

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.

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.

Bind Host

Enter a custom host name to listen on.

This setting is relevant in classic VM deployment, when working with multi-homed target hosts.

In Kubernetes the component listens on 0.0.0.0 and thus this setting is discouraged.

Additional Settings

Assign an add-on pattern to customize the configuration.

nevisDetect Database

#Database #User Behavior Analytics

Plugin: nevisadmin-plugin-nevisdetect

Configures nevisDetect to use a MariaDB database. Assign to nevisDetect Persistency Instance as Database.

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

In classic VM deployments a database including tables must be set up before deployment.

Setup instructions can be found in the nevisDetect technical documentation. See Database setup for details.

If you want to use an Oracle database you have to set Custom Connection URL, instead of using the high-level settings, and upload the JDBC Driver.

Database Type

Choose between MariaDB and Oracle 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

Enter the name of the database.

This database will be created in the database service.

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

Enter the user for the DB connection.

Database Password

Enter the password of the DB connection user.

TLS Encryption

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

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

Trust Store

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

JDBC Driver

Due to licensing, nevisDetect cannot ship the JDBC driver to connect to Oracle databases, Therefore, those who want to use an Oracle database need to obtain and provide the Oracle JDBC driver on their own.

The .jar files can be downloaded from Oracle

Uploading any other .jar files containing JDBC drivers is possible as well.

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.

Flyway License Key

Please provide a licence key in case you would use the Flyway Teams Edition.

This is recommended only in case you would use an old database version (more than 5 years old). If you do not provide a licence key, the Flyway Community Edition will be used by default.

For more information about Flyway editions please visit this page Flyway.

Datasource Configuration Method

Select which method of generation should be applied when configuring the Hikari datasource for the database connection.

Possible options:

• recommended: the default option, this sets up three explicit values:
  • Maximum session lifetime: 300s
  • Session idle timeout: 100s
  • Maximum pool size: 50
• custom: specify values in the next text area, separate keys and values with =. The valid keys can be found at HikariCP - GitHub.
• unmodified: this configuration doesn't generate anything, leaving all default configurations coming from the library in effect.

Datasource Configuration Values

Specify custom values for Hikari datasource configuration. Separate keys and values with =. The valid keys can be found at HikariCP - GitHub.

Example to set the same as if selecting recommended:

maxLifetime=300000
idleTimeout=100000
maximumPoolSize=50

Connection Parameters

Enter parameters for the DB connection string.

Enter 1 parameter per line.

Lines will be joined with &.

The default is:

useMysqlMetadata=true

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

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

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.

nevisDetect Feature Correlator Instance

#User Behavior Analytics #Instances #Experimental

Plugin: nevisadmin-plugin-nevisdetect

Using the pattern, you can set up the feature correlation within nevisDetect to be able to correlate the requests coming from nevisProxy.

See also nevisDetect Feature Correlator.

TCP Service Port

Enter the port on which nevisDetect Feature Correlator will listen.

nevisDetect Persistency

Add reference for a nevisDetect Persistency Instance pattern.

nevisDetect Message Queue

Add reference for the pattern providing Java Messaging Service.

Two different options are allowed at this time:

• nevisDetect Message Queue Instance - deployment pattern for a dedicated MQ component
• ActiveMQ Client Configuration - connect to an external ActiveMQ service via SSL

WARNING: In case of Kubernetes deployment, only ActiveMQ Client Configuration is supported.

Log Settings

Assign nevisDetect Log Settings to change the log configuration.

Content-Type Restriction

Apply restriction based on request header Content-Type

Sub-path Restriction

Set to apply this pattern on some sub-paths only.

Sub-paths must be relative (e.g. not starting with /) and will be appended to the frontend path(s) of the virtual host (/) or applications this pattern is assigned to.

Sub-paths ending with / are treated as a prefix, otherwise an exact filter-mapping will be created.

The following table provides examples to illustrate the behaviour:

Frontend Path	Sub-Path	Effective Filter Mapping
/	secure/	/secure/*
/	accounts	/accounts
/	api/secure/	/api/secure/*
/	api/accounts	/api/accounts
/app/	secure/	/app/secure/*
/app/	accounts	/app/accounts
/app/	api/secure/	/app/api/secure/*
/app/	api/accounts	/app/api/accounts

Frontend Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Frontend Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

Message Queue Client Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Message Queue Client Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

Client Authentication

Setting for 2-way TLS on the nevisAdapt HTTPs endpoint. There are 3 options will affect the callers (e.g. nevisProxy or technical clients accessing nevisAdapt REST APIs)

• required: Callers must present a client certificate.
• requested: Callers can present a client certificate.
• disabled: Callers must not use a client certificate.

The Frontend Trust Store must contain the issuing CA.

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.

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.

Bind Host

Enter a custom host name to listen on.

This setting is relevant in classic VM deployment, when working with multi-homed target hosts.

In Kubernetes the component listens on 0.0.0.0 and thus this setting is discouraged.

Additional Settings

Assign an add-on pattern to customize the configuration.

nevisDetect Log Settings

#User Behavior Analytics #Logging

Plugin: nevisadmin-plugin-nevisdetect

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

See nevisDetect Reference Guide, chapter Logging Configuration for details.

Hint: If you only change log levels nevisAdmin 4 does not restart the component in classic VM deployment. The new log configuration will be reloaded within 60 seconds after deployment.

The default configuration is:

ch.nevis.nevisadapt = INFO
ch.nevis.nevisdetect.util.logging.OpTracer = DEBUG

Examples:

org.springframework.web.filter.CommonsRequestLoggingFilter=DEBUG
ch.nevis.nevisdetect.entrypoint.icap.RequestProcessingHelper=INFO

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

Logback 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

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

nevisDetect Message Queue Instance

#User Behavior Analytics #Instances #Experimental

Plugin: nevisadmin-plugin-nevisdetect

Using the pattern, you can set up an ActiveMQ service for nevisDetect.

Message Broker Name

The name for the broker to configure ActiveMQ with.

Server Port

Enter the port on which nevisDetect MQ will listen.

Frontend Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Frontend Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

Client Authentication

Setting for 2-way TLS on the nevisAdapt HTTPs endpoint. There are 3 options will affect the callers (e.g. nevisProxy or technical clients accessing nevisAdapt REST APIs)

• required: Callers must present a client certificate.
• requested: Callers can present a client certificate.
• disabled: Callers must not use a client certificate.

The Frontend Trust Store must contain the issuing CA.

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.

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.

Bind Host

Enter a custom host name to listen on.

This setting is relevant in classic VM deployment, when working with multi-homed target hosts.

In Kubernetes the component listens on 0.0.0.0 and thus this setting is discouraged.

Additional Settings

Assign an add-on pattern to customize the configuration.

nevisDetect Persistency Instance

#User Behavior Analytics #Instances #Experimental

Plugin: nevisadmin-plugin-nevisdetect

Using the pattern, you can set up the persistency service for nevisDetect.

TCP Service Port

Enter the port on which nevisDetect Persistency will listen.

Database

Add a database connection reference pattern.

Required properties to be set in the connector pattern are as follows:

• JDBC Driver (Oracle or MariaDB)
• JDBC URL
• DB user/password

nevisDetect Message Queue

Add reference for the pattern providing Java Messaging Service.

Two different options are allowed at this time:

• nevisDetect Message Queue Instance - deployment pattern for a dedicated MQ component
• ActiveMQ Client Configuration - connect to an external ActiveMQ service via SSL

WARNING: In case of Kubernetes deployment, only ActiveMQ Client Configuration is supported.

Log Settings

Assign nevisDetect Log Settings to change the log configuration.

Frontend Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Frontend Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

SecToken Signer Trust Store

Assign the Trust Store provider for verifying the NEVIS SecToken. If no pattern is assigned the signer key will be provided by the nevisAdmin 4 PKI.

Message Queue Client Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Message Queue Client Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

Client Authentication

Setting for 2-way TLS on the nevisAdapt HTTPs endpoint. There are 3 options will affect the callers (e.g. nevisProxy or technical clients accessing nevisAdapt REST APIs)

• required: Callers must present a client certificate.
• requested: Callers can present a client certificate.
• disabled: Callers must not use a client certificate.

The Frontend Trust Store must contain the issuing CA.

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.

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.

Bind Host

Enter a custom host name to listen on.

This setting is relevant in classic VM deployment, when working with multi-homed target hosts.

In Kubernetes the component listens on 0.0.0.0 and thus this setting is discouraged.

Additional Settings

Assign an add-on pattern to customize the configuration.

nevisDetect Persistency REST API

#User Behavior Analytics #Applications #Experimental

Plugin: nevisadmin-plugin-nevisdetect

The pattern exposes the nevisDetect Frontend GUIs on a nevisProxy Virtual Host.

The nevisDetect Persistency REST API is available on /nevisdetect/persistency.

nevisDetect Persistency

Reference for the pattern with the details of the web application.

Supported patterns:

• nevisDetect Persistency Instance

Trust Store

Assign the trust store for outbound TLS connections.

If no pattern is assigned a trust store will be provided by nevisAdmin 4 automatic key management.

Hostname Validation

Enable to verify that the hostname on the certificate presented by the backend matches the hostname of nevisDetect Persistency

Virtual Host

Assign a Virtual Host which shall serve as entry point.

Authentication Realm

Mandatory setting to enforce authentication.

Application Access Token

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

Please assign a NEVIS SecToken. This is mandatory to have access to the Administration UI.

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.

nevisFIDO FIDO2 Database

#Database #FIDO2

Plugin: nevisadmin-plugin-fido2

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

#FIDO2 #Instances #Authentication #Experimental

Plugin: nevisadmin-plugin-fido2

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.

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.

User Presence Verification Timeout

Maximum time that a FIDO2 client has to send the response in a ceremony where user-verification is required.

Default value is 5 minutes.

No User Presence Verification Timeout

Maximum time that a FIDO2 client has to send the response in a ceremony where user-verification is not required.

Default value is 2 minutes.

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.

Restrict Authenticators

By default, all authenticators that fulfill the requirements given by the FIDO2 patterns are allowed.

Here you can restrict which authenticators are allowed based on metadata.

Select enabled here and provide the required metadata by configuring Allowed Authenticators.

Allowed Authenticators

Here you can configure which authenticators are allowed.

This configuration is used and required only when Allowed Authenticators is enabled.

Proceed as follows:

1. Download the official FIDO Alliance Metadata file (JWT) from the FIDO Alliance Metadata Service.
2. Decode the downloaded JWT.
3. Copy out the complete metadata statements of the desired authenticators into a new JSON file.
4. (optional) Remove the optional entries to “slim down” the metadata entry, only required entries are aaguid and attestationRootCertificates.
5. Safe the JSON file and upload it here.

You can find more information in our FIDO2 Concept and Integration Guide.

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

#FIDO2 #Logging

Plugin: nevisadmin-plugin-fido2

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

#FIDO2 #Applications #Experimental

Plugin: nevisadmin-plugin-fido2

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.

nevisFIDO UAF Connector

#Mobile Authentication #Connector

Plugin: nevisadmin-plugin-nevisfido

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

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

The entered value is used to calculate:

• AppID
• Dispatch payload

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

• Out-of-band Registration
• Out-of-band Authentication

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

#Database #Mobile Authentication

Plugin: nevisadmin-plugin-nevisfido

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 Device Service

#Mobile Authentication

Plugin: nevisadmin-plugin-nevisfido

Exposes the nevisFIDO UAF Device Service on a nevisProxy Virtual Host.

The endpoint is intended to be used by the SDK / Access App only.

It allows to query and update device-specific information such as dispatch targets and authenticators.

Virtual Host

Assign a Virtual Host which shall serve as entry point.

nevisFIDO

Assign a nevisFIDO Instance or nevisFIDO Connector.

nevisFIDO UAF Instance

#Instances #Mobile Authentication

Plugin: nevisadmin-plugin-nevisfido

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:

• AppID
• Dispatch payload

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

• Out-of-band Registration
• Out-of-band Authentication

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 required configuration for mobile authentication scenarios. The FIDO AppID and Facet Specification defines facets as identities of a single logical application across various platforms.

The following wildcard facet IDs are included for ease of use, to speed up integration of the Nevis Access App or Nevis Mobile Authentication SDK:

android:apk-key-hash:*,
ios:bundle-id:*

The wildcard facet ID entries are compatible with integration flavor Access Apps or debug flavor mobile SDKs. Production Access Apps or release mobile SDKs do not accept wildcard facet ID entries. If you want to use one of the Nevis Mobile Authentication SDK example applications with the release SDK, you will need to add one or multiple of the following facetID entries:

• android:apk-key-hash:ch.nevis.mobile.authentication.sdk.android.example
• android:apk-key-hash:ch.nevis.mobile.authentication.sdk.flutter.example
• android:apk-key-hash:ch.nevis.mobile.authentication.sdk.react.example
• ios:bundle-id:ch.nevis.mobile.authentication.sdk.ios.example
• ios:bundle-id:ch.nevis.mobile.authentication.sdk.flutter.example
• ios:bundle-id:ch.nevis.mobile.authentication.sdk.objc.proxy.example
• ios:bundle-id:ch.nevis.mobile.authentication.sdk.react.example

For production deployment you have to replace the default and add your own facets for your iOS or Android applications. The following documentation provides additional information:

• For Access Apps, refer to the FacetID Calculation documentation.
• For the mobile SDK, refer to the FacetID chapter in the configuration section.

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.
• password_only: allows only (alphanumeric) password authenticators.

supported authenticators

Note that two authenticators supplied by the policy files are currently only supported by the Nevis Mobile Authentication SDK but not the Nevis Access App, these authenticators are:

• The Device Passcode authenticator
• The Password authenticator

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.

The Android metadata statements contain the Google root certificates to support Android Key Attestation / FIDO UAF Basic Full Attestation. These entries must be kept up-to-date.

Basic Full Attestation

Android Key Attestation relies on FIDO UAF Full Basic Attestation in the backend.

Whether Android Key Attestation is applied is controlled by the FIDO UAF policy.

Here you can choose between 2 levels for the FIDO UAF Full Basic Attestation:

default - does FIDO UAF Basic Full attestation solely based on the UAF protocol specification. In practice, this means it’s limited to verifying the certificate chain.

strict - is doing additional checks on the attestation extension of the TBSCertificate, ensuring that all key material is kept in certified secure hardware and the phone bootloader was not manipulated.

Additional information can be found in the nevisFIDO UAF configuration documentation including the specifics of the additional checks done in strict mode

Refer to the following sections for additional information of how to create the necessary policy files:

• nevisFIDO policy configuration
• support of basic full and basic surrogate attestations

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.

Firebase Proxy User

Username to authenticate for Firebase Proxy Address.

Firebase Proxy Password

Password to authenticate for Firebase Proxy Address.

Link Type

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 Link

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.

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.

Deep Link Resources

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

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.

Visit our official documentation for more information.

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": [
      {
        "appIDs": [
          "<team id>.<bundle id>"
        ],
        "components": [
          {
            "/": "open",
            "?": {
              "dispatchTokenResponse": "*"
            },
            "caseSensitive": false
          }
        ]
      }
    ]
  }
}

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

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

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "<bundle id>",
      "sha256_cert_fingerprints": [
        "<certificate fingerprint>"
      ]
    }
  }
]

Custom URI Link

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.

Connection Type

Define which APIs nevisFIDO uses when talking to nevisIDM.

Choose between:

• default: use the API recommended by Nevis.
• both: uses the SOAP API for most use cases and REST for updating login counters.
• rest: uses only the REST API.

As of November 2024 our default is both. The rest mode is still experimental, but is expected to become the default in the future.

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.

Registration Token Timeout

Defines the maximum time a client has to redeem a registration token after the generation of the token by nevisFIDO.

Once the token is redeemed, the Registration Response Timeout applies: the client has a maximum time to send a RegistrationResponse to nevisFIDO.

The default value is 5 minutes. If no time unit is provided, seconds will be used.

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

Authentication Token Timeout

Defines the maximum time a client has to redeem an authentication token after the generation of the token by nevisFIDO.

Once the token is redeemed, the Authentication Response Timeout applies: the client has a maximum time to send an AuthenticationResponse to nevisFIDO.

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

Registration Response Timeout

Defines the maximum time duration between the generation of the RegistrationRequest by nevisFIDO and the RegistrationResponse by the FIDO UAF client.

If the client has not sent the response after this time, a client timeout occurs.

The default value is 5 minutes. If no time unit is provided, seconds will be used.

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

• In-Band Registration
• Out-of-Band Registration

Authentication Response Timeout

Defines the maximum time duration between the generation of the AuthenticationRequest by nevisFIDO and the AuthenticationResponse by the FIDO UAF client.

If the client has not sent the response after this time, a client timeout occurs.

The default value is 2 minutes. If no time unit is provided, seconds will be used.

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

• In-Band Authentication
• Out-of-Band Authentication

Device Service Timeout

Defines the maximum time difference that is accepted between the time in the creationTime attribute in device service requests and the time when the server processes the request.

This value is close to the time drift that is accepted between the mobile device clock and the server clock. If the time drift is bigger than this value, the operation will fail.

The default value is 5 minutes. If no time unit is provided, seconds will be used.

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

#Mobile Authentication #Logging

Plugin: nevisadmin-plugin-nevisfido

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.

nevisIDM Account Recovery

#Identity Management #Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

Account recovery provides the user an alternative way to log in.

This can be useful in cases when the user lost access to their account, for example, by losing the phone that is registered as second factor.

For background information about the credential and database tables used by this feature, see:

• Recovery code credential
• Recovery code database table.

nevisIDM

Reference a nevisIDM Instance to be used for checking terms and conditions.

On Success

Configure the step to execute after the user was successfully authenticated.

On Failure

Configure the step to execute after the authentication failed.

If no step is configured here the process ends.

nevisIDM Administration GUI

#Identity Management #Applications

Plugin: nevisadmin-plugin-nevisidm

The pattern exposes the nevisIDM Administration GUI on a nevisProxy Virtual Host.

The Administration GUI is exposed on /nevisidm/admin.

You can enable the nevisIDM Self Admin GUI under Advanced Settings.

Virtual Host

Assign a Virtual Host which shall serve as entry point.

nevisIDM

References a nevisIDM Instance.

Trust Store

Assign a trust store if you want to validate the server certificate used by nevisIDM. If this not set, the connection is 1-way TLS.

Hostname Validation

Enable to verify that the hostname on the certificate presented by the backend matches the hostname of nevisIDM

Key Store

Assign a key store if you want to use 2-way TLS for the connection between nevisProxy and nevisIDM.

Authentication Realm

Mandatory setting to enforce authentication.

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.

Request Validation (ModSecurity)

• off - no request validation
• standard - uses ModSecurity OWASP Core Rule Set (CRS) with default paranoia level 1 - Basic security
• custom - configure Request Validation Settings via Additional Settings
• log only - uses standard in log only mode

Self Admin GUI

Choose between:

• enabled - the nevisIDM self admin GUI will be exposed on the path /nevisidm/selfadmin/.
• disabled - access to the path /nevisidm/selfadmin/ will be blocked.

If you want to provide a self admin interface for end users we recommend to implement your own application and call the nevisIDM REST API instead. This way you can decide which settings to expose to your users and achieve the desired user experience.

REST API Access

Enables REST API access for the NevisIDM web application. As of 2022 May it is only needed by the Terms & Conditions functionality. If Terms & Conditions is not used, then this can be disabled safely.

• enabled - the REST API will be exposed on the path /nevisidm/api/*.
• disabled - access to the path /nevisidm/api/* will be blocked.

If the REST API is enabled here, then the use of the nevisIDM REST Service pattern is not needed.

WARNING: if the nevisIDM REST Service pattern is also used, and has different realms or SecToken patterns assigned, then the configuration may lead to a requirement clash or a similar issue

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.

nevisIDM Authorizations

#Identity Management #Add-ons

Plugin: nevisadmin-plugin-nevisidm

Use the pattern to customize roles for a nevisIDM Instance.

Assign to the nevisIDM Instance using Additional Settings.

Role Management

Add properties for authorizationConfig.properties. If a role not defined in the uploaded file default values will be used for it.

See Assigning IDM roles for details.

You can input the role with or without nevisIdm prefix. For instance, both Root are nevisIdm.Root are supported.

Role Assignment

Add properties for rolesAssignment.properties. If a role not defined in the uploaded file default values will be used for it.

See Data room authorization for details.

You can input the role with or without nevisIdm prefix. For instance, both Root are nevisIdm.Root are supported.

Role Permissions

Add properties for rolesMapping.properties. If a role not defined in the uploaded file default values will be used for it.

See Functional authorization - nevisIDM roles for details.

The following permissions are allowed:

• ApplicationCreate, ApplicationDelete, ApplicationModify, ApplicationSearch, ApplicationView
• AuthorizationApplCreate, AuthorizationApplDelete, AuthorizationApplSearch, AuthorizationApplView,
• AuthorizationClientCreate, AuthorizationClientDelete, AuthorizationClientSearch, AuthorizationClientView
• AuthorizationCreate, AuthorizationDelete, AuthorizationModify, AuthorizationSearch
• AuthorizationEnterpriseRoleCreate, AuthorizationEnterpriseRoleDelete, AuthorizationEnterpriseRoleSearch, AuthorizationEnterpriseRoleView
• AuthorizationUnitCreate, AuthorizationUnitDelete, AuthorizationUnitSearch, AuthorizationUnitView
• AuthorizationView,
• BatchJobExecute, BatchJobView
• ClientApplAssign, ClientApplDelete, ClientApplView
• ClientCreate, ClientDelete, ClientModify, ClientSearch, ClientView
• CollectionCreate, CollectionDelete, CollectionModify, CollectionView
• ConsentView
• CredentialChangeState, CredentialCreate, CredentialDelete, CredentialModify, CredentialPdfView, CredentialSearch, CredentialView, CredentialViewPlainValue
• EnterpriseAuthorizationCreate, EnterpriseAuthorizationDelete, EnterpriseAuthorizationModify, EnterpriseAuthorizationSearch, EnterpriseAuthorizationView
• EnterpriseRoleCreate, EnterpriseRoleDelete, EnterpriseRoleModify, EnterpriseRoleSearch, EnterpriseRoleView
• EnterpriseRoleMemberCreate, EnterpriseRoleMemberDelete, EnterpriseRoleMemberSearch
• EntityAttributeAccessOverride
• GenerateReport
• HistoryView
• LoginIdOverride, LoginIdModify
• PersistentQueueView, PersistentQueueDelete
• PersonalQuestionCreate, PersonalQuestionDelete, PersonalQuestionModify, PersonalQuestionView, PersonalQuestionSearch
• PolicyConfigurationCreate, PolicyConfigurationDelete, PolicyConfigurationModify, PolicyConfigurationSearch, PolicyConfigurationView
• ProfileArchive, ProfileCreate, ProfileDelete, ProfileModify, ProfileSearch, ProfileView
• DeputyCreate, DeputyDelete
• PropertyAllowedValueCreate, PropertyAllowedValueDelete, PropertyAllowedValueModify, PropertyAllowedValueSearch, PropertyAllowedValueView, PropertyAttributeAccessOverride
• PropertyView, PropertyCreate, PropertyDelete, PropertyModify, PropertySearch
• PropertyValueCreate, PropertyValueDelete, PropertyValueModify, PropertyValueSearch, PropertyValueView
• RoleCreate, RoleDelete, RoleModify, RoleSearch, RoleView
• SearchResultsExport
• SelfAdmin
• TemplateView, TemplateCreate, TemplateDelete, TemplateModify, TemplateStore
• TemplateTextCreate, TemplateTextDelete, TemplateTextModify, TemplateTextView
• TermsCreate, TermsDelete, TermsModify, TermsView
• UnitCreate, UnitCreateTopUnit, UnitDelete, UnitModify, UnitSearch, UnitView
• UnitCredPolicyCreate, UnitCredPolicyDelete, UnitCredPolicyView
• UserArchive, UserCreate, UserDelete, UserModify, UserSearch, UserView
• UserCreateTechUser, UserModifyTechUser, UserDeleteTechUser, UserArchiveTechUser

User related fine-grained permissions

For permissions UserModify and UserView a more fine-grained permission can be used.

See Configuration of fine-grained permissions for details.

Credential-type specific permissions

For permissions related to credentials (such as CredentialChangeState, CredentialCreate, CredentialDelete, CredentialModify, CredentialPdfView, CredentialSearch, CredentialView, and CredentialViewPlainValue), it's permissible to reduce the elementary permission to specific credential type(s).

See Credential-type specific permissions of nevisIDM roles for details

nevisIDM Change Password State

#Identity Management #Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

Change the credential of a user in the nevisIDM

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

On Success

Assign an authentication step to execute when the status of the URL ticket or credential is onSuccess. Required field.

On Failed

Assign an authentication step to execute when the status of the URL ticket or credential is failed.

Client Not Found

Assign an authentication step to execute when the status of the URL ticket or credential is clientNotFound.

Now Locked

Assign an authentication step to execute when the status of the URL ticket or credential is nowLocked.

Lock Warning

Assign an authentication step to execute when the status of the URL ticket or credential is lockWarn.

Locked

Assign an authentication step to execute when the status of the URL ticket or credential is locked.

Temp Locked

Assign an authentication step to execute when the status of the URL ticket or credential is tmpLocked.

Form Encryption

Set to enable form encryption.

This feature is still experimental in nevisAdmin 4 and has been added to this pattern as a preview.

The default template includes the required JavaScript (e2eenc.js) to perform client-side encryption of the form values.

Re-enter old Password

If enabled, the user has to re-enter the old password before changing it.

If disabled, the user can change the password without re-entering the old password.

Show GUI

Sets if the authState's GUI should be rendered, default is enabled.

If not set or set to disabled, the GUI will not be rendered, making New Password setting mandatory. Current Password and New Password Confirmation settings may also be required, depending on other settings.

Display Password Policy

If enabled, the active password policy is displayed on the GUI.

Show Confirmation Field

If enabled, a confirmation field is also rendered on GUI.

Current Password

Mandatory input value to use for old password if Show GUI is disabled and Re-enter old Password is enabled.

New Password

Mandatory input value to use for new password if Show GUI is disabled.

New Password Confirmation

Mandatory input value to use for confirming the new password if Show GUI is disabled and Show Confirmation Field is enabled.

nevisIDM Check User Credentials

#Identity Management #Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

Checks if user has credentials. There are possible follow-up slot for patterns if

• no credential found
• at least one, but not all Credential found
• all Credential found

It checks against all credentials, which specifically are not mentioned to not to check against.

The pattern is experimental and may be improved in future releases. We are looking forward to your feedback and requirements.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

No credential found

Configure the step to execute if the user has no credential from credential types defined in Credential Types. If no step is configured here the process ends with AUTH_DONE.

Any credential found

Configure the step to execute if the user has at least one credential from credential type selected in Credential Types, but nit from all credential type. If no step is configured here the process ends with AUTH_DONE.

All credential found

Configure the step to execute if the user has at least one credential from all type selected in Credential Types. If no step is configured here the process ends with AUTH_DONE.

Credential Types

Credential types which existence for the user should be checked.

Possible values:

• PASSWORD
• CERTIFICATE
• SECURID
• TICKET
• SAFEWORDUSER
• OTP
• TEMPSTRONGPASSWORD
• GENERIC
• KERBEROS
• MTAN
• VASCO
• PUK
• URLTICKET
• DEVICEPASSWORD
• MOBILESIGNATURE
• SAMLFEDERATION
• SECURITYQUESTIONS
• CONTEXTPASSWORD
• OATH
• FIDO_UAF
• RECOVERY_CODE
• FIDO2

nevisIDM Client

#Identity Management #Add-ons #Experimental

Plugin: nevisadmin-plugin-nevisidm

Assign this pattern to a nevisIDM Instance via Additional Settings to create a client at startup.

Note that removing this pattern won't remove the client from nevisIDM.

External ID

External ID of the new client.

Client Name

The name of the client.

Client Display Names

The name of the client in different languages.

The format is:

• two letter language code in lower case
• separator characher: = or :
• the client name in that language

For example:

de:Beispiel-Client
fr:Exemple de client

Remarks

Any other additional information about the client.

nevisIDM Client Certificate Authentication

#Identity Management #Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

Ask the user to send a client certificate.

The step uses an IdmX509State to look up the user in nevisIDM, based on the value of the Certificate credential.

If no client certificate is provided, or no user is found for this certificate, an error will be shown.

The following generic label is used: error.login.1

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

On Success

Assign an optional step to execute after successful authentication.

nevisIDM Connector

#Identity Management

Plugin: nevisadmin-plugin-nevisidm

Use to connect to an existing nevisIDM 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 nevisIDM 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.

nevisIDM Connector for Generic Authentication

#Identity Management #Authentication

Plugin: nevisadmin-plugin-nevisidm

Generates an AuthState named nevisIDM_Connector, which configures the connection to the assigned nevisIDM instance.

You can use the connection in the Generic authentication pattern by adding the following element:

<propertyRef name="nevisIDM_Connector"/>

nevisIDM

The nevisIDM instance that the generated AuthState should connect to.

Generic Authentication Patterns

Any generic Auth pattern that should have access to the generated AuthState.

nevisIDM Custom Property

#Identity Management #Add-ons #Experimental

Plugin: nevisadmin-plugin-nevisidm

Assign the pattern to a nevisIDM Instance to create a custom property.

Note that removing the pattern does not remove the property from nevisIDM. You can do this using SQL instead.

Property Name

Enter name for the property definition file.

Technical name of the property. The name has to be unique among the properties of the same scope and within the same client.

Property Scope

Select the type of property:

• USER_GLOBAL: all users have this property
• CREDENTIAL_GENERIC_GLOBAL: all Generic credentials have this property
• UNIT_GLOBAL: all units have this property

Uniqueness Scope

If set then values stored in the property must be unique within the configured scope.

• ABSOLUTE: The property's values have to be unique overall. Two property values with the same content must not exist.

Client External ID

Enter clientExtId for the property definition file.

If set, the property becomes specific to the referred client. Otherwise, the property is client-independent.

Maximum Length

Enter maxLength for the property definition file.

Defines the maximum length of the property value.

Regular Expression

Enter regex for the property definition file.

The defined regular expression will restrict the possible values that can be assigned to the property. If a value is entered, it will be checked against the specified pattern to ensure it meets the criteria.

Some examples of how regular expressions can be used for common data types:

Email address:

^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$

Telephone number in the format +[country code] (XXX) XXX-XXXX:

^\+\d{1,3}\s?\(\d{3}\)\s?\d{3}-\d{4}$

Social Insurance Number (SIN) in the format XXX-XX-XXXX:

^\d{3}-\d{2}-\d{4}$

URL in the format:

(https:\/\/www\.|http:\/\/www\.|https:\/\/|http:\/\/)?[a-zA-Z0-9]{2,}(\.[a-zA-Z0-9]{2,})(\.[a-zA-Z0-9]{2,})?

The regex will be escaped for JSON if required.

Description

The description field in the property definition file allows you to provide a clear and informative description of the custom property. This description will be valuable for understanding the purpose, expected values, or any other relevant information about the property.

The description will be escaped for JSON if required.

Modification Access

Possible settings:

• READ_WRITE: Input is possible for the if previous value was stored.
• READ_ONLY: Field is read only.
• OFF: Field is not updatable and property is not displayed GUI.

Users with AccessControl.PropertyAttributeAccessOverride can edit these field regardless of this settings.

Creation Access

Possible settings:

• READ_WRITE: Input is possible for the if no previous value was stored.
• READ_ONLY: Field is read only.
• OFF: Field is not updatable and property is not displayed GUI.

Users with AccessControl.PropertyAttributeAccessOverride can edit these field regardless of this settings.

nevisIDM Database

#Database #Identity Management

Plugin: nevisadmin-plugin-nevisidm

Configures the nevisIDM database. Assign to a nevisIDM Instance as Database. Do not assign the same pattern to multiple instances!

When deploying to Kubernetes, the database schema and connection user are set up automatically. The database schema will be automatically migrated when upgrading to a newer version of Nevis on the next deployment. This feature can be disabled with the Database Management drop-down.

In classic VM deployments, there is no schema creation and migration. You have to do Database Preparing.

If you want to use an Oracle database, additional configuration is required as we cannot bundle any Oracle dependencies due to licensing restrictions. In Kubernetes deployments you can provide these dependencies with a Volume Claim. In classic deployment you have to upload a JDBC Driver in this pattern.

Database Type

Choose between MariaDB and Oracle 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.

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

TLS Encryption

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

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

Trust Store

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

JDBC Driver

Due to licensing restrictions, we cannot ship any Oracle dependencies. If you want to use an Oracle database, upload a JDBC driver here.

The driver can be downloaded from Oracle.

Note that both the component (nevisidm) and the database migration tool (nevisidmdb) need a JDBC driver to access the database. In a classic deployment, the driver will therefore be added to 2 different instance directories.

In Kubernetes setups, and when Database Management is enabled, you have to configure Volume Claim instead of uploading the JDBC driver here. This is to avoid committing binary files to Git during the deployment process.

Volume Claim

Due to licensing restrictions, we cannot ship any Oracle dependencies.

If you are using an Oracle database, are deploying to Kubernetes, and Database Management is enabled (complete or schema), then you have to provide a Kubernetes volume containing an Oracle driver and client.

For more information, see Preparing Oracle Volume.

Enter the name of that volume here.

The volume will be mounted in the nevisidm-dbschema image to set up and patch the database schema.

The volume will be mounted in the nevisidm image to connect to the database. Because of that, there is no need to upload a JDBC Driver.

Index Tablespace

Name of the index tablespace for the oracle database. It's recommended to keep the default value unless the pattern is used with an existing database that has a different one.

Data Tablespace

Name of the data tablespace for the oracle database. It's recommended to keep the default value unless the pattern is used with an existing database that has a different one.

Application Role

Name of the application role for the oracle database. It's recommended to keep the default value unless the pattern is used with an existing database that has a different one.

Owner Role

Name of the owner role for the oracle database. It's recommended to keep the default value unless the pattern is used with an existing database that has a different one.

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.

Connection Parameters

Enter parameters for the DB connection string.

Enter 1 parameter per line.

Lines will be joined with &.

When connecting to a MariaDB database some query parameters will be added when not present. The following parameters will be enforced then:

pinGlobalTxToPhysicalConnection=1
useMysqlMetadata=true
cachePrepStmts=true
prepStmtCacheSize=1000

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.

nevisIDM Generic Batch Job

#Identity Management #Add-ons #Experimental

Plugin: nevisadmin-plugin-nevisidm

Configure a batch job for nevisIDM using the XML syntax described in the technical documentation.

Use the pattern only when there is no dedicated pattern for your batch job.

Assign the pattern to a nevisIDM Instance using Additional Settings.

Job(s)

Add configuration of a bean which configures your batch job.

The basic syntax is as follows:

<bean id="someJobId" class="org.springframework.scheduling.quartz.JobDetailFactoryBean">
    <property name="description" value="Some job description"/>
    <property name="durability" value="true"/>
    <property name="jobClass" value="some.job.Class"/>
    <property name="jobDataMap">
        <bean class="org.quartz.JobDataMap">
            <constructor-arg>
                <map>
                    <entry key="someJobParam" value="some value"/>
                </map>
            </constructor-arg>
        </bean>
    </property>
</bean>

Trigger(s)

Add configuration of a bean which acts as a trigger for job execution.

Execute every 24 hours:

<bean id="someTriggerId" class="org.springframework.scheduling.quartz.SimpleTriggerFactoryBean">
    <property name="description" value="Some description shown in nevisIDM Admin GUI"/>
    <property name="jobDetail" ref="someJobId"/> <!-- must be provided via Job(s) -->
    <property name="repeatInterval" value="86400000"/> <!-- 1 day in ms -->
    <property name="misfireInstructionName" value="MISFIRE_INSTRUCTION_RESCHEDULE_NEXT_WITH_EXISTING_COUNT"/>
</bean>

Execute once a day at midnight (cron expression):

<bean id="someTriggerId" class="org.springframework.scheduling.quartz.CronTriggerFactoryBean">
    <property name="description" value="Some description shown in nevisIDM Admin GUI"/>
    <property name="jobDetail" ref="someJobId"/> <!-- must be provided via Job(s) -->
    <property name="cronExpression" value="0 0 0 * * ?"/>
</bean>

Custom Batch Job JAR(s)

Upload JAR file(s) for custom batch jobs.

Note that batch jobs which call the nevisIDM business layer are not supported by Nevis. Please call the nevisIDM REST API only.

nevisIDM Instance

#Identity Management #Instances

Plugin: nevisadmin-plugin-nevisidm

The pattern represents a nevisIDM instance. The instance is named according to the pattern.

Multi-instance setups

In case of deploying the instance to multiple target hosts, the file auditing and asynchronous processing is enabled on the first instance only.

This is to prevent multiple instances from processing the same event concurrently, which may occasionally lead to errors, such as sending out the same e-mail twice, or splitting the audit log file over several instances.

Hint for pattern renaming

When the 'Instance Name' property is not filled, the pattern uses the pattern name as instance directory at the target host.

To rename the pattern, do the following:

1. Rename the pattern in the GUI.
2. Rename the instance directory and associated systemd files on the deployment hosts.
3. Deploy

In case step 2 is omitted the old instance is shut down during deployment.

These steps are documented in the nevisAdmin 4 technical documentation: User Guide / Configuration Projects / Working with Patterns.

Port

Port the nevisIDM instance is listening on.

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.

Encryption Key

Enter an encryption key as Base64. This is mandatory because of security.

For existing setups please enter the value of security.properties.key from your /var/opt/nevisidm/<instance>/conf/nevisidm-prod.properties file.

If you don't know which value was used so far you may generate a new key and set Encryption Fallback to enabled to ease migration.

When there are no URL tickets or encrypted properties the fallback can be disabled.

For new setups the key should consist of random bytes. The following openssl command generates a random key and returns the Base64 value:

openssl rand -base64 16

Note that when Encryption Algorithm is set to AES, the key length must be 8, 16 or 24 bytes. 8 byte long AES keys are strongly discouraged for new instances, but supported for legacy instances.

Encryption Fallback

Initialization vector ("iv") fallback mechanism

This must be set to true for customers who previously had no value set for security.properties.key / propertiesKey (old name) in the properties file and had encrypted values already stored in the database. Otherwise, the old values encrypted by default value will not be readable. If the database does not contain encrypted properties or unused URL tickets, it is safe to leave this turned off, and it is adviced to be turned off for stronger security.

Frontend Key Store

Assign the Key Store provider for the HTTPs endpoint. If no pattern is assigned a Key Store will be provided by the nevisAdmin 4 PKI.

Frontend Trust Store

Assign the Trust Store provider for the HTTPs endpoint. If no pattern is assigned the Trust Store will be provided by the nevisAdmin 4 PKI.

SecToken Trust Store

Assign a Trust Store provider pattern to use for setting up trust between nevisIDM and nevisAuth. If no pattern is assigned the signer key will be provided by the nevisAdmin 4 PKI.

Client Authentication

Setting for 2-way TLS on the nevisIDM HTTPs endpoint. There are 3 options will affect the callers (e.g. nevisProxy or technical clients accessing nevisIDM REST APIs)

• required: Callers must present a client certificate.
• requested: Callers can present a client certificate.
• disabled: Callers must not use a client certificate.

The Frontend Trust Store must contain the issuing CA.

Status Port

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

Messaging Port

Port of the messaging service.

Enter a different port to deploy multiple nevisIDM instances on the same target host in classic VM deployment.

Database

Assign a nevisIDM Database.

Query Service

Enable the Query Service to allow full-text searches on the Admin GUI and REST API. Please note that using the Query Service requires the nevisIDM REST API to be exposed with the nevisIDM REST Service pattern.

Log Settings

Add logging configuration for nevisIDM.

Multi Client Mode

If IDM should support multiple Clients.

SMTP Server

Host:port of the SMTP server used for sending emails.

Configure if you prefer to provide the SMTP server with a single configuration, instead of configuring both SMTP Host and SMTP Port.

SMTP Host

The name of the host on which the SMTP server is running.

SMTP Port

Port of the SMTP server.

SMTP SSL/TLS Mode

Choose between:

• disabled - SSL/TLS is disabled. The SMTP Trust Store is not used.
• STARTTLS - uses the STARTTLS command (see RFC 2487) to switch to SSL/TLS if supported by the SMTP server.

Trust Store

Assign a Trust Store provider pattern to use for setting up trust between nevisIDM and the SMTP server.

SMTP User

Set if a user is required to connect to the SMTP server.

SMTP Password

Set if a password is required to connect to the SMTP server.

Mail Sender

The default sender address for e-mails.

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.

Encryption Algorithm

Encryption algorithm.

Encryption Cipher

Encryption cipher.

Bind Host

Enter a custom host name to listen on.

Status Host

Enter a custom host name to open the Status Port on.

If not set 0.0.0.0 will be used in case of Kubernetes deployment and localhost for deployment to VMs.

Default Language

Sets default language for nevisIDM.

It is the same as using web.gui.languages.default in properties. If given by both way, the value in properties will be used.

See nevisIDM Reference Guide (chapter Configuration files) for details.

Batch Job Store

Select db to track job execution in the database. This ensures that a given batch job can only run once at the same time. Use this configuration when you have multiple lines / replicas.

Select ram to store track job execution in memory. You may use this value when you have only 1 line / replica.

Custom Resources

Files uploaded here will be added to the conf folder of the nevisIDM Instance.

Additional Settings

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

nevisIDM JMS Queues

#Identity Management #Add-ons #Experimental

Plugin: nevisadmin-plugin-nevisidm

Configures a nevisIDM Instance to publish events into JMS queues.

Remote Provisioning Queue

NevisIDM JMS Queue to which Provisioning messages should be sent.

Only accepts URIs starting with amqp, amqps or Endpoint=sb. Validates only URIs with amqp or amqps schemes.

Remote Expiry Queue

NevisIDM JMS Queue to which Expiry messages should be sent.

Only accepts URIs starting with amqp, amqps or Endpoint=sb. Validates only URIs with amqp or amqps schemes.

Messages in Expiry Queue are those messages which validTo time has passed without successful receive action and without failing for other reason. For further reference check NevisIdm Technical documentation > Configuration > Components > Provisioning module > Provisioning providers.

Remote Dead Letter Queue

NevisIDM JMS Queue to which Dead Letter messages should be sent.

Only accepts URIs starting with amqp, amqps or Endpoint=sb. Validates only URIs with amqp or amqps schemes.

Dead letter messages are those messages which are not in the expiryQueue and their delivery was unsuccessful. For further reference check NevisIdm Technical documentation > Configuration > Components > Provisioning module > Provisioning providers.

Trust Store

You should add a CA certificate, and then use a PEM Trust Store to provide it.

nevisIDM Log Settings

#Identity Management #Add-ons

Plugin: nevisadmin-plugin-nevisidm

Change log configuration for nevisIDM.

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.

See the nevisIDM Technical Documentation, chapter nevisIDM log levels (file: logging.yml) for details.

Hint: If you only change log levels nevisAdmin 4 does not restart the component in classic VM deployment. The new log configuration will be reloaded within 60 seconds after deployment.

The default configuration is:

ch.nevis.idm.batch.jobs = INFO
ch.nevis.idm.standalone = INFO

Examples:

ch.adnovum.nevisidm.service.properties = INFO
ch.nevis.ninja = 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.

This setting applies to application.log and batch.log only. The audit.log is rotated on a daily basis.

Max File Size

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

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

Note: This parameter only applies to application.log and batch.log (as audit.log is configured with DailyRollingFileAppender).

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.

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.

Regex Filter

If set, messages for application.log which match the given regular expression won't be logged.

The regular expression must match the entire line. For instance, you may use the following format to match some text:

.*some text.*

Log Type

Configure audit logging capability of nevisIDM.

• When JSON (default) is selected, nevisIDM will write audit entries in JSON format.
• When plain is selected, nevisIDM will write audit entries as plain log lines. This setting is deprecated and may be removed in a future release.
• When disabled is selected, nevisIDM will not log audit entries at all.

In classic VM deployments the log target is /var/opt/nevisidm/<instance>/logs/audit.log. In Kubernetes and when JSON is selected the log messages are written to the pod log with the prefix [audit.log].

If you deploy nevisIDM to multiple hosts (multi-instance setup), the audit logging will only be enabled on the first host.

Log Format

Log4j 2 log format for the default SERVER logs.

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 Format

Log4j 2 log format for the default SERVER logs.

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

Syslog Format

Log4j 2 log format for the BATCH 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.

nevisIDM Password Create

#Identity Management #Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

Creates a password credential for the current user.

This pattern requires that the user has been set in the session up already.

For instance, put a nevisIDM User Lookup pattern before this step.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

On Success

Assign a step to continue with after successfully creating the password credential.

On Password Exists

If the user already has a password credential and error will occur.

You can assign a step here to handle this case.

State after creation

The state which the credential is in when created. Options:

• INITIAL
• ACTIVE
• DISABLED

Show Policy Violations

If set to enabled then after failed credential creation displays violated policies.

nevisIDM Password Login

#Identity Management #Authentication

Plugin: nevisadmin-plugin-nevisidm

Login to nevisIDM with username and password.

The step is intended to be used as a first factor in the Initial Authentication Flow of an Authentication Realm.

To support login using email, store the email in the Login ID field of the user.

Authentication is based on the default password policy of the selected client. See the nevisIDM Technical Documentation on how to adapt the policy.

On successful authentication, the UserId of the session is set to the Ext ID of the nevisIDM user.

For Web Application, an initial redirect (to ?login) is performed and a login GUI is shown. Technical clients calling a REST Service or SOAP Service may use basic authentication and send the credential upfront.

Double-check the URL you are calling as nevisProxy also responds with a redirect if no servlet can be found otherwise (trailingSlashRedirect).

The step also supports enforced password change, for expired passwords, and provides password reset, for users who forgot their password.

nevisIDM

Reference a nevisIDM Instance to be used for the username / password authentication.

On Success

Configure the step to execute after successful authentication.

If no step is configured here the process ends and the user will be authenticated.

Buttons

Assign an Dispatcher Button to add a button which points to a different authentication step.

User Attributes

Enter user attributes to fetch from nevisIDM.

Important attributes are:

• extId - unique ID of the user in nevisIDM
• loginId - name which could be used to login (instead of email)
• firstName
• name - surname
• email
• mobile
• language - language stored for user (can differ from Accept-Language sent by the browser)

For a complete list please check the documentation of IdmGetPropertiesState.

Some attributes (e.g. extId, email, and mobile) are always fetched as they are required by standard authentication steps.

The attributes will be stored in the user session as ch.nevis.idm.User.<attribute>.

Attributes may be used in sub-sequent authentication steps or included in application access tokens (e.g. NEVIS SecToken, SAML Token, or JWT Token).

For instance, use them in a Generic Authentication Step via the expression ${sess:ch.nevis.idm.User.<attribute>}.

Password Reset

Enables the password reset process.

The password reset process works as follows:

• The user has to enter his login ID or email.
• An email with a link be sent to the user.
• The user has to click the link in the mail to set a new password.

A link will be added to the login page. Users may click this link if they have forgotten their password to request a new password.

The link text can be changed on the Realm pattern by setting translations for the label pwreset.info.linktext.

Entry Path

The path prefix of the links for the password forgotten process.

Example: given a domain www.adnovum.ch and the value /pwreset/, all password forgotten steps will use the base path www.adnovum.ch/pwreset/.

URL Ticket Policy Name

Enter the name of a nevisIDM URL Ticket policy to use for the URL Ticket that is created at the beginning of the password reset process.

If nothing is configured here the default URL Ticket policy will be used.

Among others, the policy defines how the link is communicated to the user (e.g. by sending an email) and sets the expiration.

You can create additional policies via the nevisIDM Admin GUI or via SOAP / REST API.

Require Password Confirmation

Select the behaviour of password reset and the form of the password reset screen. If

• enabled: displays password confirmation field on password reset screen which is required to be filled in for password to be reset.
• disabled: leaves out field on password reset screen and password can be reset with filling out password field only.

Email Sent Redirect

Where to redirect to once the password reset ticket has been generated.

• root: to the domain root (/) on this Virtual Host
• referrer: to the initial URL requested by the client
• custom: to a custom path or URL as configured by Custom Email Sent Redirect

Note that the referrer will always be a page requiring authentication, hence it will basically redirect to the login page.

Custom Email Sent Redirect

Enter a URL, path, or nevisAuth expression which defines where to redirect to after the ticket has been created (and sent to the user via email).

Successful Change Redirect

Where to redirect to once the password reset is successfully completed.

See the "Email Sent Redirect" property for more information about the possible values.

Note that in this case, referrer can be very useful as it will redirect the client straight to the page he initially wanted to access before he started the password forgotten process.

Custom Successful Change Redirect

Enter a URL, path, or nevisAuth expression which defines where to redirect to after the new password has been set.

Redirection Path Validation Mode

Defines how to validate the redirection path which sent in the password reset e-mail. The following modes are available:

• Allow-list regexes: Only paths that match the regexes are allowed. Only paths needs to be defined (For example in case of https://your-domain.com/your-path, only /your-path needs to be defined). Regexes can be defined in Custom Redirection Path Validation Regexes.
• Deny-list Regexes: All paths are allowed except those that match the regexes. Only paths needs to be defined (For example in case of https://your-domain.com/your-path, only /your-path needs to be defined). Regexes can be defined in Custom Redirection Path Validation Regexes.

Application Path Fallback

If Allowed then after checking regexes set in Custom Redirection Path Validation Regexes it also a check if the path starts with any declared Web Application's path. (To see which paths would be find you can check Application Reports). If yes, those requests are also allowed

Custom Redirection Path Validation Regexes

Enter regexes for Deny/Allow-list to validate redirection URL query parameter sent with the Password reset-email

Default defined for Deny-list regexes and filters out all paths containing line feed and carriage return characters.

Separate Username / Password Screens

Set to enabled to ask for the username and password in two separate screens.

Show Client Input Field

Enable this to allow the user to enter the name of the Client (tenant) when logging in to nevisIDM.

If disabled, the input field is not shown and the Client Default is used.

Login Type

Define how to look up the user.

Choose between:

• LOGINID - lookup user by loginId attribute.
• EMAIL - lookup user by email attribute.
• AUTO - depending on what has been entered, nevisIDM tries to look up the user by email or loginId attribute.

We recommend to use LOGINID as it is the most efficient way to look up users and has no side effects. This can even work when users enter their email as you can store the email in the loginId attribute as well.

For AUTO and EMAIL to work nevisIDM has to be configured accordingly. You either have to:

• Set authentication.loginWithEmail.enabled=true in the Client policy. Policies cannot be configured using patterns. You can change them on the nevisIDM Admin GUI.
• Set application.feature.emaillogin.enabled=true in nevisidm-prod.properties. Use the Generic nevisIDM Instance Settings pattern for this.

Authentication Level

Set an authentication level if authentication of this step is successful. The level is relevant only if there are is an Authorization Policy assigned to applications.

Re-enter Expired Password

When the password is expired or has been reset by an administrator, the user is forced to set a new password.

Set this drop-down to enabled to force the user to enter the old password again when this happens.

Legacy LitDict Mode

In legacy mode policy violations are displayed using 1 GUI element.

You can use enabled here until November 2021 when this mode will be removed.

Reset Locked Password

Defines whether it is possible to reset locked passwords or not.

• If enabled, it is possible to reset locked passwords as well. In this case, only disabled passwords cannot be reset.
• If disabled, it is only possible to reset active passwords.

Form Encryption

Set to enable form encryption.

This feature is still experimental in nevisAdmin 4 and has been added to this pattern as a preview.

The default template includes the required JavaScript (e2eenc.js) to perform client-side encryption of the form values.

User Properties

Enter user properties to fetch from nevisIDM and store in the user session.

Properties must be created in the nevisIDM via SQL.

Unit Attributes

Enter unit attributes to fetch from nevisIDM. Enter 1 attribute per line.

The following unit attributes are supported:

• extId, state, name
• displayName, displayAbbreviation, location, description, hname, localizedHname
• ctlCreDat, ctlCreUid, ctlModDat, ctlModUid

Unit Properties

Enter unit properties to fetch from nevisIDM. Enter 1 property per line.

The properties must have scope onUnitGlobal. The property name must be exactly as defined in nevisIDM. Otherwise, the property value will never be written into the session.

Use Default Profile

Should in the Authentication flow assume default profile is selected if the user has multiple profiles, or should it display a selection dialog for the user.

nevisIDM Prune History Job

#Identity Management #Add-ons #Experimental

Plugin: nevisadmin-plugin-nevisidm

Assign to a nevisIDM Instance to configure a batch job which cleans up old history data.

Retention

Define how long history data shall be kept in days.

Example: 30d

The minimum value is 1d. The maximum value is 1024d.

Cron Expression

Enter a cron expression which defines when this job will be executed.

Cron expressions consist of 6 required fields and one optional field separated by white space.

The field order is:

1. Seconds
2. Minutes
3. Hours
4. Day-of-Month
5. Month
6. Day-of-Week
7. Year (optional)

Cron expression can be complex and this pattern only validates the length. The most important wildcards are:

• * is used to specify all values. For example, * in the minute field means every minute.
• ? is allowed for the day-of-month and day-of-week fields. It is used to specify no specific value.
• - is used to specify ranges.

Further information about the supported syntax can be found in the javadoc of org.quartz.CronExpression.

Examples:

• 0 0 0 * * ?: fires every midnight.
• 0 0/30 8-9 5,20 * ?: fires every half hour between the hours of 8 am and 10 am on the 5th and 20th of every month.
• 0 30 10-13 ? * WED,FRI: fires at 10:30, 11:30, 12:30, and 13:30, on every Wednesday and Friday.

Skip List

Comma-separated list of versioned tables (which are used to provide history data) to be ignored by the prune history job and left with their original content.

Possible values (Any combination of the following):

• tidma_application_v
• tidma_authorization_appl_v
• tidma_authorization_client_v
• tidma_authorization_erole_v
• tidma_authorization_unit_v
• tidma_authorization_v
• tidma_cert_info_v
• tidma_client_application_v
• tidma_client_v
• tidma_consent_v
• tidma_cred_login_info_v
• tidma_credential_v
• tidma_dict_entry_v
• tidma_dict_entry_value_v
• tidma_enterprise_auth_v
• tidma_enterprise_role_v
• tidma_erole_member_v
• tidma_fido2_v
• tidma_fido_uaf_v
• tidma_mobile_signature_v
• tidma_oath_v
• tidma_personal_answer_v
• tidma_personal_question_v
• tidma_policy_configuration_v
• tidma_policy_parameter_v
• tidma_profile_v
• tidma_property_allowed_val_v
• tidma_property_v
• tidma_property_value_v
• tidma_role_v
• tidma_saml_federation_v
• tidma_template_collection_v
• tidma_template_text_v
• tidma_template_v
• tidma_terms_application_v
• tidma_terms_url_v
• tidma_terms_v
• tidma_unit_cred_policy_v
• tidma_unit_v
• tidma_user_login_info_v
• tidma_user_v

For further information about historical tables visit Versioned DB tables .

nevisIDM REST Service

#Identity Management #Applications

Plugin: nevisadmin-plugin-nevisidm

Set up access to nevisIDM REST service on a nevisProxy Virtual Host.

The nevisIDM REST Service is exposed as: /nevisidm/api.

Virtual Host

Assign a Virtual Host which shall serve as entry point.

nevisIDM

References a nevisIDM Instance.

Trust Store

Assign a trust store if you want to validate the server certificate used by nevisIDM. If this not set, the connection is 1-way TLS.

Hostname Validation

Enable to verify that the hostname on the certificate presented by the backend matches the hostname of nevisIDM

Key Store

Assign a key store if you want to use 2-way TLS for the connection between nevisProxy and nevisIDM.

Authentication Realm

Mandatory setting to enforce authentication.

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.

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.

nevisIDM SOAP Service

#Identity Management #Applications

Plugin: nevisadmin-plugin-nevisidm

Using the pattern, you can set up access to the nevisIDM SOAP APIs on a nevisProxy Virtual Host.

The nevisIDM SOAP APIs are exposed on /nevisidm/services.

Virtual Host

Assign a Virtual Host which shall serve as entry point.

nevisIDM

References a nevisIDM Instance.

Trust Store

Assign a trust store if you want to validate the server certificate used by nevisIDM. If this not set, the connection is 1-way TLS.

Hostname Validation

Enable to verify that the hostname on the certificate presented by the backend matches the hostname of nevisIDM

Key Store

Assign a key store if you want to use 2-way TLS for the connection between nevisProxy and nevisIDM.

Authentication Realm

Mandatory setting to enforce authentication.

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.

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.

nevisIDM Second-Factor Selection

#Identity Management #Authentication

Plugin: nevisadmin-plugin-nevisidm

This authentication step checks the credentials of the user to determine a second factor for authentication.

If the user has multiple supported credentials, a selection dialog is shown.

The following labels are used in that dialog and you should change their translations:

• method.mtan.label - en: mTAN Code
• method.otp.label - en: OTP (One-Time Password)
• method.oath.label - en: OATH Authenticator App
• method.fido.label - en: Mobile Authentication
• method.fido2.label - en: FIDO 2
• method.recovery.label - en: Recovery Codes

You can use the step within an Authentication Realm as follows:

• in Initial Authentication Flow, after first-factor authentication
• in Session Upgrade Flows

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

OTP card

Assign a step which may be selected when the user has an OTP card credential.

Note that OTP card credentials may be used for various authentication methods (e.g. a one-time password list or VASCO Digipass devices).

OATH (TOTP)

Assign a step which may be selected when the user has an OATH (TOTP) credential.

OATH (TOTP) credentials may be used for second factor authentication using an authentication app, e.g. Google Authenticator.

mTAN

Assign a step which may be selected when the user has an mTAN credential.

You can assign any step here but we recommend to use the Mobile TAN pattern.

The session variable user.mobile will contain the mobile number from the mTAN credential.

FIDO UAF Authenticator

Assign a step which may be selected when the user has an FIDO UAF Authenticator credential.

For instance, assign the Out-of-band Mobile Authentication pattern.

FIDO2 Authenticator

Assign a step which may be selected when the user has a FIDO2 Authenticator credential.

Assign a FIDO2 Authentication pattern here.

Recovery code

Assign a step which may be selected when the user has a recovery codes credential.

For instance, assign a Generic Authentication Step pattern.

Not Found

Assign a step to continue with if the user does not have any supported credential.

Configuration is optional but we recommend to assign a step to handle the missing second-factor credential case. For instance, you may assign the following steps:

• User Information: to show an error message and terminate the authentication flow.
• OATH Onboarding: to register an authenticator app which supports OATH Time-based One-Time Password algorithm (TOTP).
• FIDO2 Onboarding: to register a FIDO2 authenticator such as a mobile device or USB security key.

nevisIDM Terms & Conditions Acceptance

#Identity Management #Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

nevisIDM Terms & Conditions Acceptance.

Use as a follow-up step in the Initial Authentication Flow of an Authentication Realm.

This step will show the user all the terms and conditions set for the user in nevisIDM to accept. Acceptance will be stored in nevisIDM.

LitDict keys for updating are: info.terms.welcome, title.terms

Background information can be found in the nevisIDM Developer Guide.

For information about how terms & conditions are supposed to checked in nevisAuth check Developer Use Cases.

For the data model read this chapter.

nevisIDM

Reference a nevisIDM Instance to be used for checking terms and conditions.

On Success

Configure the step to execute after the user has accepted all terms and conditions.

If no step is configured here the process ends and the user will be authenticated.

nevisIDM URL Ticket Consume

#Identity Management #Authentication

Plugin: nevisadmin-plugin-nevisidm

Provides an endpoint on a Virtual Host to consume URL tickets. The request has to contain a query parameter x containing the ticket code.

Before the ticket is validated a Gui is shown. The Gui has an info text with label info.url_ticket.welcome and a continue button.

This Gui prevents that clients consume the ticket by calling the URL (e.g. to render a preview), before the user even has a chance to click the link.

When the ticket is valid, the step assigned to On Success will be executed.

Note that when a URL Ticket credential is created for a nevisIDM user, the associated URLTicket policy defines how the link is generated and communicated.

With sendingMethod=Email the user will receive an email.

Your support team can create URL tickets using the nevisIDM Admin GUI. This requires that the policy sets urlPrefix so that the link can be generated.

URL tickets are often generated during an authentication flow. As of Aug 2022 there is no high-level step to create URL tickets, use Generic Authentication Step instead.

Virtual Host

Assign a Virtual Host.

Frontend Path(s)

Enter frontend path(s) which should be handled.

Authentication Realm

Assign an Authentication Realm.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

On Success

Assign an authentication step which shall be executed when the URL ticket is valid.

Note: this pattern does not provide any content on the exposed Frontend Path(s) and does not ensure that the caller is redirected when the authentication flow terminates.

Thus, please take appropriate measures at the end of the flow to avoid a 404 error. For instance, you may trigger a redirect at the end of your flow, or assign an URL Handler to Additional Settings.

On Expired

Assign an authentication step to execute when the URL ticket is expired.

If not set a screen with title.url_ticket and error.url_ticket.expired will be shown in that case.

On Disabled

Assign an authentication step to execute when the URL ticket or user is disabled.

If not set a screen with title.url_ticket and error.user_or_url_ticket.disabled will be shown in that case.

On Not Found

Assign an authentication step to execute when the URL ticket is not found.

If not set a screen with title.url_ticket and error.url_ticket.not_found will be shown in that case.

Allowed HTTP Methods

Define the allowed HTTP methods.

If not configured, all HTTP methods are allowed.

Additional Settings

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

Example use cases:

• URL Handling with phase AFTER_AUTHENTICATION to redirect after the authentication flow completes.
• Access Restriction to restrict access based on source IPs.
• HTTP Header Customization to add, replace, or remove HTTP headers in requests or responses.

nevisIDM User Create

#Identity Management #Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

Create a user in nevisIDM.

This pattern can only create the user but does not create any credentials (e.g. password). You need additional steps to give the user appropriate credentials.

Note that when the user is created, nevisIDM policies may be applied.

For instance, you can give your user certain roles by setting defaultAuthorizations in the profile policy. You can configure this policy in the nevisIDM Admin GUI.

The pattern is experimental and may be improved in future releases. We are looking forward to your feedback and requirements.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

On Success

Define how to continue after user creation.

On Failure

Define how to continue after user creation, if it was unsuccessful.

Mandatory User Attributes

Define which attributes will always be set for the user.

The value can be constant or determined by a nevisAuth or EL expression. User creation will fail when the value is empty.

Which attributes must be provided depends on policy configuration in nevisIDM.

How to best determine the value depends on preceeding authentication states and the (session) variables they produce.

For instance, let's assume that the email is stored in a session variable called email, the first name in firstname, and the last name in name. You can then use:

email: ${sess:email}
loginId: ${sess:email}
name: ${sess:name}
firstName: ${sess:firstname}

Optional User Attributes

Define which attributes are optional and how to provide them.

Example:

firstName: ${sess:given_name}
name: ${sess:family_name}
country: ${sess:country}

Client ID

Enter the client ID where the user shall be created.

Unit ID

Enter the unit ID where the user shall be created.

Login ID

Define how the loginId is set:

• auto: the loginId is generated. loginIdGenerator.enabled=true must be set in the client policy. This can be achieved via the nevisIDM Administration GUI.
• email: use the email for the loginId. The email must be provided via Mandatory User Attributes.
• value: the loginId must be provided via Mandatory User Attributes.

nevisIDM User Login Info Checker

#Identity Management #Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

Checks if user has previously. There are possible follow-up slot for patterns if

• no previous login
• previously logged in

It checks only for successful previous login.

The pattern is experimental and may be improved in future releases. We are looking forward to your feedback and requirements.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

On User Previously Logged In

Configure the step to execute if the user has previously logged in. If no step is configured here the process ends with AUTH_DONE.

On User Never Logged In

Configure the step to execute if the user never logged in. If no step is configured here the process ends with AUTH_DONE.

nevisIDM User Login Info Update

#Identity Management #Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

Update a user's login info in nevisIDM.

The pattern is experimental and may be improved in future releases. We are looking forward to your feedback and requirements.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

On Success

Configure the step to execute after the user's login info is updated. If no step is configured here the process ends with AUTH_DONE.

On Failure

Assign a step to execute if the nevisIDM is not able to update a User's login info.

For instance, you may assign the following steps:

• User Information: show an error message and terminate the authentication flow.

nevisIDM User Lookup

#Identity Management #Authentication

Plugin: nevisadmin-plugin-nevisidm

Look up a user from nevisIDM by Login ID.

You can use the pattern in combination with other means to check user credentials.

For instance, use in front of Authentication Cloud for passwordless authentication.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

Authentication Mode

Select interactive to prompt the user to enter a Login ID.

An input form will be shown when the query or POST parameter isiwebuserid is missing or the user is not found in nevisIDM (and On User Not Found is not set).

Select pass-through to look up the user based on Login ID Source.

In this mode no input form will be shown. Instead, a 403 response will be generated if the user is not found (and On User Not Found is not set).

Login ID Source

Enter a nevisAuth expression for the login ID which is used to look up the user.

Supported and required in authentication mode pass-through only.

Examples

• ${inargs:isiwebuserid}

On Success

For security reasons nevisIDM User Lookup alone is not sufficient to authenticate the user.

The authentication flow should contain another step which checks credentials of the user and sets an Authentication Level.

Thus, it is required to assign a step here which will be executed after the user has been looked up from nevisIDM.

Examples:

• Authentication Cloud
• Mobile TAN (mTAN)
• Generic Authentication Step

On User Not Found

Assign a step to execute in the following error cases:

• User not found (1)
• User archived or disabled (98)

The variable lasterror is not cleared from the notes and thus an error message may be displayed in the next GUI which is rendered by nevisAuth.

This setting does not apply to technical errors. In case the call to nevisIDM fails the GUI will be shown (again) and the the message error_99 will be displayed.

Buttons

Assign a Dispatcher Button to add button(s) which points to a different authentication step.

Show Client Input Field

Enable this to allow the user to enter the name of the Client (tenant) when logging in to nevisIDM.

If disabled, the input field is not shown and the Client Default is used.

Client ID

The source of the client’s external ID.

Used only when Show Client Input Field is set to disabled.

Set either this or Client Name.

Client Name

The source of the client’s name.

Used only when Show Client Input Field is set to disabled.

Set either this or Client ID. When neither is set then Default is used.

User Attributes

Enter user attributes to fetch from nevisIDM.

Important attributes are:

• extId - unique ID of the user in nevisIDM
• loginId - name which could be used to login (instead of email)
• firstName
• name - surname
• email
• mobile
• language - language stored for user (can differ from Accept-Language sent by the browser)

For a complete list check the documentation of IdmGetPropertiesState.

Some attributes (e.g. extId, email, and mobile) are always fetched as they are required by standard authentication steps.

The attributes will be stored in the user session as ch.nevis.idm.User.<attribute>.

Attributes may be used in sub-sequent authentication steps or included in application access tokens (e.g. NEVIS SecToken, SAML Token, or JWT Token).

For instance, use them in a Generic Authentication Step via the expression ${sess:ch.nevis.idm.User.<attribute>}.

User Properties

Enter user properties to fetch from nevisIDM and store in the user session.

Properties must be created in the nevisIDM via SQL.

Unit Attributes

Enter unit attributes to fetch from nevisIDM.

Possible attributes are:

• extId - unique ID of the unit in nevisIDM
• state - state of the unit in nevisIDM
• name
• displayName
• displayAbbreviation
• location
• description
• hname
• localizedHname
• ctlCreDat
• ctlCreUid
• ctlModDat
• ctlModUid

For a complete list check the documentation of IdmGetPropertiesState.

The attributes will be stored in the user session as ch.nevis.idm.Unit.<attribute>.

Attributes may be used in sub-sequent authentication steps or included in application access tokens.

For instance, use them in a Generic Authentication Step via the expression ${sess:ch.nevis.idm.Unit.<attribute>}.

Unit Properties

Enter unit properties to fetch from nevisIDM and store in the unit session.

Properties must be created in the nevisIDM via SQL.

Remember Input

Select enabled to add a Remember Input checkbox.

By ticking the checkbox the whatever has been entered by the user will be stored in a long-living cookie (named like this pattern).

Using this cookie, the login ID will be prefilled on subsequent authentications.

If no GUI is shown (e.g. to look up the user based on Login ID Source) you must select disabled.

User Not Found Error

When no user is found error code 1 is set.

If you flow shows another GUI after taking the On User Not Found exit, an error text may be displayed.

The default translation for English is: Please check your input.

In some flows (e.g. self-registration) this is not desired. Thus, you can select disabled here to remove the error code.

Use Default Profile

When enabled, the default profile will be used when the user has multiple projects.

Select disabled to show a selection dialog.

Button Order

Choose progressive to show the Continue button any additional Buttons.

Choose reverse to display the Continue button last.

nevisIDM User Update

#Identity Management #Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

Update a user in nevisIDM.

The pattern is experimental and may be improved in future releases. We are looking forward to your feedback and requirements.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

On Success

Define how to continue after user update.

Mandatory User Attributes

Define which attributes are required and how to provide them.

Example:

clientExtId: 100
email: ${sess:email}
remarks:
mobile:

Optional User Attributes

Define which attributes are optional and how to provide them.

Example:

firstName: ${sess:given_name}
name: ${sess:family_name}
country: ${sess:country}

Allow Overwrite

If enabled, the attribute or property will be stored even when there already is a stored value.

If disabled, the stored value remains unchanged in this case.

Write Empty Values

If enabled, it is possible to clear user attributes or properties. The value will be overwritten with an empty value.

This is supported only if the corresponding attribute or property is optional.

If disabled, empty values are ignored, i.e., the stored value remains unchanged.

nevisKeybox Store

#Key Management

Plugin: nevisadmin-plugin-nevisproxy

Apply the pattern to use existing key material from nevisKeybox. You can assign the pattern where-ever a key store or trust store is required.

The nevisKeybox instance is to be named default.

The pattern does not deploy any key material. This is the intended behavior and not a limitation.

To deploy a private key and certificate you may use PEM Key Store instead, for deploying trusted certificates use PEM Trust Store instead.

Slot

A Slot is a directory of a nevisKeybox instance.

By default, nevisKeybox is located at /var/opt/neviskeybox/default/. If missing please run the following command on the affected target server(s):

neviskeybox handover

A Slot may contain:

• an arbitrary number of key stores (identified by label)
• up to 1 trust store.

Label

Setting the Label is required if this pattern is used as a key store provider.

This pattern relies on the standard nevisKeybox mechanism for retrieving the passphrase of the private key.

Run the following commands on all target server(s) to ensure the passphrase can be retrieved:

neviskeybox passwd -slot <slot> -label <label> -keep

neviskeybox access -slot <slot> -label <label> -group nvbgroup

The last command will generate a shell script /var/opt/neviskeybox/default/<slot>/<label>_keypass which can be invoked by NEVIS components to retrieve the passphrase.

Due to a limitation in some NEVIS components keypass files which contain base64 encoded passphrases are not supported yet. Replace any of the following content with a simple echo returning the passphrase directly.

echo "cGFzc3dvcmQ=" | openssl base64 -d

nevisKeybox may also be integrated with nevisCred to store the passphrase in a secure place. In this case the shell script will not contain the passphrase but a call of nevisCred.

Validation

Allows to the validation in case the nevisKeybox is deployed by this project (e.g. using Generic Deployment).

nevisLogrend Connector

#Authentication #Connector

Plugin: nevisadmin-plugin-nevisauth

Use to connect to an existing nevisLogrend instance.

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

Connection URL(s)

Enter hostname:port of the nevisLogrend instance.

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.

nevisLogrend Instance

#Authentication #Instances

Plugin: nevisadmin-plugin-nevisauth

Configures a nevisLogrend Instance.

TCP Service Port

Enter the port the nevisLogrend shall listen on.

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.

HTTPs

Choose between plain HTTP, normal HTTPs and mutual (2-way) HTTPs. If enabled a Key Store is required. If set to mutual, a Trust Store is required as well.

Log Settings

Add logging configuration for nevisLogrend.

Frontend Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Frontend Trust Store

Used when mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the trust 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.

Bind Host

The host name that this nevisLogrend instance will bind to. nevisProxy will connect to the same host name.

Base Path

Set a custom path for nevisLogrend resources (e.g. CSS). The path will be made accessible in nevisProxy.

You must change the path when using multiple nevisLogrend instances on the same virtual host.

Configuration: logrend.properties

Add or overwrite properties in logrend.properties.

You can use the following expressions (format: ${...}):

• ${protocol} - depends on HTTPs setting
• ${host} - depends on Bind Host setting
• ${port} - will be replaced with TCP Service Port
• ${instance} - contains the instance name

This is an advanced setting which should be used in complex setups only. If you have to configure anything here we are looking forward for your use case.

Additional Settings

Assign an add-on pattern to customize the configuration of nevisLogrend.

nevisLogrend Log Settings

#Authentication #Add-ons

Plugin: nevisadmin-plugin-nevisauth

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

See nevisLogrend Technical Documentation, chapter Logging configuration for details.

Hint: If you only change log levels nevisAdmin 4 does not restart the component in classic VM deployment. The new log configuration will be reloaded within 60 seconds after deployment.

Examples:

ch.nevis.logrend.beans.LoginBean = 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.

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.

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.

Regex Filter

If set, messages for nevislogrend.log which match the given regular expression won't be logged.

The regular expression must match the entire line. For instance, you may use the following format to match some text:

.*some text.*

Example: drop messages caused by the Kubernetes liveness checks

.*GET /nevislogrend/health.*

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.

nevisMeta Connector

#Federation #Connector

Plugin: nevisadmin-plugin-nevismeta

Use to connect to an existing nevisMeta instance.

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

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

Connection URL(s)

Enter hostname:port of the nevisMeta instance.

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.

nevisMeta Database

#Database #Federation

Plugin: nevisadmin-plugin-nevismeta

Configures nevisMeta to use a MariaDB database for storing sessions. Assign to nevisMeta 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 nevisMeta to populate the database during startup.

Setup instructions can be found in the nevisMeta 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: umet01

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

TLS Encryption

If enabled the query parameter useSSL=true will be added to enable 1-way TLS.

If no Trust Store is assigned then trustServerCertificate=true will be added to the connection string.

Assignment of a Trust Store is recommended for production use.

Note: PostgresSQL database connection configuration doesn't support TLS connection yet.

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.

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.

nevisMeta Instance

#Federation #Instances

Plugin: nevisadmin-plugin-nevismeta

Represents a nevisMeta instance. The instance is named according to the pattern.

Hint for pattern renaming

When the 'Instance Name' property is not filled, this pattern uses the pattern's name as instance directory at the target host.

To rename this pattern, follow these steps:

1. Rename the pattern in the GUI.
2. Rename the instance directory and associated systemd files on the deployment hosts.
3. Deploy.

In case step 2 is omitted, the old instance is shut down during deployment.

For more information, see User Guide / Configuration Projects / Working with Patterns.

TCP Service Port

Port the nevisMeta 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

Configure the nevisMeta log files.

Database

Assign a nevisMeta Database.

Frontend Key Store

Assign the Key Store for the HTTPs endpoint.

If no pattern is assigned a Key Store will be provided by nevisAdmin 4 automatic key management.

Frontend Trust Store

Assign the Trust Store for the HTTPs endpoint.

If no pattern is assigned a Trust Store will be provided by nevisAdmin 4 automatic key management.

SecToken Signer Trust Store

Assign a Trust Store which is used to validate the signature of a received NEVIS SecToken.

There are 2 use cases which require validation:

• when a user accesses the nevisMeta Web Console the SecToken is signed using NEVIS SecToken / Key Store.
• when nevisAuth calls nevisMeta the SecToken is signed using nevisAuth Instance / Internal SecToken Signer.

If no pattern is assigned the trust store will be provided by nevisAdmin 4 automatic key management. However, this requires that automatic key management is used in the NEVIS SecToken and nevisAuth Instance patterns.

Client Authentication

Setting for 2-way TLS on the nevisMeta HTTPs endpoint. There are 3 options will affect the callers (e.g. nevisProxy or technical clients accessing nevisAuth REST APIs)

• required: Callers must present a client certificate.
• requested: Callers can present a client certificate.
• disabled: Callers must not use a client certificate.

The Frontend Trust Store must contain the issuing CA.

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 behaviour of this nevisMeta instance.

Custom Properties

Configure properties of the nevisMeta.

Add or overwrite properties by entering a value.

Remove properties generated by this pattern by leaving the value empty.

Examples:

Key	Value
database.migration.automatic	false

nevisMeta Log Settings

#Federation #Logging

Plugin: nevisadmin-plugin-nevismeta

The pattern defines log levels and log retention of nevisMeta.

Assign to a nevisMeta 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.

See the nevisMeta Technical Documentation, chapter Logging for details.

Hint: If you only change log levels nevisAdmin 4 does not restart the component in classic VM deployment. The new log configuration will be reloaded within 60 seconds after deployment.

Examples:

ch.nevis.nevismeta = INFO
ch.nevis.ninja = 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.

This setting applies to nevismeta.log only.

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.

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.

Regex Filter

If set, messages for nevismeta.log which match the given regular expression won't be logged.

The regular expression must match the entire line. For instance, you may use the following format to match some text:

.*some text.*

Log Targets

Select type of log4j appender.

RollingFileAppender and SyslogAppender are possible options.

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.

nevisMeta REST Service

#Federation #Applications #Experimental

Plugin: nevisadmin-plugin-nevismeta

The pattern exposes the nevisMeta REST API on a nevisProxy Virtual Host.

The REST API is exposed on the path /nevismeta/rest.

nevisMeta

Reference the nevisMeta Instance.

Virtual Host

Assign a Virtual Host which shall serve as entry point.

Authentication Realm

Assign a realm pattern which authenticates access to nevisMeta.

Application Access Token

Assign a NEVIS SecToken pattern.

The token informs nevisMeta about the authenticated user.

If you are not using automatic key management then you also have to configure nevisMeta Instance / NEVIS SecToken Trust so that the signer certificate is trusted.

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.

nevisMeta Web Console

#Federation #Applications

Plugin: nevisadmin-plugin-nevismeta

Sets up the nevisMeta Web Console, which is a component supporting the setup of OAuth2 and OpenID Connect for nevisAuth.

You can access the Web console on the assigned Virtual Host.

For instance, let's say your domain is example.com, and you have entered https://example.com as a Frontend Addresses in the Virtual Host pattern. This means that you can access the Web console on https://example.com/nevismeta/.

nevisMeta

Reference the nevisMeta Instance.

Virtual Host

Assign a Virtual Host which shall serve as entry point.

Trust Store

Assign the Trust Store provider for outbound TLS connections. If no pattern is assigned a trust store will be provided by nevisAdmin 4 automatic key management.

Hostname Validation

Enable to verify that the hostname on the certificate presented by the backend matches the hostname of nevisMeta

Key Store

Assign a key store if you want to use 2-way TLS for the connection between nevisProxy and nevisMeta.

Authentication Realm

Assign a realm pattern which authenticates access to nevisMeta.

Application Access Token

A NEVIS SecToken pattern must be assigned here.

The token will be issued after authentication and propagated to nevisMeta.

The user must have the role nevisMeta.admin.

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.

nevisProxy Instance

#Application Protection #Instances

Plugin: nevisadmin-plugin-nevisproxy

The pattern represents a nevisProxy instance.

Create at least one Virtual Host pattern and assign this pattern.

Hint for pattern renaming

When the 'Instance Name' property is not filled, this pattern uses the pattern's name as instance directory at the target host.

To rename this pattern, do the following:

1. Rename the pattern in the GUI.
2. Rename the instance directory and associated systemd files on the deployment hosts.
3. Deploy.

In case step 2 is omitted, the old instance is shut down during deployment.

For more information, see User Guide / Configuration Projects / Working with Patterns.

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

Add logging configuration for nevisProxy.

Apache SSL Cache

Configures the Apache storage type of the global/inter-process SSL Session Cache.

Uses the default high-performance cyclic buffer inside a shared memory segment in RAM.

This is the recommended and default SSL Cache for nevisProxy, which is required to enable SSL session resumption.

For more information, see the official Apache documentation about the SLLSessionCache directive.

SSL Cache Size

Configures the approximate size of the Apache SSL Cache.

The minimum allowed value is 1 KB. The maximum is 100 MB.

If not, the default from Apache is used.

SSL Cache Timeout

Configures the number of seconds before an SSL session expires in the SSL Session Cache.

For more information, see the documentation of the SSLSessionCacheTimeout directive.

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.

Startup Delay

Time to wait before checking Kubernetes readiness on startup.

You may have to increase this value if start of the nevisProxy service fails because of a failing readiness check.

Sets initialDelaySeconds of the Kubernetes startup probe.

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.

Restart Policy

Determines the instance behaviour when a configuration change triggers an optional restart.

Select one of:

• eager - the instance will restart when deploying the new configuration;

• lazy - the instance will skip optional restarts.

Restart Condition

Enter an expression to prevent nevisProxy from being restarted even if the configuration changes.

nevisProxy will only be restarted if the exit status is 0.

The expression must always terminate.

In Kubernetes deployment this setting is ignored.

A use case where this is required is when nevisProxy is deployed to multiple hosts and listens on a shared IP which is bound on 1 host only.

ip address show dev eth1 | grep -q "172.29.0.5"

Example for multiple shared IPs:

ip address show dev eth1 | egrep -q "172.29.0.5|172.29.0.6"

Recommendations:

• Run the command manually on the target host to be sure that it works for you.
• You can check the exit status of the last command by running echo $?

Password Getter

Choose between:

• recommended: uses nevisadmin for Kubernetes and classic deployments. The recommended value may change in future releases.

• nevisadmin: uses a script deployed by nevisAdmin. Does not work for PKCS11.

• nevisproxy: uses /opt/nevisproxy/bin/keystorepwget to lookup passwords for encrypted key material. Requires nevisProxy version 4.4 or later. Does not support lookup of the password for the key.pem of PEM Key Store.

• neviskeybox: uses /opt/neviskeybox/bin/keystorepwget to lookup passwords for encrypted key material. nevisKeybox must be installed on the target system. Does not work in Kubernetes deployments.

Crash Recovery Strategy

Defines how to handle process crashes.

Choose between:

• recommended: uses recover for classic and kill for Kubernetes deployments;
• recover: the child process is recovered by the parent process;
• block: every request will be blocked by 503 Service Unavailable status code;
• kill: the whole nevisproxy process (including the parent process) is killed. This works only if the owner of the child process has the permissions to kill the parent process (for example in some Kubernetes setups). Otherwise, this option works like block.

Note for block and kill: these actions take place if at least one request was being processed when the crash occurred. These features can be useful for liveness test in Kubernetes setups, so the given pod can be terminated normally in case of a crash. Using one of these options in a classic setup requires to restart nevisProxy with an external tool after a crash.

Default Virtual Host

The default virtual host of this nevisProxy instance.

The default will be used for requests without a Host header or if there is no host with a corresponding frontend address.

Additional Settings

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

nevisProxy Log Settings

#Application Protection #Logging

Plugin: nevisadmin-plugin-nevisproxy

Use to configure logging for nevisProxy. Assign to your nevisProxy Instance via Log Settings.

Default Log Level

Sets the base log level of nevisProxy.

The level will be applied to BC.Tracer.ThresholdBase as follows:

• ERROR: 3
• NOTICE: 5
• INFO: 6
• DEBUG: 7
• DEBUG_HIGH: 9
• TRACE: 10

Note that if you only change log levels nevisProxy won't be restarted during deployment. The new configuration will be activated within 60 seconds.

Log Levels

Configure log levels.

Overrules the Log Level property.

See nevisProxy Reference Guide Operation and Administration / Debugging for possible trace groups.

Enter the suffix of the name of the trace group and a log level.

Supported log levels are:

• ERROR
• NOTICE
• INFO
• DEBUG
• DEBUG_HIGH
• TRACE

Do not enter numbers for the log level as nevisAdmin4 will calculate them automatically.

The default configuration is:

NavajoOp = INFO 
NProxyOp = INFO

Debug startup:

NavajoStart = INFO

Debug HTTP Header Customization:

IW4HdrDlgFlt = DEBUG

Conditional Log Levels

Can be used to configure log levels based on conditions.

Example:

Condition:REMOTE_ADDR:CIDR/10.4.12.0/24/
Pragma: block-begin
BC.Tracer.DebugProfile.NavajoOp=4
BC.Tracer.DebugProfile.IsiwebOp=4
BC.Tracer.DebugProfile.IW4IdentCreaFlt=4
Pragma: block-end

Rotation Type

Defines how to handle log retention for the access, apache and navajo log files. Rotation is possible based on:

• file size
• time interval

Max Files

Maximum number of backup files to keep in addition to the current log file.

Max File Size

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

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

If not set the following defaults will be used:

• apache.log: 1MB
• other logs: 10MB

Rotation Interval

Interval on which a logfile will be rotated.

Compress Rotated Log

Define rotated files will be compress or not

Compression Application

You may specify a program or script which shall be used to compress rotated files.

Example:

/usr/bin/gzip

Log Targets

Select if only log file should be used or if statements should also be forwarded to syslog.

This property is relevant for classic VM deployments only. In Kubernetes the main logs are written to system out so that log messages appear in the docker logs.

Choose between:

• default - log to a file
• default + syslog - log to a file and forward to syslog
• syslog - forward to syslog only. The syslog facility is localhost3 and the threshold is INFO.

Event Log

Enable event logging capability of nevisProxy.

Event logs are not forwarded to syslog.

Server LogFormat

Allows the configuration of the LogFormat Apache directive in the navajo.xml file.

For more information, check the official Apache documentation of the directive.

nevisProxy Login Renderer

#Authentication #Add-ons #Experimental

Plugin: nevisadmin-plugin-nevisauth

Set up nevisProxy to use its own, internal renderer instead of nevisLogrend.

Assign the pattern to your realm using GUI Rendering / Login Renderer.

The nevisProxy Login Renderer is less powerful. It simply translates GUI descriptors received from nevisAuth into an HTML form, and puts them in a HTML template.

Upload the HTML templates to the realm pattern using Login Templates.

Upload a <lang>_template.html for each language that is enabled in the nevisAuth Instance.

The template files must contain the placeholder \_NEVIS_AUTH_FORM\_.

Resources referenced by these HTML template files, for example images, CSS, should be uploaded on the Virtual Host using Hosted Resources.

nevisProxy Observability Settings

#Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Sets up observability with OpenTelemetry for nevisProxy.

The OpenTelemetry settings are applied to each Virtual Host of the instance.

Trace Mode

Choose one of:

• enabled: enable the trace feature of OpenTelemetry
• disabled: disable the trace feature of OpenTelemetry

Trace Exporter Address

Enter the target URL (host:port) of the backend services to which the exporter is going to send spans. The /v1/traces path is automatically attached to it.

Metrics Mode

Choose one of:

• enabled: enable the metrics feature of OpenTelemetry
• disabled: disable the metrics feature of OpenTelemetry

Metrics Exporter Address

Enter the target URL (host:port) of the backend services to which the exporter is going to send metrics. The /v1/metrics path is automatically attached to it.

Resource Service Name

Configure the service.name key-value pair resource attribute.

Deployment Environment

Allows the configuration of the deployment.environment key-value pair resource attribute.

Sampler

Configures the available head sampling methods. Possible values are:

• AlwaysOn: Samples every trace. With high traffic in a production application it may cause significant overhead.
• AlwaysOff: Samples no traces. NevisProxy still generates the spanID for internal trace ID.
• TraceIdRatio:<ratio>: Samples a given fraction of traces based on the configured ratio.
• ParentBased:<delegate_sampler>: Makes the decision based on the parent of the span. If the span has a parent, the sampler flag of the parent span will decide. If there is no parent span, the delegate sampler is used, that can be any of the samplers above.

Trace Context Extraction

Choose one of:

• enabled: if present, extract the trace context from the HTTP request header and set it as parent for the current span
• disabled: ignore the trace context from the HTTP request header

Trace Context Injection

Choose one of:

• enabled: inject the current context (span ID, trace ID, etc) as a HTTP header to the request
• disabled: do not inject the current context in the request

Capture Request Headers

HTTP client instrumentation will capture HTTP request header values for all configured header names.

Default in nevisProxy:

Content-Type, Content-Length, User-Agent, Referer, Host, X-Forwarded-For

Capture Response Headers

HTTP client instrumentation will capture HTTP response header values for all configured header names.

Default in nevisProxy:

Content-Type, Content-Length, Content-Encoding, Location, Server, Connection, Keep-Alive, X-Forwarded-For

Metrics Timeout

Configures a timeout for the metrics observable callback.

Metrics Interval

Interval of the metrics reader to initiate metrics collection.

nevisProxy Remote / Hybrid Session Store

#Database #Application Protection

Plugin: nevisadmin-plugin-nevisproxy

Configures nevisProxy to use a remote database for storing sessions. Assign to Virtual Host as Session Store.

Use this pattern when in-memory session storage cannot be used. Note that in-memory sessions may be sufficient in the following cases:

• classic (VM) deployment: only 1 line or load balancing towards proxy is session sticky
• Kubernetes deployment: only 1 pod (not recommended)

The session store is used only when there are filters or servlet which require a session. In particular, this is the case when you assign an Authentication Realm to applications.

You can choose between remote, or hybrid session store. An overview about different types can be found here. The hybrid session store can be used in classic deployment only.

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 create the database including tables. Setup instructions can be found in the nevisProxy Technical Documentation. For details see Configuration of MariaDB-based remote session store or Configuration of Postgres remote session store.

Database Type

Choose between MariaDB and PostgresSQL.

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

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.

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

TLS Encryption

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

• disabled: Do not use TLS (default)
• trust: Only use TLS for encryption. Do not perform certificate or hostname verification. This mode is not recommended for production applications but still safer than disabled.
• verify-ca: Use TLS for encryption and perform certificates verification, but do not perform hostname verification.
• verify-full: Use 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

Session Store Peer Address

The hybrid session store requires that the nevisProxy Instance is deployed on 2 lines. For illustration purposes let's call the hosts where the instances are deployed p1 and p2.

Enter the URL where the other nevisProxy Virtual Host exposes its local session store. The URL must be reachable and should not go via a load-balancer to ensure that the request reaches the peer proxy directly.

You can use variables to ensure that the correct host name is used for the configuration on each line. For instance, the variable may be a host variable and have the following values:

• for server p1 use: https://p2:443
• for server p2 use: https://p1:443

Alternatively, you can use a semantic host name and and define this name in /etc/hosts on both p1 and p2.

Example: https://proxy-peer:443

Session Store Path

Enter the path where the local session store shall be exposed and accessed by the nevisProxy peer.

Peer Servlet Strategy

Controls the used strategy of the Peer Servlet:

• FAILOVER: The loadbalancer sends all requests to the same instance (instance A). If instance A goes down, the loadbalancer will send now all requests to instance B. The loadbalancer should only switch back to instance A if it has been restarted.
• DISTRIBUTED: The loadbalancer assure at least 90% session stickiness to both instances, for example by using the client IP address. Once the request for a session goes to the other instance, this one will get the session information from the first instance and copy into its local session store.

Session Store Access Restriction

This optional configuration is available when Mode is set to hybrid.

Assign an Access Restriction pattern to define the source IPs that are allowed to access the Session Store Path.

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.

Session Store Mode

Select one of:

• classic - sessions are stored in the remote database only. Recommended setting for production setups.

• hybrid - adds a local cache to improve the performance of the session store. This value is experimental and should only be used for test setups. This mode requires a session-sticky load balancer in front of nevisProxy. The generated configuration may change in future versions.

Database Schema Check

Select one of:

• enabled - the database schema and integrity constraints are checked on startup to ensure they match the requirements of the Remote Session Store.

• disabled - the database schema and integrity constraints are not checked on startup.

Note: On certain MariaDB versions, the check produces fake errors due to a MariaDB bug. By setting this parameter to disabled, you can skip the check.

Custom Parameters

Add custom init-param for the MySQL session store servlet.

Check the nevisProxy technical documentation for supported parameters of the servlet class ch::nevis::nevisproxy::servlet::cache::mysql::MySQLSessionStoreServlet.

Connection Parameters

Enter parameters for the DB connection string.

Enter 1 parameter per line.

Lines will be joined with &.

The default for MariaDB:

ping_timeout=2
connect_timeout=10

and for PostgreSQl:

connect_timeout=10

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

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

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.

NEVIS SecToken

#Authentication #Tokens #Add-ons

Plugin: nevisadmin-plugin-nevisauth

Assign to a realm using Application Access Tokens. This enables the realm to produce a Nevis SecToken.

To issue a SecToken and propagate it to applications also assign the pattern to the corresponding Web Application, REST Application, or SOAP Application using Additional Settings.

On the application server you may use Ninja to extract the SecToken from the Authorization header. It is transferred as the Basic Auth password.

As Ninja validates the signature of the SecToken, you have import the signer certificate into the Ninja truststore.

User Attributes

Set the content of the NEVIS SecToken.

Example:

Attribute	Variable
userid	request:UserId
loginId	session:ch.nevis.session.loginid
profileId	session:ch.adnovum.nevisidm.profileId
clientId	session:ch.adnovum.nevisidm.clientId
roles	request:ActualRoles

Supported variable scopes are:

• session - a session variable.
• request - a variable from the request.
• const - a fixed value.

This configuration should work for most backend applications, including NEVIS components.

The userid is required by Ninja and must always be set. You can use ch.nevis.session.loginid when this pattern is not part of the Initial Authentication Flow.

The loginId, profileId, clientId are required by nevisIDM.

The attribute roles is required by nevisWF and nevisMeta.

For some attributes there are multiple variables to choose from. Check the nevisAuth log with log levels of Vars set to INFO to find out which variables are available in your case.

Signer Key Store

Assign a pattern which sets the key material used for signing the token.

If no pattern is assigned automatic key management is used and the signer key will be created automatically.

Custom Header

Set a custom header instead of the default Authorization header.

NGINX Ingress Settings

#Application Protection #Kubernetes #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Assign this pattern to a nevisProxy Instance using Additional Settings.

Use in Kubernetes deployments to add annotations for the NGINX Ingress which runs in front of nevisProxy and terminates incoming connections.

Annotations

Add Kubernetes annotations to customize the behaviour of the NGINX ingress.

Restrict access based on source IP:

nginx.ingress.kubernetes.io/whitelist-source-range: 213.189.148.0/24,173.245.48.0/20,103.21.244.0/22

Increase the maximum allowed request size:

nginx.ingress.kubernetes.io/proxy-body-size: 10m

Please read Annotations - NGINX Ingress Controller for details.

TLS Secrets

Use your own Kubernetes secrets to provide the frontend key store for a Virtual Host.

Syntax is a map of (primary) frontend address of the host to secret name.

www.siven.ch: customsecretname

Secrets must be of type: kubernetes.io/tls. Secrets must be prepared before deployment. They must contain a private key (tls.key), a matching certificate (tls.crt) and should contain the CA chain (ca.crt).

If not set the Nevis operator request certificates from the cluster issuer and generates a secret for each Virtual Host to store the required key material.

Ingress Class Name

Defines the ingressClassName of the generated ingress. It can be used instead of the kubernetes.io/ingress.class annotation to select which ingress controller should handle the generated ingress. For more information see Multiple Ingress controllers.

Client Cert Authentication

Enables client certificate validation in the NGINX Ingress.

Please note that client cert validation cannot be used when the TLS connection is terminated in front of the NGINX Ingress.

Choose between:

• enabled: Request a client certificate that must be signed by a certificate that is included in the CA Secret. Failed certificate verification will result in a status code 400 (Bad Request) (unless Error Page is configured`).

• optional: Do optional client certificate validation against the CAs. Requests will fail with status code 400 (Bad Request) when a certificate is provided that is not signed by the CA (unless Error Page is configured`). When no or an otherwise invalid certificate is provided, the request does not fail, but instead the request is allowed to pass through.

• optional_no_ca: Do optional client certificate validation, but do not fail the request when the client certificate is not signed by the CAs from CA Secret. The secret still has to exist with a valid certificate.

• disabled (default): Don't request client certificates and don't do client certificate verification.

This setting is used to generate the following annotation for the NGINX Ingress:

nginx.ingress.kubernetes.io/auth-tls-verify-client

CA Secret

Enter the name of the Kubernetes secret which contains the CA certificate in the key ca.crt. If the secret does not exist it will result in 403 (Forbidden), and with a missing ca.crt key the feature will not be enabled.

Can be created with: kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt

The ca.crt file can contain multiple certificates.

CA Secret Namespace

Enter the namespace of the CA Secret.

Client Cert Validation Depth

The maximum validation depth between the provided client certificate and the CA chain. (default: 1).

You only need to increase this if you only have a parent CA in the CA Secret but want to accept client certificates which have been issued by a child CA.

Error Page

An error page which will be presented in case of certificate validation error.

If you enter a path (e.g. /errorpages/403.html) then that path will be fetched from nevisProxy.

If you enter a URL then the caller is redirected to that URL.

Propagate Client Cert

Indicates if the received certificates should be passed on to nevisProxy in the header ssl-client-cert.

Path

Define a custom path for the generated ingress resource.

Example:

/nevis/

This is an ingress specific setting, the endpoints have to be configured separately to be available under the defined path. When using side-by-side deployment, the path must be the same between the primary and secondary deployment.

TLS Settings

If disabled, the TLS related settings are removed from the generated Ingress resource, which means the default certificate provided by NGINX will be used for the TLS termination.

It's only recommended to use this option, when an additional loadbalancer is used in front of NGINX (e.g. Cloudflare), which already provides a valid certificate.

NodePort Service

If enabled, the generated services for the Ingresses will be of type NodePort. This allows direct connection to the nevisProxy instance.

OATH Authentication

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

Ask the user for a One-Time Password (OTP) from an authenticator app.

Use in combination with an app hat supports OATH TOTP, such as the Google or Microsoft Authenticator.

The nevisIDM Password Login or nevisIDM User Lookup step has to be executed before this step to set the user in the session.

This step can be used as a follow-up of nevisIDM Second-Factor Selection.

The user has to have a OATH credential with label Default. To create this credential, use the OATH Onboarding pattern.

nevisIDM

Reference the nevisIDM Instance which has been used for first factor authentication.

Authentication Level

Authentication level that is set on success.

On Success

Configure the step to execute after successful authentication.

If no step is configured here the process ends and the user will be authenticated.

Login Type

Sets the type of login identifier which will be used to look up the user.

In nevisIDM any client whose users should be able to log in with their email address must have the following entry in the Client policy: authentication.loginWithEmail.enabled=true

OATH Onboarding

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

Onboard an authenticator app that supports OATH TOTP, such as the Google or Microsoft Authenticator.

The user has to scan a QR code to complete the onboarding.

This pattern is experimental and the rendered GUI may be changed in future releases, depending on customer requirements.

The user must have been set in the session already. For instance, put a nevisIDM Password Login or nevisIDM User Lookup step in front of this step.

You may can also assign this step as Not Found to nevisIDM Second-Factor Selection.

nevisIDM

Reference the nevisIDM Instance which has been used for first factor authentication.

On Success

Assign a step to execute after onboarding the authenticator app.

We recommended to assign OATH Authentication to validate that the onboarding was successful.

Also note that the nevisIDM Second-Factor Selection pattern only considers OATH credentials which have passed the OATH Authentication once.

If no step is assigned the process ends and the user will be authenticated.

OAuth 2.0 / OpenID Connect Dynamic Client Registration Endpoint

#Federation #OAuth #OpenID Connect #Experimental

Plugin: nevisadmin-plugin-oauth

Links to a Dynamic Client Registration endpoint for OAuth 2.0 / OpenID Connect.

This pattern does not generate any endpoint, it can only be used to provide information about an external endpoint.

The information is by OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

Endpoint Path

Enter the URL of the registration endpoint.

Note that this pattern does not set up a registration endpoint, it just provides information about that endpoint.

The information is then used by the OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

The prefix exact: is not supported here, enter the path as-is.

OAuth 2.0 / OpenID Connect JWKs Endpoint

#Federation #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

Sets up a JWKs endpoint for OAuth 2.0 / OpenID Connect.

Endpoint Path

If you enter a path the REST service will be generated and exposed on the nevisProxy Virtual Host assigned to the OAuth 2.0 Authorization Server / OpenID Provider.

The prefix exact: is not supported here, enter the path as-is.

If you enter a URL no REST service will be generated. Use this variant if you want to use an external service.

Either way, the information will be used by the OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

OAuth 2.0 / OpenID Connect Metadata Endpoint

#Federation #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

Sets up a Metadata endpoint for OAuth 2.0 / OpenID Connect.

Endpoint Path

If you enter a path the REST service will be generated and exposed on the nevisProxy Virtual Host assigned to the OAuth 2.0 Authorization Server / OpenID Provider.

The prefix exact: is not supported here, enter the path as-is.

If you enter a URL no REST service will be generated. Use this variant if you want to use an external service.

Either way, the information will be used by the OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

OAuth 2.0 / OpenID Connect Pushed Authorization Request Endpoint

#Federation #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

Sets up a Pushed Authorization Request endpoint for OAuth 2.0 / OpenID Connect.

Endpoint Path

If you enter a path the REST service will be generated and exposed on the nevisProxy Virtual Host assigned to the OAuth 2.0 Authorization Server / OpenID Provider.

The prefix exact: is not supported here, enter the path as-is.

If you enter a URL no REST service will be generated. Use this variant if you want to use an external service.

Either way, the information will be used by the OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

Protected Endpoint

Set Basic authentication for REST Service of OAuth 2.0 Authorization Server / OpenID Provider.

When this property is enabled, the request must include Authentication Header. The header is a combination of clientID and clientSecret with base64 encoded

Request Timeout

Configure how the PAR request shall be valid.

For security reasons, we suggest to keep this duration as low as possible.

If not set, the default in the nevisAuth component (90s) applies.

OAuth 2.0 / OpenID Connect Token Introspection Endpoint

#Federation #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

Sets up a Token Introspection endpoint for OAuth 2.0 / OpenID Connect.

Endpoint Path

If you enter a path the REST service will be generated and exposed on the nevisProxy Virtual Host assigned to the OAuth 2.0 Authorization Server / OpenID Provider.

The prefix exact: is not supported here, enter the path as-is.

If you enter a URL no REST service will be generated. Use this variant if you want to use an external service.

Either way, the information will be used by the OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

Protected Endpoint

Set Basic authentication for REST Service of OAuth 2.0 Authorization Server / OpenID Provider.

When this property is enabled, the request must include Authentication Header. The header is a combination of clientID and clientSecret with base64 encoded

OAuth 2.0 / OpenID Connect Token Revocation Endpoint

#Federation #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

Sets up a Token Revocation endpoint for OAuth 2.0 / OpenID Connect.

Endpoint Path

If you enter a path the REST service will be generated and exposed on the nevisProxy Virtual Host assigned to the OAuth 2.0 Authorization Server / OpenID Provider.

The prefix exact: is not supported here, enter the path as-is.

If you enter a URL no REST service will be generated. Use this variant if you want to use an external service.

Either way, the information will be used by the OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

Protected Endpoint

Set Basic authentication for REST Service of OAuth 2.0 Authorization Server / OpenID Provider.

When this property is enabled, the request must include Authentication Header. The header is a combination of clientID and clientSecret with base64 encoded

OAuth 2.0 / OpenID Connect User Info

#Federation #Authentication #OAuth #OpenID Connect #Experimental

Plugin: nevisadmin-plugin-oauth

An OAuth 2.0 Authorization Server / OpenID User Info returns information about the authenticated user.

Virtual Host

Assign a Virtual Host which shall serve as entry point.

Authentication Realm

Assign a realm which shall be exposed to get user information of an OAuth2 Authorization Server or OpenID Connect Provider.

Endpoint

Enter the path where the endpoint shall be exposed on nevisProxy.

Use the exact: prefix to expose only the given path. Without this prefix sub-paths will be accessible as well. This is because a normal mapping with /* at the end will be created in nevisProxy.

Signer

Configure the key material which is used to validate tokens. This signer must be the same signer that use to sign the tokens.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector to get user information.

OAuth 2.0 Authorization Server / OpenID Provider

#Federation #Authentication #OAuth #OpenID Connect #Experimental

Plugin: nevisadmin-plugin-oauth

An OAuth 2.0 Authorization Server / OpenID Provider can issue tokens for a client, considering the requested scopes, claims, and end user consent.

See AuthorizationServer for details.

The pattern is experimental. We recommend to use it for prototyping configuration only as there may be breaking changes in future versions.

The metadata of OAuth 2.0 clients is managed in nevisMeta. The pattern nevisMeta Web Console should be configured as well.

Virtual Host

Assign a Virtual Host which shall serve as entry point.

Authorization Path

This is the path where relying parties redirect the browser to.

Example use cases:

• OAuth: acquire an access and refresh tokens
• OpenID Connect: acquire access, refresh and ID tokens

Use the exact: prefix to expose only the given path. Without this prefix sub-paths will be accessible as well. This is because a normal mapping with /* at the end will be created in nevisProxy.

Token Path

The endpoint to exchange the authorization code for tokens.

Use the exact: prefix to expose only the given path. Without this prefix sub-paths will be accessible as well. This is because a normal mapping with /* at the end will be created in nevisProxy.

Authentication Realm

Assign a realm which shall be exposed as an OAuth2 Authorization Server or OpenID Connect Provider.

Signer

Configure the key material which is used to sign issued codes and tokens.

Access Token Format

Choose between:

• JWE: the access token will be encrypted. This is the default. The token is considered opaque and thus resource servers need to call the token introspection endpoint to validate the token.

• JWS: the access token will not be encrypted. Choose this mode to get a signed token which can be validated without calling the token introspection endpoint. A JWKS endpoint will be added to this pattern in 2022.

OpenID Connect

If enabled the scope openid is allowed for this client.

OpenID Connect Issuer

Enter the issuer for OpenID Connect.

The value must be a case-sensitive URL using the https scheme that contains at least scheme and host. The port number and path component are optional. No query or fragment components are allowed.

If not set the issuer will be calculated based on:

• the first Frontend Address with scheme https of the assigned Virtual Host
• the first Frontend Path

Access Token Claims

Configure additional claims for the OAuth2.0 Access Token.

Claims are added if they have a value.

For instance, claims may be added when a certain scope is requested which includes them.

OpenID Connect defines the following scope values which may be requested to get claims:

• profile. claims: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at.
• email. claims: email, email_verified
• address. claims: address
• phone. claims: phone_number, phone_number_verified

Examples:

given_name=${sess:ch.nevis.idm.User.firstName}
family_name=${sess:ch.nevis.idm.User.name}
email=${sess:ch.nevis.idm.User.email}
mobile=${sess:ch.nevis.idm.User.mobile}

ID Token Claims

Define claims for the OpenID Connect ID token.

For the value you can use a constant, a nevisAuth expression, an EL expression, or refer to an inventory variable by using the ${var.<name>} syntax.

Note that you also have to do this for standard OpenID Connect claims. The only exception are sub, iss which will always be added.

Here are some examples:

Claim	Value
given_name	${sess:ch.nevis.idm.User.firstName}
family_name	${sess:ch.nevis.idm.User.name}
email	${sess:ch.nevis.idm.User.email}
mobile	${sess:ch.nevis.idm.User.mobile}
customer	${var.customer-number}

Which claims will be added to the ID token depends on the incoming request. Non-standard claims have to be requested using the claims request parameter. Standard claims are added when a certain OpenID Connect scope is requested:

Requested Scope	Added Claims
profile	name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at
email	email, email_verified
address	address
phone	phone_number, phone_number_verified

nevisIDM Client External ID

The extId of the client in nevisIDM where the user is stored.

REST Endpoint(s)

Add extension services for OAuth 2.0 Authorization Server / OpenID Provider

JWK Set Key ID

When set to enabled a kid header value will be added to issued access and ID tokens.

The value allows the authorization server to explicitly signal a change of key material to recipients.

The meaning of the kid header is slightly different for signed and encrypted tokens.

nevisMeta

Assign a nevisMeta Instance or nevisMeta Connector.

nevisMeta is used to lookup metadata for the given OAuth2 / OpenID Connect Setup (see Setup ID).

Setup ID

ID of the nevisMeta setup.

Create your setup via the nevisMeta Web Console.

Then the ID of the setup can be determined. There are several ways to do that:

• hover over the icon which links to the REST API
• export the setup and check the exported files
• Configure a nevisMeta REST Service, login and send a GET to /nevismeta/rest/v2/modules/oauthv2/setups/

Cache Timeout

Caching of responses from a nevisMeta instance. After this time (in seconds), a response is considered outdated and attempts are made to update it.

Auth Code Lifetime

How long an authorization code issued by the authorization server should be valid.

Refresh Token Rotation

Defines if a new Refresh Token is issued together with the Access Token on the Token Endpoint while exchanging a refresh token for a new access token (grant_type=refresh_token).

• enabled, a new Refresh Token is issued, the existing Refresh token is deleted.
• disabled, the existing Refresh token is returned and remains valid.

Remove Empty Claim(s) In Token

Defines if the empty claim(s) will appear in the Access Token and ID Token.

• enabled: the ID Token and Access Token will not include empty claim(s).
• disabled (default): the ID Token and Access Token may include empty claim(s).

JWK Set Endpoint Trust Store

Assign a trust store for the outbound TLS connection to JWK Set endpoint for ID Token encryption.

Import the CA certificate of the JWK Set endpoint into this trust store.

Since version 4.38 nevisAuth trusts CA certificates included in the JDK.

Thus, it is not required to configure this.

However, you can still configure a trust store here to be as strict as possible.

JWK Set Endpoint Proxy

Forward proxy for the connection to the JWK Set endpoint for ID token encryption. Enter the hostname:port here

Example: proxy.your-internal-domain:3128

ID Token Lifetime

How long the ID token should be valid per default (can be overwritten by the setting of individual client). At most a few minutes are recommended.

Clients

Assign OAuth 2.0 Client patterns.

Configuration is ignored if nevisMeta is used.

Supported Scopes

Enter scopes which may be requested by an OAuth 2.0 / OpenID Connect Client.

The scope openid must be allowed when OpenID Connect is used.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector. Required if nevisMeta is not used to store user consent.

Invalid Client

Configure the step to execute after error when the client sending the request is not registered.

If no step is configured here the process ends and the error will display on UI.

Invalid Redirect URI

Configure the step to execute when the redirect_uri request parameter value is not registered for the client sending the request.

If no step is configured here the flow ends and an error will be displayed.

Invalid Authorization Request

Configure the step to execute after error when the authorization request is invalid. Example:

• Cannot parse Authorization Request
• Request response-type mismatch with client configuration
• Invalid scope
• Policy not allow
• PKCE method not support
• Missing code challenge
• Plain code challenge

If no step is configured here the process ends and the error will display on UI.

Invalid Token Request

Configure the step to execute after error when token request is invalid and token error response is about to be issued.

If no step is configured here the process ends and the error response issued and return to the client.

Custom Transitions

Add or overwrite ResultCond elements in the AuthorizationServer state.

This setting is advanced. Use without proper know-how may lead to incorrect behavior.

If you use this setting, we recommend that you contact Nevis to discuss your use case.

The position refers to the list of Additional Follow-up Steps. The position starts at 1.

Examples:

ResultCond	Position
valid-token-request	1
valid-authorization-request	2

The following ResultCond elements cannot be overruled by this setting:

• authenticate:valid-authorization-request
• stepup:valid-authorization-request
• server-error
• invalid-client (configure Invalid Client instead)
• invalid-redirect-uri (configure invalid Redirect URI instead)
• invalid-authorization-request (configure Invalid Authorization Request instead)
• invalid-token-request (configure Invalid Token Request instead)

Custom Follow-up Steps

Assign follow-up steps.

The order of steps is relevant. The first step in this list has index 1.

You may reference a step in the configuration via the Custom Transitions.

Propagation Scope

Define propagation scope to store information for following AuthStates. Following are propagated data:

• Authorization request:
  • oauth2.authorization_request.[requestParameter]
• Client configuration:
  • oauth2.client.id
  • oauth2.client.metadata.[field]
• Scope configuration:
  • oauth2.scope.policy.clientCredentialsFlow
  • oauth2.scope.policy.authorizationCodeFlow
  • oauth2.scope.policy.implicitFlow
  • oauth2.scope.policy.refreshTokenRequest
  • oauth2.scope.policy.authenticationRequired
  • oauth2.scope.metadata.[field]

You can find out more information in the output session of AuthorizationServer

The propagated data is intended for logging purposes only, no standard AuthState will use it. But you can access and use with Groovy Script Step.

Note: If your flow has multiple user interactions, use the scope session to ensure that the information is available throughout the flow.

Allowed Origins

List of URL from where that allow to access the authorization endpoint and token endpoint. If this field does not set, authorization endpoint and token endpoint can be access from everywhere.

Consent Screen

Select enabled if you want to ask the user to grant consents for scopes.

Which scopes require consent can be configured in nevisMeta.

Select disabled if you don't have any scopes that require consents, or if you have to do custom consent handling.

Custom Pre-Processing

Assign a step to apply custom pre-processing logic.

This pre-processing logic is executed on the Authorization Path and Token Path.

You may assign a chain of steps to build a flow. The dispatching will continue when leaving this flow on the happy path.

For On Success exits this works automatically.

However, generic exits (i.e. Additional Follow-up Steps in Generic Authentication Step) must be marked a success exits by assigning the Pre-Processing Done pattern.

Custom Properties

Configure properties of the nevisAuth AuthorizationServer.

Add or overwrite properties by entering a value.

Remove properties generated by this pattern by leaving the value empty.

Examples:

Key	Value
propagationScope	session
nevismeta.blockClientInterval	600

Out-of-band Device Management App

#Mobile Authentication #Testing #Experimental

Plugin: nevisadmin-plugin-nevisfido

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

#Mobile Authentication

Plugin: nevisadmin-plugin-nevisfido

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

#Mobile Authentication #Authentication

Plugin: nevisadmin-plugin-nevisfido

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

#Mobile Authentication #Authentication

Plugin: nevisadmin-plugin-nevisfido

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.

PEM Key Store

#Key Management

Plugin: nevisadmin-plugin-nevisproxy

Sets up a key store.

Private key and certificate must be uploaded in PEM format. If the key is encrypted, Private Key Passphrase must be set.

For performance reasons, some issues are reported during deployment only.

The store will be deployed to /var/opt/keys/own/<name>.

Some files are generated and contain entropy (e.g. generation timestamp). To avoid fake changes on subsequent deployments, these files are cached in the nevisAdmin 4 database.

The cache has an expiration of 6 months and will also be invalidated when you change the uploaded key.pem, cert.pem, or the Key Store Passphrase.

Key Store Content

Upload your key material in PEM format.

File name	Description	Required
key.pem	private key	yes
cert.pem	own certificate	yes
ca-chain.pem	CA chain	when providing a HTTPS endpoint

Examples

How to produce the required files depends on your setup. The following examples use openssl.

Generate a private key:

openssl genrsa -des3 -out key.pem 2048

Generate a certificate signing request (CSR):

openssl req -new -key key.pem -out example.csr -subj "/C=CH/O=Example Company/CN=example.com"

If this key store is used to provide a HTTPs endpoint, the common name (CN) should contain the domain.

You can now use the CSR to request a certificate from your CA. For testing a self-signed certificate is often sufficient:

openssl x509 -signkey key.pem -in example.csr -req -days 365 -out cert.pem

Hardening

We recommend to use a variable so that you can use secrets to protect the content. This example references 2 nevisAdmin 4 secrets storing private key and own certificate:

  my-variable: 
    - inv-res-secret://f370a14a36db9f29763e8dc1#key.pem
    - inv-res-secret://147cc54a5629fadac761ec01#cert.pem

When deploying to Kubernetes, the key material may be stored in a Kubernetes secret instead. nevisAdmin 4 does not retrieve Kubernetes secrets during generation and thus all key store files must be provided. This example uses a Kubernetes secret my-secret:

  my-variable: 
    - k8s-secret-file://my-secret:key.pem/
    - k8s-secret-file://my-secret:cert.pem/
    - k8s-secret-file://my-secret:ca-chain.pem/
    - k8s-secret-file://my-secret:keystore.pem/
    - k8s-secret-file://my-secret:keystore.jks/
    - k8s-secret-file://my-secret:keystore.p12/
    - k8s-secret-file://my-secret:keypass/

The additional keystore.* files contain private key, own certificate, and the CA chain. You can use the Java keytool and openssl to produce these files.

The keypass file must be a script which is executable by nvbgroup and prints the passphrase for keystore.* and key.pem to stdout.

nevisAdmin 4 does not notice when the content of the Kubernetes secret changes. Manual interaction (terminating pods) is required in that case.

Private Key Passphrase

Enter the passphrase of the private key.

The passphrase will be used to decrypt the uploaded private key, if it is encrypted.

As the passphrase is considered sensitive information it should not be published with the project. It is therefore required to use a variable and define the value in the inventory (as a secret).

The default value of the variable is not relevant as the key is not loaded during background validation.

Key Store Passphrase

Enter a passphrase.

The passphrase will be used to protect sensitive keystore files (key.pem, keystore.pem, keystore.jks, and keystore.p12) on the target hosts.

If you do not enter any passphrase a passphrase will be generated.

As the passphrase is considered sensitive information it should not be published with the project. It is therefore required to use a variable and set the value in the inventory (as a secret).

Custom Directory Name

Enter a name for the key store directory which is used instead of the pattern name.

This configuration may be used to prevent key stores overwriting each other and is only required in complex setups with multiple projects or inventories.

Custom Root Directory Name

Set to deploy the key store underneath a base directory. The key store will be established at:

/var/opt/keys/own/<base>/<name>

This configuration may be used to prevent key stores overwriting each other and is only required in complex setups with multiple projects or inventories.

PEM Trust Store

#Key Management

Plugin: nevisadmin-plugin-nevisproxy

Set up a trust store.

The trust store is deployed to /var/opt/keys/trust/<name>.

The trust store will contain the following files:

• truststore.pem
• truststore.jks - JKS format
• truststore.p12 - PKCS12 format
• keypass - used by Java-based components to retrieve the password to access the JKS or PKCS12 files

All truststore.* files contain the same certificates.

The JKS and PKCS12 files are created during the first generation, and then stored in a cache backed by the nevisAdmin 4 database.

Trusted Certificates

Upload trusted certificate(s) in PEM format.

If you set a variable, the variable should be a list of secret file references in the inventory. Example:

  my-variable: 
    - inv-res-secret://147cc54a5629fadac761ec01#some-cert.pem
    - inv-res-secret://147cc54a5629fadac761ec01#some-other-cert.pem

Upload files for this variable by clicking Attach files in the drop-down on the inventory screen.

If you are deploying to Kubernetes you may store the trust store content in a Kubernetes secret. You can pick any name for the Kubernetes secret but the keys must be as in the following example:

  my-variable: 
    - k8s-secret-file://dummy-truststore:truststore.pem/
    - k8s-secret-file://dummy-truststore:truststore.jks/
    - k8s-secret-file://dummy-truststore:truststore.p12/
    - k8s-secret-file://dummy-truststore:keypass/

Note that nevisAdmin 4 does not notice when the content of the Kubernetes secret changes. Manual interaction (terminating pods) is required in that case.

Custom Directory Name

Enter a name for the trust store directory which is used instead of the pattern name.

This configuration may be used to prevent trust stores overwriting each other and is only required in complex setups with multiple projects or inventories.

Custom Root Directory Name

Set to deploy the trust store underneath a base directory. The trust store will be established at:

/var/opt/keys/trust/<base>/<name>

This configuration may be used to prevent trust stores overwriting each other and is only required in complex setups with multiple projects or inventories.

Pre-Process Done

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Some authentication patterns (A) support configuration of a pre-processing flow.

Examples:

• SAML SP Realm
• OAuth 2.0 / OpenID Connect Authorization Server

In general, states generated by the pre-processing flow are executed before any other states.

A pre-processing flow may consist of multiple step patterns and these steps have exits.

For exits on the happy path (i.e. On Success) the step pattern ensures that the request is dispatched into the entry state generated by A.

However, some steps, i.e. Generic Authentication Step or Dispatcher Step, don't know which exits are on the happy path. Thus, you have to assign this pattern to ensure the flow continues.

Proxy Risk Plugin

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisdetect

Set up a default configuration of a custom risk plugin to be used in nevisDetect.

The risk plugin is defined by its name, REST endpoints and descriptions.

A custom set of risk scores (defined by name and chart color shown in nevisDetect GUI) can be associated with it.

For more information, see Proxy plug-in.

URL

Service URL used to connect to the plugin

Service Mapping

Mapping entries between RESTful addressees and services. One line per mapping, for example:

requestData=/processRequestData
terminateSession=/processSessionTermination
getVersion=/getVersion

Risk Scores

Risk scores to be delivered. Please add entries in the following format:

RiskScoreName=#ColorCode

Key Store

Used when simple or mutual (2-way) HTTPs is configured. If no pattern is assigned here automatic key management will provide the key store.

Trust Store

Reference a trust store provider pattern or leave empty to manage the trust store with nevisAdmin.

Web App URL

BehavioSec Dashboard URL

Description

Add description(s) for this proxy plugin

REST Service

#Application Protection #Applications

Plugin: nevisadmin-plugin-nevisproxy

Set up access to a backend application providing a REST API.

Virtual Hosts

Assign Virtual Host patterns which shall serve as entry point for this application.

Frontend Path(s)

The (base) path of the application.

Examples:

• /app/ - defines a base path. Any requests which have a path component starting with /app/ will be sent to this application.
• / - forward all requests to this application. Use this only when there are no other applications or hosted resources.
• exact:/app.html - matches requests to /app.html only (query parameters are allowed). Use this for single-page applications which don't require any additional resources.

Note that if the frontend path is different from the path used within Backend Addresses then URL rewriting will be configured to correctly route requests and responses between clients and backends.

Authentication Realm

Optionally assign a realm to protect this application or service.

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.

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.

Backend Addresses

Enter the complete URLs (scheme, host, port and path) of the backend services.

Note:

• all URLs must use the same scheme and path.
• automatic path rewriting will be performed when the path differs from the Frontend Path.

In case you are setting multiple addresses, use Load Balancing to select a request dispatching strategy.

Load Balancing

Select a request dispatching strategy when several Backend Addresses are configured.

• disabled - all requests will be sent to the first address. If this address is not available the next address is chosen;
• round-robin - one of the addresses will be picked up for each request using a round-robin rotation;
• session-sticky - one of the addresses will be picked up for each new session using a round-robin rotation, then subsequent requests for the session will be sent to the same address.

Failover strategy:

• When the selected backend cannot be accessed, nevisProxy will attempt to use another one.
• Once the said backend can be accessed again, it can be picked up for new requests if the load balancing is round-robin, or for new sessions if the load balancing is disabled or session-sticky. The requests linked to an existing session will still go to the current backend until the end of the session if the load balancing is disabled or session-sticky.

Key Store

Optional setting to use a client certificate for connecting to HTTPS backends.

Send Certificate Chain

Choose which certificates are sent to the backend during mutual authentication:

• disabled: Send the client certificate from the Key Store;
• enabled: Send the certificate chain from a PEM Key Store or a nevisKeybox Store. The certificate chain file must contain the client certificate and the intermediate CA certificates.

Trust Store

Optional setting for enabling trust to HTTPS backends.

For securing production environments:

• set Backend Addresses starting with https://
• assign a Trust Store pattern containing the certificates required for verifying the backend certificate
• set Hostname Validation to enabled

Hostname Validation

Enable to verify that the hostname on the certificate presented by the backend matches the hostname configured in Backend Addresses

Host Header

Defines the Host header for requests forwarded to the application.

When backend is selected then nevisProxy uses the host part of the backend address that has been selected. This is the default behaviour and similar to what a browser would do. Therefore, this configuration should work in most cases.

When client is selected then nevisProxy will keep the Host header as received from the client. The following init-param will be generated:

<init-param>
  <param-name>HostName</param-name>
  <param-value>ENV:HTTP_Host;</param-value>
</init-param>

The configuration is dynamic to support virtual hosts with multiple frontend addresses. Note that this may be less secure. Even though browsers do not allow this clients may sent an arbitrary value for the Host header. It is therefore recommended to test how your application behaves in this case.

Response Rewriting

Use this feature to replace backend hostnames in responses or set to custom to configure complex rewriting use cases.

• off disables automatic response rewriting
• header enables auto rewrite for response headers (including Set-Cookie header)
• complete enables auto rewrite for the entire response (including body)
• custom configure Response Rewriting Settings via Additional Settings

CSRF Protection

Cross-Site Request Forgery (CSRF) is an attack that forces an authenticated user to send unwanted requests.

• off (default) - no CSRF protection. Recommended for APIs which may be called from other sites.
• header-based - GET and HEAD requests are allowed. For other requests Referer and Origin headers must match the Host header.

JSON Validation

Choose between:

• enabled - all requests which have a request body must be valid JSON.
• log only - similar to enabled but violations are not blocked, only logged.
• content-type - validation is performed only when the Content-Type header matches application/json.
• disabled

Allowed HTTP Methods

Define the HTTP methods allowed for this application.

Methods which are listed here must also be allowed on the Virtual Host.

You may also use the following method groups:

• ALL-HTTP includes common HTTP methods.

  These are: GET, POST, HEAD, DELETE, TRACE, CONNECT, OPTIONS, PUT, PATCH

• ALL-WEBDAV includes all methods required for WebDAV.

  These are: MERGE, UNCHECKOUT, MKACTIVITY, PROPPATCH, LOCK, CHECKOUT, SEARCH, COPY, MKCOL, MKWORKSPACE, PROPFIND, UPDATE, REBIND, BASELINE-CONTROL, UNBIND, CHECKIN, VERSION-CONTROL, UNLOCK, LABEL, MOVE, ACL, BIND, REPORT

To remove methods from ALL-HTTP and ALL-WEBDAV simply add the method with a - sign in front of it.

Session Termination

Use this feature to terminate sessions on the backend application.

nevisProxy will send a GET request to this path when the nevisProxy session is terminated (due to logout or session timeout).

Custom Parameters

Add custom init-param(s) for the Http(s)ConnectorServlet. For example: ConnectionRetries=10

Please check the nevisProxy technical documentation for supported init-params of the servlet classes ch::nevis::isiweb4::servlet::connector::http::HttpConnectorServlet and ch::nevis::isiweb4::servlet::connector::http::HttpsConnectorServlet.

Request Validation Settings (ModSecurity)

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Use the pattern to customize ModSecurity rules. Assign the same pattern to multiple applications to enforce a common configuration.

Do not use rule IDs in the range 500001-500999 as they are reserved for Nevis internal purposes.

Deploying changes to an existing pattern triggers a restart of nevisProxy if the RestartPolicy is set to eager.

Restarting the instance better suits large and highly customised ModSecurity setups.

If you prefer to let nevisProxy reload the ModSecurity configuration on-the-fly, set the RestartPolicy to lazy in the corresponding nevisProxy Instance patterns.

Validation Scope

Sets the scope of request validation:

• all: validation will be applied to all requests. This includes authentication.

• backend: validation will be applied to requests which are sent to the backend application. The authentication is excluded.

• authentication: validation will be applied to requests which are sent to nevisAuth.

Log Only Mode

Allows to use the request validation settings in log only mode.

Paranoia Level

Sets the paranoia level of the ModSecurity OWASP Core Rule Set (CRS). Please see https://coreruleset.org/faq/ for more details.

• Paranoia level 1 (PL1) is recommended for beginners and setups with standard security requirements. If you encounter false positives at PL1 OWASP recommends to raise an issue at their Github site.

• Paranoia level 2 (PL2) includes SQL, XSS and code injection rules. PL2 is recommended for setups with elevated security requirements and advanced users.

• Paranoia level 3 (PL3) enables additional rules and keyword lists to cover less common attacks. Consider PL3 if you are experienced at handling false-positives and for sites with high security requirements.

• Paranoia level 4 (PL4) also restricts special characters. PL4 may produce a lot of false positives so please do extensive testing before going into production.

Rule Modifications

Use to add, modify, or remove ModSecurity rules.

Use the Rule recommender to white-list requests. Click the link to open the dialog, then paste log snippets from the nevisProxy navajo.log for requests which have been blocked by ModSecurity.

The log statement must contain the trace group IW4ModsecF and at least the id of the ModSecurity rule which has blocked the request. Example:

2020-07-21 13:00... IW4ModsecF ... Matched "Operator `Rx' with parameter ... against variable `REQUEST_BODY' ... [id "930100"] ... [uri "/nevisidm/admin/"]

The recommender will propose ModSecurity modifications to prevent these requests from being blocked in the future. The modifications will be as specific as possible, including the path, as well as parameters from the request. Please review the recommended modifications and adapt as required.

You may also enter your own rules or modifications directly, skipping the recommender dialog. Check the ModSecurity documentation for further information on how to modify rules.

Both exception modifications or whitelist modifications are allowed in this box. The pattern ensures that the statements are included into the correct place in the generated ModSecurity configuration.

New ModSecurity rules require a rule ID which has to be unique within this pattern and must not used in the rule set. According to ModSecurity documentation the range 1-99999 is reserved for local (internal) use. The rule recommender will use the range 10001-10999.

Whitelist Modifications

Configure whitelist modifications.

As explained in the ModSecurity documentation whitelist modifications are applied before including the core rules.

Note that new rule may require a rule ID which has to be unique for this pattern. Use the range 1-99,999 as it is reserved for local (internal) use.

• Remove rule with ID 900200 for the path /app/some.html:

SecRule REQUEST_URI "@streq /app/some.html" "pass,nolog,id:1000,ctl:ruleRemoveById=200002"

Exception Modifications

Configure exception modifications.

As explained in the ModSecurity documentation exception modifications are applied after including the core rules.

Note that new rule may require a rule ID which has to be unique for this pattern. Use the range 1-99,999 as it is reserved for local (internal) use.

• Remove rule with ID 900200:

SecRuleRemoveById 900200

• Whitelist body parameter upload for all rules:

SecRuleUpdateTargetByTag ".*" "!ARGS:upload"

• Whitelist body parameter upload for rule ID 123:

SecRuleUpdateTargetById 123 !ARGS:upload

• Add a new rule which allows the HTTP methods used for WebDAV:

SecAction \
 "id:1,\
  phase:1,\
  nolog,\
  pass,\
  t:none,\
  setvar:'tx.allowed_methods=GET HEAD POST OPTIONS PUT PATCH DELETE CHECKOUT COPY DELETE LOCK MERGE MKACTIVITY MKCOL MOVE PROPFIND PROPPATCH PUT UNLOCK'"

Template Parameters

Define parameters which may be used within rules.

Enter a map of key-value pairs.

For instance, a parameter my_param could be defined as follows:

my_param: 900200

These parameters can be used in:

• Additional Rules
• Whitelist Modifications
• Exception Modifications

The expression formats are:

${param.<name>}:

• name found: parameter value is used.
• name missing: expression is not replaced.

${param.<name>:<default value>}:

• name found: parameter value is used.
• name missing: default value will be used.

In <default value> the character } must be escaped as \}.

In case a variable my-variable is used this is the format you need to use in the inventory:

my-variable: |
  my_param: 900200

Rule Bundle

Add a Rule Bundle pattern for global or group ModSecurity rule configuration.

Response Rewrite Settings

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Use the pattern to replace the hostname of the backend or transform response bodies using regular expressions.

Backend Host Rewriting

• off disables automatic response rewriting
• header enables auto rewrite of response headers (includes cookies)
• complete enables auto rewrite for response headers and body

Response Body Rewriting

Configure response body rewrite rules.

In the first column enter a regular expression. In the second column enter the replacement.

Rules will be applied to each line of the response body.

Response body rewriting can be a complex task and should only be done if there is no other way. Use the browser's network tracing to have a look at the responses to find out what needs to be rewritten.

Examples:

Regex	Replacement	Description
http://my-backend.intra.siven.ch	https://www.siven.ch	replace an internal host name with the external one
https?://[^/]+(/.*)	$1	make links relative
<base href="/">	<base href="/app/">	apps which have a context root of / may require a rewrite of the base element

For further information see documentation of RewriteFilter in nevisProxy Technical Documentation.

Response Body Content Types

Enter regular expressions to match the Content-Type of responses. If the expression matches, the response body is rewritten.

Role Check Step

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Role based access control (RBAC) is usually application-specific and roles are checked in nevisProxy. For this approach, use the Authorization Policy pattern instead.

Use this pattern only when you have to make decisions based on roles in a flow of an Authentication Realm.

For instance, you may use this step to grant or restrict access to all applications protected by the realm based on roles, or to dispatch into follow-up steps for additional tasks (e.g. enforcing stronger authentication, or performing onboarding steps).

Role(s)

Enter 1 or multiple roles, 1 role per line.

If the user has any of these roles, the flow will continue with Found.

If the user has none of these roles, the flow continues with Not Found instead.

Roles managed in nevisIDM have the format <application>.<name>.

Examples:

• MyApp.Admin
• nevisIDM.Root

Any Found

Assign a step to continue with when the user has any of the configured roles.

If no step is assigned, the authentication flow will be done and the user is authenticated.

None Found

Assign a step to continue with when the user has none of the configured roles.

If no step is assigned, error code 403 will be returned in this case.

Rule Bundle (ModSecurity)

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Use the pattern to further customize ModSecurity rules.

Assign the same pattern to multiple Request Validation Settings patterns to easily configure and maintain global or group ModSecurity rule configurations.

Do not use rule IDs in the range 500001-500999 as they are reserved for Nevis internal purposes.

Whitelist Modifications

Configure whitelist modifications.

As explained in the ModSecurity documentation whitelist modifications are applied before including the core rules.

If both the Request Validation Settings and the Rule Bundle pattern have whitelist modifications configured, first the Rule Bundle, then the Request Validation Settings whitelists will be applied.

Note that new rule may require a rule ID which has to be unique for this pattern. Use the range 1-99,999 as it is reserved for local (internal) use.

• Remove rule with ID 900200 for the path /app/some.html:

SecRule REQUEST_URI "@streq /app/some.html" "pass,nolog,id:1000,ctl:ruleRemoveById=200002"

Exception Modifications

Configure exception modifications.

As explained in the ModSecurity documentation exception modifications are applied after including the core rules.

If both the Request Validation Settings and the Rule Bundle pattern have exception modifications configured, first the Request Validation Settings, then the Rule Bundle modifications will be applied.

Note that new rule may require a rule ID which has to be unique for this pattern. Use the range 1-99,999 as it is reserved for local (internal) use.

• Remove rule with ID 900200:

SecRuleRemoveById 900200

• Whitelist body parameter upload for all rules:

SecRuleUpdateTargetByTag ".*" "!ARGS:upload"

• Whitelist body parameter upload for rule ID 123:

SecRuleUpdateTargetById 123 !ARGS:upload

• Add a new rule which allows the HTTP methods used for WebDAV:

SecAction \
 "id:1,\
  phase:1,\
  nolog,\
  pass,\
  t:none,\
  setvar:'tx.allowed_methods=GET HEAD POST OPTIONS PUT PATCH DELETE CHECKOUT COPY DELETE LOCK MERGE MKACTIVITY MKCOL MOVE PROPFIND PROPPATCH PUT UNLOCK'"

SAML IDP

#Federation #Authentication #SAML

Plugin: nevisadmin-plugin-nevisauth

Sets up a SAML Identity Provider (IDP).

The Authentication Realm provides Single-Sign-On.

By default, only SP-initiated authentication is allowed. This method is most secure and standard.

Service providers (SP) may initiate authentication by sending an AuthnRequest to any of the configured Frontend Path(s).

You can enable IDP-initiated authentication via the Authentication Type drop-down.

SAML Issuer

Configure the Issuer used by this IDP.

The issuer can be an arbitrary String but it is a common practise to use the URL of the IDP.

Example: https://idp.example.org/SAML2/

Virtual Host

Assign a Virtual Host which shall serve as entry point.

Frontend Path(s)

Define paths for the following cases.

• SP-initiated authentication

Service providers may send a parameter SAMLRequest containing an AuthnRequest (using POST or redirect binding) to request authentication. On successful authentication the IDP returns a SAML Response.

On entry an initial session will be created. The session may expire during authentication due to timeout.

When this happens an error page (name: saml_dispatcher) with title title.saml.failed and error message error.saml.failed will be rendered.

• SP-initiated logout

Service providers may send a LogoutRequest (POST or redirect binding) to logout from this IDP and other service providers.

• IDP-initiated logout

Applications may have a link pointing to the IDP to trigger a global logout.

This link may point to:

• <path>/logout: to show a logout confirmation page (GUI name: saml_logout_confirm, label: info.logout.confirmation)
• <path>/?logout: to skip the logout confirmation page.

If a Referer header has been sent by the browser, the logout confirmation page will have a cancel button which redirects to the referer. Note that if the SP is NEVIS you may have to adapt the Security Response Headers of the Virtual Host. By default, the header Referrer-Policy: strict-origin-when-cross-origin is set and this will prevent the path being sent so the cancel button will redirect to /.

During SAML logout the IDP renders a GUI named saml_logout with the following hidden fields:

• saml.logoutURLs: the URL of the SPs including LogoutRequest message as query parameter
• saml.logoutURL: the URL to redirect to after successful logout

The default nevisLogrend template contains Javascript to invoke all saml.logoutURLs and redirect to saml.logoutURL after all requests have been sent. This is a best effort operation which means that the JavaScript does not check if the logout was successful.

• IDP-initiated authentication

Requests to the base path without SAMLRequest will trigger IDP-initiated authentication.

In this case the following parameters must be sent:

• Issuer: as entered for a SAML SP Connector
• RelayState: this parameter is returned to the SAML SP together with the Response

Authentication Realm

Optionally assign a realm to protect this application or service.

Service Providers

Define the SAML Service Providers which can use this IDP.

For each SP an own AuthState of class IdentityProviderState will be generated.

SAML Signer

Configure the key used by this Identity Provider to sign outgoing SAML Assertions.

Metadata Service

When enabled a SAML Metadata Service will be generated which can be accessed on the Metadata Service Path.

The SAML Metadata Service is not protected by authentication.

Metadata Service Path

Enter a path where the SAML Metadata Service shall be exposed on the assigned Virtual Host.

Authentication Type

Select which authentication types are allowed:

• SP-initiated: recommended
• IDP-initiated: less secure as no AuthnRequest is sent.

Dispatch Error Redirect

URL to redirect to when the IDP is unable to handle the request.

There are 3 cases:

• a session is required for the current operation (e.g. logout, session upgrade) but no session was found.
• the authentication type (SP-initiated or IDP-initiated) is not allowed.
• not enough information for IDP-initiated authentication (e.g. missing query parameters).

If no URL is configured, the IDP will redirect back to the Referer, or / if no Referer header has been sent.

Logout Confirmation

Choose between:

• enabled - shows a logout confirmation screen when the path ends with /logout
• disabled - never shows a logout confirmation screen

Please be aware that we plan further changes which affect SAML logout and thus this setting may change or even disappear in a future release.

Custom Pre-Processing

An an authentication step to execute before dispatching according to the issuer.

SAML IDP Connector

#Federation #SAML

Plugin: nevisadmin-plugin-nevisauth

The pattern represents the connection to a SAML IDP.

You can use the pattern in:

• SAML SP Realm
• SAML Response Consumer

IDP Issuer

Enter the Issuer of the IDP.

Example: https://idp.example.org/SAML2

The Issuer is used to look up the trust store containing the signer certificate of the IDP.

For this purpose a KeyObject element will be configured in the nevisAuth esauth4.xml using the Issuer for the attribute id.

IDP URL

Enter the Location of the SAML SingleSignOnService. This may be a URL or a path on the same virtual host.

nevisAuth will send an AuthnRequest to this location to delegate the authentication or session upgrade process to the IDP.

By default, the AuthnRequest contains a RequestedAuthnContext which specifies the required authentication level. You can disable this feature via Custom Properties.

Message Decryption Key Store

Assign a pattern to configure the private key to decrypt the incoming message of the identity provider.

Binding: Outbound

Configure the outgoing binding. This affects how the SAML AuthnRequest is sent to the IDP.

Signature Validation

Configure for which SAML elements signature validation shall be performed.

It is recommended that the IDP signs the entire Response as this is the most secure mode.

If only the Assertion is signed nevisAuth will perform additional checks to prevent attack scenarios.

IDP Signer Trust Store

Assign a pattern to configure the signer certificate of the identity provider.

Attribute Extraction

Configure to extract attributes from SAML assertions and store them in a session variable.

Examples:

Session Variable	Attribute
sess:user.email	email
sess:user.mobile	mobile

Audience Check

Define how to validate the optional Audience element of received SAML assertions.

• disabled - Audience is not checked
• lax - if present the Audience has to match the Allowed Audience
• strict - the Audience element must be present and must match the Allowed Audience

Allowed Audience

Enter a regular expression to validate the Audience of a received SAML Assertion.

Allowed Lifetime

SAML assertions have an issue timestamp. nevisAuth validates the timestamps of SAML assertions received from the IDP.

Some identity providers create the SAML assertion on login and return the same assertion as long as the session is active on the identity provider.

In this case enter a duration which is at least as long as the maximum session lifetime on the identity provider.

For identity providers which always return a new assertion (e.g. nevisAuth) the value can be very low (e.g. 30s)

Enter unlimited to disable the maximum lifetime check for received SAML Responses. This sets in.max_age to -1 in the generated ServiceProviderState.

Selection Expression

The expression configured here will be used by nevisAuth to determine the IDP for SP-initiated SAML flows.

Configuration is required there are multiple SAML IDP Connector patterns assigned to the same SAML SP Realm.

For IDP-initiated flows the expression is not relevant as the IDP can usually be determined based on the Issuer contained in received SAML messages.

You may enter nevisAuth or EL expressions.

You must ensure that there is always exactly 1 expression which evaluates to true

If there is no match or multiple IDPs are applicable then 403 Forbidden is returned.

Examples:

• IP of the user starts with 10.0.106: ${request:clientAddress:^10.0.106}
• Request path starts with /myapp: ${request:currentResource:(http.?.//[^/]+)/myapp.*}

Artifact Resolution Service

Configure to enable HTTP Artifact Binding.

Enter the Location of the ArtifactResolutionService. This information can usually be found in the SAML metadata provided by the IDP.

The location must be a valid URL. In case of https:// import the CA certificate of the endpoint into the backend truststore of nevisAuth.

When a SAML artifact is returned by the IDP the service provider will send a request to the artifact resolution service to retrieve the SAML assertion.

Authentication Request: Lifetime

SAML authentication requests have a maximum lifetime which may be validated by the identity provider.

The lifetime should be low but high enough so that the authentication works on slow network connections.

Custom Properties

Enter custom properties for the nevisAuth ServiceProviderState.

Example: overwrite authnContextClassRef in the AuthnRequest

out.authnContextClassRef = urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified

Example: remove authnContextClassRef from AuthnRequest

out.authnContextClassRef =

Logout Type

Setting for SP-initiated logout, logout methods can be chosen

• IMPLIED: the logout method will be used by getting configuration of Binding: Outbound
• POST: force logout method to POST
• SOAP: force logout method to SOAP. This only work when IdP SAML Response contain SessionIndex.

Custom Transitions

Add or overwrite ResultCond elements in the ServiceProviderState state.

This setting is advanced. Use without proper know-how may lead to incorrect behavior.

If you use this setting, we recommend that you contact Nevis to discuss your use case.

The position refers to the list of Additional Follow-up Steps. The position starts at 1.

Examples:

ResultCond	Position
status-Responder	1
status-Responder-AuthnFailed	2

The following ResultCond elements cannot be overruled by this setting:

• ok
• logout
• logoutCompleted
• logoutFailed

Custom Follow-up Steps

Assign follow-up steps.

The order of steps is relevant. The first step in this list has index 1.

You may reference a step in the configuration via the Custom Transitions.

SAML Response Consumer

#Federation #Authentication #SAML #Experimental

Plugin: nevisadmin-plugin-nevisauth

The pattern exposes an authentication service on the assigned Virtual Host.

The service can consume incoming SAML Response or SAML artifact messages, and can execute an optional post-processing flow.

The overall process may work as follows:

• Consume a SAML Response and RelayState on the Frontend Path. The RelayState must contain the URL of an application.
• If configured, execute the Post-Processing Flow.
• The authentication is now done.
• Redirect to the RelayState parameter pointing to the application.
• Assuming the application is protected by the realm assigned to this pattern, the caller is allowed access.

Frontend Paths

Enter a path where SAML Response messages sent by an external IDP shall be consumed.

The external IDP may send messages using POST or redirect binding.

SAML IDP Connector(s)

Assign a SAML IDP Connector for each SAML Identity Provider.

SP-initiated authentication is not supported and thus the Selection Expression of the connector patterns is ignored.

SAML Signer

Configure the key material for signing outbound SAML messages.

The following messages will be signed: ArtifactResolve, LogoutRequest, LogoutResponse

SAML Artifact Binding

To use SAML Artifact Binding with a certain IDP, the Artifact Resolution Service must be configured in the SAML IDP Connector.

The flow begins with the IDP sending an ArtifactResponse message to any of the configured frontend paths.

Now an ArtifactResolve message will be created and signed using this certificate. The message will then be sent to the IDP via a server-to-server call.

Authentication Processing Flow

Assign a step to apply custom post-processing logic, e.g. to enrich the authenticated user.

Virtual Host

Assign a Virtual Host which shall serve as entry point.

Authentication Realm

Optionally assign a realm to protect this application or service.

SAML Issuer

Configure the Issuer used by this SAML Service Provider (SP).

This setting is used only when Artifact Binding is used.

Example: https://sp.example.org/SAML2

Logout Processing Flow (Experimental)

Assign a step to apply custom post-processing logic which is executed when a LogoutRequest or LogoutResponse message is received.

SAML SP Backend Integration

#Authentication #Add-ons #SAML #Tokens

Plugin: nevisadmin-plugin-nevisauth

Assign to applications using Additional Settings to send a SAML Response to an SP deployed on the backend application server.

The assigned SAML Token has to have Token Type set to Response.

SAML Token

Assign a SAML Token pattern.

The referred pattern must:

• have Token Type set to Response
• be assigned to the correct Realm pattern(s)

Assertion Consumer Service Path

Enter a sub-path of the application to sent the POST request to.

The POST request is sent by a DelegationFilter mapped in phase AFTER_AUTHORIZATION.

RelayState

Enter a static value, or a nevisProxy expression, which defines the value of the POST parameter RelayState that shall be sent to the SP together with the SAML Response.

Whether a RelayState is required depends on the SP. Many SPs expect a URL and will redirect to this URL once the SAML Response has been successfully validated.

Custom Parameters

Define custom init-params for the nevisProxy DelegationFilter which propagates the SAML Response to the backend.

This setting is experimental and may be adapted in future releases.

Examples:

• DelegatePostPolicy: override - create a new POST request and send it to the Assertion Consumer Service Path. The response is returned to the client which means that the original (GET) request is lost. However, the SP can redirect to the application. This mode should be preferred for proper SP integration.

• DelegatePostPolicy: sidecall - send a POST request to the Assertion Consumer Service Path but do not return the response to the client. Afterwards, the original (GET) request is sent. This mode may be required in case the response of the POST request does not redirect to the application.

SAML SP Connector

#Federation #SAML

Plugin: nevisadmin-plugin-nevisauth

The pattern defines the connection to a SAML Service Provider (SP).

Assign the pattern to a SAML IDP.

SP Issuer

Configure the issuer used by the SAML service provider.

SP URL - Assertion Consumer Service(s)

Enter the Assertion Consumer Service URL of the SP.

Enter multiple values if the same SP can be accessed via multiple URLs.

If the SP is provided by a SAML SP Realm the URLs are structured as follows:

• scheme, host and port: Frontend Addresses of each Virtual Host where the SAML SP Realm is used.
• path component: Assertion Consumer Service of the SAML SP Realm.

The URLs are used during SP-initiated SAML authentication to validate incoming SAML requests. The assertionConsumerServiceURL attribute of received SAML AuthnRequest messages must match one of these URLs.

The first URL is also used for IDP-initiated authentication (property spURL of the IdentityProviderState).

IDP-initiated authentication may be triggered by sending a request to any of the Frontend Path(s) of the SAML IDP. The following parameters must be provided either in the query or as POST parameters:

• Issuer - the unique name used by the SP (also called entityID in the SAML metadata).
• RelayState - will be sent back to the SP together with the SAML Response when authentication is done. In case the SP is setup by a SAML SP Realm this should a URL of an application protected by this realm.

SP URL - Single Logout Service

Enter the Single Logout Service URL of the SP.

If omitted the Assertion Consumer Service URL is used.

SP Signer Trust Store

Configure the trust store used to validate incoming SAML messages (e.g. AuthnRequest, LogoutRequest) which are sent by this SP.

Encrypted Content

Select a part of the outgoing message going to be encrypted from the service provider.

Message Encryption Trust Store

Assign a pattern to configure the certificate to encrypt the outgoing message to the service provider.

Outbound Binding

The Outbound Binding controls how SAML messages are returned to the service provider.

Choose a binding which is supported by the service provider.

Use http-redirect when the SAML Response has to be returned using a 302 Redirect.

Use http-post to generate a self-submitting form which produces a POST request. This binding is recommended as SAML Response messages will include a signature.

When http-post is selected, HTML encoding will be applied to the RelayState parameter to include it in the self-submitting form. This ensures that the parameter can be returned to the service provider, even when it contains special characters.

Subject

Set to use a different subject for the SAML Assertion.

Examples:

• ${sess:ch.nevis.session.loginid} - what the user has entered to login

Subject NameID Format

Set the format of the NameID element.

Examples:

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Subject Confirmation

Many SAML service providers require a subject confirmation element to be present in the SAML assertion.

Select bearer to add a bearer subject confirmation.

Further options may be provided in future releases.

It may be required to set additional properties. Consult the documentation of the nevisAuth IdentityProviderState and apply them via Custom Properties.

User Attributes

Add attributes to SAML assertions.

Values may be static, produced by a nevisAuth expression (${...}), or an EL expressions (#{...}). This table shows how to enter the configuration:

Attribute	Value
some_attribute	${...}
some_attribute	#{...}
some_attribute	some_value

Set the log level Vars = DEBUG and check the nevisAuth esauth4sv.log to find out which variables may are available.

For instance, if you have a nevisIDM Second-Factor Selection pattern in your authentication flow, you can use the expression ${sess:user.mobile} to add a mobile attribute.

Multi Value

This setting defines how multi-value attributes are added to the SAML Assertion.

Example for enabled:

<saml2:Attribute Name="example">
  <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">value 1</saml2:AttributeValue>
  <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">value 2</saml2:AttributeValue>
</saml2:Attribute>

Example for disabled:

<saml2:Attribute Name="example">
  <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">value 1,value 2</saml2:AttributeValue>
</saml2:Attribute>

Authentication Context Class

Select nevis if the SAML service provider is provided by a SAML SP Realm and you want to use Authorization Policy to specify the required Authentication Level for application protected by that realm.

When nevis is selected the roles and attained authentication level are added to the SAML Response via an AuthnContextClassRef element.

Example:

<saml2:AuthnStatement AuthnInstant="2021-05-07T06:48:14.967Z">
  <saml2:AuthnContext>
    <saml2:AuthnContextClassRef>...,nevisIdm.Admin,urn:nevis:level:1</saml2:AuthnContextClassRef>
  </saml2:AuthnContext>
</saml2:AuthnStatement>

Select PasswordProtectedTransport to add the following standard context:

<saml2:AuthnStatement AuthnInstant="2021-05-07T06:48:14.967Z">
  <saml2:AuthnContext>
    <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
  </saml2:AuthnContext>
</saml2:AuthnStatement>

Select none to not add any AuthnContext element.

Audience Restriction

Configure if an <AudienceRestriction> element shall be added to generated SAML assertions and what the element shall contain.

Choose between:

• automatic: use Custom Audience, if configured, and SP Issuer otherwise.
• issuer: use SP Issuer.
• custom: use Custom Audience.
• none: no <AudienceRestriction> element is added.

Custom Audience

Set custom audience(s).

If you need multiple <Audience> elements in the generated <AudienceRestriction>, enter multiple lines.

This configuration is ignored when Audience Restriction is set to issuer or none.

Check the documentation of the service provider on what is expected.

Assertion Lifetime

On successful authentication this IDP will issue a SAML assertion.

The SAML assertion is re-created on each session upgrade to avoid replay attacks.

The lifetime of the assertion should be low but high enough so that the authentication works on slow network connections.

The SAML assertion will be consumed by the service provider. The service provider should then use a different mechanism to track the user session (e.g. a session cookie).

Signed Element

Configure what to sign.

The setting none is not recommended for productive setups as it is vulnerable to attacks.

The setting Assertion may require additional checks on service provider side to close the attack vector. For instance, count the number of Assertion elements in the message.

When recommended is selected the signed element depends on the Outbound Binding:

• http-redirect: nothing will be signed as signing is not supported.
• http-post: the Response is signed as this is most secure.

Signature KeyInfo

The KeyInfo embedded into the signature informs the service provider about the signer credential used.

Enter one or several of the following elements:

• SKI
• Certificate
• CertificateChain
• Subject
• IssuerSerial
• CRLs
• SubjectDNAsKeyName
• SubjectCNAsKeyName
• KeyNames
• EntityID
• PublicKey

Note that only configured fields defined in the signer certificate are actually added to the KeyInfo structure.

Minimum Required Authentication Level

Enforce a minimum required authentication level for this Service Provider.

If not set, the minimum required authentication level will depend on the incoming AuthnRequest. An SP may specify the level by including a RequestedAuthnContext, such as:

<samlp:RequestedAuthnContext Comparison="minimum">
  <saml:AuthnContextClassRef>urn:nevis:level:2</saml:AuthnContextClassRef>
</samlp:RequestedAuthnContext>

If there is any requirement for a minimum authentication level, the Authentication Realm must provide a Session Upgrade Flow for that level. See the help of the Authentication Realm pattern for details.

Note that when there is no authenticated session, the Initial Authentication Flow of the Authentication Realm will be executed first.

After successfully completing the Initial Authentication Flow the attained authentication level is compared against the minimum level and, if required, a Session Upgrade Flow is executed.

Required Roles

Check for required roles.

Roles provided by nevisIDM have the following format: <applicationName>.<roleName>. Roles provided by other systems (e.g. LDAP) may have a different format.

Examples:

myApp.Admin

Required roles are always checked at the end of authentication, after enforcing the Minimum Required Authentication Level (optional).

The user must have any of the enter roles to continue.

If the user does not have any of these roles, the authentication will fail and a SAML Response with status AuthnFailed message will be returned to the SP.

If you want to do custom error handling (e.g. show a GUI to the user), assign a step to On Forbidden.

On Forbidden

Configure a step that shall be executed when the Required Roles check fails.

Logout Mode

Configure the logout mode when a logout is initiated by or for this SP. Choose between:

• ConcurrentLogout-Redirect: IdP will send logout to all SP(s) at once.
• SingleLogout: IdP will send logout to 1 SP at a time.
• SingleLogout-SOAP: IdP will send SOAP logout to SP(s) one by one using SOAP method.

Session Index

Set current session ID to SAML Response in SessionIndex element. This element is required for IDP-initiated logout and SP-initiated logout when Logout Type is set to SOAP.

The element will be included in SAML Response like:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response Destination=... >
    ...
    <saml2:Assertion ID=...>
        ...
        <saml2:AuthnStatement SessionIndex="JeBKZSJah-0m2QjC4LJ8u74LUOY2ayAeenlPgBOx1N8" ... >
            ...
        </saml2:AuthnStatement>
    </saml2:Assertion>
</saml2p:Response>

And in SAML LogoutRequest, the SessionIndex element will be included like:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:LogoutRequest Destination=...>
    ...
    <saml2p:SessionIndex>JeBKZSJah-0m2QjC4LJ8u74LUOY2ayAeenlPgBOx1N8</saml2p:SessionIndex>
</saml2p:LogoutRequest>

Application Type

Reserved for ID Cloud use.

Custom Pre-Processing

Assign a step to apply custom pre-processing logic before validating the incoming request for this SP.

You may assign a chain of steps to build a flow.

The flow will be executed for all incoming requests, no matter if the user has a session already.

If you need to apply different logic for these 3 cases you can use Dispatcher Step and dispatch based on the following expressions:

${request:method:^authenticate$:true}
${request:method:^stepup$:true}
${request:method:^logout$:true}

The dispatching will continue after leaving this flow on the happy path.

For On Success exits this works automatically.

However, generic exits (i.e. Additional Follow-up Steps in Generic Authentication Step) must be marked as success exits by assigning the Pre-Processing Done pattern.

Authentication Request: Lifetime

SAML authentication requests have a maximum lifetime which may be validated by this identity provider.

Enter unlimited to disable the maximum lifetime check for received SAML AuthnRequests. This sets in.max_age to -1 in the generated IdentityProviderState.

Custom Properties

Configure properties of the nevisAuth IdentityProviderState.

Add or overwrite properties by entering a value.

Remove properties generated by this pattern by leaving the value empty.

Examples:

Key	Value
out.extension.Bearer	ch.nevis.esauth.auth.states.saml.extensions.SubjectConfirmationExtender
Bearer.inResponseTo	${notes:saml.request.id}
out.signatureKeyInfo	Certificate

Assertion Consume URL Validation

By default, the whitelist is calculated based on SP URL - Assertion Consumer Service(s). But in some special cases, you can use wildcards to allow a wide range of whitelisted urls. Examples:

• *.mydomain.com
• mydomain.com*

SAML SP Realm

#Federation #Realms #SAML

Plugin: nevisadmin-plugin-nevisauth

Represents a SAML Service Provider (SP).

Assign this pattern to applications to enforce authentication using SAML.

SAML Issuer

Set the Issuer used by this SAML Service Provider.

The issuer can be an arbitrary string but it is recommended to use the complete URL that the Assertion Consumer Service is exposed on.

Example: https://sp.siven.ch/SAML2/ACS/

SAML IDP Connector(s)

Assign a SAML IDP Connector for each SAML Identity Provider.

SP-initiated authentication with multiple IDPs requires a Selection Expression to be configured for each connector.

SAML Signer

Use a pattern to configure the signer certificate used by this Service Provider. If no pattern is assigned a key store will be provided automatically.

Assertion Consumer Service

Enter the path where SAML Response messages sent by the IDP shall be consumed.

This path also accepts LogoutRequest messages.

The IDP may send messages using POST or redirect binding.

Application Access Tokens

SAML Responses returned by the IDP are consumed in nevisAuth and not forwarded to applications.

If your application requires a token then you have assign a pattern which can produce that token here. For instance, assign a NEVIS SecToken or SAML Token.

To forward the token to applications you also have to assign the token pattern to these applications via Application Access Token.

The token will be created on first access (missing token role triggers a stepup). In case of a session upgrade via SAML the token (role) is revoked and thus the token is recreated on the next access.

In your application you may use the Ninja authentication filter provided by NEVIS to extract user id, roles, and custom attributes.

nevisAuth

Assign a nevisAuth Instance pattern.

Key Store

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

If no pattern is assigned automatic key management will provide the required key material. This requires that the nevisAuth Instance is part of this project and also uses automatic key management.

Automatic key management should be used for test setups only.

Trust Store

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

If no pattern is assigned automatic key management is used to provide the trust store. This requires that the nevisAuth Instance is part of this project and also uses automatic key management.

Automatic key management should be used for test setups only.

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.

If no pattern is assigned automatic key management is asked to provide the trust store. This requires that the nevisAuth Instance is part of this project and also uses automatic key management.

Automatic key management should be used for test setups only.

Custom Parameters (IdentityCreationFilter)

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

This pattern generates 2 IdentityCreationFilter elements:

1. Authentication_<name>: enforces authentication for applications.
2. SAML_<name>: provides the Assertion Consumer Service and Session Upgrade Path

If you want to patch only one of these filters consider using Generic Application Settings instead.

Note that the parameter InterceptionRedirect of the SAML_<name> filter is forced to never. If you configure InterceptionRedirect here it will be ignored for this filter as leads to message loss in SAML POST binding.

Examples:

• BodyReadSize = 64000

Custom Parameters (SecurityRoleFilter)

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

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

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:

Key	Value
EnablePollTerminatedCalls	true

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.

Login Template

By default, the Service Provider does not need any rendering template.

However, a GUI will be shown when Logout Reminder is enabled and may be shown when Custom Pre-Processing is used.

nevisLogrend: Simple Mode

Point your browser to a protected application to have a look at the login page. Download any resources (e.g. images, CSS) that you want to adapt. Then upload the changed files here.

To change the outer HTML upload a file named template.html. Here is a simple example:

<!DOCTYPE html>
<html lang="${lang.code}">
  <head>
    <title>${label.title}</title>
    <link href="${resources}/bootstrap.min.css" rel="stylesheet" type="text/css">
    <link href="${resources}/default.css" rel="stylesheet" type="text/css" media="all">
  </head>
  <body>
    <header id="header" class="container-fluid">
      <img class="logo center-block" src="${resources}/example.svg" alt="NEVIS Security Suite">
    </header>
    <main id="content" class="container">
      ${form}
    </main>
  </body>
</html>

Please also upload file resources referenced by your template (e.g. images, CSS, Javascript). Use this when you reference additional files, or if you want to override the default files provided.

The template must contain ${form} and may contain additional expressions.

Expression	Description
${form}	generated login form (required)
${lang.switch}	language switcher component
${lang.code}	current language code (i.e. EN, DE)
${label.title}	a human-readable title
${label.myLabel}	a custom text which must be defined via Custom Translations
${resources}	path to static resources (e.g. CSS, images, Javascript)

Some resources (i.e. bootstrap.min.css, default.css) are provided out of the box because they are required by the default template. Feel free to use them.

nevisLogrend: Expert Mode

Expert users may upload Velocity templates and resources to nevisLogrend.

Zip files will be extracted into the nevisLogrend application:

/var/opt/nevislogrend/<instance>/data/applications/<realm>

Flat files will be added to the following subdirectories:

• webdata/template: Velocity templates (*.vm)
• webdata/resources: additional resources (e.g. images, CSS)

nevisProxy: Simple Template

nevisProxy provides a simple login page renderer which can be used instead of nevisLogrend. See Login Renderer for details.

For each enabled language (e.g. en) upload a file named <lang>_template.html. The template must contain the placeholder NEVIS_AUTH_FORM.

If your templates require additional resources (e.g. CSS, images) upload them as Hosted Resources on the nevisProxy virtual host.

Login Template Mode

Choose between two options:

• additive: files uploaded as Login Template will be added on top of the default. Use this option when you want to add or replace files, but don't want to upload an entire template. There will be less work when you upgrade.

• complete: only the files uploaded as Login Template will be deployed. Use this option when you want to provide the entire template.

Translations

Labels are used to provide human-readable text in the language of the user. Here you can overwrite the defaults and add your own translations.

The name of uploaded files must end with the language code. As the format is compatible you may upload existing text_<code>.properties files of nevisLogrend or LitDict_<code>.properties of nevisAuth.

The encoding of uploaded files does not matter as long as all translations are HTML encoded.

So far this property is relevant only if the Logout Reminder feature is enabled because then a page will be rendered. The following labels are used:

• title - used as browser page title
• logout.text
• language.<code> - used by language switch component
• info.logout.reminder
• continue.button.label

Translations Mode

Choose between:

• combined - upload 1 file per language code named labels_<code>.properties. The labels will be added to both nevisAuth and nevisLogrend. Alternatively, you can upload a zip file called labels.zip containing these properties files.

• separate - select only when you need different labels in nevisAuth and nevisLogrend. The files must be called LitDict_<code>.properties for nevisAuth and text_<code>.properties for nevisLogrend. Alternatively, you may upload zip file called LitDict.zip and text.zip containing these properties files.

Default Translations

Choose between:

• enabled - add default translations for labels which are commonly used (e.g. title or language labels in nevisLogrend, error labels in nevisAuth) and which are required by the realm patterns (e.g. assigned authentication steps).

• disabled - select to only add what has been uploaded via Translations. Note that if Translations are incomplete users may encounter untranslated labels.

nevisLogrend default.properties

Add or overwrite properties in the default.properties of the nevisLogrend application.

Use only when there is no high-level setting. We recommend to not overwrite any language related properties, as the languages should be in sync with nevisAuth. You can configure the languages on the nevisAuth Instance.

Requires that nevisLogrend is used for GUI rendering. Check the help of Login Renderer for details.

Session Cookie Name

Each realm has its own session cookie. By default, this cookie will be called Session_<pattern-name>

Set this optional property to use a different name (e.g. ProxySession).

Note that each realm has its own session. However, if the same cookie name is configured for multiple realms running on the same host the sessions will be cleaned up together when the first session expires.

Session Cookie Same Site

In February 2020 Chrome 80 has been released which treats cookies without SameSite flag as Lax.

This change can break cross-domain use cases (e.g. SAML).

Thus, it is recommended to select None here.

If None is selected, and you have to support older browsers also check Cookie Same Site Relaxation.

If you do not expect any requests from other domains, you may also go for Lax or Strict as this increases security.

Session Cookie Same Site Relaxation (Experimental)

Some older browsers treat cookies with SameSite=None as Strict.

See this example bug report for Safari:

Bug 198181 - Cookies with SameSite=None or SameSite=invalid treated as Strict

Enable this feature to map a filter to the root location /* which evaluates the User-Agent request header to remove SameSite=None for browsers which are known to be affected.

Session Validation

A newline separated list of rules declaring attributes that must not change in the same session. A rule has the following syntax:

AUTH|ENV|CONST|PARAM|HEADER:<name of the attribute>:block|invalidate

• block: the request will be blocked and 403 (Forbidden) will be returned
• invalidate: the session will be invalidated and a new one will be created

nevisProxy Conditions are supported. See nevisProxy reference guide for details.

For instance, use the following configuration to terminate the session if the source IP changes:

ENV:REMOTE_ADDR:invalidate

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.

Timeout Page

Renders a timeout page when the user session has expired.

This is different from the Logout Reminder Page feature which also show a page when the user comes back after closing the browser.

The page contains a heading, an info message and a continue button. You can customize them via Custom Translations by setting the following labels:

• title.timeout.page
• info.timeout.page
• continue.button.label

For this feature an additional cookie Marker_<name> will be issued. The value will be set to login or logout depending on the last user action.

The following requirements must be fulfilled:

• Usage of HTTPs to access the application and for the entire SAML process.
• No other session expiration feature must be used.

Timeout Redirect

Enter a URL or path to redirect to after session timeout.

The redirect is executed on next access when the session has expired.

This is different from the Logout Reminder Redirect feature which also performs the redirect when the user comes back after closing the browser.

For this feature an additional cookie Marker_<name> will be issued. The value will be set to login or logout depending on the last user action.

The following requirements must be fulfilled:

• Usage of HTTPs to access the application and for the entire SAML process.
• No other session expiration feature must be used.

Logout Reminder Page

Enable this feature to show a logout reminder page.

The page will be shown on next access in the following cases:

• the user has closed the browser
• user session has expired due to idle timeout

The page contains a heading, an info message and a continue button. You can customize them via Custom Translations by setting the following labels:

• title.logout.reminder
• info.logout.reminder
• continue.button.label

For this feature to work an additional cookie Marker_<name> will be issued. The value will be set to login or logout depending on the last action of the user.

The following requirements must be fulfilled:

• Usage of HTTPs to access the application and for the entire SAML process.
• No other session expiration feature must be used.

Logout Reminder Redirect

Enter a URL or path to redirect to when a user accesses, and the session has expired.

The redirect is executed on next access in the following cases:

• the user has closed the browser
• user session has expired due to idle timeout

The following requirements must be fulfilled:

• Usage of HTTPs to access the application and for the entire SAML process.
• No other session expiration feature must be used.

Logout Mode

Defines how this SP should react when an SP-initiated logout completes on this SP.

• redirect-target: redirects to a defined path or URL. When this option is selected a Logout Target must be entered.

• redirect-state: redirects according to the RelayState query parameter received in combination with the LogoutResponse. The IDP is expected to return this parameter as-is and thus the RelayState should contain the URL where the logout was initiated. As this is a protected application URL authentication will be enforced and the user will be sent to the IDP again to perform a login.

Logout Target

Enter a path or URL to redirect to when an SP-initiated SAML logout completes on this SP.

The redirect is performed only when Logout Mode is set to redirect-target.

Session Upgrade Path

Applications may redirect to this location to force the SP to invoke the IDP again by sending an AuthnRequest.

This mechanism allows applications to enforce a session upgrade.

The URL must contain the following query parameters:

• relayState: the path to redirect to after successful session upgrade.
• level: the required authentication level (2-9). The level will be sent to the IDP within the RequestedAuthnContext.

Tokens produced by Application Access Token patterns assigned to applications will be re-created on next access to reflect updated user data.

Example for RequestedAuthnContext with level=2:

<saml2p:RequestedAuthnContext>
  <saml2:AuthnContextClassRef xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">urn:nevis:level:2</saml2:AuthnContextClassRef>
</saml2p:RequestedAuthnContext>

Custom Pre-Processing

Assign a step to apply custom pre-processing logic before executing SP-initiated SAML authentication. This pre-processing logic is executed for methods: authenticate, stepup, unlock, and logout.

You may assign a chain of steps to build a flow. The dispatching will continue when leaving this flow on the happy path.

For On Success exits this works automatically.

However, generic exits (i.e. Additional Follow-up Steps in Generic Authentication Step) must be marked a success exits by assigning the Pre-Processing Done pattern.

Post-Processing

Assign a Generic Authentication Step to apply custom post-processing logic to an SP-initiated SAML process (e.g. authentication, session upgrade, or logout).

By assigning a step here the last AuthState of the process will be replaced so that it points to the first AuthState provided by the assigned step. This AuthState should be marked with the name ${state.entry}.

Use the expression ${state.done} to complete with the SAML process.

SAML Token

#Authentication #SAML #Tokens #Add-ons

Plugin: nevisadmin-plugin-nevisauth

Assign to a realm pattern using Application Access Tokens to allow the realm to produce SAML tokens.

To propagate the tokens to applications set Additional Settings on the application patterns. There are several options:

• Assign the pattern to forward tokens in the Authorization header. Use in combination with Ninja.
• Use the SAML SP Integration pattern to send tokens using POST to an SP deployed on the same backend.

Issuer

Enter the Issuer which will be used to create the token.

If nothing is configured the name of the pattern is taken.

User Attributes

Define which nevisAuth session variables to include as attributes in the SAML assertion.

If not set the following default will be used:

Attribute	Session Variable
userid	ch.nevis.session.userid
loginId	ch.nevis.session.loginid
profileId	ch.adnovum.nevisidm.profileId
clientId	ch.adnovum.nevisidm.clientId

Which session variables are available depends on your authentication flow. For instance, if you use nevisIDM Password Login there will be a session variable user.email so you can easily add an attribute email.

Set the log level of Vars to INFO and check the esauth4sv.log to find out which session variables are available after authentication.

In case a session variable is not found the attribute will be omitted.

Signer Key Store

Assign a pattern which sets the key material used for signing the token.

If no pattern is assigned automatic key management is used and the signer key will be created automatically.

Token Type

• Assertion: produces a SAML Assertion.

Use for applications protected by Ninja.

• Response: produces a SAML Response.

Use for applications which have their own SAML SP. Assign the SAML SP Binding pattern to the application and link this pattern there.

Audience Restriction

Configure the AudienceRestriction.

Enter 1 line for each Audience.

Subject Type

Configure the subject of the generated SAML assertion.

• User ID: sets the internal user ID
• Login ID: sets the ID as entered by the user during login

Custom Properties

Enter custom properties for the nevisAuth IdentityProviderState which issues the SAML Response (or Assertion).

Please check the technical documentation for details.

Common use cases are:

• out.issuer: sets the Issuer element (By default, the sanitized name of the pattern is used)
• out.audienceRestriction: some recipients require this to be set to decide if they accept the token
• out.signatureKeyInfo: add information about the signer certificate

Examples:

out.authnContextClassRef = urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
out.sessionIndex = ${notes:saml.assertionId}
out.signatureKeyInfo = Certificate
out.subject.format = urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
out.ttl = 10
relayState = ${request:currentResource}

SAP Logon Ticket

#Authentication #Tokens #Add-ons #Experimental

Plugin: nevisadmin-plugin-nevisauth

Assign to a realm using Application Access Tokens to allow the realm to produce an SAP Logon Ticket.

To issue an SAP Logon Ticket and propagate it to applications you also have to assign the pattern to the corresponding Web Application, REST Service, or SOAP Service using Application Access Token.

The issued SAP Logon Ticket may either be propagated to the client as a cookie (for pseudo-federated scenarios based on shared cookie domain spaces) or propagated to a backend application behind a nevisProxy instance.

UserID Source

Source of the user ID to set for the issued SAP ticket.

The default is ${request:userId}.

Application Mappings

A list of user ID mappings of the form <application>:<ID> to be inserted in the ticket. This will be used by SAP services to retrieve local user IDs. SAP NetWeaver Portal CRM plays a special role here as its user management is based on UME and, typically, has distinct IDs.

Signer Key Store

Assign a pattern which sets the key material used for signing the token.

If no pattern is assigned automatic key management is used and the signer key will be created automatically.

Encoding

Encoding to use for the SAP token. Note that some SAP applications (in particular those running as native processes) do not support all encodings. In such cases, error messages may be misleading. Usage of the encoding "ISO8859-1 (ISO-LATIN-1)" is encouraged as this seems to be supported by all SAP products.

The default is ISO8859-1.

System ID

Identifier of issuing system (or issuer). This must match the key under which the issuer certificate was configured in the consuming service.

System Client

Identifier of client. See SAP documentation of SAP SSO logon tickets for more information. Default value is SAP's default and should be correct for most cases.

Authentication Scheme

Authentication scheme associated with this ticket. See SAP documentation of SAP SSO logon tickets for more information. Default value is SAP's default and should be correct for most cases.

Recipient Client

See SAP documentation of SAP SSO logon tickets for more information. Setting no value for this property should be correct for most cases.

Recipient SID

See SAP documentation of SAP SSO logon tickets for more information. Setting no value for this property should be correct for most cases.

Caching Allowed

If set to enabled, this property enables the CachingAllowed flag in the issued ticket. See SAP documentation of SAP SSO logon tickets for more information.

Include Certificate

When enabled, the signer's certificate is inserted into the issued SAP ticket.

Set-Cookie Header

If set, this property must specify the value of the HTTP header "Set-Cookie". The cookie will be issued to the client by nevisAuth such that a cookie-based SSO federation with SAP applications is possible. This property is evaluated after the ticket has been issued, so the variables sap.ticket, sap.ticket.maxAge and sap.ticket.expires can be used.

Example value for this property that sets the cookie as expected by SAP products:

MYSAPSSO2=${outarg:sap.ticket}; Version=1; Path=/; Secure; HttpOnly; Max-Age=${notes:sap.ticket.maxAge}; Expires=${notes:sap.ticket.expires};

To use this example value by default, set this property to true.

SOAP Service

#Application Protection #Applications

Plugin: nevisadmin-plugin-nevisproxy

The pattern sets up access to a backend application which provides a SOAP service.

Virtual Hosts

Assign Virtual Host patterns which shall serve as entry point for this application.

Frontend Path

The (base) path of the application.

Examples:

• /app/ - defines a base path. Any requests which have a path component starting with /app/ will be sent to this application.
• / - forward all requests to this application. Use this only when there are no other applications or hosted resources.
• exact:/app.html - matches requests to /app.html only (query parameters are allowed). Use this for single-page applications which don't require any additional resources.

Note that if the frontend path is different from the path used within Backend Addresses then URL rewriting will be configured to correctly route requests and responses between clients and backends.

Authentication Realm

Optionally assign a realm to protect this application or service.

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.

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.

Backend Addresses

Enter the complete URLs (scheme, host, port and path) of the backend services.

Note:

• all URLs must use the same scheme and path.
• automatic path rewriting will be performed when the path differs from the Frontend Path.

In case you are setting multiple addresses, use Load Balancing to select a request dispatching strategy.

Load Balancing

Select a request dispatching strategy when several Backend Addresses are configured.

• disabled - all requests will be sent to the first address. If this address is not available the next address is chosen;
• round-robin - one of the addresses will be picked up for each request using a round-robin rotation;
• session-sticky - one of the addresses will be picked up for each new session using a round-robin rotation, then subsequent requests for the session will be sent to the same address.

Failover strategy:

• When the selected backend cannot be accessed, nevisProxy will attempt to use another one.
• Once the said backend can be accessed again, it can be picked up for new requests if the load balancing is round-robin, or for new sessions if the load balancing is disabled or session-sticky. The requests linked to an existing session will still go to the current backend until the end of the session if the load balancing is disabled or session-sticky.

Key Store

Optional setting to use a client certificate for connecting to HTTPS backends.

Send Certificate Chain

Choose which certificates are sent to the backend during mutual authentication:

• disabled: Send the client certificate from the Key Store;
• enabled: Send the certificate chain from a PEM Key Store or a nevisKeybox Store. The certificate chain file must contain the client certificate and the intermediate CA certificates.

Trust Store

Optional setting for enabling trust to HTTPS backends.

For securing production environments:

• set Backend Addresses starting with https://
• assign a Trust Store pattern containing the certificates required for verifying the backend certificate
• set Hostname Validation to enabled

Hostname Validation

Enable to verify that the hostname on the certificate presented by the backend matches the hostname configured in Backend Addresses

Host Header

Defines the Host header for requests forwarded to the application.

When backend is selected then nevisProxy uses the host part of the backend address that has been selected. This is the default behaviour and similar to what a browser would do. Therefore, this configuration should work in most cases.

When client is selected then nevisProxy will keep the Host header as received from the client. The following init-param will be generated:

<init-param>
  <param-name>HostName</param-name>
  <param-value>ENV:HTTP_Host;</param-value>
</init-param>

The configuration is dynamic to support virtual hosts with multiple frontend addresses. Note that this may be less secure. Even though browsers do not allow this clients may sent an arbitrary value for the Host header. It is therefore recommended to test how your application behaves in this case.

Response Rewriting

Use this feature to replace backend hostnames in responses or set to custom to configure complex rewriting use cases.

• off disables automatic response rewriting
• header enables auto rewrite for response headers (including Set-Cookie header)
• complete enables auto rewrite for the entire response (including body)
• custom configure Response Rewriting Settings via Additional Settings

SOAP Schema Validation

Optional property to upload a schema.

This feature is experimental and may change in future releases.

You must upload all required XSD schema files. Each XSD schema file must declare 1 target namespace which will be extracted from the first targetNamespace attribute found in the file.

Upload of a WSDL file is optional. If provided, the WSDL must contain a types declaration containing an XSD schema. However, this schema definition can be empty. Here is a minimal example:

   <types>
      <xsd:schema targetNamespace="urn:com.example:echo"
                  elementFormDefault="qualified">
      </xsd:schema>
   </types>

The actual schemas must still be uploaded as separate files.

SOAP Schema Validation Mode

Choose between:

• strict - all requests must be valid SOAP, requests without a body are blocked.
• enabled - all requests which have a request body must be valid SOAP, requests without a body are allowed.
• log only - similar to strict but violations are not blocked, only logged.
• content-type - validation is performed only when the Content-Type header matches application/soap+xml.
• disabled

Allowed HTTP Methods

Define the HTTP methods allowed for this application.

Methods which are listed here must also be allowed on the Virtual Host.

You may also use the following method groups:

• ALL-HTTP includes common HTTP methods.

  These are: GET, POST, HEAD, DELETE, TRACE, CONNECT, OPTIONS, PUT, PATCH

• ALL-WEBDAV includes all methods required for WebDAV.

  These are: MERGE, UNCHECKOUT, MKACTIVITY, PROPPATCH, LOCK, CHECKOUT, SEARCH, COPY, MKCOL, MKWORKSPACE, PROPFIND, UPDATE, REBIND, BASELINE-CONTROL, UNBIND, CHECKIN, VERSION-CONTROL, UNLOCK, LABEL, MOVE, ACL, BIND, REPORT

To remove methods from ALL-HTTP and ALL-WEBDAV simply add the method with a - sign in front of it.

Session Termination

Use this feature to terminate sessions on the backend application.

nevisProxy will send a GET request to this path when the nevisProxy session is terminated (due to logout or session timeout).

Custom Parameters

Add custom init-param(s) for the Http(s)ConnectorServlet. For example: ConnectionRetries=10

Please check the nevisProxy technical documentation for supported init-params of the servlet classes ch::nevis::isiweb4::servlet::connector::http::HttpConnectorServlet and ch::nevis::isiweb4::servlet::connector::http::HttpsConnectorServlet.

Security Response Headers

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Configure security headers to be set by nevisProxy on responses. Assign the pattern to an entire Virtual Host or individual applications.

Response Headers

Use this property to add security headers to responses. The syntax is: <header name>:<value>

Example:

Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin

Securosys Key Store

#Key Management

Plugin: nevisadmin-plugin-nevisproxy

Sets up a Securosys HSM based key store.

The necessary configuration files are deployed into '/etc/primus', while the library itself is shipped with the image.

Certificate with private key is required.

If the certificate does not contain the private key, set the private key separately.

If the private key is encrypted, the passphrase has to be set.

The configuration files are not validated by nevisAdmin 4.

Certificates object label

The certificate objects label on the HSM.

Private Keys object label

The key objects label on the HSM.

Securosys PIN

The PIN for accessing the materials on the HSM.

You must set it as a variable for security reasons.

Securosys configuration files

The two necessary configuration files for accessing the HSM.

'primus.cfg' must contain the configuration settings for connecting to the HSM, and '.secrets.cfg' must contain the credentials to access the materials on HSM.

Keep in mind that the files are not validated, first set up a working configuration, and use the already validated files here.

Sendgrid SMTP

#Authentication #Connector

Plugin: nevisadmin-plugin-nevisauth

The pattern sets up a connection to Sendgrid for sending emails. Assign the pattern to Email TAN (eTAN) as SMTP Server.

API Key

API key to connect to Sendgrid.

Shared Storage Settings

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisadapt

Pattern to override the default settings of the shared storage used in Kubernetes deployments.

Claim Name

The name of the PersistentVolumeClaim.

For more information regarding persistent volumes in Kubernetes please visit this page

Storage Size

The size of the persistent volume. The minimum size is 1 gigabyte, we recommend to use at least 4 gigabytes.

For example: 4GB

Storage Class

The name of the StorageClass. The selected storage should support ReadWriteMany access.

For example: azurefile

For more information regarding persistent volume types in Kubernetes please visit this page

Mount Path

The path where the volume will be mounted and used by the service.

For example: /var/opt/shared

For more information regarding persistent volumes in Kubernetes please visit this page

Social Login Create User

#Federation #Authentication #OAuth #OpenID Connect #Experimental

Plugin: nevisadmin-plugin-oauth

Creates a new account in nevisIDM for the logged-in user.

On Success

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

Note: In order to have profile selection in case account have multiple profiles, you need to use the User Lookup pattern.

Unit External ID

The ExtId of the unit in nevisIDM that will be used to store the user

ID Generation

Define how the user extId and profileExtId are generated. Choose between:

• undefined: the extId and profileExtId will be generated by nevisIDM, and it depends on nevisIDM config that the id will be uuid or in any sequence
• uuid: the extId and profileExtId will be generated in UUID format by nevisAuth and send to nevisIDM. The newly created user extId and profileExtId will be in UUID format

Social Login Done

#Federation #Authentication #OAuth #OpenID Connect #Experimental

Plugin: nevisadmin-plugin-oauth

Use this step to terminate On User Found and On User Not Found flows of social login patterns (e.g. Google Login, Apple Login).

The step ensures that the conversation is completed (AUTH_DONE or AUTH_ERROR), and the user is redirected back to the originally requested path.

This step can be omitted when federation is used to access authentication as the caller will be redirected in this case.

In you flow you have to create or link the user. You can use Social Login Link User and Social Login Create User for this.

Status

Choose how to complete the flow:

• AUTH_DONE: user is authenticated
• AUTH_ERROR: session is terminated

In both cases the caller is redirect back to the path before jumping of to the social login provider.

When social login is behind federation (e.g. SAML IDP), AUTH_ERROR will be handled by sending the caller back to the origin (e.g. the SAML SP) with a technical error message.

Social Login Link User

#Federation #Authentication #OAuth #OpenID Connect #Experimental

Plugin: nevisadmin-plugin-oauth

Use to link to an existing user account.

On Success

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

Note: In order to have profile selection in case account have multiple profiles, you need to use the User Lookup pattern.

Standalone Authentication Flow

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Use this pattern to build custom self-admin use cases, for example, user registration, password reset, mobile change.

The authentication flow is exposed on the assigned Virtual Host. Requests received on the configured Frontend Path are dispatched into an authentication step.

The flow is always executed, even when the user already has an authenticated session.

Be aware that on successful execution of the flow, the caller may be authenticated in the assigned Authentication Realm, and thus will be able to access any applications protected by that realm.

For use cases which do not require an authenticated session it is therefore recommended to use a separate realm.

Virtual Host

Assign a Virtual Host.

Frontend Path(s)

Enter frontend path(s) which should be handled.

Authentication Realm

Assign an Authentication Realm.

Authentication Flow

Assign a step to execute for incoming requests.

If not present already, the step will be added to the Authentication Realm.

If no step is assigned the default flow of the Authentication Realm will be executed.

Session Upgrade Flow

Assign a step to execute for incoming requests when there already is an authenticated session.

If not present already, the step will be added to the Authentication Realm.

If no step is assigned the same step as for Authentication Flow will be executed.

Allowed HTTP Methods

Define the allowed HTTP methods.

If not configured, all HTTP methods are allowed.

Additional Settings

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

Example use cases:

• URL Handling with phase AFTER_AUTHENTICATION to redirect after the authentication flow completes.
• Access Restriction to restrict access based on source IPs.
• HTTP Header Customization to add, replace, or remove HTTP headers in requests or responses.

Static Content Cache

#Application Protection #Add-ons #Experimental

Plugin: nevisadmin-plugin-nevisproxy

Use this pattern to configure a nevisProxy filter to cache responses returned by backend applications.

This pattern should only be configured for:

• locations that emit static insensitive content,
• early hint resources,
• or backend applications that return Cache-Control headers to prevent storing sensitive responses.

Cached responses are stored in the directory:

/var/opt/nevisproxy/<instance>/run/cache/Cache_<pattern name>/

Stored response bodies can use up to Max Entries Max Entry Size of disk space. Stored response headers generally use less disk space, up to Max Entries ResponseLineSize of the HttpConnectorServlet (default: 4kB) * max number of response headers.

Max Entries

The maximum number of documents to be cached.

Max Entry Size

The maximum size of a document to be cached. Larger documents are never cached.

Max Lifetime

The maximum duration to cache a document.

Max-Age Mode

Choose one of:

• override : The cache entry lifetime is set to Max Lifetime.
• backend : The cache entry lifetime is copied from the Cache-Control: max-age directive sent by the backend. The Max Lifetime is used as a fallback.

Request Header Mode

Request headers can force an intermediate server to override its cache and answer with the response from the original server.

Choose one of:

• comply : Follow the Cache-Control: no-cache directives sent by the client.
• ignore : Answer with the stored response even if the client sent a Cache-Control: no-cache directive.

Response Header Mode

Response headers can indicate whether clients and intermediate servers should cache the response.

Choose one of:

• comply : Follow the Cache-Control directives sent by the backend.
• ignore : Store the response even if the backend sent a Cache-Control directive to prevent caching. Be aware that ignoring Cache-Control directives can lead to sharing sensitive data between clients.

Some clients or content providers try to switch off caching even for mostly static content like images or style sheets. You can limit the load on your content providers as follows:

• Add a Static Content Cache pattern and link it to your application via Additional Settings;
• Configure Apply only to sub-paths to store responses on paths that only emit static content, for instance images;
• Set Response Header Mode to ignore;
• Configure the Max Lifetime of stored responses.

Apply only to sub-paths

Set to apply the cache handling on some sub-paths only.

Sub-paths must be relative (e.g. not starting with /) and will be appended to the frontend path(s) of the virtual host (/) or applications this pattern is assigned to.

Sub-paths ending with / are treated as a prefix, otherwise an exact filter-mapping will be created.

The following table provides examples to illustrate the behaviour:

Frontend Path	Sub-Path	Effective Filter Mapping
/	secure/	/secure/*
/	accounts	/accounts
/	api/secure/	/api/secure/*
/	api/accounts	/api/accounts
/app/	secure/	/app/secure/*
/app/	accounts	/app/accounts
/app/	api/secure/	/app/api/secure/*
/app/	api/accounts	/app/api/accounts

SwissPhone SMS

#Authentication #Connector

Plugin: nevisadmin-plugin-nevisauth

Use as SMS Provider in the Mobile TAN (mTAN) pattern.

With this pattern, you can connect to the SwissPhone SMS Gateway to send a TAN code to the mobile device of the user.

Make sure that your authentication flow stores the mobile phone number of the user in the session variable ch.nevis.idm.User.mobile.

If you have a nevisIDM Password Login step in front of Mobile TAN (mTAN) and use its default configuration, then this is the case by default.

If you are using LDAP Login you have to ensure that the mobile number is fetched from LDAP (configure User Attributes), and store the mobile number in the session variable ch.nevis.idm.User.mobile using a follow-up step.

Make sure to use the same format (no spaces).

Sender

The sender phone number to use to transmit the SMS.

Default Country Code

The default country code to add to the mobile number if the number found in the session does not have a country code.

This value must not contain a +.

For instance, assuming that numbers without country code information are Swiss, enter 0041 in this field.

Username

The username to use to connect to the SwissPhone SMS Gateway.

Password

The password to use to connect to the SwissPhone SMS Gateway.

Portal Server

The address of the server hosting the SwissPhone SMS Gateway.

Trust Store

Assign a trust store for the outbound TLS connection to SwissPhone.

Import the CA certificate of the Portal Server into this trust store.

Since version 4.38 nevisAuth trusts CA certificates included in the JDK.

Thus, it is not required to configure this.

However, you can still configure a trust store here to be as strict as possible.

Proxy

Forward proxy for the connection to the SwissPhone SMS Gateway.

Example: proxy.your-internal-domain:3128

TCP Settings

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Use the pattern to customize TCP connections to backend applications. Assign the same pattern to multiple applications to enforce a common standard.

DNS Caching	Keep-Alive	Description
disabled	disabled	Always works but has the biggest impact on latency.
disabled	enabled	DNS may resolve a new IP but Keep-Alive is enabled so some requests may still be routed to the previous IP. This may be acceptable if the previous IP is still reachable and could even be required in case sessions are bound to the TCP connection.
enabled	disabled	The resolved IPs are stable but for each request a new TCP connection is established.
enabled	enabled	The resolved IPs are stable and connections are reused.

Connect Timeout

Timeout for establishing the TCP connection.

Request Timeout

Timeout waiting for the response.

DNS Caching

Cache DNS lookup results.

• default: does not generate any configuration so the default nevisProxy behaviour will apply.
• disabled: the configured backend host names are resolved for each request. Use when IP addresses may change.
• enabled: host names are resolved only once. Use when the IP addresses are stable.

DNS Caching Timeout

If DNS Caching is set to true, DNS Caching Timeout specifies how long the DNS info should be cached (in seconds) before getting again the IP address.

Keep-Alive

Pool TCP connections to backends for later reuse.

• default: does not generate any configuration so the default nevisProxy behaviour will apply.
• disabled: the TCP connection is closed after use, and a new connection will be established for the next request.
• enabled: the TCP connection is put in a pool so that it can be reused by future requests. Limiting factors are Connection Pool Size, By Client, Inactive Interval, and Lifetime.

Connection Pool Size

Number of pooled TCP connections. A TCP connection is only put in the pool if the size of the pool does not exceed the configured size. By leaving this field empty, you will be using the nevisProxy default value.

By Client

Forces TCP connections to only be reused for the same client. A call from a different client will use another TCP connection from the connection pool. If set to default, the nevisProxy default will be used.

Inactive Interval

Inactivity duration allowed before a TCP connection is dropped. By leaving this field empty, you will be using the nevisProxy default value.

Lifetime

The absolute lifetime of a TCP connection. This should be configured to less than the connection lifetime allowed by the firewall between nevisProxy and the content providers. By leaving this field empty, you will be using the nevisProxy default value.

TLS Settings

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Use the add-on to customize TLS/SSL settings for nevisProxy.

Assign to a Virtual Host to customize settings for incoming connections.

You can customize connections to backends by assigning the pattern to your service (Web Application, REST Application, SOAP Application) using Additional Settings.

Protocols

The value configured here will be applied as SSLProtocol.

Check the Apache Documentation for details.

If empty and when this pattern is assigned to a Virtual Host the following value is used:

-all +TLSv1.2 -TLSv1.3

If empty and when this pattern is assigned to an application, default SSLProtocol from nevisProxy are applied. Check the nevisProxy Technical Documentation for details.

Cipher Suite

The value configured here will be applied as SSLCipherSuite.

Check the Apache Documentation for details.

If empty and when this pattern is assigned to a Virtual Host the following value is used:

ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256

If empty and when this pattern is assigned to an application, default SSLCipherSuites from nevisProxy are applied. Check the nevisProxy Technical Documentation for details.

SSL Options

The value configured here will be applied as SSLOptions.

It should only have value when assigned to a Virtual Host pattern.

Check the Apache Documentation for details.

If empty and when this pattern is assigned to a Virtual Host the following value is used:

+OptRenegotiate +StdEnvVars +ExportCertData

Test Login

#Authentication #Testing

Plugin: nevisadmin-plugin-nevisauth

##TESTING ONLY - NOT FOR PRODUCTION USE

A simple username / password login step. Use for testing only. Enter username = password to continue.

Label

Set to show a different message.

On Success

Set the step to continue with on successful authentication. If no step is assigned, the process ends and the user will be authenticated.

Buttons

Assign an Dispatcher Button to add a button which points to a different authentication step.

Authentication Level

Set an authentication level.

Test TAN

#Authentication #Testing

Plugin: nevisadmin-plugin-nevisauth

##TESTING ONLY - NOT FOR PRODUCTION USE

A dummy TAN second factor authentication.

On Success

Set the next step on successful entry of the TAN code. If no step is assigned, the process ends and the user will be authenticated.

Authentication Level

Set an authentication level.

Label

Set to show a different message.

Token Header Propagation

#Authentication #Add-ons #Tokens

Plugin: nevisadmin-plugin-nevisauth

Assign to applications using Additional Settings to send a token to the application in a custom header.

Application Access Token

Assign a Token pattern.

The referred pattern must be assigned to the correct Realm pattern(s).

Header Name

Enter the HTTP header to set for requests to backend applications. The value of this header will be the base64 encoded token.

Transaction Confirmation

#Mobile Authentication #Authentication

Plugin: nevisadmin-plugin-nevisfido

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.

Transform Variables Step

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Set new variables, update existing variables, clear or remove them.

The pattern generates a TransformAttributes AuthState. Because of ease of use, not all features of this state are exposed via Basic Settings.

For advanced variable transformations you may configure Custom Properties via Advanced Settings.

This step does not support producing a response. If execution fails HTTP error code 403 is returned and the session will be terminated with AUTH_ERROR. If you need a response use Generic Authentication Step or Groovy Script Step instead.

Variables

Set variables.

To find out which variables are available when a request comes in set the log level of Vars to DEBUG and check the nevisAuth log.

The following syntax variants are supported:

<scope>:<name> = 
<scope>:<name> = some value
<scope>:<name> = ${some-auth-expression}
<scope>:<name> = #{some-EL-expression}

The setting On Empty Value defines how null values and empty Strings shall be handled.

Example: store the query parameter RelayState in the session:

sess:RelayState = ${inargs:RelayState}

Example: clear finishers registered in the session:

sess:ch.nevis.session.finishers = 

If you want to use advanced features of the TransformAttributes state, provide the required configuration via Custom Properties.

On Empty Value

Defines how to set the variable when null or an empty String shall be stored.

Choose between:

• skip-variable: do not set the variable. The current value is preserved.
• clear-variable: sets an empty String.
• remove-variable: removes the variable.

On Success

Set the step to continue with after successful execution.

Custom Properties

Set property elements for the TransformAttributes state.

URL Handling

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

Use the pattern to:

• redirect requests (returning status code 302 with a Location header)
• rewrite the path of a request, that is, forward.

Query parameters are always considered.

You can use the pattern as an add-on for Virtual Host or any application, for example, Web Application, REST Service, SOAP Service.

Redirect and forward rules have the following format:

<source> -> <destination>

The pattern generates a nevisProxy RewriteFilter named URLHandler_<name>. If either source or destination starts with http:// or https:// then the init-param RequestURL is set, otherwise RequestURI is used.

Redirect Rules

Terminate requests by returning a HTTP Redirect (status code 302).

In the first column (source) enter the current location. In the second column enter the destination to redirect to.

The following formats are supported:

• URL
• absolute path (starting with /)
• relative path

Regular expressions are supported in the source, and group extractions may be used in the destination.

Absolute paths always point to the host, while relative paths are appended to the path of the assigned host (/) or application.

The order of the rules matters. Only the first matching rule is applied.

Examples:

Source	Destination	Description
http://(.*)	https://$1	redirects plain HTTP to HTTPs, preserving the request path
(.*)?lang=de	de/$1	put query parameter into request path
/nevis.html	https://www.nevis.ch	redirect requests to a certain HTML page to a different domain

Forward Rules

Rewrite the path of HTTP requests.

Rewrites are done using a forward which means that they are transparent for the caller.

The format is the same as in Redirect Rules.

Apply only to sub-paths

Set to apply this pattern on some sub-paths only.

Sub-paths must be relative (e.g. not starting with /) and will be appended to the frontend path(s) of the virtual host (/) or applications this pattern is assigned to.

Sub-paths ending with / are treated as a prefix, otherwise an exact filter-mapping will be created.

The following table provides examples to illustrate the behaviour:

Frontend Path	Sub-Path	Effective Filter Mapping
/	secure/	/secure/*
/	accounts	/accounts
/	api/secure/	/api/secure/*
/	api/accounts	/api/accounts
/app/	secure/	/app/secure/*
/app/	accounts	/app/accounts
/app/	api/secure/	/app/api/secure/*
/app/	api/accounts	/app/api/accounts

Filter Phase

The phase when this filter should be applied depends on your use case.

• use START when the redirect / rewrite should be done as early as possible.
• use AFTER_SANITATION to redirect / rewrite after validating the request.
• use AFTER_AUTHENTICATION to redirect / rewrite after authentication.

Unauthenticated Realm

#Application Protection #Realms

Plugin: nevisadmin-plugin-nevisproxy

Public applications typically do not have an Authentication Realm assigned. However, there are some cases where you have to assign this pattern.

1) You have a public and an authenticated application with overlapping Frontend Paths.

Assign this pattern to your public application and select disabled in the Session Tracking drop-down.

This expresses that no sessions are expected.

This pattern ensures that session tracking and authentication are excluded from all frontend paths of your public application.

2) You are using nevisProxy features which need a session.

For instance, the Cookie Customization pattern needs a nevisProxy session to store cookies when you configure Shared Protected Cookies or Protected Cookies.

In this case, set the Session Tracking drop-down to COOKIE.

In general, we do not recommended to have a proxy session for public applications, as it can lead to a high sessions count. Thus, we recommend to set the Session Timeout as low as possible.

Session Tracking

Choose between:

• COOKIE: issue a session cookie.
• AUTHORIZATION_HEADER: track the session based on the value of the Authorization header.
• CUSTOM: track the session based on custom configuration. It generates an empty session filter which has to be replaced (see below).
• disabled: disable session tracking.

CUSTOM session tracking

Given a pattern name of SSO, the following empty filter will be generated:

    <filter>
        <filter-name>SessionHandler_SSO</filter-name>
        <filter-class>__REPLACE_USING_GENERIC__</filter-class>
    </filter>

For the filter-class, a placeholder (REPLACE_USING_GENERIC) will be used and that placeholder has to be overwritten.

Another pattern must complete the session filter. For example, use Generic Virtual Host Context pattern with the following Filters and Mappings configuration:

<filter>
    <filter-name>SessionHandler_SSO_RealmName</filter-name>
    <filter-class>ch::nevis::nevisproxy::filter::session::SessionManagementFilter</filter-class>
    <init-param>
        <param-name>Identification</param-name>
        <param-value>CUSTOM</param-value>
    </init-param>
    <init-param>
        <param-name>Custom.RequiredIdentifiers</param-name>
        <param-value>HEADER:Authorization</param-value>
    </init-param>
    <init-param>
        <param-name>Servlet</param-name>
        <param-value>LocalSessionStoreServlet</param-value>
    </init-param>
</filter>

Session Cookie Name

By default, the session cookie will be called Session_<pattern-name>

Set this optional property to use a different name (e.g. ProxySession).

If the same name is configured for multiple realms on the same host then the sessions will be cleaned up together when the first session expires.

Session Cookie Same Site

In February 2020 Chrome 80 has been released which treats cookies without SameSite flag as Lax.

This change can break cross-domain use cases (e.g. SAML).

Thus, it is recommended to select None here.

If None is selected, and you have to support older browsers also check Cookie Same Site Relaxation.

If you do not expect any requests from other domains, you may also go for Lax or Strict as this increases security.

Session Cookie Same Site Relaxation (Experimental)

Some older browsers treat cookies with SameSite=None as Strict.

See this example bug report for Safari:

Bug 198181 - Cookies with SameSite=None or SameSite=invalid treated as Strict

Enable this feature to map a filter to the root location /* which evaluates the User-Agent request header to remove SameSite=None for browsers which are known to be affected.

Session Validation

A newline separated list of rules declaring attributes that must not change in the same session. A rule has the following syntax:

ENV|CONST|PARAM|HEADER:<name of the attribute>:block|invalidate

• block: the request will be blocked and 403 (Forbidden) will be returned
• invalidate: the session will be invalidated and a new one will be created

nevisProxy Conditions are supported. See nevisProxy reference guide for details.

For instance, use the following configuration to terminate the session if the source IP changes:

ENV:REMOTE_ADDR:invalidate

Session Timeout

Defines the idle timeout of a nevisProxy session.

A nevisProxy session will be created only if required (e.g. to store application cookies).

Please set the timeout as low as possible to not increase the risk of session exhaustion attacks.

Nevis recommends not to exceed the default. A high session timeout in Unauthenticated Realm is strongly discouraged as it opens the door to DoS attacks: nevisProxy can be brought down by creating millions of sessions with simple GET requests.

Max Session Lifetime

Define the maximum lifetime of a nevisProxy 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.

User Information

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

The pattern renders a GUI with a label and an optional button.

You can also use the pattern to show error messages, and terminate the authentication flow.

The following table describes expected configurations:

Message	Button	On Submit	Description
error	submit	no set	Terminates the session. Button restarts the flow.
error	none	no set	Use for fatal errors, when there is no way to continue.
warning	cancel	not set	Show an error and restart the flow from the beginning.
warning	submit	set	Show an error and allow the user to continue.
info	submit	set	Show a message and allow the user to continue.

Message Type

• error - terminates the session (AUTH_ERROR) and shows an error message.
• warn - does not terminate the session (AUTH_CONTINUE) but the message is shown as an error.
• info - renders as a message of type info and does not terminate the session (AUTH_CONTINUE).

Terminating the session needs careful testing as state loss can lead to follow-up errors.

Title

Enter a label for the title. No expressions are supported.

By default, the label title.login is used. This label is which is translated as Login in all languages.

We recommend to use a different label depending on your use case.

Translations for the label can be defined in the realm pattern.

Message

Enter a label or an expression for the text message that shall be presented to the user.

Translations for the label can be defined in the realm pattern.

If not set the expression ${notes:lasterrorinfo} is used.

Button Type

Adds a button to the GUI:

• none - no button is added
• submit - adds a submit button. To continue with On Submit the Message Type must be warning or info.
• cancel - adds a cancel button. The button restarts the authentication flow from the beginning. The flow must be reentrant.

On Submit

Define a follow-up step.

The Button Type should be set to submit, but the form can also be submitted by other means (e.g. refreshing the browser).

User Input (multiple fields)

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

A step to ask the user for multiple inputs and store the input in variables. Use the variables in subsequent authentication steps.

Title

Enter a text or litdict key for the form title (<h1>).

Greeting

Enter a text or litdict key to be displayed in a line below the title.

The text should inform the user what has to be entered in this form.

Input Fields

List to contain Custom Input Fields and Email Input Fields, to retrieve information from the user.

Buttons

Assign an Dispatcher Button to add a button which points to a different authentication step.

On Success

Configure the step to execute after the user has provided input. If no step is configured here the process ends with AUTH_DONE.

User Input (single field)

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

A simple step to ask the user for some input and store the input in a variable. Use the variable in subsequent authentication steps.

Title

Enter a text or litdict key for the form title (<h1>).

Greeting

Enter a text or litdict key to be displayed in a line below the title.

The text should inform the user what has to be entered in this form.

Label

Enter a text or litdict key to be displayed as label in front of the input field.

Variable Name

Enter <scope>:<name> of the variable which shall be set.

The following scopes are supported:

• inargs
• notes
• sess or session

For instance, enter notes:loginid to prefill the login form which is produced by the nevisIDM Password Login pattern.

On Success

Configure the step to execute after the user has provided input. If no step is configured here the process ends with AUTH_DONE.

Remember Input

Enable this feature to show a Remember Input checkbox.

If selected the user input is stored in a cookie (named like this step) so that the value can be prefilled on subsequent authentications.

User Notification (Adaptive Authentication)

#User Behavior Analytics #Experimental

Plugin: nevisadmin-plugin-nevisadapt

The pattern works out-of-the-box as a follow-up for nevisAdapt Authentication Connector step.

It sends notifications to users about suspicious login attempts.

Configure nevisIDM to send notifications as described here.

nevisIDM

Reference for the nevisIDM service. The nevisAdapt Authentication Connector uses nevisIDM's REST API to send notification emails to the user if the calculated weighted risk score exceeds the configured threshold.

On Success

Set the step to continue with on successful authentication.

Notification type

This mandatory property selects the actual communication event and thus the used template text type.

Sending method

This mandatory property defines the communication method. For the configuration and usage of these methods, refer to the nevisIDM reference guide.

Asynchronous communication

This property defines whether the communication should happen immediately (disabled) or via the EventQueue (enabled).

Usernameless Out-of-band Mobile Authentication

#Mobile Authentication #Experimental

Plugin: nevisadmin-plugin-nevisfido

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.

Virtual Host

#Application Protection #Virtual Hosts

Plugin: nevisadmin-plugin-nevisproxy

The pattern represents a virtual host of a nevisProxy Instance.

A virtual host provides access to applications: applications are reachable on their Frontend Path(s) on all of the Frontend Addresses of this virtual host.

To assign an application, add a Web Application, REST Service, or SOAP Service pattern, and reference this virtual host.

The pattern supports IP-based, port-based, and name-based virtual hosting. Name-based virtual hosting with HTTPs requires server name indication (SNI).

Basic Usage

Define the addresses under which the host is reachable using Frontend Addresses.

The addresses must be fully qualified, they have to they have to start with http:// or https://.

You can define multiple addresses and you can mix HTTP and HTTPs, as long as you do not use more than one port for each protocol.

Examples:

Frontend Addresses: https://www.siven.ch
Frontend Addresses: https://www.siven.ch http://www.siven.ch http://partners.siven.ch
Frontend Addresses: https://www.siven.ch:8443 http://www.siven.ch:8080 http://partners.siven.ch:8080

The pattern is required for all nevisProxy instances, even those having only one frontend address.

Listening on Internal Addresses

Set Bind Addresses to make the host listen on addresses (DNS host names or IPs and ports) other than the configured frontend addresses.

Supporting both HTTPS and HTTP

To expose a host using HTTP and HTTPS, specify the two schemas in Frontend Addresses:

Frontend Addresses: https://www.siven.ch http://www.siven.ch

Name-based Virtual Hosts

With name-based virtual hosting, the server relies on the client to report the hostname as part of the HTTP headers. Using this technique, many different hosts can share the same IP address.

To configure name-based virtual hosts, set the Frontend Addresses to the virtual name(s) of the host and set the Bind Addresses to the physical addresses of the host.

For example, to set up a two virtual hosts to be reachable on the same internal address IP and port but with different public host names, configure as follows:

Frontend Addresses: https://www.siven.ch http://www.siven.ch
Bind Addresses: https://0.0.0.0:8443 http://0.0.0.0:8080

Then configure another virtual host to use the same Bind Addresses but different Frontend Addresses:

Frontend Addresses: https://partners.siven.ch http://partners.siven.ch
Bind Addresses: https://0.0.0.0:8443 http://0.0.0.0:8080

Note: name-based virtual hosts using HTTPS requires all clients supporting SNI.

nevisProxy

Assign the nevisProxy Instance this virtual host should be assigned to.

Frontend Addresses

Define addresses (HTTPS or HTTP) at which this host will be reachable from a client perspective.

The basic syntax is:

• <scheme>://<hostname>
• <scheme>://<hostname>:<port>

A variable may be used to define different addresses for different stages (e.g. DEV, TEST, PROD).

The expression ${deployment_host} may be used when the name of the target host is required.

Examples:

• http://www.siven.ch
• https://www.siven.ch
• http://${deployment_host}:8080

The port will, if omitted, default to 443 for HTTPS and to 80 for HTTP.

You also have to set Bind Addresses if:

• the addresses cannot be resolved on the target host(s)
• the port should be opened on different addresses / IPs, or ports.
• multiple virtual hosts should listen on the same endpoint (name-based virtual hosts).

Bind Addresses

The physical address(es) to bind on, with scheme HTTP or HTTPS and ports.

Must be set when multiple virtual hosts should listen on the same endpoint (name-based virtual hosts).

If not set the Frontend Addresses will be used to bind.

The host name must resolve to an IP which is bound to a network interface.

You can also use 0.0.0.0 for the host name to listen on all network interfaces.

Examples:

https://www.siven.ch:8443
http://localhost:8080
https://192.168.1.1:443
http://0.0.0.0:80

Frontend Key Store

A key store is required when HTTPS is used for any of the Frontend Addresses.

If not set a key store will be set up automatically. This requires automatic key management to be enabled.

The key store should provide a certificate which is valid for all frontend addresses, e.g. because SANs (subject alternative names) are set or because it is a wildcard certificate.

In a Kubernetes deployment the TLS connection is terminated by an NGINX Ingress in front of nevisProxy and this configuration does not apply. The required key material will be generated automatically.

You can configure the NGINX Ingress to use key material from a Kubernetes secret as follows:

1. assign a NGINX Ingress Settings pattern to your nevisProxy Instance via Additional Settings
2. in the NGINX Ingress Settings pattern configure TLS Secrets.

Frontend Trust Store

Set a trust store to validate client certificates for incoming TLS connections.

The trust store may contain an arbitrary number of CA certificates. Client certificates must be signed by those CAs.

Caution: client certificate authentication is not enabled automatically. As of release 4.3.1 there are no dedicated patterns but client cert authentication can be enforced for the entire host (e.g. using Generic nevisProxy Settings) or in the authentication process (X509State and IdentityCreationFilter init-param ClientCert).

Frontend TLS Settings

Choose between:

• recommended: for high security, apply the recommended settings for SSLProtocol and SSLCipherSuite. The settings may change in future releases. Check the nevisProxy Technical Documentation for details. This works with modern browsers and clients. Current recommended values are:

  sslProtocol = '-all +TLSv1.2 -TLSv1.3'
  sslCipherSuite = 'ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256'

• compatible: the SSLProtocol and SSLCipherSuite will be based on Mozilla's SSL configuration for Apache server. These settings provide high compatibility with older browsers and clients. Current compatible values are:

  sslProtocol = '-all +TLSv1.1 +TLSv1.2 -TLSv1.3'
  sslCipherSuite = 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA'

• custom: assign a TLS Settings pattern via Additional Settings to apply your own configuration. If not provided, SSLProtocol and SSLCipherSuite follow the recommended settings.

Root URL Redirect

Set to redirect requests for the root path (/) to an absolute path or a full URL.

Hosted Resources

Upload a ZIP to provide your own resources.

By default, the following resources are provided:

• /favicon.ico
• /index.html
• /errorpages/403.html
• /errorpages/404.html
• /errorpages/500.html
• /errorpages/502.html
• /resources/logo.png
• /resources/bootstrap.min.css
• /resources/default.css

This host has its own error handler (ErrorHandler_Default) which is assigned to the root location (/*). The error handler will replace the response body when an HTTP error code occurs and an error page is available.

Error pages for HTML must be added the sub-directory errorpages and named <code>.html.

The error code is returned to the caller as this may be required by some REST clients.

If you do not want this you can assign a specific HTTP Error Handling pattern to this Virtual Host or to applications via Additional Settings.

The servlet hosting the above resources is usually mapped to the root location (/*), however if there is already another servlet mapped there, the servlet is mapped to individual root files and directories.

If there is an undesired mapping, it can be deleted by removing the given resource from the zip file.

Session Store

Assign a nevisProxy Remote / Hybrid Session Store pattern here if you want to store sessions in a remote session store.

A remote session store must be used when the nevisProxy instance is deployed with redundancy and there is no sticky load balancer in front.

Unsecure Connection

This property defines how to handle requests received via plain HTTP. Choose between:

• redirect If a request is received via plain HTTP the client is redirect to the HTTPS endpoint (requires a Frontend Address with scheme https://).
• allow the request is processed.

Require Client Certificate

Choose from:

• disabled (default): No client certificate is required to connect to this virtual host.

• enabled: Clients must present a client certificate signed by a CA. The CA which has issued the client certificate must be part of the Frontend Truststore. When no client certificate is presented or the certificate is not valid the connection will be aborted. As no error page is rendered this feature is not recommended when there are browser-based clients. Use for technical clients only.

Qos Configuration (mod_qos)

nevisProxy uses the mod_qos module to ensure quality of service (QoS). Choose between:

• off: the module is disabled on this virtual host.
• standard: provides a default configuration which protects against common denial of service (DoS) attacks.
• custom: configure Generic mod_qos Configuration via Additional Settings.

Allowed HTTP Methods

Define the HTTP methods which are allowed on this virtual host.

The setting default (complete) is quite relaxed as it enables most methods. Only two are excluded:

• CONNECT: no use case of nevisProxy.
• TRACE: may be useful for debugging but can be a security vulnerability.

If you do not have any applications using WebDav select basic.

The allowed HTTP methods can be restricted further in application patterns.

For more fine-grained control you may use Generic nevisProxy Instance Settings to overwrite the allowedMethods (see pattern help for details).

OWASP ModSecurity CRS Version

Allows to select the OWASP ModSecurity CRS version.

Available options are:

• 4.7.0: newest version of CRS, uses Anomaly Scoring Mode, minimal CRS setup
• 3.3.5: default and recommended setup, uses Anomaly Scoring Mode
• 3.3.2: previous version of CRS, uses Anomaly Scoring Mode, kept for easier migration
• custom: allows to upload a custom rule set. See the ModSecurity Rule Set option for more information.

The following HTTP methods are allowed by default when selecting any of the included versions:

CHECKOUT, COPY, DELETE, GET, HEAD,
LOCK, MERGE, MKACTIVITY, MKCOL, MOVE, OPTIONS,
POST, PROPFIND, PROPPATCH, PATCH, POST, PUT, TRACE, UNLOCK

ModSecurity Rule Set

Upload a .zip file containing configuration for ModSecurity. The .zip must contain a configuration file called modsecurity.conf.

The modsecurity.conf file will be included for all Web Application patterns which have Request Validation set to standard, custom, or log only.

Click Download Default Configuration to download the default configuration which is applied when no .zip is uploaded. There is one link per provided OWASP ModSecurity CRS Version.

Security Response Headers

Configure security response headers:

• off does not set any security headers
• basic sets default headers on responses. That is:
  • Strict-Transport-Security: max-age=63072000
  • X-Content-Type-Options: nosniff
  • Referrer-Policy: strict-origin-when-cross-origin
• custom configure Security Response Headers via Additional Settings

Session Store Resource

Exposes the REST interface of the session store servlet on the given path. For security reasons, only DELETE requests are allowed and assigning an access restriction pattern is recommended.

Before setting this parameter, make sure that there will be an actual session store servlet.

Session Store Access Restriction

Assign an access restriction patterns to prevent unauthorized access to the REST interface of the session resource.

HTTP/2 Support

Enables the support of HTTP/2 for incoming connections on this nevisProxy virtual host.

Note that mod_qos has limited support for HTTP/2, therefore only request level directives are supported if enabled.

Early Hints

Enables the HTTP/2 feature of early hints.

Configures early hints with the Apache directive H2PushResource

It will send out a "103 Early Hints" response to a client as soon as the server starts processing the request.

Static Cache

Add a Static Content Cache pattern to the Virtual Host.

Use it to cache the early hint resources as static content in nevisProxy to further increase the performance. Map the Static Content Cache pattern to the same paths as the Early Hints parameter.

Encoded Slashes

Choose from:

• allowed: URLs containing encoded slashes are allowed and will not be decoded (AllowEncodedSlashes NoDecode). Also URLEncoding will be set to false for each HttpsConnectorServlet.

• forbidden: URLs containing encoded slashes will be denied and a 404 will be returned. This is the default behaviour of Apache.

Additional HTTP Status Codes

Allow non-standard HTTP status codes.

The configuration of additional status codes is required, for example, when using WebDav (HTTP status code 207 is used by WebDav).

Trailing Slash Redirect

nevisProxy generates redirects to the same resource with a / appended, in case a servlet mapping only matches, when the trailing / is present.

Additional Settings

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

Web Application

#Application Protection #Applications

Plugin: nevisadmin-plugin-nevisproxy

Using the pattern, you can set up access to a web application on a nevisProxy Virtual Host.

Virtual Hosts

Assign Virtual Host patterns which shall serve as entry point for this application.

Frontend Path(s)

Enter the path(s) where this application shall be accessible on the assigned Virtual Host.

It is recommended to set only 1 path. Examples:

• /app/ - defines a base path. Requests which have a path component starting with /app/ will be sent to this application. This is the most common scenario.

• / - may be used when there are no other applications. The Hosted Resources of the Virtual Host are still accessible but all other requests will be sent to the backend application.

• exact:/app.html - matches requests to /app.html only (query parameters may also be added). Use for single-page applications which don't require any additional resources.

• prefix:/app - matches requests which have a path component starting with /app. Examples: /application, /app/index.html, /app2/secure/

In case the frontend path is different from the path used within Backend Addresses then the path will be rewritten in incoming requests.

Note that for response by default only the headers are rewritten. See Response Rewriting for further options.

Note that when you enter multiple paths there are some limitations:

• Filters created by a Realm or Additional Settings will be mapped to all paths.
• The paths have to be the same on the backend server.

Authentication Realm

Optionally assign a realm to protect this application or service.

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.

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.

Backend Addresses

Enter the complete URLs (scheme, host, port and path) of the backend services.

Note:

• all URLs must use the same scheme and path.
• automatic path rewriting will be performed when the path differs from the Frontend Path.

In case you are setting multiple addresses, use Load Balancing to select a request dispatching strategy.

Load Balancing

Select a request dispatching strategy when several Backend Addresses are configured.

• disabled - all requests will be sent to the first address. If this address is not available the next address is chosen;
• round-robin - one of the addresses will be picked up for each request using a round-robin rotation;
• session-sticky - one of the addresses will be picked up for each new session using a round-robin rotation, then subsequent requests for the session will be sent to the same address.

Failover strategy:

• When the selected backend cannot be accessed, nevisProxy will attempt to use another one.
• Once the said backend can be accessed again, it can be picked up for new requests if the load balancing is round-robin, or for new sessions if the load balancing is disabled or session-sticky. The requests linked to an existing session will still go to the current backend until the end of the session if the load balancing is disabled or session-sticky.

Key Store

Optional setting to use a client certificate for connecting to HTTPS backends.

Send Certificate Chain

Choose which certificates are sent to the backend during mutual authentication:

• disabled: Send the client certificate from the Key Store;
• enabled: Send the certificate chain from a PEM Key Store or a nevisKeybox Store. The certificate chain file must contain the client certificate and the intermediate CA certificates.

Trust Store

Optional setting for enabling trust to HTTPS backends.

For securing production environments:

• set Backend Addresses starting with https://
• assign a Trust Store pattern containing the certificates required for verifying the backend certificate
• set Hostname Validation to enabled

Hostname Validation

Enable to verify that the hostname on the certificate presented by the backend matches the hostname configured in Backend Addresses

Host Header

Defines the Host header for requests forwarded to the application.

When backend is selected then nevisProxy uses the host part of the backend address that has been selected. This is the default behaviour and similar to what a browser would do. Therefore, this configuration should work in most cases.

When client is selected then nevisProxy will keep the Host header as received from the client. The following init-param will be generated:

<init-param>
  <param-name>HostName</param-name>
  <param-value>ENV:HTTP_Host;</param-value>
</init-param>

The configuration is dynamic to support virtual hosts with multiple frontend addresses. Note that this may be less secure. Even though browsers do not allow this clients may sent an arbitrary value for the Host header. It is therefore recommended to test how your application behaves in this case.

Response Rewriting

Enable to replace backend host names in responses or set to custom for complex rewriting use cases.

• off - disables automatic response rewriting
• header - enables auto rewrite for response headers (including Set-Cookie header)
• complete - enables auto rewrite for the entire response (including body)
• custom - requires assignment of Response Rewriting Settings via Additional Settings

CSRF Protection

Cross-Site Request Forgery (CSRF) is an attack to force an authenticated user to send unwanted requests.

• off (default) - no CSRF protection. Recommended for applications which may be called from other sites.
• header-based - GET and HEAD requests are allowed (assumption: these methods must not manipulate server-side state). For other requests the Referer and Origin headers must match the Host header.

Request Validation (ModSecurity)

• off - no request validation
• standard - uses ModSecurity OWASP Core Rule Set (CRS) with default paranoia level 1 - Basic security
• custom - configure Request Validation Settings via Additional Settings
• log only - uses standard in log only mode

Allowed HTTP Methods

Define the HTTP methods allowed for this application.

Methods which are listed here must also be allowed on the Virtual Host.

You may also use the following method groups:

• ALL-HTTP includes common HTTP methods.

  These are: GET, POST, HEAD, DELETE, TRACE, CONNECT, OPTIONS, PUT, PATCH

• ALL-WEBDAV includes all methods required for WebDAV.

  These are: MERGE, UNCHECKOUT, MKACTIVITY, PROPPATCH, LOCK, CHECKOUT, SEARCH, COPY, MKCOL, MKWORKSPACE, PROPFIND, UPDATE, REBIND, BASELINE-CONTROL, UNBIND, CHECKIN, VERSION-CONTROL, UNLOCK, LABEL, MOVE, ACL, BIND, REPORT

To remove methods from ALL-HTTP and ALL-WEBDAV simply add the method with a - sign in front of it.

Session Termination

Use this feature to terminate sessions on the backend application.

nevisProxy will send a GET request to this path when the nevisProxy session is terminated (due to logout or session timeout).

Custom Parameters

Add custom init-param(s) for the Http(s)ConnectorServlet. For example: ConnectionRetries=10

Please check the nevisProxy technical documentation for supported init-params of the servlet classes ch::nevis::isiweb4::servlet::connector::http::HttpConnectorServlet and ch::nevis::isiweb4::servlet::connector::http::HttpsConnectorServlet.

WebSocket Support for Application

#Application Protection #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

The pattern enables WebSocket support for backend applications. Assign to your application using Additional Settings.

The pattern generates two additional servlets:

• a WebSocketServlet named Connector_<application>_WS
• a ServletMappingServlet which selects Connector_<application>_WS when the HTTP Header Upgrade contains the value websocket

The TCP connection is reserved for each WebSocket connection.

Custom Parameters

Add custom init-param for the WebSocket servlet.

Please check the nevisProxy technical documentation for supported init-params of the servlet class ch::nevis::isiweb4::servlet::connector::websocket::WebSocketServlet.