Authentication

Advanced Session Upgrade

#Authentication

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.

Authentication Done

#Authentication

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

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

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:

1. the logout is invoked by a request to a protected application with query parameter ?logout.
2. nevisAuth receives a request with method logout. The default implementation simply terminates the session and returns a Gui descriptor
3. a page is shown that informs the user that the logout is done.
4. 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.

OriginalURL SecretKey

If set, the parameter OriginalUrl.Enable of the IdentityCreationFilter will be set to true and the parameter OriginalUrl.SecretKey to the configured value.

This parameter solves many issues with multiple tabs, multiple frames, and incorrect redirects after login.

Custom Parameters (IdentityCreationFilter)

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

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

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

Examples:

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

Custom Parameters (SecurityRoleFilter)

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

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

Custom Parameters (Esauth4ConnectorServlet)

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

That servlet is called Connector_<name>.

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

Examples:

Key	Value
EnablePollTerminatedCalls	true

Login Renderer

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 not overwriting 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 Login Renderer

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

Session Cookie Name

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

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

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

Session Cookie Same Site

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

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

Thus, it is recommended to select None here.

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

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

Session Cookie Same Site Relaxation (Experimental)

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

See this example bug report for Safari:

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

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

Session Cookie Validity Timeout

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

Language Cookie Name

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

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

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

Language Cookie Domain

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

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

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

Reset Authentication Condition

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

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

Authorization Policy

#Authentication

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.

AuthState Patch

#Authentication #Experimental

Patches AuthState elements generated by other patterns.

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

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

Credential Intelligence

#Authentication #Connector

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

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.

Default Service

#Applications #Experimental

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

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

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

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

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 entering a label here and providing 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.

Generic Authentication Step

#Authentication #Generic

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: "<!DOCTYPE html>"
counter: 1

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

Parameters can be used in:

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

The expression formats are:

${param.<name>}:

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

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

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

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

On Success

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

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

On Failure

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

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

Custom Follow-up Steps

Assign follow-up steps.

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

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

Entry AuthState

Define the name of the first AuthState.

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

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

Authentication Level

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

Resources

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

Key Objects

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

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

Generic nevisAuth REST Service

#Authentication

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

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 SMTP

#Authentication #Connector

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.

Groovy Script Step

#Authentication #Generic

This step generates a nevisAuth ch.nevis.esauth.auth.states.scripting.ScriptState.

The GUI descriptor cannot be customized, unless you overwrite the response template in the Groovy script.

If script execution fails HTTP error code 403 is returned, and the session will be terminated using AUTH_ERROR.

Groovy Script

Upload the Groovy script as a file.

Further information can be found in the nevisAuth Technical Documentation:

• ScriptState
• Writing scripts in Groovy

Use the expression ${service.postfix} to refer to Kubernetes services deployed by this nevisAdmin 4 project.

The expression can always be used as it produces an empty String when the deployment is not a Kubernetes side-by-side deployment.

For instance, the following snippet declares a URL which points to the REST API of a nevisIDM Instance that has been deployed as a Kubernetes service called idm:

def url = "https://idm${service.postfix}:8989/nevisidm/api"

You may use var expressions to insert values from inventory variables at generation time. For instance, use ${var.<name>} to insert a variable called <name>.

If the variable is a scalar, the value will be returned as-is. If the variable is a sequence, a Groovy list will be returned (start: [, end: ], separator: ,, String quote: ").

If your Groovy script fails to validate, see Script Validation.

Script Parameters

Set parameters for your Groovy script.

Enter the name of the parameter as Key.

The Value can be either:

1. constant String value
2. nevisAuth expression (${...:...})
3. an EL expression (#{...})
4. a reference to an inventory variable (${var.<name>}). Such expressions are resolved during generation.

Parameters can then be used inside the Groovy script via the parameters map.

Example usage:

parameters.get('backend-url')

Script Validation

Choose between:

• enabled - parse the Groovy script and run against mock objects.
• parse-only - only parse the Groovy script.
• disabled - the script is not validated.

The validation is not feature complete and thus there may false negatives.

For instance, import statements can make the validation fail as the corresponding classes are usually not on the nevisAdmin 4 classpath. This case is quite common and thus failed imports will be reported as info issues to not block deployment.

If your Groovy script produces warning or error issues but is working inside nevisAuth please select disabled and provide the script to Nevis Security so that we can improve the validation.

When set to enabled the following mock objects will be used for validation:

Map<String, String> parameters
Map<String, Object> inctx
Properties inargs
Map<String, Object> session
Properties outargs
Properties notes
Request request
Response response
Tracer LOG

On Success

Assign an authentication step which shall be executed when the Groovy script sets the result ok.

response.setResult('ok')

If no step is assigned a default state will be added.

On Failure

Assign an authentication step which shall be executed when the Groovy script sets the result error.

response.setResult('error')

If no step is assigned a default state will be added.

Custom Follow-up Step(s)

Assign follow-up steps.

For each step a transition (called ResultCond in esauth4.xml) is added. The name of the transition depends on the position in the list.

For instance, if 2 steps are assigned the following transitions will be added:

• exit.1
• exit.2

The Groovy script may trigger a certain transition by calling the method response.setResult handing over the name of the transition.

Example:

response.setResult('exit.1')

Custom Class Path

Set the classPath attribute of the AuthState element.

Lines will be joined with :. Enter 1 path per line.

When set, the classLoadStrategy attribute will be set to PARENT_LAST.

Log Category

Use a different category for logging in your Groovy script.

Response Type

Choose between:

• AUTH_ERROR: terminates the session.
• AUTH_CONTINUE: use to produce a response and continue with this state on next request.

Error Status Code

Set the status code for responses when the Response Type is set to AUTH_ERROR.

The default of 403 is backward compatible.

Note that we generally use 403 for unhandled error cases in authentication step patterns. This is to avoid exposing the information that a certain case is not properly handled.

Depending on your case, a 500 or 400 may be a more appropriate choice.

Gui Elements

Add Gui elements to the Response.

For each line 1 Gui element will be generated.

Most authentication states have only 1 Gui element.

The format is key-value pairs. The key is used as name. The value is optional and used as label.

For instance, the line auth:title.login will produce the following Gui element:

<Gui name="auth" label="title.login"/>

Configuration of GuiElem elements is not supported. You have to create them dynamically in your script.

Here is an example how to render a certain Gui and add GuiElem elements:

response.setGuiName('login')
response.addInfoGuiField('info', 'info.login', null)

JSON Response Step

#Authentication #Generic

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 Token

#Authentication #Tokens #Add-ons

Assign to a realm using Application Access Tokens to allow the realm to produce a JWT token.

To issue a JWT token and propagate it to applications you also have to assign the pattern to the corresponding Web Application, REST Service, or SOAP Service using Application Access Token.

The JWT token is sent in an HTTP header (default: Authorization) in the format Bearer <token>.

Token Type

The following types of JWT token are supported:

• JWS: JSON Web Signature - using HS256 or HS512 algorithm
• JWE: JSON Web Encryption - using RSA-OAEP-256 and A256GCM algorithm

Note: in case asymmetric encryption is used, the x5t#S256 Certificate thumbprint header parameter will automatically be added according to RFC 7515.

Token Algorithm

The following algorithms of JWT token are supported:

• HS256 or HS512: compatible with JWS token type
• RSA-OAEP-256: compatible with JWE token type

Secret

Enter a shared secret to be used for symmetric algorithms.

This is required for JWS because of the HS256 algorithm.

Signer Key Store

A Key Store is required when an asymmetric algorithm is used.

This is required for JWE because of the RSA-OAEP-256 algorithm.

Issuer

The issuer (iss) is an optional claim which may be checked by applications receiving this token.

Subject

Enter a nevisAuth expression for the claim sub. The default refers to the ID of the authenticated user.

Audience

The audience (aud) is an optional claim which may be checked by applications receiving this token.

User Attributes

Add custom claims to the JWT token.

Values can be static, nevisAuth expressions (${...}) or EL expressions (#{...}).

Examples:

Claim	Expression
email	${sess:user.email}

Key Identifier

The kid (key ID) Header Parameter is a hint indicating which key was used to secure the JWS. This parameter allows originators to explicitly signal a change of key to recipients.

When used with a JWK, the kid value is used to match a JWK kid parameter value.

For reference, please consult RFC 7515.

Header

When this pattern is assigned to an application, the JWT token will be added to all requests which are forwarded to that application.

Here you can define the name of the HTTP header which should contain the token.

Custom Properties

Set low-level properties for the JWTToken AuthState.

Kerberos Login

#Authentication

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

LDAP Login

#Authentication

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

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.

Mobile TAN (mTAN)

#Authentication

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 entering a label here and providing 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.

Nevis SecToken

#Authentication #Tokens #Add-ons

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.

You can also use this pattern as an authentication step. Assign it at the end of an authentication flow to issue the token during authentication without requiring a session upgrade (step-up).

Be aware that a token issued this way is not automatically propagated to application requests because the pattern cannot be assigned to an application. To propagate the token to the application, assign a lower-level pattern that generates the required nevisProxy filter.

For example, use the Generic Application Settings pattern with the following Filters and Mappings configuration. The token is available as token.<pattern name>, where <pattern name> is the sanitized name of this pattern.

To transfer the token as Basic Auth password, use a DelegationFilter:

<filter>
    <filter-name>Token_MySecToken</filter-name>
    <filter-class>ch::nevis::isiweb4::filter::delegation::DelegationFilter</filter-class>
    <init-param>
        <param-name>DelegateBasicAuth</param-name>
        <param-value>
            AUTH:user.auth.UserId
            AUTH:token.MySecToken
        </param-value>
    </init-param>
</filter>

To transfer the token in a custom header, use a HeaderDelegationFilter:

<filter>
    <filter-name>Token_MySecToken</filter-name>
    <filter-class>ch::nevis::isiweb4::filter::delegation::HeaderDelegationFilter</filter-class>
    <init-param>
        <param-name>DelegateToBackend</param-name>
        <param-value>X-SecToken: Basic AUTH:token.MySecToken.basic</param-value>
    </init-param>
</filter>

The token.<pattern name>.basic source contains the user ID and the token base64-encoded as a Basic Auth value. It is only available if Custom Header is set.

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.

nevisAdapt Analyzer Configuration

#User Behavior Analytics #Add-ons

Pattern to configure individual settings for the NevisAdapt analyzer.

The NevisAdapt analyzer is a powerful tool to detect and prevent fraud in your application during authentication. It uses a combination of device, fingerprint, and geo/ip analysis to detect suspicious attempts.

Disabling analyzer submodules will reduce the accuracy of the fraud detection, resulting in lower risk scores. Disabling all modules will result in the default login flow being "On Untrained User".

We discourage disabling submodules unless you have a specific use case for it.

Device Analyzer

Device Analyzer is a global setting, disabling this means that the device analyzer will not be used to calculate risk scores. This will result in a lower risk score for all users.

If you wish to disable, consider disabling all other submodules as well.

Shared Device Analyzer

Used to disable the shared device analyzer. This means that the shared device analyzer will not be used to calculate risk scores.

Device Cookie Analyzer

Used to disable Device Cookie creation.

Fingerprint Analyzer

Fingerprint Analyzer is a global setting, disabling this means that the device analyzer will not be used to calculate risk scores. This will result in a lower risk score for all users.

If you wish to disable, consider disabling all other submodules as well.

Browser-Type Fingerprint Analyzer

Used to disable Browser Finger creation and analysis.

Device-Type Fingerprint Analyzer

Used to disable Device Finger creation and analysis.

Geo/IP Analyzer

Geo/IP Analyzer is a global setting, disabling this means that the device analyzer will not be used to calculate risk scores. This will result in a lower risk score for all users.

If you wish to disable, consider disabling all other submodules as well.

Suspicious Country Analyzer

Used to disable suspicious country analysis. Use with caution.

IP Analyzer

Used to disable IpAddress analysis. If you wish to disable filtering for private address, the configuration can be found at nevisAdapt Instance / IP Geolocation.

If you wish to disable this setting also consider disabling the IP Geolocation settings as well in the nevisAdapt Instance / IP Geolocation configuration and the nevisAdapt Instance / IP Reputation configuration.

Geo Analyzer

Used to disable GeoLocation analysis. If you wish to disable this setting also consider disabling the IP Geolocation settings as well in the nevisAdapt Instance / IP Geolocation configuration and the nevisAdapt Instance / IP Reputation configuration.

nevisAdapt Authentication Connector

#User Behavior Analytics #Connector

Using the pattern, you can integrate nevisAdapt as an authentication step in nevisAuth. Depending on the risk score, a different AuthState can follow this step.

nevisAdapt

Reference for the nevisAdapt service to calculate risk scores during authentication.

On Success

Set the step to continue with on successful authentication.

On Failure

Set the step to continue with in case of error. If nothing is set, the authentication fails.

On Timeout

Set the step to continue with in case the authentication attempt runs into a timeout.

Risk Profile configuration: Setting this step is optional, but the highest available from High and Medium step will replace it.

Risk Event configuration: Setting this step is mandatory.

On Untrained User

Set the step to continue with in case the user is untrained.

Risk Profile configuration: Setting this step is optional, but the highest available from High and Medium step will replace it.

Risk Event configuration: Setting this step is mandatory.

On Medium Risk

Will be considered only if Profile is set to either balanced, strict or custom.

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

In case it remains unset:

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

On High Risk

Will be considered only if Profile is set to either balanced, strict or custom.

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

In case it remains unset:

1. On Medium Risk becomes mandatory
2. Applies the same next step as On Medium Risk

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.

Cookie Domain

If unset, the cookie will not be scoped to subdomains. Set this value to a specific domain to include more than one hostname.

Example: The user wants to login through example.com

If no value is given, the cookie will be effective for requests with the following addresses:

• https://example.com/one/two/three...

If the value is actually set as example.com, the cookie will be effective for requests against subdomains as well:

• https://shopping.example.com/one...
• https://account.example.com/two...
• https://example.com/three...

FingerprintJS version

This configuration option gives the administrator the ability to ensure backwards compatibility in case so far V2 fingerprints have been in use.

• V2 - to ensure backward compatibility, FingerprintJS V2 will be used
• V3 - default option, uses FingerprintJS V3

Pass-through Mode

The passthrough mode disables the nevisAdapt validation. All analysers are still executed and results (risks/active sessions) are persisted.

When enabled, all risks follow the On Success step. High and Medium risk actions are ignored.

This mode is useful for data gathering and troubleshooting.

Enforce Cookie Update

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 do not return the cookies to the browser.

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

nevisAdapt Feedback Configuration

#User Behavior Analytics #Add-ons

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

#User Behavior Analytics #Applications

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

Key Store

The key store used by nevisProxy when connecting to nevisAdapt. Configure an automatic key store to enable client-certificate authentication.

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.

nevisAuth Domain Patch

#Authentication #Experimental

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

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.

nevisIDM Administration GUI

#Identity Management #Applications

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.

Outbound Client Authentication

Controls whether the service access presents a client certificate on outbound TLS connections.

automatic follows the referenced target's server-side client-authentication setting. required ensures that client authentication is used, preserving an explicitly configured key store and generating an implicit identity only when no key store is configured. disabled prevents client authentication and is rejected when the referenced target requires it.

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

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.

If a new role is added here (not a default role), it should be added in Role Permissions and Role Assignment properties.

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.

If a new role is added here (not a default role), it should be added in Role Permissions and Role Management properties.

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

If a new role is added here (not a default role), it should be added in Role Management and Role Assignment properties.

User related fine-grained permissions

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

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

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

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

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

#Identity Management #Add-ons

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

#Identity Management #Authentication

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

Creates a password credential for the current user.

This pattern requires that the user has been set in the session up already.

For instance, put a nevisIDM User Lookup pattern before this step.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

On Success

Assign a step to continue with after successfully creating the password credential.

On Password Exists

If the user already has a password credential and error will occur.

You can assign a step here to handle this case.

State after creation

The state which the credential is in when created. Options:

• INITIAL
• ACTIVE
• DISABLED

Show Policy Violations

If set to enabled then after failed credential creation displays violated policies.

nevisIDM Password Login

#Identity Management #Authentication

Login to nevisIDM with username and password.

The step is intended to be used as a first factor in the Initial Authentication Flow of an Authentication Realm.

To support login using email, store the email in the Login ID field of the user.

Authentication is based on the default password policy of the selected client. See the nevisIDM Technical Documentation on how to adapt the policy.

On successful authentication, the UserId of the session is set to the Ext ID of the nevisIDM user.

For Web Application, an initial redirect (to ?login) is performed and a login GUI is shown. Technical clients calling a REST Service or SOAP Service may use basic authentication and send the credential upfront.

Double-check the URL you are calling as nevisProxy also responds with a redirect if no servlet can be found otherwise (trailingSlashRedirect).

The step also supports enforced password change, for expired passwords, and provides password reset, for users who forgot their password.

nevisIDM

Reference a nevisIDM Instance to be used for the username / password authentication.

On Success

Configure the step to execute after successful authentication.

If no step is configured here the process ends and the user will be authenticated.

Buttons

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

User Attributes

Enter user attributes to fetch from nevisIDM.

Important attributes are:

• extId - unique ID of the user in nevisIDM
• loginId - name which could be used to login (instead of email)
• firstName
• name - surname
• email
• mobile
• language - language stored for user (can differ from Accept-Language sent by the browser)

For a complete list please check the documentation of IdmGetPropertiesState.

Some attributes (e.g. extId, email, and mobile) are always fetched as they are required by standard authentication steps.

The attributes will be stored in the user session as ch.nevis.idm.User.<attribute>.

Attributes may be used in sub-sequent authentication steps or included in application access tokens (e.g. Nevis SecToken, SAML Token, or JWT Token).

For instance, use them in a Generic Authentication Step via the expression ${sess:ch.nevis.idm.User.<attribute>}.

Password Reset

Enables the password reset process.

The password reset process works as follows:

• The user has to enter his login ID or email.
• An email with a link be sent to the user.
• The user has to click the link in the mail to set a new password.

A link will be added to the login page. Users may click this link if they have forgotten their password to request a new password.

The link text can be changed on the Realm pattern by setting translations for the label pwreset.info.linktext.

Entry Path

The path prefix of the links for the password forgotten process.

Example: given a domain www.adnovum.ch and the value /pwreset/, all password forgotten steps will use the base path www.adnovum.ch/pwreset/.

URL Ticket Policy Name

Enter the name of a nevisIDM URL Ticket policy to use for the URL Ticket that is created at the beginning of the password reset process.

If nothing is configured here the default URL Ticket policy will be used.

Among others, the policy defines how the link is communicated to the user (e.g. by sending an email) and sets the expiration.

You can create additional policies via the nevisIDM Admin GUI or via SOAP / REST API.

Require Password Confirmation

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

Login Type

Define how to look up the user.

Choose between:

• LOGINID - lookup user by loginId attribute.
• EMAIL - lookup user by email attribute.
• AUTO - depending on what has been entered, nevisIDM tries to look up the user by email or loginId attribute.

We recommend using 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 Recovery Code Authentication

#Identity Management #Authentication

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

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

#Identity Management #Applications

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.

Outbound Client Authentication

Controls whether the service access presents a client certificate on outbound TLS connections.

automatic follows the referenced target's server-side client-authentication setting. required ensures that client authentication is used, preserving an explicitly configured key store and generating an implicit identity only when no key store is configured. disabled prevents client authentication and is rejected when the referenced target requires it.

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

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

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 using 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 assigning 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 SOAP Service

#Identity Management #Applications

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.

Outbound Client Authentication

Controls whether the service access presents a client certificate on outbound TLS connections.

automatic follows the referenced target's server-side client-authentication setting. required ensures that client authentication is used, preserving an explicitly configured key store and generating an implicit identity only when no key store is configured. disabled prevents client authentication and is rejected when the referenced target requires it.

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 Terms & Conditions Acceptance

#Identity Management #Authentication

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

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

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

Login ID

Define how the loginId is set:

• auto: the loginId is generated. loginIdGenerator.enabled=true must be set in the client policy. This can be achieved via the nevisIDM Administration GUI.

• email: use the email for the loginId. The email must be provided via Mandatory User Attributes.

• value: the loginId must be provided via Mandatory User Attributes.

nevisIDM User Login Info Checker

#Identity Management #Authentication

Checks if user has previously. There are possible follow-up slot for patterns if

• no previous login
• previously logged in

It checks only for successful previous login.

The pattern is experimental and may be improved in future releases. We are looking forward to your feedback and requirements.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

On User Previously Logged In

Configure the step to execute if the user has previously logged in. If no step is configured here the process ends with AUTH_DONE.

On User Never Logged In

Configure the step to execute if the user never logged in. If no step is configured here the process ends with AUTH_DONE.

nevisIDM User Login Info Update

#Identity Management #Authentication

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

Look up a user from nevisIDM by Login ID.

You can use the pattern in combination with other means to check user credentials.

For instance, use in front of Authentication Cloud for passwordless authentication.

nevisIDM

Assign a nevisIDM Instance or nevisIDM Connector.

Authentication Mode

Select interactive to prompt the user to enter a Login ID.

An input form will be shown when the query or POST parameter isiwebuserid is missing or the user is not found in nevisIDM (and On User Not Found is not set).

Select pass-through to look up the user based on Login ID Source.

In this mode no input form will be shown. Instead, a 403 response will be generated if the user is not found (and On User Not Found is not set).

Login ID Source

Enter a nevisAuth expression for the login ID which is used to look up the user.

Supported and required in authentication mode pass-through only.

Examples

• ${inargs:isiwebuserid}

On Success

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

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.

nevisLogrend Application

#Authentication #Experimental

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.

Login Template

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

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

nevisProxy Login Renderer

#Authentication #Add-ons #Experimental

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.

OATH Authentication

#Identity Management #Authentication

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.

Login Type

Sets the type of login identifier which will be used to look up the user.

In nevisIDM any client whose users should be able to log in with their email address must have the following entry in the Client policy: authentication.loginWithEmail.enabled=true

OATH Onboarding

#Identity Management #Authentication #Onboarding

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

Pre-Process Done

#Authentication

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.

Redirect Step

#Authentication

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.

Reset Session Step

#Authentication #Generic

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.

Role Check Step

#Authentication

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.

SAML SP Backend Integration

#Authentication #Add-ons #SAML #Tokens

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 Token

#Authentication #SAML #Tokens #Add-ons

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}

Sendgrid SMTP

#Authentication #Connector

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.

Standalone Authentication Flow

#Authentication

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.

SwissPhone SMS

#Authentication #Connector

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

Test Login

#Authentication #Testing

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

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

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

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.

Transform Variables Step

#Authentication #Generic

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.

User Decision (binary)

#Authentication #Experimental

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

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 translated as Login in all languages.

We recommend using 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

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

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

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