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, or

Ask our AI Pattern-bot!

Filter by category

Placeholder Values

placeholder:// values are experimental. They are intended for Git deployments where a continuous integration and continuous delivery (CI/CD) pipeline replaces markers in generated files before deployment. The pattern generator removes every placeholder:// prefix and preserves the remaining text unchanged. It does not resolve or replace the marker.

These enhancements are available in nevisAdmin 4 Patterns version >= 9.2605.4 in the RR line and >= 8.2607.2 in the LTS26 line.

The syntax is:

placeholder://<marker-name>

The marker name may contain only ASCII letters, digits, underscores, and hyphens. For example:

placeholder://WASL_DOMAIN
placeholder://@@WASL_DOMAIN@@

The @@ characters are optional delimiters for making markers easy to identify; they are not part of the marker name. Bare markers may occur inside a larger scalar and end at the first character outside the marker-name character set:

https://login.placeholder://tenant-prod.example

The marker in this example is tenant-prod; .example remains unchanged. A scalar can contain multiple markers:

placeholder://@@ALLOWED_IP_RANGE_1_FROM@@ - placeholder://@@ALLOWED_IP_RANGE_1_TO@@

Do not put Helm, Kustomize, Jsonnet, Argo CD, shell, or other deployment-tool template expressions inside a marker. For example, this is not supported:

placeholder://{{ .Values.domain }}

Do not use a complete unresolved URL as a placeholder:

placeholder://https://login.example/issuer

nevisAdmin 4 does not interpret the marker or know which CI/CD tool will process the generated files. The CI/CD pipeline is responsible for replacing the remaining marker before deployment. The replacement must preserve the generated configuration syntax and structure.

Use placeholders only where the setting accepts a scalar value and the pattern can generate its configuration without interpreting the marker. If a pattern validates, parses, or uses the value to choose a generation branch, such as a dropdown or other selection that produces different configuration, a placeholder cannot be used. A placeholder represents one scalar or one sequence item; it does not expand into multiple items, a sequence, a map, or another structured value.

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 File

IP geolocation database file for country filtering.

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

Country Database URL

IP geolocation database URL for country filtering.

The resource behind the given URL is periodically downloaded and used as an IP geolocation database. Currently only the mmdb format (MaxMind Database) is supported. This is a binary file format. Using dbUrl and dbFile together is not supported, only set one of them.

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 behavior:

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.

Custom GeoLocation Lookups

The geolocation database contains multiple attributes to its IP-groups. The attribute(s) that are retrieved by an IP-lookup can be altered using this parameter. To check what attributes are in your database, use the tool mmdbinspect. To set a path, separate its elements by slashes (/). Each lookup entry contains a path as key and an output variable name as value. This output variable makes the returned entries accessible from LuaFilter with req:getAttribute('output_var').

Examples:

country/names/en➜geolocation: Uses the country's English name and sets the geolocation request attribute.
country/iso_code➜countrycode: Uses the country's two letter long code and sets the countrycode request attribute.
country/names/en➜geolocation, country/iso_code➜countrycode, continent/code➜continentcode Keep the default country name but also set the country code and continent code.

By default, the country's English name is used.

Country Database Download Periodicity

The IP geolocation database download periodicity. Only has effect when the database URL is set.

Access Token Consumer

#Federation #Authentication #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

This step generates an AccessTokenConsumer AuthState which is able to validate access tokens issued by an OAuth 2.0 Authorization Server / OpenID Provider.

Use this step in the Initial Authentication Flow of a Authentication Realm to provide a 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 session variables prefixed with oauth2.token.claim..

The sub claim of the access token will be used as user ID for nevisAuth. This is technically sufficient for authentication.

However, it is recommended to perform additional checks in subsequent steps. For instance, you may use a nevisIDM User Lookup step to look up a user in nevisIDM.

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

This pattern is experimental and it has some 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 that is part of this project.

If you need improvements for this pattern, please create a feature request.

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 #Add-ons #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.

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

AuthState Patch

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

Patches AuthState elements generated by other patterns.

We recommend to use this pattern only if there is no other alternative. Consider creating a ticket at Nevis with your requirements.

If want to add a ResultCond element where the next points to an AuthState that is not yet part of any flow, you can assign the pattern that generates this AuthState via Additional Steps.

Authentication Realm

Assign the authentication realm pattern that generates the AuthState elements that you want to patch.

Patch File

Upload an XML file containing patches for AuthState elements.

The name has to match an existing AuthState. Check the esauth4.xml in the deployment preview to find out which elements exist.

You can change overwrite any other attribute of the AuthState, such as class, final, and resumeState.

The following example shows the basic syntax:

<AuthState name="example-realm_example-state" 
           class="ch.nevis.esauth.auth.states.directResponse.DirectResponseState" 
           final="true" resumeState="false">
    <Response value="AUTH_ERROR"/>
    <property name="statusCode"     value="401"/>    
    <property name="contentType"    value="application/json"/>
    <property name="content"        value='{"status":"forbidden"}'/>
</AuthState>

The patches are generally additive. However, you can also remove child elements.

To remove a property, set an empty value:

<property name="example" value=""/>

Likewise, to remove a ResultCond element, leave the next attribute empty:

<ResultCond name="example" next=""/>

Additional Steps

Assign any steps that are referenced by your patches.

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

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 Management 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(s)

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.

Button Order

Choose primary to show the primary button before any additional buttons.

Choose reverse to display the primary button last.

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 configures authentication.

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 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 pages during authentication, a Login Renderer is used.

Initial Authentication Flow

The initial authentication flow starts with the assigned authentication step. To create a multistep flow, 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 multistep 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.

Unlock Flow

To support the unlock method assign a step here.

This method is triggered by nevisProxy in the following cases:

after the session was locked due to timeout
after the session was locked with a request containing the query parameter ?lock

This is an advanced configuration.

The unlock method is sometimes used in setups where nevisProxy acts as a reverse proxy in front of applications.

Logout Flow

The default logout behavior is as follows:

the logout is invoked by a request to a protected application with query parameter ?logout.
nevisAuth receives a request with method logout. The default implementation simply terminates the session and returns a Gui descriptor
a page is shown that informs the user that the logout is done.
when the user clicks the Continue button, they can log in again on the same URL.

To replace this behavior, assign a step here. The following step types are supported:

Logout: this step has settings that apply to the logout flow
Generic Authentication Step: in case you need a custom implementation

To offer the logout function to the user, you have to add a link to your applications.

When this realm is used through a SAML IDP, then customization of the logout flow is limited. This is because the SAML protocol defines how logouts are performed.

The only thing that you can customize in case of SAML is the URL to redirect to in case of IDP-initiated SAML logout, after the SAML logout is done, and the process ends on the IDP side. To do this, you have to assign a Logout pattern and configure a custom Redirect.

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

Choose a login renderer.

In Kubernetes deployments, assignment of a renderer is mandatory.

Assign either a nevisLogrend Instance or a Proxy Login Renderer pattern.

The renderer has to be compatible with the Default Template (see Login Template tab).

In classic VM deployments, a default login renderer will be created when no pattern is assigned.

In case of nevisLogrend, the instance will be called default and deployed on the same host as nevisProxy.

Key Store

Configure a key store to use for 2-way TLS connections to nevisLogrend.

If no pattern is assigned no key store will be created.

The connection will be either 1-way TLS or plain HTTP, depending on the URL of nevisLogrend.

This configuration does not apply when a Proxy Login Renderer is used.

Trust Store

Configure a trust store to use for TLS connections to nevisLogrend.

If no pattern is assigned an automatic trust store will be created.

This configuration does not apply when plain HTTP or the Proxy Login Renderer is used.

Hostname Validation

When enabled the server cert has to match the hostname of nevisLogrend.

This configuration does not apply when plain HTTP or the Proxy Login Renderer is used.

nevisLogrend / Application default.properties

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

This is an advanced setting. Use only when there is no other alternative and consider creating a support ticket with your use case.

Check Login Application Configuration for supported properties.

We recommend to not overwrite any language related properties, as the languages have to be in sync with nevisAuth. You can configure the supported languages on the nevisAuth Instance.

This setting requires that nevisLogrend is used for GUI rendering. Check the help of Login Renderer for details.

Template Style

Choose a default template:

classic: default in releases before May 2025.
modern: default since May 2025.
proxy: a template for the nevisProxy Login Renderer.

The modern template is recommended for new setups.

Company Logo

Upload a logo to be displayed on the login page.

The logo file should have an appropriate size, e.g. 50x50 pixels.

Out of the box, this setting is supported by the modern template only.

If you use a different nevisLogrend template, you can add the expression ${logo} to point to the uploaded file.

Download the modern template to see how the expression is used there.

Primary Color

Configure the primary color.

Out of the box, this setting is supported by the modern template only. It is used to color buttons.

If you use a different nevisLogrend template, you can add the expression ${primaryColor} in your CSS file.

Download the modern template to see how the expression is used there.

Border Radius

Configure the corder radius of the login box.

Out of the box, this setting is supported by the modern template only.

If you use a different nevisLogrend template, you can add the expression ${borderRadius} in your CSS file.

Download the modern template to see how the expression is used there.

Font Family

Configure the font family.

By default, this setting is supported by the modern template only.

If you use another template, you can reference the expression ${fontFamily} in your CSS file.
Check the modern template for an example of how the expression is applied.

The actual font used depends on the browser and operating system.

You can specify multiple font families, separated by commas, to provide fallbacks.
The CSS files in the template append additional fonts to ensure all characters (even emojis) can be rendered.

This approach follows the idea described here: Bootstrap Native Font Stack.

Example values:

Arial, sans-serif
Helvetica, Arial, sans-serif
Times New Roman, serif

Template Customization

Customize the rendering of login pages.

Download one of the default templates to get started.

nevisLogrend: Direct Mode

You can upload Velocity template files 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: static resources (e.g. images, CSS, Javascript)

nevisLogrend: Expressions

In nevisLogrend templates you may use the following expressions:

Expression	Description
`${form}`	login form (`form.vm`)
`${lang.switch}`	language switcher component (`lang.vm`)
`${lang.code}`	current language code (i.e. `en`, `de`)
`${label.myLabel}`	a label which must be translated via `Custom Translations`
`${resources}`	path to static resources (e.g. CSS, images, Javascript)
`${resource:<name>}`	path to static resource `name` with attached hash

These expressions will be replaced with a corresponding Velocity snippet at generation time.

For instance, using the expression ${resource:bootstrap.min.css} with the modern template yields the following path:

${login.appDataPath}/resources/bootstrap.min.css?v=3f1c72e8.

Note that the expression ${login.appDataPath} is handled at runtime by nevisLogrend.

nevisProxy provides a basic login 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.

nevisLogrend: Simple Mode

In simple cases you may not have to deal with Velocity template files.

To replace the outer HTML you can upload a file named template.html. The template must contain the ${form} expression.

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}/logo.png" alt="Company Logo">
    </header>
    <main id="content" class="container">
      ${form}
    </main>
  </body>
</html>

Customization Mode

Choose between:

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.
complete: only the files uploaded as Login Template will be deployed.
- Use this option when you want to provide the entire template.

Dynamic Template Selection

Configure how the login template is selected based on the request. Choose between:

disabled: The login template configured in this tab is used.
OAuth client: select the login template based on the OAuth client ID.

The OAuth client variant requires that you fill out the Template Selection Rules table.

Template Mapping

When Template Selection is set to OAuth client, you have to define which login template to use for which OAuth client ID.

Fill out this table as follows:

Key: The OAuth client ID.
Value: Index within Login Templates

Dynamic Templates

Assign additional login templates that are dynamically selected based on the request.

Check the Template Selection and Template Selection Rules settings for details.

This setting is ignored when Template Selection is disabled.

Default Translations

Choose between:

enabled - add translations for labels which are commonly used (e.g. title or language.* labels in nevisLogrend, error.* labels in nevisAuth) and which are provided by realm patterns (e.g. assigned authentication steps).
disabled - add only what has been uploaded via Custom Translations. If your translations are incomplete, users will see the untranslated labels.

Note that nevisAuth supports only 1 set of translations and the generation is cumulative. Thus, if you have 1 nevisAuth Instance with multiple realms, and you want to leave out default labels, then you have select disabled in all these realms.

Custom 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

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

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.

When CUSTOM is selected, an empty filter will be generated based on the name of the realm:

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

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.

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.

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.

Configures the number of seconds a cookie is still valid after a new cookie is generated, for example, due to a successful login.

Increasing the value can help minimize the chance of session loss during a login or step-up with parallel requests.

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 Parameters (SessionManagementFilter)

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

Examples:

Key	Value
Cookie.Persistent	true
Cookie.Path	/some/path

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.

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 behavior:

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

Custom Parameters

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.

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 Cert(s)

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 #Add-ons #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.

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

Certbot Key Store

#Key Management #Experimental

Plugin: nevisadmin-plugin-nevisproxy

Sets up a key store that uses certbot to request a certificate from Let's Encrypt via the ACME protocol.

This pattern can only be used in classic deployment and requires that certbot is installed on the deployment host.

The pattern was tested in combination with nevisAppliance as Frontend Key Store in the Virtual Host pattern.

The pattern is experimental and provided as a proof of concept so that you can try it out.

If you need additional settings or want to use the pattern in another place, you may request a pattern improvement by raising a feature request with Nevis.

The certbot command will open a service on port 80 as the CA (Let's Encrypt) has to do a callback to validate the DNS name. The alternative mode (DNS01) is not supported.

This pattern generates the required command and also ensures that the nevisProxy instance is restarted, once the new key material is available.

Certbot will register a job that will renew the certificate before expiry.

Admin Email

Enter an email address.

The email will be handed over to the certbot command and can be used by the CA for urgent renewal and security notices.

If not configured, then an email will be determined based on primary domain of the Virtual Host.

That email will be noreply@<domain>.

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

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

Credential Intelligence

#Authentication #Connector

Plugin: nevisadmin-plugin-nevisauth

This plugin provides a step that checks the password against the Have I Been Pwned database.

The Have I Been Pwned database is a collection of passwords that have been exposed in data breaches. The step checks the password against the database and returns a configurable warning if the password is found in the database.

If you are using labels, please make sure the following labels are available in the translation: credential_intelligence.title, credential_intelligence.message, credential_intelligence.continue_button, credential_intelligence.change_password_button

You can find these labels in the translation file Authentication Realm > Translations > Custom Translations, within the corresponding language files (e.g.: labels_en.properties).

Example setting:

credential_intelligence.title=Credential Intelligence
credential_intelligence.message=You should change your password.
credential_intelligence.continue_button=Continue
credential_intelligence.change_password_button=Change Password

On Continue

This is the default next authentication step.

Notification Type

Password Change Optional (password-change-optional)

In the Password Change Optional mode, the user has the flexibility to decide whether to change their password or not. This mode provides an option to disregard the message if the user chooses to do so.

Password Change Mandatory (password-change-mandatory)

In the Password Change Optional mode, the user is required to change their password. This mode does not provide an option to disregard the message, ensuring that the password change is mandatory.

Title

It is a text field to change the title of the pages. The default value is exci.title, which is used for translation.

Message

It is a text field to change the message of the pages. The default value is exci.message, which is used for translation.

Continue Button Label

It is a text field to change the change password button's label. The default value is exci.continue_button, which is used for translation.

On Change Password

Text field to change the change password button's label. The default value is exci.change_password_button which is used for translation.

Change Password Button Action

This pattern is used when the user presses the "Change Password" button. It defines the follow-up authentication step required to complete the password change process.

Pattern when using nevisIDM as identity provider: nevisIDM Change Password State

Timeout

The HTTP timeout setting determines the maximum amount of time (in seconds) that the system will wait for an HTTP response before timing out.

If the response times out in the given time, it will not halt and use On Continue as default.

Custom Input Field

#Authentication

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.

Source Variable

Enter a variable to populate the input field.

Use the syntax <scope>:<name>, where <scope> is one of:

sess
notes
inargs
request

Check your nevisAuth log with the log levels of Vars on INFO to find out which variables are available.

Target Variable

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.

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

Plugin: nevisadmin-plugin-nevisauth

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

A typical use case is to add a signup button to a login screen.

Button Label

Enter a label for the text that shall be displayed on this button.

The following labels exist by default:

accept.button.label
cancel.button.label
continue.button.label
login.button.label
reject.button.label
signup.button.label
skip.button.label
submit.button.label

If you want to use another label, you have to define it by providing Translations in your realm pattern.

On Click

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

Button Type

Select inline here to display the button as a link.

Inline Label

Enter a label to be displayed in front of the button.

This setting is used only when Button Type is set to inline.

Button Name

Enter the name of the button.

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

Button Value

Enter the value of the button element.

The default (true) is usually fine.

Change this setting 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.

Source Variable

Enter a variable to populate the email input field.

Use the syntax <scope>:<name>, where <scope> is one of:

sess
notes
inargs
request

Check your nevisAuth log with the log levels of Vars on INFO to find out which variables are available.

Target Variable

Configure the variable where nevisAuth stores the user input.

Use the syntax <scope>:<name>, where <scope> is one of:

sess or session
notes
inargs

In most cases, you will want to use the session scope so the stored value is available to any later authentication step.

However, the notes scope can be useful when you need the value only within the current request, because notes variables are cleared afterward. For example, if the next authentication step is nevisIDM Password Login, you can set notes:loginid to prefill the login form.

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 a one-time code to a user via email.

You can use this pattern for email validation or authentication.

The defaults of this pattern work out-of-the-box when connected to On Success for nevisIDM Password Login.

If you have a different flow, you may have to adapt some settings. For instance, you may have to adapt the Recipient to use the email from a different variable.

To configure the Gui or email content check the corresponding tabs.

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.

SMTP Server

The SMTP service for the sending the email code.

Choose between Sendgrid SMTP and a Generic SMTP patterns.

Buttons

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

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}

Subject

The subject for the email.

The default uses an expression which resolves a label.

This way the subject can be translated.

Body

The body of the email.

The default uses an expression which resolves a label.

This way the subject can be translated.

To keep things simple, the code is added with a second expression.

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.

Show Email

Configure if the email address shall be shown in the UI or not.

Select disabled to not show the email address. The label etan.info will be used in this case.

Select enabled here to also show the email address. In this case, a different label etan.info.email will be used.

Button Order

Choose primary to show the primary button before any additional buttons.

Choose reverse to display the primary button last.

Max Retries

The maximum retry attempts for each code.

When this threshold is reached, the behavior 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 code that the user has to enter.

Option	Format	Testing Mode Code
`4 digits`	4 numbers [0-9]	`1111`
`5 digits`	5 numbers [0-9]	`11111`
`6 digits`	6 numbers [0-9]	`111111`
`4 letters`	4 upper case letters [A-Z]	`AAAA`
`5 letters`	5 upper case letters [A-Z]	`AAAAA`
`6 letters`	6 upper case letters [A-Z]	`AAAAAA`
`4 alphanumeric`	4 out of [0-9A-Z]	`AAA1`
`5 alphanumeric`	5 out of [0-9A-Z]	`AAAA1`
`6 alphanumeric`	6 out of [0-9A-Z]	`AAAAA1`

Testing Mode

Select enabled to not send any code to the user.

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

The code that needs to be entered depends on the selected TAN Format (see Advanced Settings).

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.

Button Order

Choose primary to show the primary button before any additional buttons.

Choose reverse to display the primary button last.

FIDO2 Authentication

#FIDO2 #Authentication

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

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(s)

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

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(s)

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(s)

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.

Button Order

Choose primary to show the primary button before any additional buttons.

Choose reverse to display the primary button last.

#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

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.

Gateway API Rate Limit Rule

#Application Protection

Plugin: nevisadmin-plugin-nevisproxy

Defines a rate limiting rule for the Gateway API.

Max Requests

Configure the maximum number of requests allowed in the selected time period.

Time Period

Configure the time period over which the rate limit is applied (for example, per second, per minute, or per hour).

Gateway API Settings

#Application Protection #Kubernetes #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

In Kubernetes deployments, a Gateway API controller terminates TLS connections and forwards requests to nevisProxy. Basic settings are available in the Gateway API tab in the Virtual Host pattern.

This pattern provides additional options, e.g. related to TLS secrets and client certificate authentication. Assign the pattern to your Virtual Host using Additional Settings.

TLS Secrets

Configure custom TLS certificate(s) for your domain(s).

Enter the fully qualified domain name (FQDN) in the key column and the name of the Kubernetes Secret in the value column.

The domain names correspond to the Frontend Addresses of your Virtual Host which use the HTTPS protocol.

The referenced Kubernetes Secret must:

Be of type kubernetes.io/tls
Contain the following entries in data:
- tls.key – the private key (PEM encoded)
- tls.crt – the certificate (PEM encoded, including the full certificate chain is recommended)

If multiple domains use the same certificate, you can reference the same Secret for each domain.

Gateway Class Name

Defines the gatewayClassName of the generated NevisGateway resource.

Gateway Resource Name

Configure to use an existing Gateway resource.

If not configured, the resource will be created by the Nevis Operator.

Gateway Resource Namespace

Configure to use an existing Gateway resource.

If not configured, the resource will be created by the Nevis Operator.

If set to a different namespace than the deployment, then the IP Detection, Client Cert Auth and Key Exchange Algorithms settings will be ignored.

Key Exchange Algorithms

Configure the allowed key exchange algorithms for TLS connections.

By default, the default of the gateway applies.

Currently, the post-quantum hybrid X25519MLKEM768 and the legacy X25519 and P-256 algorithms are supported.

If Gateway Resource Namespace is set to a different namespace than the deployment, then this setting will be ignored.

Client IP Detection

Choose how to determine the source IP of the request.

The source IP is used by Envoy for the following optional features:

IP Restriction
Rate Limiting

Choose between:

disabled: use the source IP of the incoming TCP request. This option is appropriate when there are no proxies in front of the cluster.
trusted CIDRs:
- IPs found in X-Forwarded-For that match these CIDR expressions will be ignored.
- This option is recommended when you know the outbound IPs of proxies in front of the cluster.
- You have to configure Trusted CIDR Ranges to use this option.
trusted hops:
- You have to configure Trusted Hops to use this option.
- Use the n-th IP address from the X-Forwarded-For header, counting from the rightmost side.

If Gateway Resource Namespace is set to a different namespace than the deployment, then these settings will be ignored.

Trusted Hops

NumTrustedHops specifies how many trusted hops to count from the rightmost side of the X-Forwarded-For (XFF) header when determining the original client’s IP address.

If this value is set to N, the client IP is taken from the Nth address from the right end of the XFF header.

Trusted CIDR Ranges

List of CIDR ranges to trust when evaluating the remote IP address to determine the original client’s IP address.

When the remote IP address matches a trusted CIDR and the x-forwarded-for header was sent, each entry in the x-forwarded-for header is evaluated from right to left and the first public non-trusted address is used as the original client address.

If all addresses in x-forwarded-for are within the trusted list, the first (leftmost) entry is used.

Action Type

Action defines whether to allow or deny the specified IP ranges.

CIDR Ranges

List of CIDR ranges to which the Action Type applies.

Rate Limiting Rules

Assign rules to define rate limits based on the source.

Client Cert Authentication

Enables client certificate validation.

If you want to validate a client cert used by the user agent, and the TLS connection is terminated in front of the Gateway API controller, then you cannot use this setting.

Choose between:

required: Request a client cert that must be signed by a CA cert that is included in the CA Secret. Failed verification will result in a TLS handshake error.
optional: Do optional client cert validation against the CAs.
- When no client cert is provided, the request is allowed to pass through.
- When a client cert is provided, it the logic is the same as for required.
disabled (default): Don't request client certificates and don't do client cert verification.

If Gateway Resource Namespace is set to a different namespace than the deployment, then these settings will be ignored.

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.

Path Match Type

Specifies how to match the HTTP request path.

Value	Description
`PathPrefix`	Matches requests whose path starts with the configured prefix. Default.
`Exact`	Matches requests whose path is exactly equal to the configured value.
`RegularExpression`	Matches requests whose path matches the configured regular expression. Implementation-specific support.

See HTTPPathMatch for details.

Path Value

The HTTP path to match against. Defaults to /.

For Exact and PathPrefix types the value must start with / and must not contain consecutive slashes or path traversal sequences.

Example: /nevis/

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

Choose a login renderer.

In Kubernetes deployments, assignment of a renderer is mandatory.

Assign either a nevisLogrend Instance or a Proxy Login Renderer pattern.

The renderer has to be compatible with the Default Template (see Login Template tab).

In classic VM deployments, a default login renderer will be created when no pattern is assigned.

In case of nevisLogrend, the instance will be called default and deployed on the same host as nevisProxy.

Key Store

Configure a key store to use for 2-way TLS connections to nevisLogrend.

If no pattern is assigned no key store will be created.

The connection will be either 1-way TLS or plain HTTP, depending on the URL of nevisLogrend.

This configuration does not apply when a Proxy Login Renderer is used.

Trust Store

Configure a trust store to use for TLS connections to nevisLogrend.

If no pattern is assigned an automatic trust store will be created.

This configuration does not apply when plain HTTP or the Proxy Login Renderer is used.

Hostname Validation

When enabled the server cert has to match the hostname of nevisLogrend.

This configuration does not apply when plain HTTP or the Proxy Login Renderer is used.

nevisLogrend / Application default.properties

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

This is an advanced setting. Use only when there is no other alternative and consider creating a support ticket with your use case.

Check Login Application Configuration for supported properties.

We recommend to not overwrite any language related properties, as the languages have to be in sync with nevisAuth. You can configure the supported languages on the nevisAuth Instance.

This setting requires that nevisLogrend is used for GUI rendering. Check the help of Login Renderer for details.

Template Style

Choose a default template:

classic: default in releases before May 2025.
modern: default since May 2025.
proxy: a template for the nevisProxy Login Renderer.

The modern template is recommended for new setups.

Company Logo

Upload a logo to be displayed on the login page.

The logo file should have an appropriate size, e.g. 50x50 pixels.

Out of the box, this setting is supported by the modern template only.

If you use a different nevisLogrend template, you can add the expression ${logo} to point to the uploaded file.

Download the modern template to see how the expression is used there.

Primary Color

Configure the primary color.

Out of the box, this setting is supported by the modern template only. It is used to color buttons.

If you use a different nevisLogrend template, you can add the expression ${primaryColor} in your CSS file.

Download the modern template to see how the expression is used there.

Border Radius

Configure the corder radius of the login box.

Out of the box, this setting is supported by the modern template only.

If you use a different nevisLogrend template, you can add the expression ${borderRadius} in your CSS file.

Download the modern template to see how the expression is used there.

Font Family

Configure the font family.

By default, this setting is supported by the modern template only.

If you use another template, you can reference the expression ${fontFamily} in your CSS file.
Check the modern template for an example of how the expression is applied.

The actual font used depends on the browser and operating system.

You can specify multiple font families, separated by commas, to provide fallbacks.
The CSS files in the template append additional fonts to ensure all characters (even emojis) can be rendered.

This approach follows the idea described here: Bootstrap Native Font Stack.

Example values:

Arial, sans-serif
Helvetica, Arial, sans-serif
Times New Roman, serif

Template Customization

Customize the rendering of login pages.

Download one of the default templates to get started.

nevisLogrend: Direct Mode

You can upload Velocity template files 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: static resources (e.g. images, CSS, Javascript)

nevisLogrend: Expressions

In nevisLogrend templates you may use the following expressions:

Expression	Description
`${form}`	login form (`form.vm`)
`${lang.switch}`	language switcher component (`lang.vm`)
`${lang.code}`	current language code (i.e. `en`, `de`)
`${label.myLabel}`	a label which must be translated via `Custom Translations`
`${resources}`	path to static resources (e.g. CSS, images, Javascript)
`${resource:<name>}`	path to static resource `name` with attached hash

These expressions will be replaced with a corresponding Velocity snippet at generation time.

For instance, using the expression ${resource:bootstrap.min.css} with the modern template yields the following path:

${login.appDataPath}/resources/bootstrap.min.css?v=3f1c72e8.

Note that the expression ${login.appDataPath} is handled at runtime by nevisLogrend.

nevisProxy provides a basic login 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.

nevisLogrend: Simple Mode

In simple cases you may not have to deal with Velocity template files.

To replace the outer HTML you can upload a file named template.html. The template must contain the ${form} expression.

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}/logo.png" alt="Company Logo">
    </header>
    <main id="content" class="container">
      ${form}
    </main>
  </body>
</html>

Customization Mode

Choose between:

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.
complete: only the files uploaded as Login Template will be deployed.
- Use this option when you want to provide the entire template.

Default Translations

Choose between:

enabled - add translations for labels which are commonly used (e.g. title or language.* labels in nevisLogrend, error.* labels in nevisAuth) and which are provided by realm patterns (e.g. assigned authentication steps).
disabled - add only what has been uploaded via Custom Translations. If your translations are incomplete, users will see the untranslated labels.

Custom 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

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

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.

When CUSTOM is selected, an empty filter will be generated based on the name of the realm:

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

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

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.

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.

Configures the number of seconds a cookie is still valid after a new cookie is generated, for example, due to a successful login.

Increasing the value can help minimize the chance of session loss during a login or step-up with parallel requests.

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 Parameters (SessionManagementFilter)

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

Examples:

Key	Value
Cookie.Persistent	true
Cookie.Path	/some/path

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(s)

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 behavior 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 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"/>).

<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

Choose a login renderer.

In Kubernetes deployments, assignment of a renderer is mandatory.

Assign either a nevisLogrend Instance or a Proxy Login Renderer pattern.

The renderer has to be compatible with the Default Template (see Login Template tab).

In classic VM deployments, a default login renderer will be created when no pattern is assigned.

In case of nevisLogrend, the instance will be called default and deployed on the same host as nevisProxy.

Key Store

Configure a key store to use for 2-way TLS connections to nevisLogrend.

If no pattern is assigned no key store will be created.

The connection will be either 1-way TLS or plain HTTP, depending on the URL of nevisLogrend.

This configuration does not apply when a Proxy Login Renderer is used.

Trust Store

Configure a trust store to use for TLS connections to nevisLogrend.

If no pattern is assigned an automatic trust store will be created.

This configuration does not apply when plain HTTP or the Proxy Login Renderer is used.

Hostname Validation

When enabled the server cert has to match the hostname of nevisLogrend.

This configuration does not apply when plain HTTP or the Proxy Login Renderer is used.

nevisLogrend / Application default.properties

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

This is an advanced setting. Use only when there is no other alternative and consider creating a support ticket with your use case.

Check Login Application Configuration for supported properties.

We recommend to not overwrite any language related properties, as the languages have to be in sync with nevisAuth. You can configure the supported languages on the nevisAuth Instance.

This setting requires that nevisLogrend is used for GUI rendering. Check the help of Login Renderer for details.

Template Style

Choose a default template:

classic: default in releases before May 2025.
modern: default since May 2025.
proxy: a template for the nevisProxy Login Renderer.

The modern template is recommended for new setups.

Company Logo

Upload a logo to be displayed on the login page.

The logo file should have an appropriate size, e.g. 50x50 pixels.

Out of the box, this setting is supported by the modern template only.

If you use a different nevisLogrend template, you can add the expression ${logo} to point to the uploaded file.

Download the modern template to see how the expression is used there.

Primary Color

Configure the primary color.

Out of the box, this setting is supported by the modern template only. It is used to color buttons.

If you use a different nevisLogrend template, you can add the expression ${primaryColor} in your CSS file.

Download the modern template to see how the expression is used there.

Border Radius

Configure the corder radius of the login box.

Out of the box, this setting is supported by the modern template only.

If you use a different nevisLogrend template, you can add the expression ${borderRadius} in your CSS file.

Download the modern template to see how the expression is used there.

Font Family

Configure the font family.

By default, this setting is supported by the modern template only.

If you use another template, you can reference the expression ${fontFamily} in your CSS file.
Check the modern template for an example of how the expression is applied.

The actual font used depends on the browser and operating system.

You can specify multiple font families, separated by commas, to provide fallbacks.
The CSS files in the template append additional fonts to ensure all characters (even emojis) can be rendered.

This approach follows the idea described here: Bootstrap Native Font Stack.

Example values:

Arial, sans-serif
Helvetica, Arial, sans-serif
Times New Roman, serif

Template Customization

Customize the rendering of login pages.

Download one of the default templates to get started.

nevisLogrend: Direct Mode

You can upload Velocity template files 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: static resources (e.g. images, CSS, Javascript)

nevisLogrend: Expressions

In nevisLogrend templates you may use the following expressions:

Expression	Description
`${form}`	login form (`form.vm`)
`${lang.switch}`	language switcher component (`lang.vm`)
`${lang.code}`	current language code (i.e. `en`, `de`)
`${label.myLabel}`	a label which must be translated via `Custom Translations`
`${resources}`	path to static resources (e.g. CSS, images, Javascript)
`${resource:<name>}`	path to static resource `name` with attached hash

These expressions will be replaced with a corresponding Velocity snippet at generation time.

For instance, using the expression ${resource:bootstrap.min.css} with the modern template yields the following path:

${login.appDataPath}/resources/bootstrap.min.css?v=3f1c72e8.

Note that the expression ${login.appDataPath} is handled at runtime by nevisLogrend.

nevisProxy provides a basic login 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.

nevisLogrend: Simple Mode

In simple cases you may not have to deal with Velocity template files.

To replace the outer HTML you can upload a file named template.html. The template must contain the ${form} expression.

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}/logo.png" alt="Company Logo">
    </header>
    <main id="content" class="container">
      ${form}
    </main>
  </body>
</html>

Customization Mode

Choose between:

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.
complete: only the files uploaded as Login Template will be deployed.
- Use this option when you want to provide the entire template.

Default Translations

Choose between:

enabled - add translations for labels which are commonly used (e.g. title or language.* labels in nevisLogrend, error.* labels in nevisAuth) and which are provided by realm patterns (e.g. assigned authentication steps).
disabled - add only what has been uploaded via Custom Translations. If your translations are incomplete, users will see the untranslated labels.

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

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

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.

When CUSTOM is selected, an empty filter will be generated based on the name of the realm:

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

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

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.

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.

Configures the number of seconds a cookie is still valid after a new cookie is generated, for example, due to a successful login.

Increasing the value can help minimize the chance of session loss during a login or step-up with parallel requests.

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 Parameters (SessionManagementFilter)

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

Examples:

Key	Value
Cookie.Persistent	true
Cookie.Path	/some/path

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.

The name attribute of GuiElem elements must be unique within a Gui.

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: "&lt;!DOCTYPE html&gt;"
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 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.

Supported protocols:

smtps — TLS from the start (typically port 465). Recommended.
starttls — plain connection upgraded to TLS via STARTTLS (typically port 587). The SMTP server's CA certificate must be trusted by the nevisAuth Instance (Default Backend Trust Store).
smtp — plain connection without TLS. Not recommended for production.

SMTP Protocol

Select the protocol of the SMTP server.

The default value smtps uses a TLS encrypted connection.

Note that the STARTTLS protocol is not supported by nevisAuth.

SMTP Server

Enter host:port of the SMTP server.

Check that you are using the correct port for the selected SMTP Protocol.

Also note that in some environments connections to port 25 are blocked, but most SMTP servers provide an alternative port.

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.

#Federation #Authentication #OAuth #OpenID Connect

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.

PKCE

Setting for PKCE in Authorization/Authentication request.

enabled, the Code Challenge and Code Verifier will be included in the Authorization/Authentication request.
disabled (default), the Code Challenge and Code Verifier will not be included in the Authorization/Authentication request.

PKCE Secret

Allow to set the secret for PKCE. The secret format should follow RFC 7636.

Code Challenge Method

Setting for PKCE Code Challenge Method.

plain (default), the Code Challenge will be sent with raw format.
S256, the Code Challenge will be hashed and base 64 encoded.

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.

JWKS Endpoint

The JWKS endpoint of the OAuth2 server. It's optional when Provider Type 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

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.

Account Linking - User Property

Enter the name of the nevisIDM user property that is used for linking the account.

The property will contain the value of the sub claim of the social login provider.

This pattern will ensure that the property is created in nevisIDM by contributing to the generation of the nevisIDM configuration. The pattern adds a property definition file to /var/opt/nevisidm/<instance>/conf/import/user_<name>.json. This file is interpreted by nevisIDM during startup.

Before the May 2025 release, the sanitized pattern name was used for this property. This is not recommended anymore, as the account link will break when the pattern is renamed.

To avoid this problem, it is now recommended to configure this setting. If you are upgrading from a previous version you must use the property name which was used so far.

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

When CUSTOM is selected, an empty filter will be generated based on the name of the realm:

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

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.

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.

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.

Configures the number of seconds a cookie is still valid after a new cookie is generated, for example, due to a successful login.

Increasing the value can help minimize the chance of session loss during a login or step-up with parallel requests.

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.

Custom Parameters (SessionManagementFilter)

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

Examples:

Key	Value
Cookie.Persistent	true
Cookie.Path	/some/path

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.

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.

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.

nevisAdapt Properties

Add properties for nevisadapt.properties. See nevisAdapt Reference Guide for details.

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.

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:

management:
  server:
    port: 9089
  healthchecks:
    enabled: true

Generic nevisFIDO UAF Instance Settings

#Mobile Authentication #Authentication #Add-ons

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:

management:
  server:
    port: 9089
  healthchecks:
    enabled: true

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
env.conf

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 the number of parallel requests (worker threads):

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

Increase the maximum allowed request body size:

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

When patching a certain Host, you have to provide the name.

Let's say you use the variable domain for Frontend Addresses in your Virtual Host. You then have to use the expression ${var.domain} to patch the corresponding Host element.

Allow additional status codes by patching the Context element:

<Service>
    <Engine>
        <Host name="${var.domain}">
            <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:

<Service>
    <Engine>
        <Host name="${var.domain}">
            <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.

Environment Variables

Add additional environment variables to the nevisProxy env.conf.

Each variable is written as KEY=VALUE followed by an export KEY line so it becomes part of the nevisProxy process environment.

Keys defined by other patterns (for example PKCS11_PIN, SECUROSYS_PKCS11_CONF, SECUROSYS_SECRETS_CONF and OPENSSL_CONF from the Securosys Key Store pattern) must not be set here.

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 nevisProxy 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 applications (Web Application, REST Service, SOAP Service) using Additional Settings.

Protocols

The value(s) configured here will be used as SSLProtocol. Read the Apache Documentation for supported values.

The SSLProtocol can appear in 2 different places, depending on where this pattern is assigned:

as attribute for the SSL element in navajo.xml.
as init-param for the HttpsConnectorServlet.

If nothing is configured, a default will apply. The default is determined as follows:

For the SSL element in navajo.xml the SSLProtocol attribute will be generated as -all +TLSv1.2 +TLSv1.3 by the Virtual Host pattern.
For the HttpsConnectorServlet no SSLProtocol init-param will be generated, and thus the default of this servlet applies. Read the documentation of the HttpsConnectorServlet for further information.

Cipher Suite

Configure the allowed cipher suites.

Read the Apache Documentation for the supported format.

The value configured here will be applied as:

SSLCipherSuite for the SSL element in navajo.xml when the pattern is assigned to a Virtual Host.
SSLCipherSuites for the HttpsConnectorServlet element in the web.xml when this pattern is assigned to an application.

If nothing is configured, a default will apply. The default is determined as follows:

For the SSLCipherSuite attribute of the SSL element in navajo.xml a default will be generated by the Virtual Host pattern.
For HttpsConnectorServlet nothing will be generated, and thus the default of this servlet applies. Read the documentation of the HttpsConnectorServlet 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

Geolocation Service

#Application Protection #Add-ons #Experimental

Plugin: nevisadmin-plugin-nevisproxy

This pattern sets up a service that responds with the geolocation of the caller, based on the callers source IP.

The response is a JSON with the following format:

{
  "query":"<IP>"
  "status":"success|fail"
  "continentCode":"<ISO continent code>"
  "countryCode":"<ISO country code>"
  "licence":"https://www.maxmind.com/en/geolite2/eula"
}

The pattern requires that nevisProxy is able to correctly determine the source IP for the incoming request.

If a component in front of nevisProxy terminates TLS connections (e.g. a load balancer, ingress, Cloudflare), then you have to configure a Source IP Header in the Virtual Host pattern.

Virtual Host(s)

Assign a Virtual Host which shall serve as entry point.

Frontend Path

The path on which the service shall be accessible.

Geolocation Database

Upload a Maxmind database file.

For further information, see the documentation in the nevisProxy reference guide.

Authentication Realm

Optionally assign a realm to protect this application or service.

Additional Settings

Assign add-on patterns to customize the behavior 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.

#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

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:

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:

constant String value
nevisAuth expression (${...:...})
an EL expression (#{...})
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 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 behavior:

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

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

START - manipulate request headers late to also cover any headers set by nevisProxy.
AFTER_AUTHENTICATION - default behavior 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 behavior:

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(s)

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 behavior 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 behavior:

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:

The user opens the mobile application and accesses a protected resource, for which they have no authorization yet.
The mobile application prompts the user to authenticate.
The mobile app sends a request to /auth/fidouaf to authenticate.
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

Choose a login renderer.

In Kubernetes deployments, assignment of a renderer is mandatory.

Assign either a nevisLogrend Instance or a Proxy Login Renderer pattern.

The renderer has to be compatible with the Default Template (see Login Template tab).

In classic VM deployments, a default login renderer will be created when no pattern is assigned.

In case of nevisLogrend, the instance will be called default and deployed on the same host as nevisProxy.

Key Store

Configure a key store to use for 2-way TLS connections to nevisLogrend.

If no pattern is assigned no key store will be created.

The connection will be either 1-way TLS or plain HTTP, depending on the URL of nevisLogrend.

This configuration does not apply when a Proxy Login Renderer is used.

Trust Store

Configure a trust store to use for TLS connections to nevisLogrend.

If no pattern is assigned an automatic trust store will be created.

This configuration does not apply when plain HTTP or the Proxy Login Renderer is used.

Hostname Validation

When enabled the server cert has to match the hostname of nevisLogrend.

This configuration does not apply when plain HTTP or the Proxy Login Renderer is used.

nevisLogrend / Application default.properties

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

This is an advanced setting. Use only when there is no other alternative and consider creating a support ticket with your use case.

Check Login Application Configuration for supported properties.

We recommend to not overwrite any language related properties, as the languages have to be in sync with nevisAuth. You can configure the supported languages on the nevisAuth Instance.

This setting requires that nevisLogrend is used for GUI rendering. Check the help of Login Renderer for details.

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(s)

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

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

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

With this cookie, the registration operation can be initiated.

This is a convenience feature.

The configuration that is generated is similar to the configuration described here. To match this example, the Authentication Service Path should be /auth/pwd but we suggest using a more specific path.

There are several alternatives to how you can provide authentication:

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.

Client Name

Enter the name of the nevisIDM Client.

JSON Response Step

#Authentication #Generic

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

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

#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

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 this file.

In complex setups with multiple Kerberos Realms and/or Frontend Addresses you may have to upload multiple keytab files.

For increased security we recommend to use a variable containing either:

a nevisAdmin secret file
a file stored in a Kubernetes secret (k8s-secret-file://<secret-name>:<file-name>/)

Alternatively, you can also set Keytab File Path instead of uploading and deploy the file by other means (e.g. a volume mount).

Important: When uploading the file directly, note that the pattern does not rename the file. If you have multiple Kerberos Login patterns, you have to use a different file name in each pattern.

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.

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.

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.

Custom Properties

Enter custom properties for the nevisAuth ch.nevis.esauth.auth.states.kerberos.KerberosLoginAuthState.

You can add new properties or overwrite properties generated by the pattern.

For instance, you may set permittedRealms to * to allow any realm, or adapt the userIdFormat to your needs.

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

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.
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 behavior:

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.

#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

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(s)

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.

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.

Button Order

Choose primary to show the primary button before any additional buttons.

Choose reverse to display the primary button last.

Max Retries

The maximum retry attempts for each code.

When this threshold is reached, the behavior 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 code that the user has to enter.

Option	Format	Testing Mode Code
`4 digits`	4 numbers [0-9]	`1111`
`5 digits`	5 numbers [0-9]	`11111`
`6 digits`	6 numbers [0-9]	`111111`
`4 letters`	4 upper case letters [A-Z]	`AAAA`
`5 letters`	5 upper case letters [A-Z]	`AAAAA`
`6 letters`	6 upper case letters [A-Z]	`AAAAAA`
`4 alphanumeric`	4 out of [0-9A-Z]	`AAA1`
`5 alphanumeric`	5 out of [0-9A-Z]	`AAAA1`
`6 alphanumeric`	6 out of [0-9A-Z]	`AAAAA1`

Testing Mode

Select enabled to not send any code to the user.

No SMS will be sent and no SMS Provider needs to be assigned.

The code that needs to be entered depends on the selected TAN Format (see Advanced Settings).

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.

Button Order

Choose primary to show the primary button before any additional buttons.

Choose reverse to display the primary button last.

NGINX Ingress Settings

#Application Protection #Kubernetes #Add-ons

Plugin: nevisadmin-plugin-nevisproxy

In Kubernetes deployments, an NGINX Ingress Controller terminates TLS connections and forwards requests to nevisProxy. Basic settings are available in the Ingress tab of Virtual Host patterns.

This pattern provides additional options, e.g. related to TLS secrets and client certificate authentication. Assign the pattern to your Virtual Host using Additional Settings.

Annotations

Add Kubernetes annotations to customize the behavior 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.

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 Application Access Token.

The SecToken is transferred as Basic Auth password.

On the application server you have to use Ninja to extract the SecToken from the Authorization header. You can download Ninja from the Nevis Portal.

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
domain	session:ch.nevis.session.domain
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 domain is required by nevisAdapt.

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.

OATH Authentication

#Identity Management #Authentication

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.

On Cancel

If assigned, the user can cancel the OATH authentication.

Define which step to continue with.

Client Name

This has to be configured when you have multiple Clients in nevisIDM.

If the client name is always the same, you may enter the name directly.

If the client name depends on the authenticated user, try the expression ${sess:ch.adnovum.nevisidm.clientName} instead.

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

#Identity Management #Authentication #Onboarding

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.

On Cancel

If assigned, the user can cancel the OATH onboarding.

Define which step to continue with.

Client Name

This has to be configured when you have multiple Clients in nevisIDM.

If the client name is always the same, you may enter the name directly.

If the client name depends on the authenticated user, try the expression ${sess:ch.adnovum.nevisidm.clientName} instead.

OAuth 2.0 / OpenID Connect Dynamic Client Registration Endpoint

#Federation #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

Links to a Dynamic Client Registration endpoint for OAuth 2.0 / OpenID Connect.

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 if the value contains a hostname, this pattern will 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

Plugin: nevisadmin-plugin-oauth

An OAuth 2.0 Authorization Server / OpenID User Info returns information about the authenticated user.

Virtual Host(s)

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

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`

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.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

Required when User Info is enabled.

Assignment is required to determine the URL for the REST API call to the nevisIDM user info endpoint.

User Info

When enabled, the nevisIDM user info endpoint is called to retrieve information about the authenticated user.

The following property will be added to the configuration of the AuthorizationServer AuthState:

<property name="openid.userInfoEndpointUri" value="https://<idm-host>:<idm-port>/nevisidm/api/oic1.0/userinfo"/>

For reasons of backward compatibility, the default is disabled.

The information from the user info endpoint is used to populate any claims in the returned ID and access tokens.

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

Audience Field Strategy

Defines whether the audience (aud) claim is added to the issued Access Tokens, following RFC 9068 and RFC 8707.

disabled (default): the Access Token will not contain the aud claim. The resource request parameter is ignored.
resource: the audience is derived from the resource request parameter or from the configured resource servers in nevisMeta that own the requested scopes. The eligible resource servers must have the URL field set in nevisMeta. Requires nevisMeta as the data source.

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

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.

Valid Authorization Request Authentication Required

The nevisMeta UI has a setting on the Client called Force Reauthentication.

If enabled, users need to authenticate for every invocation of the Authorization Path.

To ensure that this setting works out of the box, this pattern generates configuration which always dispatches the request into the Initial Authentication Flow of the assigned Authentication Realm.

If you want to use a different authentication flow for re-authentication, then assign a different step here.

When configured, a ResultCond with name valid-authorization-request-authentication-required will be added.

Configure the step to execute after authorization request is valid and end-user authentication can be skipped.

If no step is configured here the process ends and the final AUTH_DONE will be reached.

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.

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

Old Signer

Configure the key material which is used to validate codes and tokens during the certificate rollover period.

Out-of-band Device Management App

#Mobile Authentication #Testing #Experimental

Plugin: nevisadmin-plugin-nevisfido

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(s)

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 behavior 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: A QR-code is rendered server-side by nevisFIDO and shown to the user. The user scans the QR code with the camera app or with the mobile app directly. This option uses the link-png-qr-code dispatcher in nevisFIDO. This option uses GUI name mauth_png_qr_link and mauth_png_qr_link.js.

Push / QR-Code: 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 or using the camera app of the mobile device. This option uses GUI name mauth_push_qr and mauth_push_qr.js.

Link / QR-Code (legacy) (deprecated, use Link / QR-Code instead): User can click a link if they are navigating on the same mobile device as the app resides on. A QR-code is rendered client-side via JavaScript and shown to the user. This option uses the link dispatcher in nevisFIDO. This option uses GUI name mauth_link_qr and mauth_link_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 cancel.button.label.

On Client Failure

When authentication fails due to user behavior, 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 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 #Onboarding

Plugin: nevisadmin-plugin-nevisfido

This pattern provides Out-of-Band Registration for mobile authentication.

This pattern can be part of a self-registration sub-flow of an Authentication Realm, or exposed on a separate path using the Standalone Authentication Flow pattern.

This process requires a browser and works as follows:

QR code display – A page is rendered using the Login Template of your Authentication Realm. The QR code is rendered client-side via JavaScript (Link / QR-Code (legacy) channel) or generated server-side by nevisFIDO (Link / QR-Code channel).
QR code scan – The user scans the QR code with their mobile device:
- Camera app: The user is redirected to an HTML page with app installation instructions.
- Mobile app: The registration process continues (step 3).
Client-side credential creation – The mobile app generates a client-side credential.
Credential registration in nevisIDM – The mobile app ensures the required credentials are created in nevisIDM.
Continuation – The process continues with the configured On Success step.

You must configure either a custom URI or a deep link in the nevisFIDO UAF Instance pattern.

The user must have been set in the session (e.g., via nevisIDM User Lookup) before this step is executed.
This requirement is not validated during pattern generation because of the variety of possible configurations (e.g., using Generic Authentication Step). Automatic validation may cause false negatives.

If the user cannot be identified, the ERROR message out-of-band mobile onboarding failed. missing username. will be written to the nevisAuth log.

Channel

Select how to transfer information to the mobile application.

Link / QR-Code (legacy): A QR-code is rendered client-side via JavaScript and shown to the user. On mobile devices, a tappable link is also displayed. The link behaviour depends on the Link Type configured in the nevisFIDO UAF Instance:

Custom URI (myapp://): Opens the app directly. Requires the app to be installed — if it is not, the link leads nowhere.
Deep Link (https://): Falls back to the browser when the app is not installed. The browser can show an installation page.

Because onboarding typically happens before the app is installed, Deep Link is recommended for this pattern. This option uses the link dispatcher in nevisFIDO. This option uses GUI name mauth_onboard and mauth_onboard.js.

Link / QR-Code: A QR-code is rendered server-side by nevisFIDO and shown to the user. The user scans the QR code with the camera app or with the mobile app directly. Note: This option does not yet support a tappable link on mobile devices. This option uses the link-png-qr-code dispatcher in nevisFIDO. This option uses GUI name mauth_onboard_png_qr_link and mauth_onboard_png_qr_link.js.

You must configure either a custom URI or a deep link in the nevisFIDO UAF Instance pattern.

Frontend Address determination for Link / QR-Code: The frontend address of nevisFIDO is needed to build the redeem_url provided to the mobile app. It is resolved as follows:

Frontend Address set on the assigned nevisFIDO UAF Instance or nevisFIDO UAF Connector — used directly.
Otherwise, the HTTPS Frontend Address of the single associated Virtual Host is used.

Auto-detection (step 2) fails if:

No Virtual Host is assigned to this pattern, or
More than one Virtual Host is assigned.

In these cases, set Frontend Address explicitly on the nevisFIDO pattern.

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 cancel.button.label.

User Name

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

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

This pattern generates an EL expression with fallbacks so ensure all well-known session variables are checked. The order of fallbacks was chosen to follow integrator best practices.

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.

Gui Title

The default label for the Gui title is title.signup.mauth.

The default translations for this label are:

en: Go passwordless
de: Login ohne Passwort
fr: Aller sans mot de passe
it: Vai senza password

Translations for labels can be provided via the Translations tab in your realm pattern.

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:

The user accesses a Web application which generates a QR code.
The user scans the QR code with the mobile app.
The mobile app creates a client-side credential.
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(s)

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.

Kubernetes PEM-only mode

In Kubernetes deployments, you may provide one or more k8s-secret-file:// references to .pem certificate files instead of the complete 4-file set (truststore.pem, truststore.jks, truststore.p12, keypass). In this mode, a NevisTrustStore CRD is generated and the Nevis Operator assembles the full trust store from the supplied PEM certificates. Only .pem files are accepted; providing a non-PEM file in this mode results in a validation error.

Trusted Cert(s)

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 #Add-ons #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 Host(s)

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

OpenAPI Validation File

You can configure an OpenAPI validation file in JSON format. All incoming requests to this service will be validated against that file.

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.

Redirect Step

#Authentication

Plugin: nevisadmin-plugin-nevisauth

Redirects the caller to a given destination.

The destination can be a URL or a path.

You have to choose the Response Type depending on your requirements.

Destination

Enter a URL or path to redirect to.

Response Type

Use AUTH_CONTINUE to keep the current session and stay in state. If and when the next request comes in, the On Reentry exit will be taken.

Use AUTH_DONE to finish the current flow and establish an authenticated session.

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 Reentry

When the Response Type is set to AUTH_CONTINUE, the authentication flow is not terminated.

In case the user comes back to the current URL, the flow will continue with this step.

As we do not want to ask the same question again, we have to dispatch to a later step.

Assign this step here.

This setting is ignored when the Response Type is set to AUTH_ERROR or AUTH_DONE.

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.

Reset Session Step

#Authentication #Generic

Plugin: nevisadmin-plugin-nevisauth

Clears the session to ensure that subsequent steps start with a clean slate.

Certain session variables have to be preserved because they are set before this step is executed.

For instance, any session variables associated with federation (e.g., SAML, OAuth 2.0, OpenID Connect) and with dynamic logrend template selection need to be preserved.

On Success

Assign a step to continue with after clearing the session.

Skipped Variables

Enter regular expressions to match variables which should not be cleared.

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/

The value configured here is used as the SAML entity ID (out.issuer) of the generated IdentityProviderState. Use this exact value as the {id} path parameter when retrieving metadata for a single identity provider. The default value is IDP.

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.failedwill 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.
both: both sp-initiated and idp-initiated are allowed.

Error Handling

Define how dispatching errors are handled.

Choose between:

redirect: Redirect according to the configuration of Error Redirect.
show-gui: Stay in state to show an error screen.

Error Redirect

URL or path to redirect to when the IDP is unable to handle the request.

If no URL is configured, the IDP will redirect back to the Referer, or / if no Referer header has been sent.

There are several cases:

session loss due to timeout.
a session is required for the current operation (e.g., logout, stepup), 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).

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

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.

This setting is used to generate the property in.verify of the ServiceProviderState.

When nothing is selected, then the option recommended is used. The recommended option produces the following configuration:

<property name="in.verify" value="Response Assertion"/>

Thus, both the signature of the Response and the Assertion contained in the Response are expected to be signed and the signature of both elements will be checked.

This configuration is compatible with the default configuration of the SAML IDP pattern.

This also is the strictest configuration. If your IDP signs only one of these 2 elements, then you have to adapt the configuration here.

It is recommended that the IDP signs the entire Response. If only the Assertion is signed, then that is potentially vulnerable because an attacker may replace the Response.

To prevent common attack scenarios, nevisAuth will perform additional checks when only the Assertion is signed.

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.

Disable Restore Level States

Defines if the additional AuthStates need to be added for restore pre-adding context from Nevis SP

enabled (default): the additional AuthState will be added for context restoration from Nevis SP.
disabled: no additional AuthState will be added.

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(s)

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

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.

When nothing is selected then the option recommended is used.

With recommended 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.

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.

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>

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:

Authentication_<name>: enforces authentication for applications.
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

Choose a login renderer.

In Kubernetes deployments, assignment of a renderer is mandatory.

Assign either a nevisLogrend Instance or a Proxy Login Renderer pattern.

The renderer has to be compatible with the Default Template (see Login Template tab).

In classic VM deployments, a default login renderer will be created when no pattern is assigned.

In case of nevisLogrend, the instance will be called default and deployed on the same host as nevisProxy.

Key Store

Configure a key store to use for 2-way TLS connections to nevisLogrend.

If no pattern is assigned no key store will be created.

The connection will be either 1-way TLS or plain HTTP, depending on the URL of nevisLogrend.

This configuration does not apply when a Proxy Login Renderer is used.

Trust Store

Configure a trust store to use for TLS connections to nevisLogrend.

If no pattern is assigned an automatic trust store will be created.

This configuration does not apply when plain HTTP or the Proxy Login Renderer is used.

Hostname Validation

When enabled the server cert has to match the hostname of nevisLogrend.

This configuration does not apply when plain HTTP or the Proxy Login Renderer is used.

nevisLogrend / Application default.properties

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

This is an advanced setting. Use only when there is no other alternative and consider creating a support ticket with your use case.

Check Login Application Configuration for supported properties.

We recommend to not overwrite any language related properties, as the languages have to be in sync with nevisAuth. You can configure the supported languages on the nevisAuth Instance.

This setting requires that nevisLogrend is used for GUI rendering. Check the help of Login Renderer for details.

Template Style

Choose a default template:

classic: default in releases before May 2025.
modern: default since May 2025.
proxy: a template for the nevisProxy Login Renderer.

The modern template is recommended for new setups.

Company Logo

Upload a logo to be displayed on the login page.

The logo file should have an appropriate size, e.g. 50x50 pixels.

Out of the box, this setting is supported by the modern template only.

If you use a different nevisLogrend template, you can add the expression ${logo} to point to the uploaded file.

Download the modern template to see how the expression is used there.

Primary Color

Configure the primary color.

Out of the box, this setting is supported by the modern template only. It is used to color buttons.

If you use a different nevisLogrend template, you can add the expression ${primaryColor} in your CSS file.

Download the modern template to see how the expression is used there.

Border Radius

Configure the corder radius of the login box.

Out of the box, this setting is supported by the modern template only.

If you use a different nevisLogrend template, you can add the expression ${borderRadius} in your CSS file.

Download the modern template to see how the expression is used there.

Font Family

Configure the font family.

By default, this setting is supported by the modern template only.

If you use another template, you can reference the expression ${fontFamily} in your CSS file.
Check the modern template for an example of how the expression is applied.

The actual font used depends on the browser and operating system.

You can specify multiple font families, separated by commas, to provide fallbacks.
The CSS files in the template append additional fonts to ensure all characters (even emojis) can be rendered.

This approach follows the idea described here: Bootstrap Native Font Stack.

Example values:

Arial, sans-serif
Helvetica, Arial, sans-serif
Times New Roman, serif

Template Customization

Customize the rendering of login pages.

Download one of the default templates to get started.

nevisLogrend: Direct Mode

You can upload Velocity template files 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: static resources (e.g. images, CSS, Javascript)

nevisLogrend: Expressions

In nevisLogrend templates you may use the following expressions:

Expression	Description
`${form}`	login form (`form.vm`)
`${lang.switch}`	language switcher component (`lang.vm`)
`${lang.code}`	current language code (i.e. `en`, `de`)
`${label.myLabel}`	a label which must be translated via `Custom Translations`
`${resources}`	path to static resources (e.g. CSS, images, Javascript)
`${resource:<name>}`	path to static resource `name` with attached hash

These expressions will be replaced with a corresponding Velocity snippet at generation time.

For instance, using the expression ${resource:bootstrap.min.css} with the modern template yields the following path:

${login.appDataPath}/resources/bootstrap.min.css?v=3f1c72e8.

Note that the expression ${login.appDataPath} is handled at runtime by nevisLogrend.

nevisProxy provides a basic login 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.

nevisLogrend: Simple Mode

In simple cases you may not have to deal with Velocity template files.

To replace the outer HTML you can upload a file named template.html. The template must contain the ${form} expression.

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}/logo.png" alt="Company Logo">
    </header>
    <main id="content" class="container">
      ${form}
    </main>
  </body>
</html>

Customization Mode

Choose between:

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.
complete: only the files uploaded as Login Template will be deployed.
- Use this option when you want to provide the entire template.

Default Translations

Choose between:

enabled - add translations for labels which are commonly used (e.g. title or language.* labels in nevisLogrend, error.* labels in nevisAuth) and which are provided by realm patterns (e.g. assigned authentication steps).
disabled - add only what has been uploaded via Custom Translations. If your translations are incomplete, users will see the untranslated labels.

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

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

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

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.

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.

Configures the number of seconds a cookie is still valid after a new cookie is generated, for example, due to a successful login.

Increasing the value can help minimize the chance of session loss during a login or step-up with parallel requests.

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.

Custom Parameters (SessionManagementFilter)

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

Examples:

Key	Value
Cookie.Persistent	true
Cookie.Path	/some/path

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.

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 Host(s)

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

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

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 configuration files for accessing the HSM.

This two are mandatory:
'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.

This one is mandatory for classic setup:
'openssl.cnf' contains the information for the the OpenSSL provider. In K8S setup the 'openssl.cnf' is already provided by the nevisProxy docker image.

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.

The host name is smtp.sendgrid.net.

By default a non-encrypted SMTP connection is used as this allows for quicker integration. See the Protocol setting for details.

Assign the pattern to Email TAN (eTAN) as SMTP Server.

Protocol

Choose between the following options:

smtp
- Uses a non-encrypted SMTP connection.
- Does not require any additional configuration (apart from the API key).
- Uses port 2525, since port 25 is blocked by default in some environments.
smtps
- Uses a TLS-encrypted (SMTPS) connection.
- Requires additional configuration: you must upload the CA certificate of smtp.sendgrid.net to the Default Backend Trust Store of the nevisAuth instance.
- Uses port 465.

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

Simple Virtual Host

#Application Protection #Virtual Hosts

Plugin: nevisadmin-plugin-nevisproxy

Adds a virtual host to a nevisProxy Instance.

In the navajo.xml the pattern generates 1 Connector and 1 Host.

To ensure that the pattern is easy to use we make the following restrictions:

Kubernetes deployment only.
The virtual host serves a single domain.
Inside the docker image the nevisProxy process listens on port 8443.
The public port is always 443.
Connection towards nevisProxy uses TLS.
Automatic key management is used.

nevisProxy Instance

Assign the nevisProxy Instance for this virtual host.

Domain

Enter the domain used to access this virtual host.

You have to ensure that DNS is configured in a way so that requests are routed to the Kubernetes cluster.

Inside the cluster, we use Envoy to route the request to the nevisProxy service that this virtual host belongs to.

When doing a Git deployment, you can use a placeholder for the domain name. Example:

placeholder://@@DOMAIN@@

Additional Settings

Assign patterns to customize how this virtual host is generated.

For instance, use Generic Virtual Host Settings to add custom or overwrite filters and servlets.

#Federation #Authentication #OAuth #OpenID Connect

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

#Federation #Authentication #OAuth #OpenID Connect

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.

#Federation #Authentication #OAuth #OpenID Connect

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.

User External ID

By default, the extId is taken from the request.

Here you can enter a different source for the extId.

Examples:

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

This setting only has to be set when you have specific patterns in yoru flow that determine the user to link to.

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(s)

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 behavior 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 behavior:

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`

#Federation #Authentication #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

Creates and verifies Swiss e-ID logins with swiyu. For more information, see the swiyu documentation

Verifier Base URL

The URL where the verifier management service is available. For example https://verifier-agent-management.name.region.service-type.io/api/v1

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.

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

Maximum 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 setting empty, you will be using the nevisProxy default value of 50.

For performance reasons, we do not recommend to configure a size bigger than 300.

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.

#Authentication #Testing

Plugin: nevisadmin-plugin-nevisauth

warning

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.

Button Order

Choose primary to show the primary button before any additional buttons.

Choose reverse to display the primary button last.

Test TAN

#Authentication #Testing

Plugin: nevisadmin-plugin-nevisauth

warning

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.

Throttle User Step

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

When a user passes this step a cooldown period is started for this user.

When the cooldown is active, the configured handling applies.

On Success

Assign a step to continue with when the user is not on cooldown.

Cooldown Mode

Choose how cooldown is handled.

Select dispatch to continue with the On Cooldown step.

Select wait to display a screen that informs the user about the cooldown.

The screen has the following labels:

title.cooldown - default: Too many attempts
info.cooldown - default: Please try again later
retry.button.label - default: Retry

You may change the translations to give the user more information about the cooldown.

Cooldown Duration

Defines how long the cooldown lasts.

By default, values are in seconds, but you can also enter minutes (m), hours (h), or days (d).

The minimum value is 1s (1 second), and the maximum value is 1d (1 day).

On Cooldown

Assign a step to continue with when the user is on cooldown and the Mode is dispatch.

If no step is assigned, a default configuration will be used.

The default configuration produces a GUI with the text System problems. Please try later..

The response type is AUTH_ERROR and thus the session is terminated.

In federation scenarios, the user will be redirected (back) to the relying party instead.

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 Service

#Mobile Authentication #Authentication

Plugin: nevisadmin-plugin-nevisfido

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

This use case typically involves 2 devices.

The transaction confirmation is:

started on device 1 (e.g. a browser running on a desktop)
completed on device 2 (e.g. a mobile app).

The pattern provides fine-grained control over which endpoints are exposed in the Endpoints tab.

We recommend to start with the default configuration and then disable any endpoints that you don't need.

Virtual Host(s)

Assign a Virtual Host to expose the enabled endpoints.

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.

nevisFIDO

Assign a nevisFIDO UAF Instance.

This instance will provide the transaction confirmation services.

Token Dispatch Targets Query Endpoint

Exposes the Query Dispatch Target endpoint /nevisfido/token/dispatch/targets.

This endpoint can be called by an application from device 1 to find out which dispatch targets the user has.

This endpoint should be protected. We provide the option to expose this endpoint as public for testing purposes only. Do not use public for production deployment.

Token Dispatch Endpoints

Exposes the endpoints for token dispatching. These endpoints are called from device 1.

The Dispatch Token Service endpoint /nevisfido/token/dispatch/authentication is called to dispatch a push notification to a mobile app running on device 2.

The Status Service endpoint /nevisfido/status is called to check if the transaction was confirmed by the user on device 2.

Token Redeem Endpoints

Exposes several endpoints that are used by a mobile app running on device 2 to confirm the transaction.

/nevisfido/token/redeem/authentication
/nevisfido/uaf/1.1/facets
/nevisfido/uaf/1.1/authentication

In some setups, the mobile app calls another domain. In this case, you can set these endpoints to disabled and use another pattern to expose these endpoints on another Virtual Host.

Compat Endpoints

Some setups require legacy endpoints to be exposed.

Enable them only if required, e.g., if your device calls any of these endpoints.

The endpoint /auth/fidouaf/authenticationresponse/ is an alias for the Authentication Response Service endpoint /nevisfido/uaf/1.1/authentication on nevisFIDO.

The endpoint /nevisfido/uaf/1.1/authentication/ is imprecise as it also exposes sub-paths. Current apps call /nevisfido/uaf/1.1/authentication (without trailing slash) instead.

Transform Variables Step

#Authentication #Generic

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

In order to redirect the context root of an application, leave the Key field empty.

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 behavior:

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.

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.

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.

When CUSTOM is selected, an empty filter will be generated based on the name of the realm:

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

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.

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.

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.

Configures the number of seconds a cookie is still valid after a new cookie is generated, for example, due to a successful login.

Increasing the value can help minimize the chance of session loss during a login or step-up with parallel requests.

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.

Custom Parameters (SessionManagementFilter)

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

Examples:

Key	Value
Cookie.Persistent	true
Cookie.Path	/some/path

User Decision (binary)

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

Use in an authentication flow to present the user with a binary choice.

The user selects one of two options by clicking the corresponding button.

You can customize the title, the question, and the labels for both options.

Title

Enter a title for the screen.

You can translate this label in your authentication realm.

Question

Enter a label for the question to ask the user.

You can translate this label in your authentication realm.

Option 1

Choose a follow-up step for option 1.

Option 1 Label

Enter a label to use for the button for option 1.

You can translate this label in your authentication realm.

Option 2

Choose a follow-up step for option 2.

Option 2 Label

Enter a label to use for the button for option 2.

You can translate this label in your authentication realm.

User Information

#Authentication

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

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.

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.

Button Label

Change the label of the primary button which is used to submit the form.

Additional Buttons

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

Button Order

Choose primary to show the primary button before any additional buttons.

Choose reverse to display the primary button last.

User Input (single field)

#Authentication

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.

User Notification (Adaptive Authentication)

#User Behavior Analytics

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

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 cancel.button.label.

On Failure

Assign a step to continue with when the authentication fails.

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, reachable on one or more Frontend Addresses.

In Kubernetes deployment, an Ingress or Gateway API controller terminates TLS connections towards nevisProxy.

A virtual host can provide access to various applications and services.

To act as reverse proxy for applications, add a Web Application, REST Service, or SOAP Service pattern, and reference this virtual host.

To provide authentication, use the OAuth 2.0 Authorization Server / OpenID Provider or the SAML IDP pattern.

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

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.

Frontend Key Store

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. If there are multiple frontend addresses, you have to ensure that the certificate has Subject Alternative Name (SAN) entries for all of them.

If no pattern is assigned, automatic key management will provide a key store.

Frontend Trust Store

Configure a trust store to validate client certificates for incoming connections.

The trust store may contain an arbitrary number of CA certificates issuing these client certificates.

Caution: additional configuration is required to enforce client cert authentication.

Choose between the following options:

Authenticate against a user that has a Certificate credential in nevisIDM.
- Use the nevisIDM Client Certificate Authentication pattern in your authentication flow, ideally at the beginning of the flow.
- The pattern will patch the IdentityCreationFilter by adding the init-param ClientCert. This leads to an additional handshake to request a client certificate.
Enforce client certificate authentication for the entire host.
- Use the Generic nevisProxy Settings pattern to set the required attributes of the Connector element.
- Refer the documentation of nevisProxy frontend connectors for further information.

Frontend TLS Settings

Choose between:

modern: allows TLSv1.3 only.
intermediate: allows TLSv1.2 and TLSv1.3,
custom: assign a Generic nevisProxy TLS settings pattern via Additional Settings and provide the TLS settings there.

The following legacy options are provided to replace options that existed in pattern version < 9.2605.

legacy recommended: replaces the previous default of recommended.
legacy compatible: replaces the option compatible.

The cipher configuration is generated based on the enabled protocols automatically. If you need different ciphers, select custom, assign a Generic nevisProxy TLS Settings pattern, and configure the Cipher Suite there.

Client Authentication

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.

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.

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.22.0: newest version of CRS, uses Anomaly Scoring Mode, minimal CRS setup
3.3.8: default and recommended setup, uses Anomaly Scoring Mode
custom: allows to upload a custom rule set. See the ModSecurity Rule Set option for more information.

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.

Gateway API Generation

To make a Virtual Host accessible from outside the Kubernetes cluster, you need a Gateway API or Ingress controller.

Support for Gateway API was introduced in pattern version 8.2511.3 and is the default for 9.2605.x and later. Versions <= 8.2511.x use NGINX Ingress as the default controller. This is also to avoid a breaking change and manual cleanups.

Choose the controller type by setting the following inventory variables:

__nevisadmin_ingress_enabled
__nevisadmin_gateway_api_enabled

Only one of these variables should be set to true. You can also disable the generation entirely by setting both variables to false.

The patterns then generate a NevisIngress or NevisGateway resource for each Virtual Host. During reconcile, the Nevis Operator component produces a standard Ingress or Gateway resource for the selected controller.

This setting applies only when __nevisadmin_gateway_api_enabled is true and allows disabling generation of the NevisGateway resource for this host.

When disabled, any Gateway API Settings pattern assigned to the host will be ignored.

Host

Use when requests are terminated in front of the Gateway API controller and the Host header sent by the user agent has to be replaced.

Enter a value that matches the value configured via Frontend Addresses.

This setting is used in Nevis ID but may be useful in other deployments as well.

Ingress Generation

To make a Virtual Host accessible from outside the Kubernetes cluster, you need a Gateway API or Ingress controller.

Choose the controller type by setting the following inventory variables:

__nevisadmin_ingress_enabled
__nevisadmin_gateway_api_enabled

Only one of these variables should be set to true. You can also disable the generation entirely by setting both variables to false.

This setting applies only when __nevisadmin_ingress_enabled is true and allows disabling generation of the NevisIngress resource for this host.

When disabled, any NGINX Ingress Settings pattern assigned to the host will be ignored.

Host

Set a value for the nginx.ingress.kubernetes.io/upstream-vhost annotation.

Ingress uses this when forwarding the request to the nevisProxy service, as Host header.

This setting is used in Nevis ID but may be useful in other deployment scenarios as well.

Use when requests are terminated in front of the ingress and the Host header sent by the user agent is replaced.

Enter a value that matches the Frontend Addresses.

TLS Secret

Set a custom value for the TLS secret used for the ingress host.

Reserved for usage in Nevis ID.

Source IP Header

If set, the source IP for the request will be taken from the configured request header.

Set this in environments where the request is terminated in front of nevisProxy.

For instance, when deploying to Kubernetes, ingress usually terminates the request.

You have to make sure that the request header value is correct and cannot be spoofed.

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 behavior 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 behavior of this virtual host.

WaltID Step

#Federation #Authentication #OAuth #OpenID Connect

Plugin: nevisadmin-plugin-oauth

This pattern implements the WaltID authentication step. WaltID is a decentralized identity solution that allows users to authenticate using their electronic identification.

See more details in the WaltID documentation.

Verifier URL

Enter a valid verifier URL for WaltID. If nothing is set, the default verifier URL (https://verifier.demo.walt.id) is used.

On Success

Set the step to continue with on successful authentication. If no step is configured here the process ends with AUTH_DONE.

On Failure

Set the step to continue with in case of error. If no step is assigned an AuthState named <Realm>_Authentication_Failed is generated.

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 Host(s)

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 matching /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 behavior 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 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>

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

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.

gRPC Service

#Application Protection #Applications

Plugin: nevisadmin-plugin-nevisproxy

Set up access to a backend application providing a gRPC API.

Virtual Host(s)

Assign Virtual Host patterns which shall serve as entry point for this application. HTTP/2 has to be enabled on each Virtual Host.

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 behavior 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 URL (scheme, host, port and path) of the gRPC service.

Note:

Only one backend is allowed.
Automatic path rewriting will be performed when the path differs from the Frontend Path.

Key Store

Optional setting to use a client certificate for connecting to HTTPS backends.

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

Allowed HTTP Methods

Define the HTTP methods allowed for this application.

Methods which are listed here must also be allowed on the Virtual Host.

The only valid HTTP method used in gRPC over HTTP/2 is POST.

Note: While gRPC itself only uses POST, higher-level frameworks like Cloud Endpoints support HTTP/JSON transcoding, which can map HTTP GET, POST, PUT, and DELETE methods to gRPC methods using annotations (e.g., option (google.api.http) = { get: "/v1/shelves/{shelf}" };).

Custom Parameters

Add custom init-param(s) for the Http2Servlet. For example: ConnectionPoolSize=200

Please check the nevisProxy technical documentation for supported init-params of the servlet class ch::nevis::nevisproxy::servlet::connector::http::Http2Servlet.

nevisAdapt Analyzer Configuration

#User Behavior Analytics #Add-ons

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.

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

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:

On High Risk becomes mandatory
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:

On Medium Risk becomes mandatory
Applies the same next step as On Medium Risk

Logout Event Handling

This authentication step pattern can be used during both the login and the logout authentication flow. This parameter setting affects validation steps for generating the logout flow.

There are two options for the logout profile:

explicit - this authentication step has to be included in the logout flow.
- nevisAdapt will also close the session immediately
- remember-me token becomes deprecated (if any)
none - this authentication step is not necessary for the logout flow.
- if the logout flow contains this step, the effects above are the same
- otherwise nevisAdapt will only close the session after the timeout and the remember-me token remains valid

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.

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:

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.

Enabling this setting will make sure that the cookies generated before the nevisAdapt risk calculation step are updated on the browser side. This is not always necessary, but it can be useful in scenarios where the risk calculation step is followed by steps that don't return the cookies to the browser.

Default value: enabled (explicit cookie update step is required)

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

Configure how TLS is used when connecting to the database:

disabled – Connect without TLS (no encryption).
trust – Use TLS, but skip certificate and hostname validation.
verify-ca – Use TLS with certificate validation, but without hostname verification.
verify-full – Use TLS with full validation: encryption, certificate verification, and hostname verification.

When certificate validation is enabled and the server certificate is not trusted by the component, you must configure the Trust Store setting.

As the default trust varies by component (some use the Java default trust store, others also include OS-level trust stores), configuring Trust Store is recommended whenever you use private CAs or self-signed certificates.

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.

Min Pool Size

Set the minimum connection pool size.

The connection pool will always attempt to maintain at least the minimum pool size.

However, the number of open connections may temporarily fall below the minimum in the following cases:

During pool initialization.
When connections are terminated due to idle timeout, maximum lifetime, network issues, or database server configuration.

Max Pool Size

Set the maximum number of available and borrowed (in use) connections that a pool maintains.

If the maximum number of connections is borrowed, no connections will be available until a connection is returned to the pool.

This setting allows the number of connections in the pool to increase as demand increases.

Max Idle Time

Sets the maximum amount of time that unused excess connections stay in the pool before it is considered stale and is removed (closed) to free up resources.

Max Lifetime

This setting controls the maximum lifetime of a connection in the pool.

After the specified lifetime, database connections are removed from the pool, closed, and reopened.

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.

Hikari Configuration Values

Enter custom values for Hikari datasource configuration.

Supported keys are described at HikariCP - GitHub.

The prefix spring.datasource.hikari. must not be included as it will be added automatically to each key.

The following keys should not be configured here as there are settings in the Connection Pool tab:

minimumIdle
maximumPoolSize
idleTimeout
maxLifetime

If you still configure these keys, they will overrule the high-level settings.

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.

Instead of using 'jdbc:mysql' either

Use the high-level configuration for the Database Host instead of providing a custom URL
Add the query parameter permitMysqlScheme to the custom URL

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

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

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

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.

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

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. In Kubernetes deployments, the certificate subject must contain a CN entry with the service name.

If no pattern is assigned, automatic key management will provide a 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 mutual TLS (mTLS) on the HTTPS endpoint.

Choose between:

required: Clients must present a valid client certificate. Connections without a certificate, or with an invalid certificate, will be rejected.
requested: Clients may present a client certificate. If a certificate is provided, it must be valid. If no certificate is provided, the connection will still be accepted.
disabled: Clients must not present a client certificate. The server will not request a certificate. Presenting one may cause the connection to fail.

TLS Protocol(s)

The TLS protocol versions supported for inbound connections to this endpoint.

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.

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.

File Selection IPv6

Choose the IPv6 IP-to-location database source.

This setting is optional. If you set either IPv6 setting, you must also set this selector.

Supported values:

upload - use a custom CSV upload for IPv6 mapping.
DB1BIN - commercial IPv6 database, IP-Country.
DB1LITEBIN - free IPv6 database, IP-Country.
DB5BIN - commercial IPv6 database, IP-Country-City-GPS.
DB5LITEBIN - free IPv6 database, IP-Country-City-GPS.

IPv4 and IPv6 must use the same source type (upload or downloaded database), because schedule and token settings are shared.

Mapping File Upload IPv6

Provide an IPv6 mapping file upload.

Use this only when File Selection IPv6 is set to upload.

The file must:

be a CSV file (.csv or .CSV),
contain non-overlapping IPv6 ranges,
follow the same CSV format requirements as the IPv4 upload.

If IPv6 upload is enabled, an IPv6 file must be provided for deployment.

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

nevisAdapt filters private addresses out by default because they don't provide any reputation related information. If you want to allow internal IP addresses for risk scoring, you can disable this feature.

The generated property will look like this:

nevisadapt.ipReputation.service.privateNetworkFilter=false

IP Private Network Country Code

When selected 'disabled' on IP Private Network Filter, the country code of the IP address will be assigned to this, regardless of the original input value. You can assign a Geolocation by country code using ISO 3166 alpha-2.

The generated property will look like this:

nevisadapt.ipReputation.service.privateNetworkCountryCode=<2-letter country code>

The default value is CH.

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)

Stage URL

Used by Nevis ID to reach the common geolocation mapping download location.

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)

Startup Probe Delay

Delay for before Kubernetes will call the startup probe.

Set a higher value if deployment fails due to slow startup of the pods.

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

Proxy Host

Enter the host for the forward proxy if available.

Proxy Port

Enter the port of the forward proxy if available.

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.

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

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(s)

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

Trust Store

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 Calculation Step

#User Behavior Analytics #Connector #Experimental

Plugin: nevisadmin-plugin-nevisadapt

Using the pattern, you can integrate nevisAdapt as a risk calculation 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.

On Medium Risk

Set the step to continue with if the calculated risk score exceeds the Medium threshold.

In case it remains unset:

On High Risk becomes mandatory
Applies the same next step as On Success

On High Risk

Set the step to continue with if the calculated risk score exceeds the High threshold.

In case it remains unset:

On Medium Risk becomes mandatory
Applies the same next step as On Medium Risk

Key Store

Trust Store

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:

nevisAdapt Risk Plugin

#User Behavior Analytics #Add-ons #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 #Logging

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

Configure how TLS is used when connecting to the database:

disabled – Connect without TLS (no encryption).
trust – Use TLS, but skip certificate and hostname validation.
verify-ca – Use TLS with certificate validation, but without hostname verification.
verify-full – Use TLS with full validation: encryption, certificate verification, and hostname verification.

When certificate validation is enabled and the server certificate is not trusted by the component, you must configure the Trust Store setting.

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

Min Pool Size (Session Store)

Set the minimum connection pool size.

The connection pool will always attempt to maintain at least the minimum pool size.

However, the number of open connections may temporarily fall below the minimum in the following cases:

During pool initialization.
When connections are terminated due to idle timeout, maximum lifetime, network issues, or database server configuration.

Min Pool Size (Out-of-Context Data Store)

Set the minimum connection pool size.

The connection pool will always attempt to maintain at least the minimum pool size.

However, the number of open connections may temporarily fall below the minimum in the following cases:

During pool initialization.
When connections are terminated due to idle timeout, maximum lifetime, network issues, or database server configuration.

Max Pool Size (Session Store)

Set the maximum number of available and borrowed (in use) connections that a pool maintains.

If the maximum number of connections is borrowed, no connections will be available until a connection is returned to the pool.

This setting allows the number of connections in the pool to increase as demand increases.

Max Pool Size (Out-of-Context Data Store)

Set the maximum number of available and borrowed (in use) connections that a pool maintains.

If the maximum number of connections is borrowed, no connections will be available until a connection is returned to the pool.

This setting allows the number of connections in the pool to increase as demand increases.

Max Idle Time (Session Store)

Sets the maximum amount of time that unused excess connections stay in the pool before it is considered stale and is removed (closed) to free up resources.

Max Idle Time (Out-of-Context Data Store)

Sets the maximum amount of time that unused excess connections stay in the pool before it is considered stale and is removed (closed) to free up resources.

Max Lifetime (Session Store)

This setting controls the maximum lifetime of a connection in the pool.

After the specified lifetime, database connections are removed from the pool, closed, and reopened.

Max Lifetime (Out-of-Context Data Store)

This setting controls the maximum lifetime of a connection in the pool.

After the specified lifetime, database connections are removed from the pool, closed, and reopened.

Database Management

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

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

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:

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
`session: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.

Instead of using 'jdbc:mysql' either

Use the high-level configuration for the Database Host instead of providing a custom URL
Add the query parameter permitMysqlScheme to the custom URL

nevisAuth Domain Patch

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

Patches a Domain element generated by a realm pattern.

This is an advanced pattern.

Use only when the realm pattern does not give you enough control.

Authentication Realm

Assign the authentication realm pattern that generates the Domain that you want to patch.

Entry Patches

Assign Entry Patch patterns.

nevisAuth Entry Patch

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

Use to add, overwrite, or remove an Entry child element of a Domain element in nevisAuth.

This is an advanced pattern.

Use only when the realm pattern does not give you enough control.

Method

Enter the method of the Entry element.

Examples: authenticate, stepup, or logout.

This configuration is mandatory.

State

In case the Mode is patch you have to define the AuthState to dispatch to.

This is an advanced and low-level configuration.

If you need a higher-level configuration consider opening a support ticket with your requirements.

You can even dispatch into an AuthState that belongs to another realm.

You can enter any AuthState name that already exists in your esauth4.xml.

Check the deployment preview to find out what is available.

If no AuthState is found with that name, the generation will fail with an error.

Selector

If your Entry element requires a selector attribute, provide its value here. The value must be a nevisAuth or EL expression that evaluates to a boolean.

To patch or remove an Entry element with a selector attribute, paste the value from the deployment preview of esauth4.xml.

The name and selector attributes together uniquely identify the Entry element. When adding a new Entry element, the selector attribute is optional.

Mode

For now only remove is supported.

The pattern will ensure that no Entry element with the given method and selector (optional) is present in the Domain.

The patch operation may be implemented in the future.

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:

Rename the pattern in the GUI.
Rename the instance directory and associated systemd files on the deployment hosts.
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

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. In Kubernetes deployments, the certificate subject must contain a CN entry with the service name.

If no pattern is assigned, automatic key management will provide a key store.

Frontend Trust Store

Configure a trust store for validating incomining connections with a client certificate.

This setting is relevant only when Client Authentication is set to required or requested.

If no pattern is assigned here, automatic key management will be used to provide the trust store. Note that automatic key management works only for callers that use an automatic key store and are part of the same nevisAdmin project.

Client Authentication

Setting for mutual TLS (mTLS) on the HTTPS endpoint.

Choose between:

required: Clients must present a valid client certificate. Connections without a certificate, or with an invalid certificate, will be rejected.
requested: Clients may present a client certificate. If a certificate is provided, it must be valid. If no certificate is provided, the connection will still be accepted.
disabled: Clients must not present a client certificate. The server will not request a certificate. Presenting one may cause the connection to fail.

TLS Protocol(s)

The TLS protocol versions supported for inbound connections to this endpoint.

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.

Session Eviction Mode

Controls how sessions are retained in memory and how expiry is handled when a nevisAuth Database is assigned.

Scenario	Description
Legacy	Default, backward-compatible behavior. Sessions synced to the remote store remain in the local in-memory store for their full lifetime. The remote reaper deletes expired sessions from the database directly without firing termination events.
Consistency	The local reaper evicts synced sessions from memory. When sessions expire in the remote store, the remote reaper fires session termination events before bulk-deleting them. Recommended when running multiple nevisAuth instances with a shared remote session store and terminated session polling is enabled in nevisProxy.
Performance	The local reaper evicts synced sessions from memory, reducing the in-memory footprint. However, the remote reaper deletes expired sessions directly from the database without firing termination events. Suitable only when terminated session polling in nevisProxy is not required.

The Consistency and Performance scenarios are only effective when a nevisAuth Database is assigned.

For more information, see Session Management.

Max Sessions Per Reaper Run

Maximum number of expired sessions to process per reaper run.

Only used when Session Eviction Scenario is set to Consistency.

Batch Size Per Reaper Run

Number of sessions loaded and processed per batch within a reaper run.

Must be between 1 and 1000. Smaller batches reduce memory pressure but require more database round-trips.

Only used when Session Eviction Scenario is set to Consistency.

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

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.

Management Service

The nevisAuth Session Management REST endpoint can be called to terminate sessions.

The endpoint is enabled by default as it eases the integration of use cases provided by nevisAdapt.

The following element will be generated into the esauth4.xml:

<RESTService name="ManagementService" class="ch.nevis.esauth.rest.service.session.ManagementService"/>

As nevisAuth is typically not directly exposed to the internet (only via nevisProxy) and can only be reached using 2-way TLS, the endpoint does not increase the attack surface.

However, if you are sure that you don't need this endpoint, then you can opt out and select disabled here.

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 add-on patterns 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`

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 for nevisAuth.

Log messages are in JSON format.

The message contains a trace ID (trId) to allow for correlation with other logs.

Example:

{ "logVersion":"1", "timestamp":"2025-02-07T12:03:42.031Z", "logType":"sessionEvent", "eventType":"authenticate-completed", "trID":"a4c86aab76cff97c2156fd80d70b4fcc", "sessionID":"XDPl4CdfNaEcUpc4aVAbYaYxgr3a9rdYk6vO4Xef_ug", "conversationID":"450160216478", "client":{ "sessionID":"12ca12ac0200Y0FHJGcgRaQgv8fJ70cRSC9Ss9AIROUyW1fWcMcBZaAIWF", "clientID":"4818", "entryPoint":"nevis", "sslCipher":"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", "clientIP":"172.18.0.2" }, "agent":{ "userAgent":"Mozilla\/5.0 (X11; Linux x86_64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/133.0.0.0 Safari\/537.36", "agentIP":"172.18.0.1", "sslProtocol":"TLSv1.2", "sslCipher":"ECDHE-RSA-CHACHA20-POLY1305", "resPath":"https:\/\/nevis\/nevisidm\/admin", "reqPath":"https:\/\/nevis\/nevisidm\/admin", "reqQuery":"login" }, "hostName":"172.18.0.2", "port":8991, "sessionStartTimestamp":"2025-02-07T12:03:42.027Z", "loginID":"bootstrap", "userID":"100", "authLevel":"1", "roles":[ "1", "nevisIdm", "nevisIdm.SelfAdmin", "nevisMeta", "nevisMeta.admin", "nevisAdapt", "nevisAdapt.admin", "nevisAdapt.user", "nevisIdm.Root" ], "realm":"SSO", "language":"en", "eventTrail":[ { "stateName":"SSO_login_screen", "stateClass":"ch.nevis.idm.authstate.IdmPasswordVerifyState", "timestamp":"2025-02-07T12:03:21.633Z", "tech":"nevisIDM", "type":"username\/password", "detail":"bootstrap" }, { "stateName":"SSO_login_screen", "stateClass":"ch.nevis.idm.authstate.IdmPasswordVerifyState", "timestamp":"2025-02-07T12:03:27.229Z", "tech":"nevisIDM", "type":"username\/password", "detail":"bootstrap" }, { "stateName":"SSO_login_screen-IdmPasswordChange", "stateClass":"ch.nevis.idm.authstate.IdmChangePasswordState", "timestamp":"2025-02-07T12:03:41.298Z", "tech":"nevisIDM", "type":"mutation" }, { "stateName":"SSO_login_screen-IdmPostProcessing", "stateClass":"ch.nevis.idm.authstate.IdmGetPropertiesState", "timestamp":"2025-02-07T12:03:41.383Z", "tech":"nevisIDM", "type":"selection", "detail":"profile: BootstrapProfile\/100" } ], "custom":{ } }

In Kubernetes deployment the prefix [nevisauth-events.log] is added to each message.

In classic VM deployment the messages are written to a separate file nevisauth-events.log.

Log Format

Log4j 2 log format for log messages written to nevisauth-events.log.

We recommend to not change this configuration as log messages may not be valid JSON anymore.

This configuration is not when Log Targets is set to syslog.

Syslog Format

Log4j 2 log format for messages sent via Syslog.

This configuration is used when Log Targets contains syslog.

We recommend to not change this configuration as log messages may not be valid JSON anymore.

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

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

Status Port

The port on which Azure is making request to get liveness and health status from the NevisDP management port.

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.

In the XML, you can use ${var. expressions to reference inventory variables.

For instance, use ${var.a} to reference an inventory variable named a.

The value of the inventory variable must be a scalar.

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>

Startup Probe Delay

Delay for before Kubernetes will call the startup probe.

Set a higher value if deployment fails due to slow startup of the pods.

Start Inactive

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.

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.

Java Opts

Upload additional jvm configuration here.

Example of a JVM configuration file

-Dcom.sun.jndi.ldap.connect.pool.debug=all

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

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. In Kubernetes deployments, the certificate subject must contain a CN entry with the service name.

If no pattern is assigned, automatic key management will provide a 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 mutual TLS (mTLS) on the HTTPS endpoint.

Choose between:

required: Clients must present a valid client certificate. Connections without a certificate, or with an invalid certificate, will be rejected.
requested: Clients may present a client certificate. If a certificate is provided, it must be valid. If no certificate is provided, the connection will still be accepted.
disabled: Clients must not present a client certificate. The server will not request a certificate. Presenting one may cause the connection to fail.

TLS Protocol(s)

The TLS protocol versions supported for inbound connections to this endpoint.

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.

Startup Probe Delay

Delay for before Kubernetes will call the startup probe.

Set a higher value if deployment fails due to slow startup of the pods.

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

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(s)

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 behavior 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 #Connector #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.

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:

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

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. In Kubernetes deployments, the certificate subject must contain a CN entry with the service name.

If no pattern is assigned, automatic key management will provide a 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 mutual TLS (mTLS) on the HTTPS endpoint.

Choose between:

required: Clients must present a valid client certificate. Connections without a certificate, or with an invalid certificate, will be rejected.
requested: Clients may present a client certificate. If a certificate is provided, it must be valid. If no certificate is provided, the connection will still be accepted.
disabled: Clients must not present a client certificate. The server will not request a certificate. Presenting one may cause the connection to fail.

TLS Protocol(s)

The TLS protocol versions supported for inbound connections to this endpoint.

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.

Startup Probe Delay

Delay for before Kubernetes will call the startup probe.

Set a higher value if deployment fails due to slow startup of the pods.

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

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

Configure how TLS is used when connecting to the database:

disabled – Connect without TLS (no encryption).
trust – Use TLS, but skip certificate and hostname validation.
verify-ca – Use TLS with certificate validation, but without hostname verification.
verify-full – Use TLS with full validation: encryption, certificate verification, and hostname verification.

When certificate validation is enabled and the server certificate is not trusted by the component, you must configure the Trust Store setting.

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.

Min Pool Size

Set the minimum connection pool size.

The connection pool will always attempt to maintain at least the minimum pool size.

However, the number of open connections may temporarily fall below the minimum in the following cases:

During pool initialization.
When connections are terminated due to idle timeout, maximum lifetime, network issues, or database server configuration.

Max Pool Size

Set the maximum number of available and borrowed (in use) connections that a pool maintains.

If the maximum number of connections is borrowed, no connections will be available until a connection is returned to the pool.

This setting allows the number of connections in the pool to increase as demand increases.

Max Idle Time

Sets the maximum amount of time that unused excess connections stay in the pool before it is considered stale and is removed (closed) to free up resources.

Max Lifetime

This setting controls the maximum lifetime of a connection in the pool.

After the specified lifetime, database connections are removed from the pool, closed, and reopened.

Database Management

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

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

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.

Hikari Configuration Values

Enter custom values for Hikari datasource configuration.

Supported keys are described at HikariCP - GitHub.

The prefix spring.datasource.hikari. must not be included as it will be added automatically to each key.

The following keys should not be configured here as there are settings in the Connection Pool tab:

minimumIdle
maximumPoolSize
idleTimeout
maxLifetime

If you still configure these keys, they will overrule the high-level settings.

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.

Instead of using 'jdbc:mysql' either

Use the high-level configuration for the Database Host instead of providing a custom URL
Add the query parameter permitMysqlScheme to the custom URL

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.

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 behavior:

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

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. In Kubernetes deployments, the certificate subject must contain a CN entry with the service name.

If no pattern is assigned, automatic key management will provide a 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 mutual TLS (mTLS) on the HTTPS endpoint.

Choose between:

required: Clients must present a valid client certificate. Connections without a certificate, or with an invalid certificate, will be rejected.
requested: Clients may present a client certificate. If a certificate is provided, it must be valid. If no certificate is provided, the connection will still be accepted.
disabled: Clients must not present a client certificate. The server will not request a certificate. Presenting one may cause the connection to fail.

TLS Protocol(s)

The TLS protocol versions supported for inbound connections to this endpoint.

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.

Startup Probe Delay

Delay for before Kubernetes will call the startup probe.

Set a higher value if deployment fails due to slow startup of the pods.

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

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

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

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. In Kubernetes deployments, the certificate subject must contain a CN entry with the service name.

If no pattern is assigned, automatic key management will provide a 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 mutual TLS (mTLS) on the HTTPS endpoint.

Choose between:

required: Clients must present a valid client certificate. Connections without a certificate, or with an invalid certificate, will be rejected.
requested: Clients may present a client certificate. If a certificate is provided, it must be valid. If no certificate is provided, the connection will still be accepted.
disabled: Clients must not present a client certificate. The server will not request a certificate. Presenting one may cause the connection to fail.

TLS Protocol(s)

The TLS protocol versions supported for inbound connections to this endpoint.

Startup Probe Delay

Delay for before Kubernetes will call the startup probe.

Set a higher value if deployment fails due to slow startup of the pods.

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

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

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. In Kubernetes deployments, the certificate subject must contain a CN entry with the service name.

If no pattern is assigned, automatic key management will provide a 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 mutual TLS (mTLS) on the HTTPS endpoint.

Choose between:

required: Clients must present a valid client certificate. Connections without a certificate, or with an invalid certificate, will be rejected.
requested: Clients may present a client certificate. If a certificate is provided, it must be valid. If no certificate is provided, the connection will still be accepted.
disabled: Clients must not present a client certificate. The server will not request a certificate. Presenting one may cause the connection to fail.

TLS Protocol(s)

The TLS protocol versions supported for inbound connections to this endpoint.

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.

Startup Probe Delay

Delay for before Kubernetes will call the startup probe.

Set a higher value if deployment fails due to slow startup of the pods.

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

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(s)

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 behavior 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 behavior 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'.

TLS Encryption

Configure how TLS is used when connecting to the database:

disabled – Connect without TLS (no encryption).
trust – Use TLS, but skip certificate and hostname validation.
verify-ca – Use TLS with certificate validation, but without hostname verification.
verify-full – Use TLS with full validation: encryption, certificate verification, and hostname verification.

When certificate validation is enabled and the server certificate is not trusted by the component, you must configure the Trust Store setting.

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

Min Pool Size

Set the minimum connection pool size.

The connection pool will always attempt to maintain at least the minimum pool size.

However, the number of open connections may temporarily fall below the minimum in the following cases:

During pool initialization.
When connections are terminated due to idle timeout, maximum lifetime, network issues, or database server configuration.

Max Pool Size

Set the maximum number of connections allowed in the connection pool.

Default value is 10.

Max Idle Time

Sets the maximum amount of time that unused excess connections stay in the pool before it is considered stale and is removed (closed) to free up resources.

Max Lifetime

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

A high value improves the performance, but it should be lower than the connection idle timeout of the database (parameter wait_timeout in MariaDB).

If not specified, the default value is 10 minutes. If no time unit is provided, seconds will be used.

Database Management

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

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

Connection Timeout

Defines the maximum time that nevisFIDO waits for the connection to receive a response from the database.

Default is 30 seconds.

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.

Instead of using 'jdbc:mysql' either

Use the high-level configuration for the Database Host instead of providing a custom URL
Add the query parameter permitMysqlScheme to the custom URL

nevisFIDO FIDO2 Instance

#FIDO2 #Instances #Authentication

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.

SecToken Signer Trust Store

Assign a trust store for SecToken verification.

Database

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

Log Settings

Assign nevisFIDO Log Settings to change the log configuration.

User Name

Configure what is expected as username in incoming API calls.

Choose between extId and loginId.

Display Name Source

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

The default is loginId.

Frontend Key Store

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. In Kubernetes deployments, the certificate subject must contain a CN entry with the service name.

If no pattern is assigned, automatic key management will provide a key store.

Frontend Trust Store

Configure a trust store for validating incomining connections with a client certificate.

This setting is relevant only when Client Authentication is set to required or requested.

Client Authentication

Setting for mutual TLS (mTLS) on the HTTPS endpoint.

Choose between:

required: Clients must present a valid client certificate. Connections without a certificate, or with an invalid certificate, will be rejected. Generates server.tls.client-auth=required.
requested: Clients may present a client certificate. If a certificate is provided, it must be valid. If no certificate is provided, the connection will still be accepted. Generates server.tls.client-auth=requested.
disabled: Clients must not present a client certificate. The server will not request a certificate. Presenting one may cause the connection to fail. Generates server.tls.client-auth=disabled.

TLS Protocol(s)

The TLS protocol versions supported for inbound connections to this endpoint.

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

Metadata Location

Choose how to provide the metadata for allowed FIDO2 authenticators.

Select remote to fetch metadata from a remote service. The URL(s) are defined by the setting Metadata Service URL(s) and you can customize them there.

We recommend to use the official service provided by the FIDO Alliance. As the endpoint certificate is not trusted by default, you will have to configure Metadata Service Trust Store.

If you need to use a proxy to connect to this service, you have to set at least the Proxy Address. If your proxy requires authentication, you also have to set Proxy User and Proxy Password.

When local is selected, you will be asked to upload your metadata via Local Metadata.

When none is selected, no metadata will be configured. This means all authenticators will be allowed.

The option compat allows for a seemless upgrade. In compat mode the configuration depends on the setting Local Metadata (called Allowed Authenticators in previous versions). When Local Metadata is provided, compat behaves like local. Otherwise, it behaves like none.

Metadata Service URL(s)

Here you can configure a list of FIDO2 metadata service URLs.

In normal scenarios you most likely want to use the official metadata endpoint of the FIDO alliance.

For this HTTPS connection to succeed you also have to configure the Metadata Service Trust Store.

Check our configuration guide for additional information.

Metadata Service Trust Store

If Metadata Location is set to remote and the Metadata Service URL(s) use HTTPs, you have to configure this trust store.

Assign a PEM Trust Store and upload the CA certificate of the endpoint there.

Proxy Address

Here you can configure a proxy URL through which requests to the metadata service will be routed.

It is useful in environments where direct internet access is restricted or security policies mandate proxy usage.

By default, no proxy is set.

Proxy User

This setting defines the username required for authentication with the configured proxy.

It should be provided if the proxy service requires authentication.

By default, this setting is not set.

Proxy Password

This setting defines the password used alongside the proxy username for authentication purposes.

It must be defined if the proxy server requires password-based authentication.

By default, this setting is not set.

Local Metadata

Here you can configure which authenticators are allowed.

Upload the FIDO2 authenticator metadata file here.

This setting is used only when Metadata Location is set to local.

Usage of local metadata is recommended when Allowed Authenticators is enabled.

Proceed as follows:

Download the official FIDO Alliance Metadata file (JWT) from the FIDO Alliance Metadata Service.
Decode the downloaded JWT.
Copy out the complete metadata statements of the desired authenticators into a new JSON file.
(optional) Remove the optional entries to “slim down” the metadata entry, only required entries are aaguid and attestationRootCertificates.
Safe the JSON file and upload it here.

You can find more information in our FIDO2 Concept and Integration Guide.

Restrict Authenticators

By default, all authenticators that fulfill the requirements are allowed.

Here you can restrict which authenticators are allowed based on metadata.

If you select enabled here, it is typically required to provide customized metadata. Thus, you should set the Metadata Location to local and upload the required metadata file.

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

Enter the extId 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.

Startup Probe Delay

Delay for before Kubernetes will call the startup probe.

Set a higher value if deployment fails due to slow startup of the pods.

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

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.

Signature Algorithms

Configure the allowed signature algorithms.

Recommended by IANA:

ES256 : ECDSA using P-256 and SHA-256 (allowed by default)
ES384 : ECDSA using P-384 and SHA-384
ES512 : ECDSA using P-521 and SHA-512
EdDSA : Edwards-curve Digital Signature Algorithm (allowed by default)

Not recommended:

RS384 : RSASSA-PKCS1-v1_5 using SHA-384
RS256 : RSASSA-PKCS1-v1_5 using SHA-256
RS512 : RSASSA-PKCS1-v1_5 using SHA-512
RS1 : RSASSA-PKCS1-v1_5 with SHA1 (deprecated)

Registration Authorization

Configure if a SecToken is required to perform operations associated with registration.

Note that the Groovy script used by FIDO2 Onboarding pattern adds a SecToken to calls of the nevisFIDO REST API.

User Presence Requirement

Defines the user presence requirement of nevisFIDO during FIDO2 authentication and onboarding.

This setting is closely related to the user verification requirement, which is expressed in the options request (/nevisfido/fido2/attestation/options). Both the FIDO2 Authentication and FIDO2 Onboarding pattern have a setting User Verification for this.

User verification is the process of verifying the user through biometric recognition or by manually entering a PIN, while a user presence test is a simple interaction, such as pressing a button, to confirm human presence.

Together, the user presence and user verification requirements define the characteristics of the required authorization gesture from the user during the ceremony.

Cancel Endpoint

Enable or disable the POST /nevisfido/cancel endpoint, which allows cancelling ongoing mobile authentication operations.

Only enable this if the endpoint is secured, for example via a nevisProxy Virtual Host with an Authentication Realm.

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

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(s)

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 behavior 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:

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

Configure how TLS is used when connecting to the database:

disabled – Connect without TLS (no encryption).
trust – Use TLS, but skip certificate and hostname validation.
verify-ca – Use TLS with certificate validation, but without hostname verification.
verify-full – Use TLS with full validation: encryption, certificate verification, and hostname verification.

When certificate validation is enabled and the server certificate is not trusted by the component, you must configure the Trust Store setting.

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

Min Pool Size

Set the minimum connection pool size.

The connection pool will always attempt to maintain at least the minimum pool size.

However, the number of open connections may temporarily fall below the minimum in the following cases:

During pool initialization.
When connections are terminated due to idle timeout, maximum lifetime, network issues, or database server configuration.

Max Pool Size

Set the maximum number of connections allowed in the connection pool.

Default value is 10.

Max Idle Time

Sets the maximum amount of time that unused excess connections stay in the pool before it is considered stale and is removed (closed) to free up resources.

Max Lifetime

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

Database Management

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

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

Connection Timeout

Defines the maximum time that nevisFIDO waits for the connection to receive a response from the database.

Default is 30 seconds.

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.

Instead of using 'jdbc:mysql' either

Use the high-level configuration for the Database Host instead of providing a custom URL
Add the query parameter permitMysqlScheme to the custom URL

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(s)

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:

SecToken Signer Trust Store

Assign a trust store 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.

Frontend Key Store

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. In Kubernetes deployments, the certificate subject must contain a CN entry with the service name.

If no pattern is assigned, automatic key management will provide a key store.

Frontend Trust Store

Configure a trust store for validating incomining connections with a client certificate.

This setting is relevant only when Client Authentication is set to required or requested.

Client Authentication

Setting for mutual TLS (mTLS) on the HTTPS endpoint.

Choose between:

required: Clients must present a valid client certificate. Connections without a certificate, or with an invalid certificate, will be rejected. Generates server.tls.client-auth=required.
requested: Clients may present a client certificate. If a certificate is provided, it must be valid. If no certificate is provided, the connection will still be accepted. Generates server.tls.client-auth=requested.
disabled: Clients must not present a client certificate. The server will not request a certificate. Presenting one may cause the connection to fail. Generates server.tls.client-auth=disabled.

TLS Protocol(s)

The TLS protocol versions supported for inbound connections to this endpoint.

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, referring to specific authenticator implementations.

The policy for a certain operation can be specified in the context of the GetUafRequest object. Example snippet (JavaScript) 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

Application Attestation (App Attestation)

For configuring Android and iOS app attestation, refer to the Application Attestation Concept Guide and the Policy configuration examples.

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.

nevisFIDO ignores any authenticators and prevents all operations, when there is no corresponding metadata entry.

The default metadata works for the NEVIS Access App.

You have to update the metadata if you are using either:

a custom app based on the NEVIS Mobile Authentication SDK or
a customized Whitelabel Access App

To support Full Basic Attestation for Android the metadata must contain the Google root certificates. These entries must be kept up-to-date.

Android Verification Level

Android Key Attestation relies on FIDO UAF Full Basic Attestation. Whether Android Key Attestation is applied is controlled by the FIDO UAF policy.

Here you can choose between 2 verification levels for the FIDO UAF Full Basic Attestation:

default - does FIDO UAF Full Basic Attestation solely based on the FIDO UAF protocol specification. In practice, this means it’s limited to verifying the certificate chain.

strict - conducts 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.

The Nevis documentation provides additional information of how to create the necessary policy files:

Android Permissive Mode

Select disabled to fail the registration when the full basic attestation checks for Android fail. Read the help of Full Basic Attestation - Android Verification Level for further information about these checks.

Select enabled to still perform the same checks, but not fail the registration even when checks fail. Only a warning message will be logged.

Visit the Permissive Mode documentation for further information.

Android Reload Interval

Defines how often the Android attestation key revocation list is automatically refreshed.

Regular updates help protect the system against revoked or compromised keys.

The default interval is 6 hours, balancing key freshness with network usage.

Android Proxy Address

Configure a proxy for requests to the Android attestation key revocation service.

This is useful in environments where direct internet access is restricted or where security policies require proxy usage.

By default, no proxy is configured.

Android Proxy User

If your proxy requires authentication, you can enter the username here.

Android Proxy Password

If your proxy requires authentication, you can enter the password here.

Android Service Account

If required by the configured FIDO UAF policies, the integrity of the application will be validated.

On Android, nevisFIDO uses the Google Play Integrity API to perform this validation.

To enable this functionality, upload the service account JSON file provided by Google.

You can also use a variable containing either:

a nevisAdmin secret file
a Kubernetes file secret (k8s-secret-file://).

iOS Team Identifier

The 10-character identifier of the team that signs your iOS applications, as listed on Apple's developer account portal.

This value is also known as the App ID prefix (without the trailing dot).

iOS DeviceCheck Key Identifier

The 10-character identifier of your DeviceCheck key.

This identifier is required to validate attestation receipts during iOS app attestation.

For more information, see Accessing Fraud Risk in Apple’s documentation.

iOS DeviceCheck Key

For app attestation on iOS, nevisFIDO uses Apple’s DeviceCheck service.

Specify the file that contains the APNs (Apple Push Notification service) private key.

This key must be in PEM format.

For instructions on creating a DeviceCheck private key, refer to Apple’s official documentation.

You can also use a variable containing either:

a nevisAdmin secret file
a Kubernetes file secret (k8s-secret-file://).

iOS Attestation Limit

The maximum number of app attestation keys that a device can generate within a 30-day period.

Typically, an application attestation key is generated once during the lifetime of the app — unless it expires or the app is reinstalled.

On compromised iOS devices, malicious clients may generate excessive attestation keys.

A high number of keys generated on a single device could be an indicator that the device has been compromised.

You should set this limit based on how frequently your application might reasonably be reinstalled within 30 days.

In development environments, frequent re-installations are common, so you may want to set a high number.

For more details, refer to Apple's documentation on assessing fraud risk.

Default value: 20

Proxy Address

This setting allows specification of a proxy URL through which requests to the Android & iOS backend services will be routed.

It is useful in environments where direct internet access is restricted or security policies mandate proxy usage.

By default, no proxy is configured.

Proxy User

This setting defines the username required for authentication with the configured proxy.

It should be provided if the proxy service requires authentication.

By default, this setting is unset.

Proxy Password

This setting sets the password used alongside the proxy username for authentication purposes.

It must be defined if the proxy server requires password-based authentication.

By default, this setting is unset.

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 or app 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, they don't use the standard https:// scheme.

The scheme must be registered for the mobile app.

See Link Structure for Custom URIs for details.

Example:

myaccessapp://x-callback-url/authenticate

nevisIDM

For user and credential management, nevisFIDO needs nevisIDM.

Assign a nevisIDM Instance or nevisIDM Connector here.

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

Client ID

Enter the extId 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.

Credential Management API

When set to dedicated, nevisFIDO uses the nevisIDM dedicated-entity REST API to manage dispatch targets and iOS App Attestation credentials, instead of the legacy generic credential-based implementation.

Before switching to dedicated, existing dispatch targets and iOS App Attestation credentials stored as generic credentials in nevisIDM must be migrated to the dedicated-entity format.

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:

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:

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. This is indicated by a JWS in request is expired error in the logs.

This configuration value influences the behavior of the following HTTP API endpoints:

The default value is 5 minutes. If no time unit is provided, seconds will be used.

Push Message Timeout

The duration how long a push message is valid.

Should match the Authentication Token Timeout.

If no unit is given seconds is assumed.

Startup Probe Delay

Delay for before Kubernetes will call the startup probe.

Set a higher value if deployment fails due to slow startup of the pods.

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

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.

FIDO UAF Credential Policy

The extId of the nevisIDM credential policy to be used for FIDO UAF credentials.

This setting allows you to specify the extId of the policy to be used for the credential type.

Use it in case your project is using custom policies, and you need fine-granular control over the policy assigned to the credential.

Modify operations do not update existing credentials.

Dispatch Target Policy

The extId of the nevisIDM credential policy to be used for Dispatch Target Generic credentials.

This setting allows you to specify the extId of the policy to be used for the credential type.

Use it in case your project is using custom policies, and you need fine-granular control over the policy assigned to the credential.

Modify operations do not update existing credentials.

iOS App Attestation Policy

The extId of the nevisIDM credential policy to be used for iOS App Attestation Generic credentials.

This setting allows you to specify the extId of the policy to be used for the credential type.

Use it in case your project is using custom policies, and you need fine-granular control over the policy assigned to the credential.

Modify operations do not update existing credentials.

User Name

Configure what is expected as username in incoming API calls.

Choose between extId and loginId.

Deregistration Authorization

Configure if a SecToken is required to perform deregistration.

Cancel Endpoint

Enable or disable the POST /nevisfido/cancel endpoint, which allows cancelling ongoing mobile authentication operations.

Only enable this if the endpoint is secured, for example via a nevisProxy Virtual Host with an Authentication Realm.

Custom Dependencies

Add plugins to nevisFIDO.

The easiest way is to upload a JAR file with Java code. This is the only option for classic VM deployments.

In Kubernetes deployments, you can use a Kubernetes secret instead. This way you can avoid it that the JAR is pushed to the deployment GIT.

Proceed as follows:

Create 1 Kubernetes secret containing the JAR file(s) in the target namespace.
Click the var button to use a variable here and enter a name for the variable.
Add the variable to your inventory and reference files from the Kubernetes secret there.

Additional configuration may be required to use the plugin. Use the Generic nevisFIDO UAF Instance Settings pattern to add the required entries to the nevisfido.yml.

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

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 (deprecated)

#Identity Management #Authentication #Experimental

Plugin: nevisadmin-plugin-nevisidm

Account recovery provides the user an alternative way to log in. The user needs to have a recovery code credential in nevisIDM.

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.

This pattern is deprecated and will be removed in a future release. The main reason for the deprecation is that the pattern is too oppinionated.

The first AuthState it generates asks the user to enter their password and this severely limits the use cases where this pattern can be used.

Use the new patterns nevisIDM Recovery Code Onboarding and nevisIDM Recovery Code Authentication instead. If those patterns do not fit your requirements please get in touch.

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(s)

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

Customize roles for a nevisIDM Instance.

Assign to the nevisIDM Instance using Additional Settings.

Role Management

Add or overwrite entries for authorizationConfig.properties.

The format is:

<role>=<role1>,<role2>,...

Where <role> refers to the role of the actor and <roleX> to a role of a user that shall be changed.

See Assigning IDM roles for details.

Example:

nevisIdm.UserAdmin=nevisIdm.SelfAdmin

This configuration allows users with role UserAdmin to access users with role SelfAdmin.

You can input the role with or without nevisIdm prefix. For instance, both Root are nevisIdm.Root are supported.

Role Assignment

Add or overwrite entries for rolesAssignment.properties.

The format is:

<assignableRole>=<role1>,<role2>,...

Meaning that users with role <role1>, <role2>, ... can assign the role <assignableRole>.

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.

Example:

nevisIdm.Helpdesk=nevisIdm.Root,nevisIdm.ClientRoot

Role Permissions

Add or overwrite entries for rolesMapping.properties.

The format is:

<role>=<permission1>,<permission2>,...

Where <role> is the name of a nevisIDM role and <permissionX> is one of the elementary permissions of nevisIDM.

You can enter the role with or without nevisIdm prefix. For instance, both Root are nevisIdm.Root are supported.

See Functional authorization - nevisIDM roles for details.

Example:

nevisIdm.SelfAdmin=AccessControl.SelfAdmin

For the permissions UserModify and UserView a fine-grained permission can be used instead.

See Configuration of fine-grained permissions for details.

Credential-type specific permissions

For permissions related to credentials, it's possible to reduce the elementary permission to specific credential type(s).

See Credential-type specific permissions of nevisIDM roles for details

nevisIDM Change Password

#Identity Management #Authentication

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

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 Cert Authentication

#Identity Management #Authentication

Plugin: nevisadmin-plugin-nevisidm

Requires the caller to present a client certificate.

The certificate should be validated and trusted by the component that does the TLS termination. In a Kubernetes deployment of Nevis that component may be the Envoy Gateway (in-cluster) or Cloudflare (external, used in Nevis ID). For NGINX Ingress, use the Legacy option.

This pattern does not ensure that these components enforce mTLS. Use Gateway API Settings to apply the required configuration for Envoy Gateway, or NGINX Ingress Settings for NGINX Ingress.

If TLS is terminated in front of Nevis, ensure that the component that does the TLS termination forwards the client cert in the correct HTTP header. Check the setting TLS Terminator for details. Only trust such headers if they are set or overwritten by a trusted TLS terminator or reverse proxy, and if any incoming x-forwarded-client-cert / client-cert / ssl-client-cert headers from untrusted clients are stripped before the request is forwarded to Nevis. Otherwise an attacker could spoof a client certificate by injecting the header.

A preprocessing script extracts the client certificate from the configured source and hands it over to the IdmX509State, which looks up the user in nevisIDM based on the Certificate credential.

There are various exits for error cases. Check the help and configure them as required for your use case.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

TLS Terminator

Select the component that terminates TLS and forwards the client certificate to Nevis.

Envoy Gateway (default for Nevis on-premise): The certificate is read from the x-forwarded-client-cert HTTP header. Envoy Gateway forwards the client certificate in semicolon-separated key-value pairs; the Cert field contains the full URL-encoded PEM certificate.

Cloudflare (default for Nevis ID): The certificate is read from the client-cert HTTP header as defined by RFC 9440. Cloudflare forwards the DER-encoded certificate as base64 wrapped with leading and trailing colons (:BASE64:).

Legacy: The certificate is read from the ssl-client-cert HTTP header. This is the format historically used by NGINX Ingress, where the PEM certificate is URL-encoded with spaces separating the base64 chunks. Use this option only if you are still running NGINX Ingress.

This option also configures nevisProxy to actively request a client certificate from the TLS peer via ClientCert: want and to store it in the session via StoreClientCert: true. This requires TLS to be terminated at nevisProxy itself, not by an upstream component.

On Success

Assign an optional step to execute after successful authentication.

On Missing Cert

Assign an optional step to execute when no client certificate is found in the request.

This may be an integration mistake, or the consequence of mTLS being optional in the component that does the TLS termination.

If not configured, the request follows the realm's default authentication failure handling.

On Forbidden

Called when a user is found in nevisIDM, but authentication is forbidden because either:

the user is disabled
or the user is locked.

If not configured, the flow falls back to the realm's generic Authentication_Failed step, which typically shows the default error (for example error_99).

On Failed

Called when the IdmX509State cannot authenticate the user.

This covers the following cases:

No user is registered for the certificate (clientNotFound)
The certificate is assigned to multiple users (failed)
The user has multiple certificate credentials and no selection can be made (chooseClient)

If not configured, failures are routed to the realm's generic Authentication_Failed step, which typically shows the default error label (for example error_99) unless overridden by the realm.

Client Name

Sets the client.name property of the IdmX509State.

If not set, the AuthState applies its built-in fallback strategy to resolve the client name.

Set this property if the user base spans multiple clients in nevisIDM and the client cannot be determined automatically via the fallback chain.

nevisIDM Connector

#Identity Management #Connector

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

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

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

Configure how TLS is used when connecting to the database:

disabled – Connect without TLS (no encryption).
trust – Use TLS, but skip certificate and hostname validation.
verify-ca – Use TLS with certificate validation, but without hostname verification.
verify-full – Use TLS with full validation: encryption, certificate verification, and hostname verification.

When certificate validation is enabled and the server certificate is not trusted by the component, you must configure the Trust Store setting.

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.

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.

Min Pool Size

Set the minimum connection pool size.

The connection pool will always attempt to maintain at least the minimum pool size.

However, the number of open connections may temporarily fall below the minimum in the following cases:

During pool initialization.
When connections are terminated due to idle timeout, maximum lifetime, network issues, or database server configuration.

Max Pool Size

Set the maximum number of available and borrowed (in use) connections that a pool maintains.

If the maximum number of connections is borrowed, no connections will be available until a connection is returned to the pool.

This setting allows the number of connections in the pool to increase as demand increases.

Max Idle Time

Sets the maximum amount of time that unused excess connections stay in the pool before it is considered stale and is removed (closed) to free up resources.

Max Lifetime

This setting controls the maximum lifetime of a connection in the pool.

After the specified lifetime, database connections are removed from the pool, closed, and reopened.

Database Management

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

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

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.

Instead of using 'jdbc:mysql' either

Use the high-level configuration for the Database Host instead of providing a custom URL
Add the query parameter permitMysqlScheme to the custom URL

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:

Rename the pattern in the GUI.
Rename the instance directory and associated systemd files on the deployment hosts.
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.

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.

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.

Frontend Key Store

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. In Kubernetes deployments, the certificate subject must contain a CN entry with the service name.

If no pattern is assigned, automatic key management will provide a key store.

Frontend Trust Store

Configure a trust store for validating incomining connections with a client certificate.

This setting is relevant only when Client Authentication is set to required or requested.

Client Authentication

Setting for mutual TLS (mTLS) on the HTTPS endpoint.

Choose between:

required: Clients must present a valid client certificate. Connections without a certificate, or with an invalid certificate, will be rejected. Generates server.tls.require-client-auth=true.
disabled: Clients must not present a client certificate. The server will not request a certificate. Generates server.tls.require-client-auth=false.

TLS Protocol(s)

The TLS protocol versions supported for inbound connections to this endpoint.

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 TLS Mode

Choose between:

disabled - TLS is disabled. The SMTP Trust Store is not used.
STARTTLS - uses the STARTTLS command (see RFC 2487) to switch to 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.

Startup Probe Delay

Delay for before Kubernetes will call the startup probe.

Set a higher value if deployment fails due to slow startup of the pods.

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

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.

Default: AES/CBC/PKCS5Padding for historical reasons.

AES/GCM/NoPadding advised for new installations.

Migration of old cipher is possible with EncryptionFallbackJob.

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.

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.

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

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 Manage Roles

#Identity Management #Authentication

Plugin: nevisadmin-plugin-nevisidm

Add or remove roles for a nevisIDM user.

The user must have been determined by an authenticating AuthState. Check the Nevis documentation to find out which nevisIDM AuthState classes fall into this category.

Patterns which determine the user are nevisIDM Password Login and nevisIDM User Lookup. If you have any of them in your flow before this step, role adding and removal will be possible.

Note that the nevisIDM User Lookup does not perform any authentication, and thus you have to use additional patterns in your flow to ensure the caller is allowed to use the user account.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

Add Roles

Roles to add to nevisIDM user.

Examples:

nevisIdm.Root
nevisIdm.SelfAdmin

nevisAuth and EL expressions are supported.

Remove Roles

Roles to remove from nevisIDM user.

Examples:

nevisIdm.Root
nevisIdm.SelfAdmin

nevisAuth and EL expressions are supported.

On Success

Step to execute after adding and/or removing roles.

nevisIDM Password Create

#Identity Management #Authentication

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.

#Identity Management #Authentication

Plugin: nevisadmin-plugin-nevisidm

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

Client Name

This field specifies the client name to use when Show Client Input Field is disabled. If left unset, the default client name Default will be applied.

When Show Client Input Field is enabled this value is used to display the initially suggested client in the input field.

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.

Button Order

Choose primary to show the primary button before any additional buttons.

Choose reverse to display the primary button last.

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:

Seconds
Minutes
Hours
Day-of-Month
Month
Day-of-Week
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(s)

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 behavior 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 Recovery Code Authentication

#Identity Management #Authentication

Plugin: nevisadmin-plugin-nevisidm

This pattern uses the nevisIDM recovery code credential to authenticate the user.

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.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

On Success

FIXME

On Exhausted

Assign a step to continue with when the user has no valid recovery code (remaining).

nevisIDM Recovery Code Onboarding

#Identity Management #Authentication #Onboarding

Plugin: nevisadmin-plugin-nevisidm

This pattern ensures that the user has valid recovery codes.

Recovery codes are useful when a user loses access to their account — for example, after losing the mobile phone used for two-factor authentication.

The pattern checks whether a valid recovery code credential exists in nevisIDM. If no such credential exists, or if all codes have been used, a new credential is created.

After the credential is created, a GUI is displayed prompting the user to store or print the recovery codes.

The Gui descriptor generated by this pattern includes several GUI elements that require custom handling (CSS and JavaScript) in the login template.

In your realm pattern, set the Login Template to modern.

If you use your own template, make sure to handle the following gui elements:

displayrecoverycodes: an info element to display the recover codes
copyrecoverycode: a button which copies the recovery codes to the clipboard.
downloadrecoverycode: a button to download the recovery codes as a file.
printrecoverycode: a button to print the recovery codes.

Check the modern template for the required CSS and JavaScript.

Use the nevisIDM Recovery Code Authentication pattern to authenticate the user.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

On Success

Assign a step to continue with once it is clear that the user has valid recovery codes.

On Failure

FIXME

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(s)

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 behavior 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 Onboarding

#Identity Management #Authentication #Onboarding

Plugin: nevisadmin-plugin-nevisidm

This authentication step checks the credentials of the user to determine which second factors may still be onboarded.

If the user has any credentials not created yet, a selection dialog is shown.

The following labels are used in that dialog and you may 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

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

OTP card

Assign a step which may be selected to onboard 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 to onboard an OATH (TOTP) credential.

OATH (TOTP) credentials may be used for second factor authentication using an authentication app, e.g. Google Authenticator.

Assign an OATH Onboarding pattern here.

mTAN

Assign a step which may be selected to onboard an mTAN credential.

FIDO UAF Authenticator

Assign a step which may be selected to onboard a FIDO UAF Authenticator credential.

FIDO2 Authenticator

Assign a step which may be selected to onboard a FIDO2 Authenticator credential.

Assign a FIDO2 Onboarding pattern here.

Recovery code

Assign a step which may be selected to onboard a recovery codes credential.

For instance, assign a Generic Authentication Step pattern.

On Exhausted

Assign a step to continue with when the user has onboarded all configured credentials.

On Cancel

Configure a step to continue with when the user clicks Skip this step. The button is defined by the label info.signup.2fa.skip.

Note that the button will be displayed only when the user has onboarded enough credentials to satisfy the Onboarding Mode.

Buttons

Add additional buttons to the onboarding screen which are always shown.

Onboarding Mode

Choose an onboarding mode:

optional: allow the user to skip the onboarding completely
at least 1: require at least one credential to be onboarded
all: require all credentials to be onboarded

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

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.

Acceptance

Choose between:

explicit: The user must tick a checkbox for each terms to accept.
implicit: No checkboxes are shown. It is sufficient to click the button to continue.

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(s)

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.

Welcome label

LitDict label of text to be displayed on the welcome screen of the ticket consumption page.

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

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 preceding 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}

Mandatory User Properties

Define which custom user properties will always be set.

The value can be constant or determined by a nevisAuth or EL expression. User creation will fail when the value is empty.

How to best determine the value depends on preceding authentication states and the (session) variables they produce.

The user property must be defined as a schema customization in nevisIDM. Some federation patterns and the nevisIDM Custom Property patterns can be used to define user properties.

Optional User Properties

Define which custom user properties are optional and how to provide them.

The value may be a static String or determined by a nevisAuth or EL expression.

Client ID

Enter the client ID where the user shall be created.

It can be a plain string or an expression (e.g.: ${notes:clientId}).

Unit ID

Enter the unit ID where the user shall be created.

It can be a plain string or an expression (e.g.: ${notes:unitId}).

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.

#Identity Management #Authentication

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.

#Identity Management #Authentication

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

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

Assign a step to continue with when the user was found.

Your authentication flow should contain at least 1 step which authenticates the user, e.g. by checking credentials.

Thus, it is usually required to assign a step here.

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.

Passkey Autofill

Select enabled to support passkey autofill on the login page.

The Authentication Mode must be set to interactive so that a login page is shown.

The User Name in the nevisFIDO FIDO2 Instance must be set to extId.

You can use the FIDO2 Onboarding pattern anywhere in your authentication flow to allow users to set up a passkey. The FIDO2 Onboarding pattern must be configured as follows:

User Verification must be set to required.
Resident Key must be set to required.

nevisFIDO FIDO2

Assign a nevisFIDO FIDO2 Instance.

On Passkey Success

Assign a step to continue with after successful passkey authentication.

If not assigned, the standard On Success exit will be taken.

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.

Use Default Profile

When enabled, the default profile will be used in case the user has multiple profiles.

When disabled the Profile Selection setting applies.

Profile Selection

This setting controls how the profile is selected when the user has multiple profiles.

You can ignore this when your users have only 1 profile as it will be selected automatically.

Choose between:

interactive - the user is asked to select a profile based on its name.
Unit for OAuth client - use this option when you have a Unit in nevisIDM for each OAuth client.

The Unit for OAuth client variant requires that you to fill out the Profile Mapping table.

Profile Mapping

Provide a mapping for the selected Profile Selection mode.

This setting is ignored when the mode is interactive.

In case of Unit for OAuth client, fill out the table as follows:

Key: OAuth client ID
Value: nevisIDM Unit name

On Missing Profile

Assign a step to continue with when the Profile Selection is unable to determine a profile.

For instance, you may assign a step to perform progressive onboarding by creating a new profile.

This setting is ignored when the mode is interactive.

When no pattern is assigned, a profile selection dialog will be shown as a fallback.

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.

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.

Title

Enter a label to customize the title.

By default, the label title.login is used.

Description

Enter a label to show underneath the title.

By default, the label info.login is used.

If you do not want to show any text underneath the title enter none.

Button Label

Enter a label for the primary button that submits the form.

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.

Button Order

Choose primary to show the primary button before any additional buttons.

Choose reverse to display the primary button last.

nevisIDM User Update

#Identity Management #Authentication

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}`

Optional User Properties

Define which properties are optional and how to provide them. Make sure the properties exist in the IDM.

User Properties can be created by using the nevisIDM Custom Property pattern or directly via SQL. More information about user properties can be found here: Properties - customizing the nevisIDM data model

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 Application

#Authentication #Experimental

Plugin: nevisadmin-plugin-nevisauth

Adds an additional nevisLogrend Application to a nevisLogrend Instance. This pattern should only be used when you need to use a different login template based on the request.

To use this pattern additional configuration is required in your Authentication Realm:

assign this pattern as a Dynamic Template,
select one of the variants for Dynamic Template Selection,
and configure the Template Mapping for the selected variant.

nevisLogrend Instance

Assign a nevisLogrend Instance. Assignment is mandatory.

Application Name

Enter a name for this nevisLogrend application.

The value will be sanitized to be a valid directory name.

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

Make sure to configure the nevisLogrend Application in your realm pattern accordingly.

Company Logo

Upload a logo to be displayed on the login page.

The logo file should have an appropriate size, e.g., 50x50 pixels.

If you use a different nevisLogrend template, you can add the expression ${logo} to point to the uploaded file.

Download the login template to see how the expression is used there.

Customize the rendering of login pages.

Download one of the default templates to get started.

nevisLogrend: Direct Mode

You can upload Velocity template files 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: static resources (e.g. images, CSS, Javascript)

nevisLogrend: Expressions

In nevisLogrend templates you may use the following expressions:

Expression	Description
`${form}`	login form (`form.vm`)
`${lang.switch}`	language switcher component (`lang.vm`)
`${lang.code}`	current language code (i.e. `en`, `de`)
`${label.myLabel}`	a label which must be translated via `Custom Translations`
`${resources}`	path to static resources (e.g. CSS, images, Javascript)
`${resource:<name>}`	path to static resource `name` with attached hash

These expressions will be replaced with a corresponding Velocity snippet at generation time.

For instance, using the expression ${resource:bootstrap.min.css} with the modern template yields the following path:

${login.appDataPath}/resources/bootstrap.min.css?v=3f1c72e8.

Note that the expression ${login.appDataPath} is handled at runtime by nevisLogrend.

nevisLogrend: Simple Mode

In simple cases you may not have to deal with Velocity template files.

To replace the outer HTML you can upload a file named template.html. The template must contain the ${form} expression.

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}`/logo.png" alt="Company Logo">
    </header>
    <main id="content" class="container">
      ${form}
    </main>
  </body>
</html>

Template Mode

Choose between:

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.
complete: only the files uploaded as Login Template will be deployed.
- Use this option when you want to provide the entire template.

Default Translations

Choose between:

enabled - add default translations for labels which are commonly used (e.g. title or language labels in nevisLogrend, error labels from nevisAuth) and which are recommended by realm patterns (e.g., assigned authentication steps).
disabled - select to only add what has been uploaded via Custom Translations. If your translations are incomplete, users may see the untranslated labels.

This configuration overrules the corresponding configuration in the realm pattern.

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

default.properties

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

This is an advanced setting. Use only when there is no other alternative and consider creating a support ticket with your use case.

Check Login Application Configuration for supported properties.

We recommend to not overwrite any language related properties, as the languages have to be in sync with nevisAuth. You can configure the supported languages on the nevisAuth Instance.

This setting requires that nevisLogrend is used for GUI rendering. Check the help of Login Renderer for details.

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.

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.

Log Settings

Add logging configuration for nevisLogrend.

Frontend Key Store

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. In Kubernetes deployments, the certificate subject must contain a CN entry with the service name.

If no pattern is assigned, automatic key management will provide a key store.

Frontend Trust Store

Configure a trust store for validating incomining connections with a client certificate.

This setting is relevant only when Client Authentication is set to required or requested.

Client Authentication

Setting for mutual TLS (mTLS) on the HTTPS endpoint.

Choose between:

required: Clients must present a valid client certificate. Connections without a certificate, or with an invalid certificate, will be rejected.
requested: Clients may present a client certificate. If a certificate is provided, it must be valid. If no certificate is provided, the connection will still be accepted.
disabled: Clients must not present a client certificate. The server will not request a certificate. Presenting one may cause the connection to fail.

TLS Protocol(s)

The TLS protocol versions supported for inbound connections to this endpoint.

Startup Probe Delay

Delay for before Kubernetes will call the startup probe.

Set a higher value if deployment fails due to slow startup of the pods.

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

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.

Custom MIME Types

Add or overwrite MIME types.

nevisLogrend supports common MIME types by default.

MIME types which are not known to the component, have to be defined in the mimetypes.properties file.

You can add or overwrite entries in the mimetypes.properties here.

The default content is:

ico=image/x-icon
json=application/json
woff=font/woff
woff2=font/woff2

Custom Properties (LoginRendererServlet)

Advanced configuration to add, overwrite, or remove init-param elements of the LoginRendererServlet servlet.

To remove enter just the name with an empty value.

By default, the servlet has the following init-param elements:

PropagateRemoteHeaders:
- value: Set-Cookie
- reason: to ensure nevisLogrend can issue LANG cookie.
authmethod.Unlock:
- value: embedded
- reason: the nevisProxy default for the unlock method is to open a popup. This is not appropriate nowadays.
RenderingProvider:
- value: remote:NevisLogrendConnector_<name>:/nevislogrend/index.vm?logrendresourcepath=/nevislogrend
- required for the connection to nevisLogrend. Do not change this unless you know what you are doing.

Additional Settings

Assign an add-on pattern to customize the configuration of nevisLogrend.

nevisLogrend Log Settings

#Authentication #Add-ons #Logging

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.

Check the Nevis documentation for important log categories.

If you only change log levels and deploy to classic VMs, nevisAdmin does not restart the component. 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 behavior 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

Configure how TLS is used when connecting to the database:

disabled – Connect without TLS (no encryption).
trust – Use TLS, but skip certificate and hostname validation.
verify-ca – Use TLS with certificate validation, but without hostname verification.
verify-full – Use TLS with full validation: encryption, certificate verification, and hostname verification.

When certificate validation is enabled and the server certificate is not trusted by the component, you must configure the Trust Store setting.

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

Min Pool Size

Set the minimum connection pool size.

The connection pool will always attempt to maintain at least the minimum pool size.

However, the number of open connections may temporarily fall below the minimum in the following cases:

During pool initialization.
When connections are terminated due to idle timeout, maximum lifetime, network issues, or database server configuration.

Max Pool Size

Set the maximum number of available and borrowed (in use) connections that a pool maintains.

If the maximum number of connections is borrowed, no connections will be available until a connection is returned to the pool.

This setting allows the number of connections in the pool to increase as demand increases.

Max Idle Time

Sets the maximum amount of time that unused excess connections stay in the pool before it is considered stale and is removed (closed) to free up resources.

Max Lifetime

This setting controls the maximum lifetime of a connection in the pool.

After the specified lifetime, database connections are removed from the pool, closed, and reopened.

Database Management

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

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

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.

Instead of using 'jdbc:mysql' either

Use the high-level configuration for the Database Host instead of providing a custom URL
Add the query parameter permitMysqlScheme to the custom URL

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:

Rename the pattern in the GUI.
Rename the instance directory and associated systemd files on the deployment hosts.
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.

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

This setting specifies the key store used for the HTTPS endpoint.

The certificate in the key store must be valid for all frontend addresses. In Kubernetes deployments, the certificate subject must contain a CN entry with the service name.

If no pattern is assigned, automatic key management will provide a key store.

Frontend Trust Store

Configure a trust store for validating incomining connections with a client certificate.

This setting is relevant only when Client Authentication is set to required or requested.

Client Authentication

Setting for mutual TLS (mTLS) on the HTTPS endpoint.

Choose between:

required: Clients must present a valid client certificate. Connections without a certificate, or with an invalid certificate, will be rejected.
requested: Clients may present a client certificate. If a certificate is provided, it must be valid. If no certificate is provided, the connection will still be accepted.
disabled: Clients must not present a client certificate. The server will not request a certificate. Presenting one may cause the connection to fail.

TLS Protocol(s)

The TLS protocol versions supported for inbound connections to this endpoint.

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.

Startup Probe Delay

Delay for before Kubernetes will call the startup probe.

Set a higher value if deployment fails due to slow startup of the pods.

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

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

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(s)

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 behavior 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(s)

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 behavior 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:

Rename the pattern in the GUI.
Rename the instance directory and associated systemd files on the deployment hosts.
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

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 Probe 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 behavior 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.

SSL VHost SNI Policy

Set compatibility policy for SNI client access to virtual hosts

Possible values are:

strict
secure
authonly
insecure

The following defaults are used:

classic VM deployment: secure
kubernetes setup: authonly

Considerations when deploying to Kubernetes:

if the Ingress is SNI aware, you should set this value at least to secure to avoid vulnerability to CVE-2025-23048.
if the Ingress is not SNI aware, make sure that the entrypoint is protected against CVE-2025-23048.

You can find more technical information here: https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslvhostsnipolicy

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

Check the nevisProxy reference guide to learn about log files and debugging.

The trace groups that you can configure here are described on the following subpages:

Note that the description in the reference guide includes a prefix BC.Tracer.DebugProfile. which is not needed here. Enter only the suffix of the name of the trace group.

Further, this pattern uses semantic log levels instead of the numeric levels that nevisProxy uses. Do not enter numbers for the log level as nevisAdmin4 will calculate them automatically.

Choose between:

ERROR
NOTICE
INFO
DEBUG
DEBUG_HIGH
TRACE

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

ModSecurity Audit Log

Controls the ModSecurity audit log engine (SecAuditEngine).

disabled: audit logging is off
enabled: all transactions are logged
relevant only: only transactions matching SecAuditLogRelevantStatus are logged

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.

#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

#Application Protection #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.

Transport Protocol

Choose one of:

gRPC: The nevisProxy OpenTelemetry service supports gRPC
http: The nevisProxy OpenTelemetry service does not support gRPC

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 ([http[s]://]host:port) of the backend services to which the exporter is going to send spans. The /v1/traces path is automatically attached to it. This parameter is required if a Deployment Environment is set.

Trace Exporter Trust Store

Optional setting for enabling trust to the Opentelemetry service.

For securing production environments:

set Trace Exporter Address starting with https://
assign a Trust Store pattern containing the certificates required for verifying the backend certificate

Trace Exporter Key Store

Optional setting to use a client certificate for connecting to the Opentelemetry service.

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 ([http[s]://]host:port) of the backend services to which the exporter is going to send metrics. The /v1/metrics path is automatically attached to it.

Metrics Exporter Trust Store

Optional setting for enabling trust to the Opentelemetry service.

For securing production environments:

set Metrics Exporter Address starting with https://
assign a Trust Store pattern containing the certificates required for verifying the backend certificate

Metrics Exporter Key Store

Optional setting to use a client certificate for connecting to the Opentelemetry service.

Resource Service Name

Configure the service.name key-value pair resource attribute.

Deployment Environment

Allows the configuration of the deployment.environment.name key-value pair resource attribute. The configured value will be the values of the deployment.environment.name attribute sent to the OpenTelemetry service.

Logs Mode

Choose one of:

enabled: enable the logs feature of OpenTelemetry
disabled: disable the logs feature of OpenTelemetry

Logs Exporter Address

Enter the target URL ([http[s]://]host:port) of the backend services to which the exporter is going to send the logs. The /v1/logs path is automatically attached to it.

Logs Exporter Trust Store

Optional setting for enabling trust to the OpenTelemetry service.

For securing production environments:

set Logs Exporter Address starting with https://
assign a Trust Store pattern containing the certificates required for verifying the backend certificate

Logs Exporter Key Store

Optional setting to use a client certificate for connecting to the OpenTelemetry service.

Sampler

Configure 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 behavior 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

Configure how TLS is used when connecting to the database:

disabled – Connect without TLS (no encryption).
trust – Use TLS, but skip certificate and hostname validation.
verify-ca – Use TLS with certificate validation, but without hostname verification.
verify-full – Use TLS with full validation: encryption, certificate verification, and hostname verification.

When certificate validation is enabled and the server certificate is not trusted by the component, you must configure the Trust Store setting.

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.

Min Pool Size (MariaDB)

Set the minimum connection pool size.

This configuration is ignored for PostgreSQL databases, as it is not supported by the PostgreSQL JDBC driver.

The connection pool will always attempt to maintain at least the minimum pool size.

However, the number of open connections may temporarily fall below the minimum in the following cases:

During pool initialization.
When connections are terminated due to idle timeout, maximum lifetime, network issues, or database server configuration.

Max Pool Size

Set the maximum number of available and borrowed (in use) connections that a pool maintains.

If the maximum number of connections is borrowed, no connections will be available until a connection is returned to the pool.

This setting allows the number of connections in the pool to increase as demand increases.

Max Idle Time

Sets the maximum amount of time that unused excess connections stay in the pool before it is considered stale and is removed (closed) to free up resources.

Database Management

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

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

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 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 configured Database Type.

Check the nevisProxy technical documentation for supported parameters either of the servlet class ch::nevis::nevisproxy::servlet::cache::mysql::MySQLSessionStoreServlet for the MariaDB Database Type or of the servlet class ch::nevis::nevisproxy::servlet::cache::postgresql::PostgreSQLSessionStoreServlet for the PostgreSQL Database Type

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.

Instead of using 'jdbc:mysql' either

Use the high-level configuration for the Database Host instead of providing a custom URL
Add the query parameter permitMysqlScheme to the custom URL

Placeholder Values
Access Restriction
Access Token Consumer
ActiveMQ Client Configuration
Advanced Session Upgrade
Apple Login Step
AuthState Patch
Authentication Cloud Login
Authentication Cloud Lookup
Authentication Cloud Onboarding
Authentication Done
Authentication Failed
Authentication Realm
Authorization Policy
Automatic Key Store
Automatic Trust Store
Azure Service Bus
Azure Service Bus Remote Queue
BehavioSec Risk Plugin
CSRF Protection Settings
Certbot Key Store
Cookie Customization
Credential Intelligence
Custom Input Field
Custom Risk Score Weight Configuration
Default Service
Dispatcher Button
Dispatcher Step
Email Input Field
Email TAN (eTAN)
FIDO2 Authentication
FIDO2 Management Demo
FIDO2 Onboarding
Facebook Login Step
Gateway API Rate Limit Rule
Gateway API Settings
Generic Application Settings
Generic Authentication Realm
Generic Authentication Service
Generic Authentication Step
Generic Deployment
Generic QoS Configuration (mod_qos)
Generic SMTP
Generic Social Login Step
Generic Third-Party Authentication Realm
Generic Virtual Host Settings
Generic nevisAdapt Instance Settings
Generic nevisAuth Instance Settings
Generic nevisAuth REST Service
Generic nevisAuth Web Service
Generic nevisDetect Instance Settings
Generic nevisFIDO FIDO2 Instance Settings
Generic nevisFIDO UAF Instance Settings
Generic nevisIDM Instance Settings
Generic nevisLogrend Instance Settings
Generic nevisMeta Instance Settings
Generic nevisProxy Instance Settings
Generic nevisProxy TLS Settings
Geolocation Service
Google Login Step
Groovy Script Step
HTTP Error Handling
HTTP Header Customization
Hosting Service
ICAP Scanning
In-band Mobile Authentication Realm
In-band Mobile Registration Service
JSON Response Step
JWT Access Restriction
JWT Token
Java Observability Settings
Kerberos Login
LDAP Login
Logout
Lua HTTP Processing
Maintenance Page
Microsoft Login Step
Mobile Deregistration Service
Mobile TAN (mTAN)
NGINX Ingress Settings
Nevis SecToken
OATH Authentication
OATH Onboarding
OAuth 2.0 / OpenID Connect Dynamic Client Registration Endpoint
OAuth 2.0 / OpenID Connect JWKs Endpoint
OAuth 2.0 / OpenID Connect Metadata Endpoint
OAuth 2.0 / OpenID Connect Pushed Authorization Request Endpoint
OAuth 2.0 / OpenID Connect Token Introspection Endpoint
OAuth 2.0 / OpenID Connect Token Revocation Endpoint
OAuth 2.0 / OpenID Connect User Info
OAuth 2.0 Authorization Server / OpenID Provider
Out-of-band Device Management App
Out-of-band Mobile Authentication
Out-of-band Mobile Onboarding
Out-of-band Mobile Registration Service
PEM Key Store
PEM Trust Store
Pre-Process Done
Proxy Risk Plugin
REST Service
Redirect Step
Request Validation Settings (ModSecurity)
Reset Session Step
Response Rewrite Settings
Role Check Step
Rule Bundle (ModSecurity)
SAML IDP
SAML IDP Connector
SAML Response Consumer
SAML SP Backend Integration
SAML SP Connector
SAML SP Realm
SAML Token
SAP Logon Ticket
SOAP Service
Security Response Headers
Securosys Key Store
Sendgrid SMTP
Shared Storage Settings
Simple Virtual Host
Social Login Create User
Social Login Done
Social Login Link User
Standalone Authentication Flow
Static Content Cache
Swiss eID Login Step
SwissPhone SMS
TCP Settings
Test Login
Test TAN
Throttle User Step
Token Header Propagation
Transaction Confirmation Service
Transform Variables Step
URL Handling
Unauthenticated Realm
User Decision (binary)
User Information
User Input (multiple fields)
User Input (single field)
User Notification (Adaptive Authentication)
Usernameless Out-of-band Mobile Authentication
Virtual Host
WaltID Step
Web Application
WebSocket Support for Application
gRPC Service
nevisAdapt Analyzer Configuration
nevisAdapt Authentication Connector
nevisAdapt Database
nevisAdapt Event
nevisAdapt Feedback Configuration
nevisAdapt Instance
nevisAdapt Log Settings
nevisAdapt Observation Cleanup Configuration
nevisAdapt REST API
nevisAdapt Remember Me Step
nevisAdapt Risk Calculation Step
nevisAdapt Risk Plugin
nevisAuth Audit Channel
nevisAuth Connector
nevisAuth Database
nevisAuth Domain Patch
nevisAuth Entry Patch
nevisAuth Instance
nevisAuth KeyObject
nevisAuth Log Settings
nevisAuth Radius Facade
nevisAuth Radius Response
nevisDataPorter Instance
nevisDataPorter Log Settings
nevisDetect Admin Instance
nevisDetect Administration GUI
nevisDetect Authentication Connector
nevisDetect Core Instance
nevisDetect Database
nevisDetect Feature Correlator Instance
nevisDetect Log Settings
nevisDetect Message Queue Instance
nevisDetect Persistency Instance
nevisDetect Persistency REST API
nevisFIDO FIDO2 Database
nevisFIDO FIDO2 Instance
nevisFIDO FIDO2 Log Settings
nevisFIDO FIDO2 REST Service
nevisFIDO UAF Connector
nevisFIDO UAF Database
nevisFIDO UAF Device Service
nevisFIDO UAF Instance
nevisFIDO UAF Log Settings
nevisIDM Account Recovery (deprecated)
nevisIDM Administration GUI
nevisIDM Authorizations
nevisIDM Change Password
nevisIDM Check User Credentials
nevisIDM Client
nevisIDM Client Cert Authentication
nevisIDM Connector
nevisIDM Connector for Generic Authentication
nevisIDM Custom Property
nevisIDM Database
nevisIDM Generic Batch Job
nevisIDM Instance
nevisIDM JMS Queues
nevisIDM Log Settings
nevisIDM Manage Roles
nevisIDM Password Create
nevisIDM Password Login
nevisIDM Prune History Job
nevisIDM REST Service
nevisIDM Recovery Code Authentication
nevisIDM Recovery Code Onboarding
nevisIDM SOAP Service
nevisIDM Second-Factor Onboarding
nevisIDM Second-Factor Selection
nevisIDM Terms & Conditions Acceptance
nevisIDM URL Ticket Consume
nevisIDM User Create
nevisIDM User Login Info Checker
nevisIDM User Login Info Update
nevisIDM User Lookup
nevisIDM User Update
nevisKeybox Store
nevisLogrend Application
nevisLogrend Connector
nevisLogrend Instance
nevisLogrend Log Settings
nevisMeta Connector
nevisMeta Database
nevisMeta Instance
nevisMeta Log Settings
nevisMeta REST Service
nevisMeta Web Console
nevisProxy Instance
nevisProxy Log Settings
nevisProxy Login Renderer
nevisProxy Observability Settings
nevisProxy Remote / Hybrid Session Store

Placeholder Values​

Access Restriction​

Listing Type​

Source IPs​

Source IP HTTP-Header​

Country Database File​

Country Database URL​

Rules​

Default Action​

Apply only to sub-paths​

Allow Override​

Custom GeoLocation Lookups​

Country Database Download Periodicity​

Access Token Consumer​

On Success​

On Missing Token​

OAuth 2.0 Authorization Server / OpenID Provider​

ActiveMQ Client Configuration​

Message Broker URL​

Advanced Session Upgrade​

Authentication Level​

Custom Condition​

On Entry​

Apple Login Step​

Client ID​

Client Secret​

Return Path​

Scope(s)​

Virtual Host​

On Success​

On Failure​

Private Key​

Issuer​

nevisIDM​

Client External ID​

On User Not Found​

On User Found​

Claims Request​

User ID Field​

Additional Auth Request Parameters​

Button Label​

AuthState Patch​

Authentication Realm​

Patch File​

Additional Steps​

Authentication Cloud Login​

Authentication Type​

On Success​

On User Not Exists​

On Abort​

On Failure​

Instance​

Access Key​

Access Key File​

On Skip​

Skip Element Type​

Skip Label​

Title​

Deep Link Label​

Username Prefix​

Hash Username​

Proxy Server​

Authentication Cloud Lookup​

On User Exists​

On User Not Exists​

On Failure​

Instance​

Access Key​

Access Key File​

Username Prefix​

Hash Username​

Proxy Server​

Authentication Cloud Onboarding​

On Success​

On User Exists​

On Abort​

On Failure​

Instance​

Access Key​

Access Key File​

Placeholder Values

Access Restriction

Listing Type

Source IPs

Source IP HTTP-Header

Country Database File

Country Database URL

Rules

Default Action

Apply only to sub-paths

Allow Override

Custom GeoLocation Lookups

Country Database Download Periodicity

Access Token Consumer

On Success

On Missing Token

OAuth 2.0 Authorization Server / OpenID Provider

ActiveMQ Client Configuration

Message Broker URL

Advanced Session Upgrade

Authentication Level

Custom Condition

On Entry

Apple Login Step

Client ID

Client Secret

Return Path

Scope(s)

Virtual Host

On Success

On Failure

Private Key

Issuer

nevisIDM

Client External ID

On User Not Found

On User Found

Claims Request

User ID Field

Additional Auth Request Parameters

Button Label

AuthState Patch

Authentication Realm

Patch File

Additional Steps

Authentication Cloud Login

Authentication Type

On Success

On User Not Exists

On Abort

On Failure

Instance

Access Key

Access Key File

On Skip

Skip Element Type

Skip Label

Title

Deep Link Label

Username Prefix

Hash Username

Proxy Server

Authentication Cloud Lookup

On User Exists

On User Not Exists

On Failure

Instance

Access Key

Access Key File

Username Prefix

Hash Username

Proxy Server

Authentication Cloud Onboarding

On Success

On User Exists

On Abort

On Failure

Instance

Access Key

Access Key File