nevisadmin-plugin-nevisauth

Advanced Session Upgrade

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

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

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

This pattern defines how to authenticate access to applications.

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

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

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

Initial Authentication Flow

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

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

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

Session Upgrade Flows

Applications may be configured to trigger a session upgrade flow.

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

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

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

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

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

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

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

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

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

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

Default Session Upgrade Flow

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

Logout Flow

The default logout flow works as follows:

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

To replace this behavior, assign a logout step here.

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

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

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

Application Access Tokens

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

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

nevisAuth

Assign a nevisAuth Instance pattern.

Key Store

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

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

Automatic key management should be used for test setups only.

Trust Store

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

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

Automatic key management should be used for test setups only.

Hostname Validation

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

Internal SecToken Trust Store

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

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

Automatic key management should be used for test setups only.

Custom Parameters (IdentityCreationFilter)

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

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

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

Examples:

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

Custom Parameters (Esauth4ConnectorServlet)

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

That servlet is called Connector_<name>.

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

Examples:

Key	Value
EnablePollTerminatedCalls	true

Login Renderer

Assign a pattern which defines the login renderer.

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

Key Store

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

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

Trust Store

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

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

Hostname Validation

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

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

Login Template

Customize the rendering of login pages.

Download the default template to get started.

nevisLogrend: Simple Mode

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

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

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

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

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

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

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

nevisLogrend: Expert Mode

Expert users may upload Velocity templates and resources to nevisLogrend.

Zip files will be extracted into the nevisLogrend application:

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

Flat files will be added to the following subdirectories:

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

nevisProxy: Simple Template

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

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

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

Login Template Mode

Choose between two options:

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

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

Translations

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

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

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

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

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

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

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

The default login template uses the following labels:

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

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

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

Translations Mode

Choose between:

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

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

Default Translations

Choose between:

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

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

nevisLogrend default.properties

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

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

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

Session Tracking

Choose between:

• COOKIE: issue a session cookie.
• AUTHORIZATION_HEADER: track the session based on the value of the Authorization header.

Session Cookie Name

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

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

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

Session Cookie Same Site

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

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

Thus, it is recommended to select None here.

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

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

Session Cookie Same Site Relaxation (Experimental)

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

See this example bug report for Safari:

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

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

Session Validation

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

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

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

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

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

ENV:REMOTE_ADDR:invalidate

Initial Session Timeout

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

Authenticated Session Timeout

Define the idle timeout of an authenticated session.

Max Session Lifetime

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

Update Session Timestamp Interval

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

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

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

Language Cookie Name

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

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

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

Language Cookie Domain

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

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

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

Reset Authentication Condition

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

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

Authorization Policy

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

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

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

Required Roles

Optional setting to enforce authorization.

Callers need any of the specified roles to access.

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

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

Usage examples:

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

Forbidden Roles

Optional setting to enforce authorization.

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

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

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

Usage examples:

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

Authentication Level

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

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

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

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

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

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

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

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

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

Usage examples:

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

Apply only to sub-paths

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

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

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

The following table provides examples to illustrate the behaviour:

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

Required Roles Mode

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

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

Choose one of:

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

Forbidden Roles Mode

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

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

Choose one of:

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

Authentication Level Mode

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

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

Choose one of:

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

Custom Input Field

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

Use the variable in subsequent authentication steps.

Label

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

Variable Name

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

The following scopes are supported:

• inargs
• notes
• sess or session

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

Optional

Input into the field is optional or mandatory.

Choose between:

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

Dispatcher Button

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

Label

Enter the label which shall be used for this button.

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

On Click

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

Name

Enter a name to use for the GuiElem.

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

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

Value

Enter a value to use for the GuiElem.

Configure only when you need a different value.

Dispatcher Step

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

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

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

Label

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

Variable Name

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

The following scopes are supported:

• inargs
• notes
• sess or session

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

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)

Use to send TAN codes to users via email.

You can use this pattern for email validation or authentication.

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

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

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

On Success

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

On Failure

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

The step will be executed in the following cases:

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

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

Buttons

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

SMTP Server

The connection provider for the sending the email code.

Choose between Sendgrid SMTP and a Generic SMTP patterns.

Sender

Sender email address.

Recipient

Enter a nevisAuth or EL expression for the recipient.

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

Examples:

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

Max Retries

The maximum attempts for each code.

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

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

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

Max Regenerations

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

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

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

TAN Format

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

Testing Mode

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

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

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

Authentication Level

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

GUI Name

Change the name of the Gui element.

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

Gui Title

Change the Gui title.

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

Generic Authentication Realm

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

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

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

There are several ways to trigger a stepup:

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

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

Configuration

Upload an XML file containing AuthState elements.

Upload of a complete esauth4.xml is not supported.

The Domain element is optional.

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

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

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

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

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

The following expressions are supported:

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

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

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

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

<propertyRef name="nevisIDM_Connector"/>

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

Template Parameters

Define Template Parameters.

Examples:

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

These parameters can be used in your Configuration.

The expression formats are:

${param.<name>}:

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

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

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

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

Resources

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

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

Key Objects

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

nevisAuth

Assign a nevisAuth Instance pattern.

Key Store

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

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

Automatic key management should be used for test setups only.

Trust Store

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

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

Automatic key management should be used for test setups only.

Hostname Validation

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

Internal SecToken Trust Store

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

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

Automatic key management should be used for test setups only.

Custom Parameters (IdentityCreationFilter)

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

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

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

Examples:

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

Custom Parameters (Esauth4ConnectorServlet)

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

That servlet is called Connector_<name>.

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

Examples:

Key	Value
EnablePollTerminatedCalls	true

Login Renderer

Assign a pattern which defines the login renderer.

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

Key Store

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

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

Trust Store

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

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

Hostname Validation

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

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

Login Template

Customize the rendering of login pages.

Download the default template to get started.

nevisLogrend: Simple Mode

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

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

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

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

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

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

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

nevisLogrend: Expert Mode

Expert users may upload Velocity templates and resources to nevisLogrend.

Zip files will be extracted into the nevisLogrend application:

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

Flat files will be added to the following subdirectories:

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

nevisProxy: Simple Template

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

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

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

Login Template Mode

Choose between two options:

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

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

Translations

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

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

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

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

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

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

The default login template uses the following labels:

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

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

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

Translations Mode

Choose between:

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

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

Default Translations

Choose between:

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

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

nevisLogrend default.properties

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

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

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

Session Tracking

Choose between:

• COOKIE: issue a session cookie.
• AUTHORIZATION_HEADER: track the session based on the value of the Authorization header.

Session Cookie Name

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

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

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

Session Cookie Same Site

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

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

Thus, it is recommended to select None here.

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

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

Session Cookie Same Site Relaxation (Experimental)

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

See this example bug report for Safari:

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

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

Session Validation

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

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

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

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

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

ENV:REMOTE_ADDR:invalidate

Initial Session Timeout

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

Authenticated Session Timeout

Define the idle timeout of an authenticated session.

Max Session Lifetime

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

Update Session Timestamp Interval

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

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

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

Custom Dependencies

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

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

Generic Authentication Service

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

Requests received on this path are forwarded to nevisAuth.

Use to import an existing configuration.

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

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

Virtual Host

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

Frontend Path

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

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

Configuration

Enter AuthState elements as XML.

The Domain element is optional.

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

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

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

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

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

The following expressions are supported:

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

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

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

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

<propertyRef name="nevisIDM_Connector"/>

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

Template Parameters

Define Template Parameters.

Examples:

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

These parameters can be used in your Configuration.

The expression formats are:

${param.<name>}:

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

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

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

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

Resources

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

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

Key Objects

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

nevisAuth

Assign a nevisAuth Instance pattern.

Key Store

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

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

Automatic key management should be used for test setups only.

Trust Store

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

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

Automatic key management should be used for test setups only.

Hostname Validation

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

Internal SecToken Trust Store

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

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

Automatic key management should be used for test setups only.

Custom Parameters (IdentityCreationFilter)

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

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

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

Examples:

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

Custom Parameters (Esauth4ConnectorServlet)

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

That servlet is called Connector_<name>.

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

Examples:

Key	Value
EnablePollTerminatedCalls	true

Login Renderer

Assign a pattern which defines the login renderer.

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

Key Store

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

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

Trust Store

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

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

Hostname Validation

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

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

Login Template

Customize the rendering of login pages.

Download the default template to get started.

nevisLogrend: Simple Mode

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

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

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

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

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

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

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

nevisLogrend: Expert Mode

Expert users may upload Velocity templates and resources to nevisLogrend.

Zip files will be extracted into the nevisLogrend application:

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

Flat files will be added to the following subdirectories:

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

nevisProxy: Simple Template

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

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

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

Login Template Mode

Choose between two options:

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

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

Translations

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

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

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

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

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

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

The default login template uses the following labels:

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

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

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

Translations Mode

Choose between:

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

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

Default Translations

Choose between:

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

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

nevisLogrend default.properties

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

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

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

Session Tracking

Choose between:

• COOKIE: issue a session cookie.
• AUTHORIZATION_HEADER: track the session based on the value of the Authorization header.

Session Cookie Name

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

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

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

Session Cookie Same Site

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

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

Thus, it is recommended to select None here.

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

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

Session Cookie Same Site Relaxation (Experimental)

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

See this example bug report for Safari:

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

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

Session Validation

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

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

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

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

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

ENV:REMOTE_ADDR:invalidate

Initial Session Timeout

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

Authenticated Session Timeout

Define the idle timeout of an authenticated session.

Max Session Lifetime

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

Update Session Timestamp Interval

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

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

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

Custom Dependencies

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

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

Frontend Path Settings

Assign add-on patterns to customize the Frontend Path.

Generic Authentication Step

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

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

Configuration

Upload an XML file containing AuthState elements.

Example to illustrate the syntax:

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

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

The following expressions may be used:

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

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

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

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

<propertyRef name="nevisIDM_Connector"/>

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

Template Parameters

Define Template Parameters.

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

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

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

Parameters can be used in:

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

The expression formats are:

${param.<name>}:

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

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

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

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

On Success

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

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

On Failure

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

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

Custom Follow-up Steps

Assign follow-up steps.

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

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

Entry AuthState

Define the name of the first AuthState.

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

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

Authentication Level

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

Resources

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

Key Objects

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

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

Generic SMTP

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

SMTP Protocol

Select the protocol of the SMTP server.

SMTPS is usually mentioned as the TLS secured SMTP protocol.

SMTP Server

Enter host:port of the SMTP server.

SMTP User

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

SMTP Password

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

Generic Third-Party Authentication Realm

Assign the pattern to applications as Authentication Realm to enforce authentication using a third-party authentication service.

Integration of a third-party authentication service usually consists of several steps:

• Configure an Authentication Filter which is mapped to applications to enforce authentication. The filter is expected to either trigger a redirect to a different path or perform a side-call.
• Provide a template for the Roles Filter. The template is used to generate a filter in case an Authorization Policy is assigned to an application.

Limitations of the pattern:

• No support for session upgrades. In combination with nevisAuth you can demand a minimum Authentication Level for an application. If the session is not yet at the desired level then a session upgrade is performed.
• No automatic support for sharing cookies between applications and the authentication service. However, you can configure this manually by configuring an Authentication Application and assigning a Cookie Customization pattern to Protected Application Settings and Authentication Application Settings.

Authentication Filter

Define the filter that shall be application to applications to enforce authentication.

The following variables may be used:

• ${realm.id} - unique ID of this realm pattern
• ${realm.name} - name of this realm pattern
• ${auth.servlet} - name of the servlet of the Authentication Application. May be used to perform a side-call.

Roles Filter

Define the filter that shall be application to applications to enforce the presence of certain roles.

The following expressions may be used:

• ${realm.id} - unique ID of this realm pattern
• ${realm.name} - name of this realm pattern
• ${auth.servlet} - name of the servlet of the Authentication Application. May be used to perform a side-call.
• ${filter.name} - a proposed filter name calculated from the required roles
• *{roles} - duplicates the entire line once for each role

Protected Application Settings

Assign add-on patterns to customize the behaviour of applications protected by this realm.

A common case for redirect-based authentication is to assign a Cookie Customization here and to Authentication Application Settings to share cookies between applications and the authentication application.

Authentication Application

Optionally assign an application which provides the authentication service and shall be exposed on the same virtual host as the applications.

Not required for federation-based authentication where the authentication service is hosted on another domain.

Additional Settings

Assign add-on patterns to customize the behaviour of the Authentication Application.

Assigning these add-ons here may be more appropriate to have the complete authentication logic concentrated here.

Session Tracking

Choose between:

• COOKIE: issue a session cookie.
• AUTHORIZATION_HEADER: track the session based on the value of the Authorization header.

Session Cookie Name

By default, the session cookie will be called Session_<pattern-name>

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

If the same name is configured for multiple realms on the same host then the sessions will be cleaned up together when the first session expires.

Session Cookie Same Site

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

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

Thus, it is recommended to select None here.

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

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

Session Cookie Same Site Relaxation (Experimental)

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

See this example bug report for Safari:

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

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

Session Validation

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

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

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

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

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

ENV:REMOTE_ADDR:invalidate

Initial Session Timeout

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

Authenticated Session Timeout

Defines the idle timeout of a nevisProxy session.

A nevisProxy session will be created only if required (e.g. to store application cookies).

Please set the timeout as low as possible to not increase the risk of session exhaustion attacks.

Max Session Lifetime

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

Update Session Timestamp Interval

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

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

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

Generic nevisAuth Instance Settings

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

Java Opts

Add additional entries to the JAVA_OPTS environment variable.

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

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

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

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

Environment Variables

Add additional environment variables to the nevisAuth env.conf.

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

Generic nevisAuth REST Service

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

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 nevisLogrend Instance Settings

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

Java Opts

Add additional entries to the JAVA_OPTS environment variable.

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

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

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

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

Groovy Script Step

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

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. When the next request comes in, the On Continue exit will be taken.

Use AUTH_DONE to complete the current flow and establish an authenticated session. The request will continue in the filter chain in nevisProxy, towards a backend application.

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

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

The Kerberos Login configures Kerberos authentication based on the simple and protected GSS-API negotiation mechanism (SPNEGO) for nevisAuth.

Kerberos Realms

Enter the allowed Kerberos realms (AD domains).

Example:

• SIVEN.CH

In case multiple values have to be configured you can define which Keytab File or Keytab File Path
to use by referencing its file name.

Example:

• SIVEN.CH -> kerberos_ch.keytab
• SIVEN.DE -> kerberos_de.keytab

Frontend Addresses

Enter the Frontend Addresses of the nevisProxy Virtual Host patterns for which this pattern provides authentication.

Example:

• www.siven.ch

In case multiple values are configured you can define which Keytab File or Keytab File Path to use by referencing its file name.

Example:

• www.siven.ch -> kerberos_ch.keytab
• www.siven.de -> kerberos_de.keytab

Keytab File Path

Enter the path of the Kerberos keytab file.

The path must exist on the target host(s) of the nevisAuth Instance.

This configuration is ignored when keytab file(s) are uploaded via Keytab File.

In complex setups with multiple Kerberos Realms and/or Frontend Addresses you may want to enter multiple keytab file paths.

Keytab File

Upload the Kerberos keytab file.

nevisAuth uses this file to validate Kerberos tokens sent by browsers.

Please check the nevisAuth Technical Documentation on how to create the keytab file.

The keytab file will be deployed to the conf directory of the nevisAuth instance.

For a more secure and environment-specific configuration you have the following alternatives:

• create a variable and upload the keytab file in the inventory
• set Keytab File Path instead of uploading the file and deploy the file by other means

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

Authentication Level

Authentication level that is set on success.

Limit Session Lifetime

If set to true then the lifetime of the underlying Kerberos service ticket used by the client during the SPNEGO negotiation will be considered when determining the lifetime of Nevis session. In this case the expiration time of Nevis session cannot be longer than the expiration time of the Kerberos service ticket.

Default is false.

On Success

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

On Failure

Assign authentication step that is processed if Kerberos authentication fails.

If no step is assigned an AuthState Authentication_Failed will be created automatically.

Kerberos Login (Deprecated)

The Kerberos Login configures Kerberos authentication based on the simple and protected GSS-API negotiation mechanism (SPNEGO) for nevisAuth.

Kerberos Realms

Enter the allowed Kerberos realms (AD domains).

Example:

• SIVEN.CH

In case multiple values have to be configured you can define which Keytab File or Keytab File Path
to use by referencing its file name.

Example:

• SIVEN.CH -> kerberos_ch.keytab
• SIVEN.DE -> kerberos_de.keytab

Frontend Addresses

Enter the Frontend Addresses of the nevisProxy Virtual Host patterns for which this pattern provides authentication.

Example:

• www.siven.ch

In case multiple values are configured you can define which Keytab File or Keytab File Path to use by referencing its file name.

Example:

• www.siven.ch -> kerberos_ch.keytab
• www.siven.de -> kerberos_de.keytab

Keytab File Path

Enter the path of the Kerberos keytab file.

The path must exist on the target host(s) of the nevisAuth Instance.

This configuration is ignored when keytab file(s) are uploaded via Keytab File.

In complex setups with multiple Kerberos Realms and/or Frontend Addresses you may want to enter multiple keytab file paths.

Keytab File

Upload the Kerberos keytab file.

nevisAuth uses this file to validate Kerberos tokens sent by browsers.

Please check the nevisAuth Technical Documentation on how to create the keytab file.

The keytab file will be deployed to the conf directory of the nevisAuth instance.

For a more secure and environment-specific configuration you have the following alternatives:

• create a variable and upload the keytab file in the inventory
• set Keytab File Path instead of uploading the file and deploy the file by other means

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

Authentication Level

Authentication level that is set on success.

On Success

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

On Failure

Assign authentication step that is processed if Kerberos authentication fails.

If no step is assigned an AuthState Authentication_Failed will be created automatically.

LDAP Login

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

A logout can be triggered by sending a request with query parameter logout to a protected location. For example: /my-app/?logout

The default flow renders a GUI with a message and a submit button. On submit the user is redirected to the same URL with the query parameter logout removed. This leads to re-authentication. The logout flow cannot be aborted.

Note that in Chrome the logout GUI may NOT be shown because some versions sends multiple GET requests.

Use this pattern to customize the logout flow by showing a different message or redirecting to a different URL (in this case the GUI will not be shown).

Note that if the application is protected by a SAML SP Realm the logout process is managed by the IDP. Thus, the pattern is to be assigned to the realm of the IDP instead.

Logout Behaviour

• gui - shows a logout GUI. On submit the user is redirected to the same URL with the query parameter logout removed.
• redirect - does not show a GUI. The user is immediately redirected to the given URL or path.

Custom Label

Enter a label for the message that shall be presented to the user. This is used when Logout Behaviour is set to gui.

Redirect

Enter a URL or path to redirect to after logout.

Mobile TAN (mTAN)

Use to send a TAN code to the user using SMS, for example, for second factor authentication.

The pattern works out-of-the-box as On Success for nevisIDM Password Login, in case the mobile is stored on the user.

In case users may have multiple mobiles and the mobile is stored in a mobile credential, add the nevisIDM Second Factor Selection in front of this step.

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

On Success

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

On Failure

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

The step will be executed in the following cases:

• there is no session variable (user.mobile or sess:ch.nevis.idm.User.mobile) which contains the mobile number of the user
• the mobile number cannot be converted into a format supported by the Connection Provider
• all attempts had been exhausted and the user has failed to authenticate

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

Buttons

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

SMS Provider

The connection provider for the TAN transmission. Currently the only supported connection provider is a SwissPhone SMS Gateway.

Max Retries

The maximum attempts for each code.

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

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

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

Max Regenerations

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

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

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

TAN Format

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

Testing Mode

Enables "Testing Mode". The TAN challenge is AAAAA.

When testing mode is enabled, the TAN challenge is constant and might not be sent over the linked connection.

Each connection pattern decides individually how it behaves with respect to "Testing Mode".

For instance, the SwissPhone Connection does not sent a message to the gateway when "Testing Mode" is enabled.

Authentication Level

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

GUI Name

Change the name of the Gui element.

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

Gui Title

Change the Gui title.

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

NEVIS SecToken

Assign to a realm using Application Access Tokens. This enables the realm to produce a Nevis SecToken.

To issue a SecToken and propagate it to applications also assign the pattern to the corresponding Web Application, REST Application, or SOAP Application using Additional Settings.

On the application server you may use Ninja to extract the SecToken from the Authorization header. It is transferred as the Basic Auth password.

As Ninja validates the signature of the SecToken, you have import the signer certificate into the Ninja truststore.

User Attributes

Set the content of the NEVIS SecToken.

Example:

Attribute	Variable
userid	request:UserId
loginId	session:ch.nevis.session.loginid
profileId	session:ch.adnovum.nevisidm.profileId
clientId	session:ch.adnovum.nevisidm.clientId
roles	request:ActualRoles

Supported variable scopes are:

• session - a session variable.
• request - a variable from the request.
• const - a fixed value.

This configuration should work for most backend applications, including NEVIS components.

The userid is required by Ninja and must always be set. You can use ch.nevis.session.loginid when this pattern is not part of the Initial Authentication Flow.

The loginId, profileId, clientId are required by nevisIDM.

The attribute roles is required by nevisWF and nevisMeta.

For some attributes there are multiple variables to choose from. Check the nevisAuth log with log levels of Vars set to INFO to find out which variables are available in your case.

Signer Key Store

Assign a pattern which sets the key material used for signing the token.

If no pattern is assigned automatic key management is used and the signer key will be created automatically.

Custom Header

Set a custom header instead of the default Authorization header.

Pre-Process Done

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.

Role Check Step

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 IDP

Sets up a SAML Identity Provider (IDP).

The Authentication Realm provides Single-Sign-On.

By default, only SP-initiated authentication is allowed. This method is most secure and standard.

Service providers (SP) may initiate authentication by sending an AuthnRequest to any of the configured Frontend Path(s).

You can enable IDP-initiated authentication via the Authentication Type drop-down.

SAML Issuer

Configure the Issuer used by this IDP.

The issuer can be an arbitrary String but it is a common practise to use the URL of the IDP.

Example: https://idp.example.org/SAML2/

Virtual Host

Assign a Virtual Host which shall serve as entry point.

Frontend Path(s)

Define paths for the following cases.

• SP-initiated authentication

Service providers may send a parameter SAMLRequest containing an AuthnRequest (using POST or redirect binding) to request authentication. On successful authentication the IDP returns a SAML Response.

On entry an initial session will be created. The session may expire during authentication due to timeout.

When this happens an error page (name: saml_dispatcher) with title title.saml.failed and error message error.saml.failed will be rendered.

• SP-initiated logout

Service providers may send a LogoutRequest (POST or redirect binding) to logout from this IDP and other service providers.

• IDP-initiated logout

Applications may have a link pointing to the IDP to trigger a global logout.

This link may point to:

• <path>/logout: to show a logout confirmation page (GUI name: saml_logout_confirm, label: info.logout.confirmation)
• <path>/?logout: to skip the logout confirmation page.

If a Referer header has been sent by the browser, the logout confirmation page will have a cancel button which redirects to the referer. Note that if the SP is NEVIS you may have to adapt the Security Response Headers of the Virtual Host. By default, the header Referrer-Policy: strict-origin-when-cross-origin is set and this will prevent the path being sent so the cancel button will redirect to /.

During SAML logout the IDP renders a GUI named saml_logout with the following hidden fields:

• saml.logoutURLs: the URL of the SPs including LogoutRequest message as query parameter
• saml.logoutURL: the URL to redirect to after successful logout

The default nevisLogrend template contains Javascript to invoke all saml.logoutURLs and redirect to saml.logoutURL after all requests have been sent. This is a best effort operation which means that the JavaScript does not check if the logout was successful.

• IDP-initiated authentication

Requests to the base path without SAMLRequest will trigger IDP-initiated authentication.

In this case the following parameters must be sent:

• Issuer: as entered for a SAML SP Connector
• RelayState: this parameter is returned to the SAML SP together with the Response

Authentication Realm

Optionally assign a realm to protect this application or service.

Service Providers

Define the SAML Service Providers which can use this IDP.

For each SP an own AuthState of class IdentityProviderState will be generated.

SAML Signer

Configure the key used by this Identity Provider to sign outgoing SAML Assertions.

Metadata Service

When enabled a SAML Metadata Service will be generated which can be accessed on the Metadata Service Path.

The SAML Metadata Service is not protected by authentication.

Metadata Service Path

Enter a path where the SAML Metadata Service shall be exposed on the assigned Virtual Host.

Authentication Type

Select which authentication types are allowed:

• SP-initiated: recommended
• IDP-initiated: less secure as no AuthnRequest is sent.

Dispatch Error Redirect

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

There are 3 cases:

• a session is required for the current operation (e.g. logout, session upgrade) but no session was found.
• the authentication type (SP-initiated or IDP-initiated) is not allowed.
• not enough information for IDP-initiated authentication (e.g. missing query parameters).

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

Logout Confirmation

Choose between:

• enabled - shows a logout confirmation screen when the path ends with /logout
• disabled - never shows a logout confirmation screen

Please be aware that we plan further changes which affect SAML logout and thus this setting may change or even disappear in a future release.

Custom Pre-Processing

An an authentication step to execute before dispatching according to the issuer.

SAML IDP Connector

The pattern represents the connection to a SAML IDP.

You can use the pattern in:

• SAML SP Realm
• SAML Response Consumer

IDP Issuer

Enter the Issuer of the IDP.

Example: https://idp.example.org/SAML2

The Issuer is used to look up the trust store containing the signer certificate of the IDP.

For this purpose a KeyObject element will be configured in the nevisAuth esauth4.xml using the Issuer for the attribute id.

IDP URL

Enter the Location of the SAML SingleSignOnService. This may be a URL or a path on the same virtual host.

nevisAuth will send an AuthnRequest to this location to delegate the authentication or session upgrade process to the IDP.

By default, the AuthnRequest contains a RequestedAuthnContext which specifies the required authentication level. You can disable this feature via Custom Properties.

Message Decryption Key Store

Assign a pattern to configure the private key to decrypt the incoming message of the identity provider.

Binding: Outbound

Configure the outgoing binding. This affects how the SAML AuthnRequest is sent to the IDP.

Signature Validation

Configure for which SAML elements signature validation shall be performed.

It is recommended that the IDP signs the entire Response as this is the most secure mode.

If only the Assertion is signed nevisAuth will perform additional checks to prevent attack scenarios.

IDP Signer Trust Store

Assign a pattern to configure the signer certificate of the identity provider.

Attribute Extraction

Configure to extract attributes from SAML assertions and store them in a session variable.

Examples:

Session Variable	Attribute
sess:user.email	email
sess:user.mobile	mobile

Audience Check

Define how to validate the optional Audience element of received SAML assertions.

• disabled - Audience is not checked
• lax - if present the Audience has to match the Allowed Audience
• strict - the Audience element must be present and must match the Allowed Audience

Allowed Audience

Enter a regular expression to validate the Audience of a received SAML Assertion.

Allowed Lifetime

SAML assertions have an issue timestamp. nevisAuth validates the timestamps of SAML assertions received from the IDP.

Some identity providers create the SAML assertion on login and return the same assertion as long as the session is active on the identity provider.

In this case enter a duration which is at least as long as the maximum session lifetime on the identity provider.

For identity providers which always return a new assertion (e.g. nevisAuth) the value can be very low (e.g. 30s)

Enter unlimited to disable the maximum lifetime check for received SAML Responses. This sets in.max_age to -1 in the generated ServiceProviderState.

Selection Expression

The expression configured here will be used by nevisAuth to determine the IDP for SP-initiated SAML flows.

Configuration is required there are multiple SAML IDP Connector patterns assigned to the same SAML SP Realm.

For IDP-initiated flows the expression is not relevant as the IDP can usually be determined based on the Issuer contained in received SAML messages.

You may enter nevisAuth or EL expressions.

You must ensure that there is always exactly 1 expression which evaluates to true

If there is no match or multiple IDPs are applicable then 403 Forbidden is returned.

Examples:

• IP of the user starts with 10.0.106: ${request:clientAddress:^10.0.106}
• Request path starts with /myapp: ${request:currentResource:(http.?.//[^/]+)/myapp.*}

Artifact Resolution Service

Configure to enable HTTP Artifact Binding.

Enter the Location of the ArtifactResolutionService. This information can usually be found in the SAML metadata provided by the IDP.

The location must be a valid URL. In case of https:// import the CA certificate of the endpoint into the backend truststore of nevisAuth.

When a SAML artifact is returned by the IDP the service provider will send a request to the artifact resolution service to retrieve the SAML assertion.

Authentication Request: Lifetime

SAML authentication requests have a maximum lifetime which may be validated by the identity provider.

The lifetime should be low but high enough so that the authentication works on slow network connections.

Custom Properties

Enter custom properties for the nevisAuth ServiceProviderState.

Example: overwrite authnContextClassRef in the AuthnRequest

out.authnContextClassRef = urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified

Example: remove authnContextClassRef from AuthnRequest

out.authnContextClassRef =

Logout Type

Setting for SP-initiated logout, logout methods can be chosen:

• IMPLIED: the logout method will be used by getting configuration of Binding: Outbound
• POST: force logout method to POST
• SOAP: force logout method to SOAP. This only work when IdP SAML Response contain SessionIndex.

Custom Transitions

Add or overwrite ResultCond elements in the ServiceProviderState state.

This setting is advanced. Use without proper know-how may lead to incorrect behavior.

If you use this setting, we recommend that you contact Nevis to discuss your use case.

The position refers to the list of Additional Follow-up Steps. The position starts at 1.

Examples:

ResultCond	Position
status-Responder	1
status-Responder-AuthnFailed	2

The following ResultCond elements cannot be overruled by this setting:

• ok
• logout
• logoutCompleted
• logoutFailed

Custom Follow-up Steps

Assign follow-up steps.

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

You may reference a step in the configuration via the Custom Transitions.

SAML Response Consumer

The pattern exposes an authentication service on the assigned Virtual Host.

The service can consume incoming SAML Response or SAML artifact messages, and can execute an optional post-processing flow.

The overall process may work as follows:

• Consume a SAML Response and RelayState on the Frontend Path. The RelayState must contain the URL of an application.
• If configured, execute the Post-Processing Flow.
• The authentication is now done.
• Redirect to the RelayState parameter pointing to the application.
• Assuming the application is protected by the realm assigned to this pattern, the caller is allowed access.

Frontend Paths

Enter a path where SAML Response messages sent by an external IDP shall be consumed.

The external IDP may send messages using POST or redirect binding.

SAML IDP Connector(s)

Assign a SAML IDP Connector for each SAML Identity Provider.

SP-initiated authentication is not supported and thus the Selection Expression of the connector patterns is ignored.

SAML Signer

Configure the key material for signing outbound SAML messages.

The following messages will be signed: ArtifactResolve, LogoutRequest, LogoutResponse

SAML Artifact Binding

To use SAML Artifact Binding with a certain IDP, the Artifact Resolution Service must be configured in the SAML IDP Connector.

The flow begins with the IDP sending an ArtifactResponse message to any of the configured frontend paths.

Now an ArtifactResolve message will be created and signed using this certificate. The message will then be sent to the IDP via a server-to-server call.

Authentication Processing Flow

Assign a step to apply custom post-processing logic, e.g. to enrich the authenticated user.

Virtual Host

Assign a Virtual Host which shall serve as entry point.

Authentication Realm

Optionally assign a realm to protect this application or service.

SAML Issuer

Configure the Issuer used by this SAML Service Provider (SP).

This setting is used only when Artifact Binding is used.

Example: https://sp.example.org/SAML2

Logout Processing Flow (Experimental)

Assign a step to apply custom post-processing logic which is executed when a LogoutRequest or LogoutResponse message is received.

SAML SP Backend Integration

Assign to applications using Additional Settings to send a SAML Response to an SP deployed on the backend application server.

The assigned SAML Token has to have Token Type set to Response.

SAML Token

Assign a SAML Token pattern.

The referred pattern must:

• have Token Type set to Response
• be assigned to the correct Realm pattern(s)

Assertion Consumer Service Path

Enter a sub-path of the application to sent the POST request to.

The POST request is sent by a DelegationFilter mapped in phase AFTER_AUTHORIZATION.

RelayState

Enter a static value, or a nevisProxy expression, which defines the value of the POST parameter RelayState that shall be sent to the SP together with the SAML Response.

Whether a RelayState is required depends on the SP. Many SPs expect a URL and will redirect to this URL once the SAML Response has been successfully validated.

Custom Parameters

Define custom init-params for the nevisProxy DelegationFilter which propagates the SAML Response to the backend.

This setting is experimental and may be adapted in future releases.

Examples:

• DelegatePostPolicy: override - create a new POST request and send it to the Assertion Consumer Service Path. The response is returned to the client which means that the original (GET) request is lost. However, the SP can redirect to the application. This mode should be preferred for proper SP integration.

• DelegatePostPolicy: sidecall - send a POST request to the Assertion Consumer Service Path but do not return the response to the client. Afterwards, the original (GET) request is sent. This mode may be required in case the response of the POST request does not redirect to the application.

SAML SP Connector

The pattern defines the connection to a SAML Service Provider (SP).

Assign the pattern to a SAML IDP.

SP Issuer

Configure the issuer used by the SAML service provider.

SP URL - Assertion Consumer Service(s)

Enter the Assertion Consumer Service URL of the SP.

Enter multiple values if the same SP can be accessed via multiple URLs.

If the SP is provided by a SAML SP Realm the URLs are structured as follows:

• scheme, host and port: Frontend Addresses of each Virtual Host where the SAML SP Realm is used.
• path component: Assertion Consumer Service of the SAML SP Realm.

The URLs are used during SP-initiated SAML authentication to validate incoming SAML requests. The assertionConsumerServiceURL attribute of received SAML AuthnRequest messages must match one of these URLs.

The first URL is also used for IDP-initiated authentication (property spURL of the IdentityProviderState).

IDP-initiated authentication may be triggered by sending a request to any of the Frontend Path(s) of the SAML IDP. The following parameters must be provided either in the query or as POST parameters:

• Issuer - the unique name used by the SP (also called entityID in the SAML metadata).
• RelayState - will be sent back to the SP together with the SAML Response when authentication is done. In case the SP is setup by a SAML SP Realm this should a URL of an application protected by this realm.

SP URL - Single Logout Service

Enter the Single Logout Service URL of the SP.

If omitted the Assertion Consumer Service URL is used.

SP Signer Trust Store

Configure the trust store used to validate incoming SAML messages (e.g. AuthnRequest, LogoutRequest) which are sent by this SP.

Encrypted Content

Select a part of the outgoing message going to be encrypted from the service provider.

Message Encryption Trust Store

Assign a pattern to configure the certificate to encrypt the outgoing message to the service provider.

Outbound Binding

The Outbound Binding controls how SAML messages are returned to the service provider.

Choose a binding which is supported by the service provider.

Use http-redirect when the SAML Response has to be returned using a 302 Redirect.

Use http-post to generate a self-submitting form which produces a POST request. This binding is recommended as SAML Response messages will include a signature.

When http-post is selected, HTML encoding will be applied to the RelayState parameter to include it in the self-submitting form. This ensures that the parameter can be returned to the service provider, even when it contains special characters.

Subject

Set to use a different subject for the SAML Assertion.

Examples:

• ${sess:ch.nevis.session.loginid} - what the user has entered to login

Subject NameID Format

Set the format of the NameID element.

Examples:

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Subject Confirmation

Many SAML service providers require a subject confirmation element to be present in the SAML assertion.

Select bearer to add a bearer subject confirmation.

Further options may be provided in future releases.

It may be required to set additional properties. Consult the documentation of the nevisAuth IdentityProviderState and apply them via Custom Properties.

User Attributes

Add attributes to SAML assertions.

Values may be static, produced by a nevisAuth expression (${...}), or an EL expressions (#{...}). This table shows how to enter the configuration:

Attribute	Value
some_attribute	${...}
some_attribute	#{...}
some_attribute	some_value

Set the log level Vars = DEBUG and check the nevisAuth esauth4sv.log to find out which variables may are available.

For instance, if you have a nevisIDM Second-Factor Selection pattern in your authentication flow, you can use the expression ${sess:user.mobile} to add a mobile attribute.

Multi Value

This setting defines how multi-value attributes are added to the SAML Assertion.

Example for enabled:

<saml2:Attribute Name="example">
  <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">value 1</saml2:AttributeValue>
  <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">value 2</saml2:AttributeValue>
</saml2:Attribute>

Example for disabled:

<saml2:Attribute Name="example">
  <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">value 1,value 2</saml2:AttributeValue>
</saml2:Attribute>

Authentication Context Class

Select nevis if the SAML service provider is provided by a SAML SP Realm and you want to use Authorization Policy to specify the required Authentication Level for application protected by that realm.

When nevis is selected the roles and attained authentication level are added to the SAML Response via an AuthnContextClassRef element.

Example:

<saml2:AuthnStatement AuthnInstant="2021-05-07T06:48:14.967Z">
  <saml2:AuthnContext>
    <saml2:AuthnContextClassRef>...,nevisIdm.Admin,urn:nevis:level:1</saml2:AuthnContextClassRef>
  </saml2:AuthnContext>
</saml2:AuthnStatement>

Select PasswordProtectedTransport to add the following standard context:

<saml2:AuthnStatement AuthnInstant="2021-05-07T06:48:14.967Z">
  <saml2:AuthnContext>
    <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
  </saml2:AuthnContext>
</saml2:AuthnStatement>

Select none to not add any AuthnContext element.

Audience Restriction

Configure if an <AudienceRestriction> element shall be added to generated SAML assertions and what the element shall contain.

Choose between:

• automatic: use Custom Audience, if configured, and SP Issuer otherwise.
• issuer: use SP Issuer.
• custom: use Custom Audience.
• none: no <AudienceRestriction> element is added.

Custom Audience

Set custom audience(s).

If you need multiple <Audience> elements in the generated <AudienceRestriction>, enter multiple lines.

This configuration is ignored when Audience Restriction is set to issuer or none.

Check the documentation of the service provider on what is expected.

Assertion Lifetime

On successful authentication this IDP will issue a SAML assertion.

The SAML assertion is re-created on each session upgrade to avoid replay attacks.

The lifetime of the assertion should be low but high enough so that the authentication works on slow network connections.

The SAML assertion will be consumed by the service provider. The service provider should then use a different mechanism to track the user session (e.g. a session cookie).

Signed Element

Configure what to sign.

The setting none is not recommended for productive setups as it is vulnerable to attacks.

The setting Assertion may require additional checks on service provider side to close the attack vector. For instance, count the number of Assertion elements in the message.

When recommended is selected the signed element depends on the Outbound Binding:

• http-redirect: nothing will be signed as signing is not supported.
• http-post: the Response is signed as this is most secure.

Signature KeyInfo

The KeyInfo embedded into the signature informs the service provider about the signer credential used.

Enter one or several of the following elements:

• SKI
• Certificate
• CertificateChain
• Subject
• IssuerSerial
• CRLs
• SubjectDNAsKeyName
• SubjectCNAsKeyName
• KeyNames
• EntityID
• PublicKey

Note that only configured fields defined in the signer certificate are actually added to the KeyInfo structure.

Minimum Required Authentication Level

Enforce a minimum required authentication level for this Service Provider.

If not set, the minimum required authentication level will depend on the incoming AuthnRequest. An SP may specify the level by including a RequestedAuthnContext, such as:

<samlp:RequestedAuthnContext Comparison="minimum">
  <saml:AuthnContextClassRef>urn:nevis:level:2</saml:AuthnContextClassRef>
</samlp:RequestedAuthnContext>

If there is any requirement for a minimum authentication level, the Authentication Realm must provide a Session Upgrade Flow for that level. See the help of the Authentication Realm pattern for details.

Note that when there is no authenticated session, the Initial Authentication Flow of the Authentication Realm will be executed first.

After successfully completing the Initial Authentication Flow the attained authentication level is compared against the minimum level and, if required, a Session Upgrade Flow is executed.

Required Roles

Check for required roles.

Roles provided by nevisIDM have the following format: <applicationName>.<roleName>. Roles provided by other systems (e.g. LDAP) may have a different format.

Examples:

myApp.Admin

Required roles are always checked at the end of authentication, after enforcing the Minimum Required Authentication Level (optional).

The user must have any of the enter roles to continue.

If the user does not have any of these roles, the authentication will fail and a SAML Response with status AuthnFailed message will be returned to the SP.

If you want to do custom error handling (e.g. show a GUI to the user), assign a step to On Forbidden.

On Forbidden

Configure a step that shall be executed when the Required Roles check fails.

Logout Mode

Configure the logout mode when a logout is initiated by or for this SP. Choose between:

• ConcurrentLogout-Redirect: IdP will send logout to all SP(s) at once.
• SingleLogout: IdP will send logout to 1 SP at a time.
• SingleLogout-SOAP: IdP will send SOAP logout to SP(s) one by one using SOAP method.

Session Index

Set current session ID to SAML Response in SessionIndex element. This element is required for IDP-initiated logout and SP-initiated logout when Logout Type is set to SOAP.

The element will be included in SAML Response like:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response Destination=... >
    ...
    <saml2:Assertion ID=...>
        ...
        <saml2:AuthnStatement SessionIndex="JeBKZSJah-0m2QjC4LJ8u74LUOY2ayAeenlPgBOx1N8" ... >
            ...
        </saml2:AuthnStatement>
    </saml2:Assertion>
</saml2p:Response>

And in SAML LogoutRequest, the SessionIndex element will be included like:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:LogoutRequest Destination=...>
    ...
    <saml2p:SessionIndex>JeBKZSJah-0m2QjC4LJ8u74LUOY2ayAeenlPgBOx1N8</saml2p:SessionIndex>
</saml2p:LogoutRequest>

Application Type

Reserved for ID Cloud use.

Custom Pre-Processing

Assign a step to apply custom pre-processing logic before validating the incoming request for this SP.

You may assign a chain of steps to build a flow.

The flow will be executed for all incoming requests, no matter if the user has a session already.

If you need to apply different logic for these 3 cases you can use Dispatcher Step and dispatch based on the following expressions:

${request:method:^authenticate$:true}
${request:method:^stepup$:true}
${request:method:^logout$:true}

The dispatching will continue after leaving this flow on the happy path.

For On Success exits this works automatically.

However, generic exits (i.e. Additional Follow-up Steps in Generic Authentication Step) must be marked as success exits by assigning the Pre-Processing Done pattern.

Authentication Request: Lifetime

SAML authentication requests have a maximum lifetime which may be validated by this identity provider.

Enter unlimited to disable the maximum lifetime check for received SAML AuthnRequests. This sets in.max_age to -1 in the generated IdentityProviderState.

Custom Properties

Configure properties of the nevisAuth IdentityProviderState.

Add or overwrite properties by entering a value.

Remove properties generated by this pattern by leaving the value empty.

Examples:

Key	Value
out.extension.Bearer	ch.nevis.esauth.auth.states.saml.extensions.SubjectConfirmationExtender
Bearer.inResponseTo	${notes:saml.request.id}
out.signatureKeyInfo	Certificate

Assertion Consume URL Validation

By default, the whitelist is calculated based on SP URL - Assertion Consumer Service(s). But in some special cases, you can use wildcards to allow a wide range of whitelisted urls. Examples:

• *.mydomain.com
• mydomain.com*

SAML SP Realm

Represents a SAML Service Provider (SP).

Assign this pattern to applications to enforce authentication using SAML.

SAML Issuer

Set the Issuer used by this SAML Service Provider.

The issuer can be an arbitrary string but it is recommended to use the complete URL that the Assertion Consumer Service is exposed on.

Example: https://sp.siven.ch/SAML2/ACS/

SAML IDP Connector(s)

Assign a SAML IDP Connector for each SAML Identity Provider.

SP-initiated authentication with multiple IDPs requires a Selection Expression to be configured for each connector.

SAML Signer

Use a pattern to configure the signer certificate used by this Service Provider. If no pattern is assigned a key store will be provided automatically.

Assertion Consumer Service

Enter the path where SAML Response messages sent by the IDP shall be consumed.

This path also accepts LogoutRequest messages.

The IDP may send messages using POST or redirect binding.

Application Access Tokens

SAML Responses returned by the IDP are consumed in nevisAuth and not forwarded to applications.

If your application requires a token then you have assign a pattern which can produce that token here. For instance, assign a NEVIS SecToken or SAML Token.

To forward the token to applications you also have to assign the token pattern to these applications via Application Access Token.

The token will be created on first access (missing token role triggers a stepup). In case of a session upgrade via SAML the token (role) is revoked and thus the token is recreated on the next access.

In your application you may use the Ninja authentication filter provided by NEVIS to extract user id, roles, and custom attributes.

nevisAuth

Assign a nevisAuth Instance pattern.

Key Store

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

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

Automatic key management should be used for test setups only.

Trust Store

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

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

Automatic key management should be used for test setups only.

Hostname Validation

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

Internal SecToken Trust Store

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

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

Automatic key management should be used for test setups only.

Custom Parameters (IdentityCreationFilter)

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

This pattern generates 2 IdentityCreationFilter elements:

1. Authentication_<name>: enforces authentication for applications.
2. SAML_<name>: provides the Assertion Consumer Service and Session Upgrade Path

If you want to patch only one of these filters consider using Generic Application Settings instead.

Note that the parameter InterceptionRedirect of the SAML_<name> filter is forced to never. If you configure InterceptionRedirect here it will be ignored for this filter as leads to message loss in SAML POST binding.

Examples:

• BodyReadSize = 64000

Custom Parameters (Esauth4ConnectorServlet)

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

That servlet is called Connector_<name>.

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

Examples:

Key	Value
EnablePollTerminatedCalls	true

Login Renderer

Assign a pattern which defines the login renderer.

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

Key Store

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

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

Trust Store

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

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

Hostname Validation

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

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

Login Template

By default, the Service Provider does not need any rendering template.

A GUI will be shown only when Logout Reminder is enabled and but may also be shown when Custom Pre-Processing is used.

nevisLogrend: Simple Mode

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

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

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

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

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

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

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

nevisLogrend: Expert Mode

Expert users may upload Velocity templates and resources to nevisLogrend.

Zip files will be extracted into the nevisLogrend application:

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

Flat files will be added to the following subdirectories:

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

nevisProxy: Simple Template

nevisProxy also provides a simple login page renderer.

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

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

Login Template Mode

Choose between two options:

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

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

Translations

Labels are used to provide human-readable text in the language of the user. Here you can overwrite the defaults and add your own translations.

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

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

So far this property is relevant only if the Logout Reminder feature is enabled because then a page will be rendered. The following labels are used:

• title - used as browser page title
• logout.text
• language.<code> - used by language switch component
• info.logout.reminder
• continue.button.label

Translations Mode

Choose between:

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

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

Default Translations

Choose between:

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

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

nevisLogrend default.properties

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

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

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

Session Cookie Name

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

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

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

Session Cookie Same Site

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

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

Thus, it is recommended to select None here.

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

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

Session Cookie Same Site Relaxation (Experimental)

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

See this example bug report for Safari:

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

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

Session Validation

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

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

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

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

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

ENV:REMOTE_ADDR:invalidate

Initial Session Timeout

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

Authenticated Session Timeout

Define the idle timeout of an authenticated session.

Max Session Lifetime

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

Update Session Timestamp Interval

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

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

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

Timeout Page

Renders a timeout page when the user session has expired.

This is different from the Logout Reminder Page feature which also show a page when the user comes back after closing the browser.

The page contains a heading, an info message and a continue button. You can customize them via Custom Translations by setting the following labels:

• title.timeout.page
• info.timeout.page
• continue.button.label

For this feature an additional cookie Marker_<name> will be issued. The value will be set to login or logout depending on the last user action.

The following requirements must be fulfilled:

• Usage of HTTPs to access the application and for the entire SAML process.
• No other session expiration feature must be used.

Timeout Redirect

Enter a URL or path to redirect to after session timeout.

The redirect is executed on next access when the session has expired.

This is different from the Logout Reminder Redirect feature which also performs the redirect when the user comes back after closing the browser.

For this feature an additional cookie Marker_<name> will be issued. The value will be set to login or logout depending on the last user action.

The following requirements must be fulfilled:

• Usage of HTTPs to access the application and for the entire SAML process.
• No other session expiration feature must be used.

Logout Reminder Page

Enable this feature to show a logout reminder page.

The page will be shown on next access in the following cases:

• the user has closed the browser
• user session has expired due to idle timeout

The page contains a heading, an info message and a continue button. You can customize them via Custom Translations by setting the following labels:

• title.logout.reminder
• info.logout.reminder
• continue.button.label

For this feature to work an additional cookie Marker_<name> will be issued. The value will be set to login or logout depending on the last action of the user.

The following requirements must be fulfilled:

• Usage of HTTPs to access the application and for the entire SAML process.
• No other session expiration feature must be used.

Logout Reminder Redirect

Enter a URL or path to redirect to when a user accesses, and the session has expired.

The redirect is executed on next access in the following cases:

• the user has closed the browser
• user session has expired due to idle timeout

The following requirements must be fulfilled:

• Usage of HTTPs to access the application and for the entire SAML process.
• No other session expiration feature must be used.

Logout Mode

Defines how this SP should react when an SP-initiated logout completes on this SP.

• redirect-target: redirects to a defined path or URL. When this option is selected a Logout Target must be entered.

• redirect-state: redirects according to the RelayState query parameter received in combination with the LogoutResponse. The IDP is expected to return this parameter as-is and thus the RelayState should contain the URL where the logout was initiated. As this is a protected application URL authentication will be enforced and the user will be sent to the IDP again to perform a login.

Logout Target

Enter a path or URL to redirect to when an SP-initiated SAML logout completes on this SP.

The redirect is performed only when Logout Mode is set to redirect-target.

Session Upgrade Path

Applications may redirect to this location to force the SP to invoke the IDP again by sending an AuthnRequest.

This mechanism allows applications to enforce a session upgrade.

The URL must contain the following query parameters:

• relayState: the path to redirect to after successful session upgrade.
• level: the required authentication level (2-9). The level will be sent to the IDP within the RequestedAuthnContext.

Tokens produced by Application Access Token patterns assigned to applications will be re-created on next access to reflect updated user data.

Example for RequestedAuthnContext with level=2:

<saml2p:RequestedAuthnContext>
  <saml2:AuthnContextClassRef xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">urn:nevis:level:2</saml2:AuthnContextClassRef>
</saml2p:RequestedAuthnContext>

Custom Pre-Processing

Assign a step to apply custom pre-processing logic before executing SP-initiated SAML authentication. This pre-processing logic is executed for methods: authenticate, stepup, unlock, and logout.

You may assign a chain of steps to build a flow. The dispatching will continue when leaving this flow on the happy path.

For On Success exits this works automatically.

However, generic exits (i.e. Additional Follow-up Steps in Generic Authentication Step) must be marked a success exits by assigning the Pre-Processing Done pattern.

Post-Processing

Assign a Generic Authentication Step to apply custom post-processing logic to an SP-initiated SAML process (e.g. authentication, session upgrade, or logout).

By assigning a step here the last AuthState of the process will be replaced so that it points to the first AuthState provided by the assigned step. This AuthState should be marked with the name ${state.entry}.

Use the expression ${state.done} to complete with the SAML process.

SAML Token

Assign to a realm pattern using Application Access Tokens to allow the realm to produce SAML tokens.

To propagate the tokens to applications set Additional Settings on the application patterns. There are several options:

• Assign the pattern to forward tokens in the Authorization header. Use in combination with Ninja.
• Use the SAML SP Integration pattern to send tokens using POST to an SP deployed on the same backend.

Issuer

Enter the Issuer which will be used to create the token.

If nothing is configured the name of the pattern is taken.

User Attributes

Define which nevisAuth session variables to include as attributes in the SAML assertion.

If not set the following default will be used:

Attribute	Session Variable
userid	ch.nevis.session.userid
loginId	ch.nevis.session.loginid
profileId	ch.adnovum.nevisidm.profileId
clientId	ch.adnovum.nevisidm.clientId

Which session variables are available depends on your authentication flow. For instance, if you use nevisIDM Password Login there will be a session variable user.email so you can easily add an attribute email.

Set the log level of Vars to INFO and check the esauth4sv.log to find out which session variables are available after authentication.

In case a session variable is not found the attribute will be omitted.

Signer Key Store

Assign a pattern which sets the key material used for signing the token.

If no pattern is assigned automatic key management is used and the signer key will be created automatically.

Token Type

• Assertion: produces a SAML Assertion.

Use for applications protected by Ninja.

• Response: produces a SAML Response.

Use for applications which have their own SAML SP. Assign the SAML SP Binding pattern to the application and link this pattern there.

Audience Restriction

Configure the AudienceRestriction.

Enter 1 line for each Audience.

Subject Type

Configure the subject of the generated SAML assertion.

• User ID: sets the internal user ID
• Login ID: sets the ID as entered by the user during login

Custom Properties

Enter custom properties for the nevisAuth IdentityProviderState which issues the SAML Response (or Assertion).

Please check the technical documentation for details.

Common use cases are:

• out.issuer: sets the Issuer element (By default, the sanitized name of the pattern is used)
• out.audienceRestriction: some recipients require this to be set to decide if they accept the token
• out.signatureKeyInfo: add information about the signer certificate

Examples:

out.authnContextClassRef = urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
out.sessionIndex = ${notes:saml.assertionId}
out.signatureKeyInfo = Certificate
out.subject.format = urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
out.ttl = 10
relayState = ${request:currentResource}

SAP Logon Ticket

Assign to a realm using Application Access Tokens to allow the realm to produce an SAP Logon Ticket.

To issue an SAP Logon Ticket and propagate it to applications you also have to assign the pattern to the corresponding Web Application, REST Service, or SOAP Service using Application Access Token.

The issued SAP Logon Ticket may either be propagated to the client as a cookie (for pseudo-federated scenarios based on shared cookie domain spaces) or propagated to a backend application behind a nevisProxy instance.

UserID Source

Source of the user ID to set for the issued SAP ticket.

The default is ${request:userId}.

Application Mappings

A list of user ID mappings of the form <application>:<ID> to be inserted in the ticket. This will be used by SAP services to retrieve local user IDs. SAP NetWeaver Portal CRM plays a special role here as its user management is based on UME and, typically, has distinct IDs.

Signer Key Store

Assign a pattern which sets the key material used for signing the token.

If no pattern is assigned automatic key management is used and the signer key will be created automatically.

Encoding

Encoding to use for the SAP token. Note that some SAP applications (in particular those running as native processes) do not support all encodings. In such cases, error messages may be misleading. Usage of the encoding "ISO8859-1 (ISO-LATIN-1)" is encouraged as this seems to be supported by all SAP products.

The default is ISO8859-1.

System ID

Identifier of issuing system (or issuer). This must match the key under which the issuer certificate was configured in the consuming service.

System Client

Identifier of client. See SAP documentation of SAP SSO logon tickets for more information. Default value is SAP's default and should be correct for most cases.

Authentication Scheme

Authentication scheme associated with this ticket. See SAP documentation of SAP SSO logon tickets for more information. Default value is SAP's default and should be correct for most cases.

Recipient Client

See SAP documentation of SAP SSO logon tickets for more information. Setting no value for this property should be correct for most cases.

Recipient SID

See SAP documentation of SAP SSO logon tickets for more information. Setting no value for this property should be correct for most cases.

Caching Allowed

If set to enabled, this property enables the CachingAllowed flag in the issued ticket. See SAP documentation of SAP SSO logon tickets for more information.

Include Certificate

When enabled, the signer's certificate is inserted into the issued SAP ticket.

Set-Cookie Header

If set, this property must specify the value of the HTTP header "Set-Cookie". The cookie will be issued to the client by nevisAuth such that a cookie-based SSO federation with SAP applications is possible. This property is evaluated after the ticket has been issued, so the variables sap.ticket, sap.ticket.maxAge and sap.ticket.expires can be used.

Example value for this property that sets the cookie as expected by SAP products:

MYSAPSSO2=${outarg:sap.ticket}; Version=1; Path=/; Secure; HttpOnly; Max-Age=${notes:sap.ticket.maxAge}; Expires=${notes:sap.ticket.expires};

To use this example value by default, set this property to true.

Sendgrid SMTP

The pattern sets up a connection to Sendgrid for sending emails. Assign the pattern to Email TAN (eTAN) as SMTP Server.

API Key

API key to connect to Sendgrid.

Standalone Authentication Flow

Use this pattern to build custom self-admin use cases, for example, user registration, password reset, mobile change.

The authentication flow is exposed on the assigned Virtual Host. Requests received on the configured Frontend Path are dispatched into an authentication step.

The flow is always executed, even when the user already has an authenticated session.

Be aware that on successful execution of the flow, the caller may be authenticated in the assigned Authentication Realm, and thus will be able to access any applications protected by that realm.

For use cases which do not require an authenticated session it is therefore recommended to use a separate realm.

Virtual Host

Assign a Virtual Host.

Frontend Path(s)

Enter frontend path(s) which should be handled.

Authentication Realm

Assign an Authentication Realm.

Authentication Flow

Assign a step to execute for incoming requests.

If not present already, the step will be added to the Authentication Realm.

If no step is assigned the default flow of the Authentication Realm will be executed.

Session Upgrade Flow

Assign a step to execute for incoming requests when there already is an authenticated session.

If not present already, the step will be added to the Authentication Realm.

If no step is assigned the same step as for Authentication Flow will be executed.

Allowed HTTP Methods

Define the allowed HTTP methods.

If not configured, all HTTP methods are allowed.

Additional Settings

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

Example use cases:

• URL Handling with phase AFTER_AUTHENTICATION to redirect after the authentication flow completes.
• Access Restriction to restrict access based on source IPs.
• HTTP Header Customization to add, replace, or remove HTTP headers in requests or responses.

SwissPhone SMS

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

#TESTING ONLY - NOT FOR PRODUCTION USE

A simple username / password login step. Use for testing only. Enter username = password to continue.

Label

Set to show a different message.

On Success

Set the step to continue with on successful authentication. If no step is assigned, the process ends and the user will be authenticated.

Buttons

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

Authentication Level

Set an authentication level.

Test TAN

#TESTING ONLY - NOT FOR PRODUCTION USE

A dummy TAN second factor authentication.

On Success

Set the next step on successful entry of the TAN code. If no step is assigned, the process ends and the user will be authenticated.

Authentication Level

Set an authentication level.

Label

Set to show a different message.

Token Header Propagation

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

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 Information

The pattern renders a GUI with a label and an optional button.

You can also use the pattern to show error messages, and terminate the authentication flow.

The following table describes expected configurations:

Message	Button	On Submit	Description
error	submit	no set	Terminates the session. Button restarts the flow.
error	none	no set	Use for fatal errors, when there is no way to continue.
warning	cancel	not set	Show an error and restart the flow from the beginning.
warning	submit	set	Show an error and allow the user to continue.
info	submit	set	Show a message and allow the user to continue.

Message Type

• error - terminates the session (AUTH_ERROR) and shows an error message.
• warn - does not terminate the session (AUTH_CONTINUE) but the message is shown as an error.
• info - renders as a message of type info and does not terminate the session (AUTH_CONTINUE).

Terminating the session needs careful testing as state loss can lead to follow-up errors.

Title

Enter a label for the title. No expressions are supported.

By default, the label title.login is used. This label is which is translated as Login in all languages.

We recommend to use a different label depending on your use case.

Translations for the label can be defined in the realm pattern.

Message

Enter a label or an expression for the text message that shall be presented to the user.

Translations for the label can be defined in the realm pattern.

If not set the expression ${notes:lasterrorinfo} is used.

Button Type

Adds a button to the GUI:

• none - no button is added
• submit - adds a submit button. To continue with On Submit the Message Type must be warning or info.
• cancel - adds a cancel button. The button restarts the authentication flow from the beginning. The flow must be reentrant.

On Submit

Define a follow-up step.

The Button Type should be set to submit, but the form can also be submitted by other means (e.g. refreshing the browser).

User Input (multiple fields)

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.

User Input (single field)

A simple step to ask the user for some input and store the input in a variable. Use the variable in subsequent authentication steps.

Title

Enter a text or litdict key for the form title (<h1>).

Greeting

Enter a text or litdict key to be displayed in a line below the title.

The text should inform the user what has to be entered in this form.

Label

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

Variable Name

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

The following scopes are supported:

• inargs
• notes
• sess or session

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

On Success

Configure the step to execute after the user has provided input. If no step is configured here the process ends with AUTH_DONE.

Remember Input

Enable this feature to show a Remember Input checkbox.

If selected the user input is stored in a cookie (named like this step) so that the value can be prefilled on subsequent authentications.

nevisAuth Connector

Use to connect to an existing nevisAuth instance.

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

Connection URL(s)

Enter hostname:port of the nevisAuth instance.

Languages

Enter the language codes which are enabled in nevisAuth.

This property is considered only if nevisLogrend is generated by nevisAdmin to ensure that nevisLogrend provides support for the same languages.

Kubernetes

This setting is used when deploying to Kubernetes only.

Choose between:

• disabled: instance running on a VM.

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

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

• other_cluster: service running in another cluster.

Namespace

Enter the Kubernetes namespace.

Configuration is required when Kubernetes is set to other_namespace.

nevisAuth Database

Configures nevisAuth to use a MariaDB database for storing sessions and out-of-context data. Assign to a nevisAuth Instance as Database.

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

In classic VM deployments a database including tables for sessions and out-of-context data must be set up manually before deployment. Setup instructions can be found in the nevisAuth technical documentation.

The log category for the session store is RemoteSessionStore.

Database Type

Choose between MariaDB and PostgresSQL.

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

Note: PostgresSQL database is only experimental configuration.

Database Host

Enter the host name of the database service.

The database service must be up when you deploy.

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

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

Database Name

Here you can change the name of the database.

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

Schema User

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

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

If not set, the database connection user will be used.

Example: schema-user

Schema User Password

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

Root Credential

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

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

This is the default behaviour in Kubernetes.

With complete the secret should contain the following:

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

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

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

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

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

Root Credential Namespace

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

Database User

Database connection user.

This setting is used in the following cases:

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

Database Password

Password for the database connection user.

This setting is used in the following cases:

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

Password Type

Choose between:

• automatic: behaves like command when the password starts with /opt/.
• command: use when the input is a command. In esauth4.xml the prefix pipe:// will be added.
• plain: take the password as-is.

TLS Encryption

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

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

Trust Store

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

Key Store

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

This configuration only accept PEM Key Store pattern configuration.

Noted: This is an experimental configuration

Database Management

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

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

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

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

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

Synchronize Sessions

Defines when sessions are stored to the remote session store.

• after-successful-authentication

A session is stored to the remote session store once authentication has been completed successfully.

Use this mode when performance is critical, when the authentication flow is stateless (e.g. no GUI is shown), when there is only 1 nevisAuth instance, or in classic VM-based deployment scenarios.

• always

Session are always stored to the remote session store.

This mode requires nevisAuth version 4.28.0.216 or newer.

We recommend this mode when you want to restart nevisAuth without user impact and for deployments to Kubernetes.

Typically, while a user is logging in, multiple requests are sent to nevisAuth.

If you configure multiple replicas of nevisAuth, the Kubernetes service may forward these requests to any of the replicas. By selecting always, you ensure that all replicas can access the user's session during the authentication process.

• recommended (default)

Uses always when deploying to Kubernetes and after-successful-authentication for classic, VM-based deployments.

Custom Attributes

Add or overwrite attributes of the RemoteSessionStore XML element.

Example:

Attribute	Value
syncPullInitial	true

Connection Parameters

Enter parameters for the DB connection string.

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

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

Enter 1 parameter per line.

Lines will be joined with &.

Examples (from various Nevis components):

pinGlobalTxToPhysicalConnection=1
useMysqlMetadata=true
autocommit=0

Connection URL

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

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

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

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

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

nevisAuth Instance

Represents a nevisAuth instance. The instance is named according to the pattern.

Hint for pattern renaming

When the 'Instance Name' property is not filled, the pattern uses the pattern's name as instance directory at the target host.

To rename the pattern, do the following:

1. Rename the pattern in the GUI.
2. Rename the instance directory and associated systemd files on the deployment hosts.
3. Deploy.

In case step 2 is omitted the old instance is shut down during deployment.

For more information, see technical documentation: User Guide / Configuration Projects / Working with Patterns.

Port

Port the nevisAuth instance is listening on.

Instance Name

Enter the instance name.

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

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

Log Settings

Add logging configuration for nevisAuth.

Database

By default, nevisAuth stores sessions and out of context data in memory.

In most setups you should use a database instead, and you should assign a nevisAuth Database pattern here.

In memory should be used only when there is only 1 line / pod of nevisAuth, or in a classic deployment where nevisProxy can ensure session-sticky load balancing towards nevisAuth.

Languages

Configure the language codes that shall be supported.

Each language code must be entered on a new line. By default, translations are provided for the following codes:

• en: English
• de: German
• fr: French
• it: Italian

nevisAuth uses the Accept-Language header sent by the browser to determine the user language. In case this header is not available the first configured language code will be used as a default.

Frontend Key Store

Assign the Key Store provider for the HTTPs endpoint. If no pattern is assigned a Key Store will be provided by the nevisAdmin 4 PKI.

Frontend Trust Store

Assign the Trust Store provider for the HTTPs endpoint. If no pattern is assigned the Trust Store will be provided by the nevisAdmin 4 PKI.

Client Authentication

Enable to enforce 2-way TLS on the nevisAuth HTTPs endpoint.

This means that callers (e.g. nevisProxy or technical clients accessing nevisAuth REST APIs) must present a client certificate.

The Frontend Trust Store must contain the issuing CA.

Default Backend Key Store

Assign the Key Store provider for outbound TLS connections. If no pattern is assigned a key store will be provided by the nevisAdmin 4 PKI.

Default Backend Trust Store

Assign the Trust Store provider for outbound TLS connections. If no pattern is assigned a trust store will be provided by nevisAdmin 4 automatic key management.

Internal SecToken Signer Key Store

Assign a key store for signing the internal NEVIS SecToken.

This token is returned to nevisProxy and validated there. It should not be added to calls to applications. If your applications need a NEVIS SecToken, assign a NEVIS SecToken pattern to your applications.

If no pattern is assigned, the signer key material will be provided by automatic key management.

Internal SecToken Signer Trust Store

Assign a trust store to validate the signature of the internal NEVIS SecToken.

This is an advanced setting and it is usually not required to configure this.

If no pattern, an Automatic Key Store pattern, or a PEM Key Store, is assigned to Internal SecToken Signer Key Store, then you do not have to configure this. The configuration of nevisAuth will be generated correctly, based on the deployment type and scaling.

Configuration is required in classic VM deployment, when this instance is deployed to multiple hosts, and the hosts have different key material in the Internal SecToken Signer Key Store.

Session Limit

Defines the maximum number of user sessions than may be created in this nevisAuth instance.

A nevisAuth session requires at least 10kb but the session can be much bigger when a user has many roles or multiple tokens are used.

Custom Dependencies

In case AuthStates uses custom AuthState classes upload the required JAR file(s) here. Files will be deployed into the plugin directory of the nevisAuth instance.

Classpath Prefix

Enter directory paths to be added to the classPath of the AuthEngine.

The paths will be added as a prefix. Entries added by other patterns (e.g. /opt/nevisidmcl/nevisauth/lib or /opt/nevisauth/plugin) are preserved.

This is an advanced setting which should only be used when working with custom AuthState classes.

Liveness Delay

Time to wait before checking Kubernetes liveness.

You may have to increase this value if start of the nevisAuth service fails because of a failing liveness check.

Sets initialDelaySeconds of the Kubernetes liveness probe.

Readiness Delay

Time to wait before checking Kubernetes readiness.

You may have to increase this value if start of the nevisAuth service fails because of a failing readiness check.

Sets initialDelaySeconds of the Kubernetes readiness probe.

Memory Limit

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

VM Deployment

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

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

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

Kubernetes Deployment

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

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

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

Initial Memory Ratio

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

This setting applies to classic VM deployments only.

Line Preference

This setting (together with the inventory) defines the order of nevisAuth endpoints in the connection string from nevisProxy.

nevisAuth stores unauthenticated sessions in memory. In a classic deployment to VMs, even when a nevisAuth MariaDB Remote Session Store is configured, sessions are synced to the DB only after successful authentication. Thus, multi-step login flows require that requests for the same session are routed to the same nevisAuth endpoint.

nevisProxy uses a simple fail-over strategy. The first URL in the connection string for nevisAuth is always used, unless this instance is not available. This strategy works well when:

• there is only 1 nevisProxy instance
• there are 2 lines of nevisProxy but line 1 is active and line 2 is standby
• there is a session-sticky load-balancer in front of nevisProxy is session-sticky

The order of the connection string depends on the inventory. See also: Defining Lines and Fail-over Association

This strategy may fail in active / active setups when line groups are defined in the inventory. In such setups you can set this drop-down to disabled to ensure that the order in the connection string is the same on all nevisProxy lines.

Start Timeout

Enter a timeout to wait for nevisAuth startup.

Set a higher value if nevisAuth takes longer to start.

This setting applies to classic VM-based deployment only.

Instance Rename Detection

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

If instance rename is detected the current instance is stopped.

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

This setting is relevant for classic VM deployment only.

Start Inactive

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

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

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

Check Minimum Version

Select enabled to perform basic version checks.

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

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

This check can be disabled for testing purposes.

Open Telemetry

OpenTelemetry is used for several use cases:

• cross-component tracing in logs
• exposing metrics

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

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

Connection Host:Port

Enter the host:port pair(s) which nevisProxy should use to connect to this nevisAuth instance.

This setting is required when the primary names of the nevisAuth hosts are not accessible by nevisProxy, which is sometimes the case in classic VM deployment, when working with multi-homed target hosts.

The server certificate provided by the Frontend Key Store must be valid for all provided hosts names.

Bind Host:Port

Enter a custom host name to listen on.

This setting is relevant in classic VM deployment, when working with multi-homed target hosts.

In Kubernetes nevisAuth listens on 0.0.0.0 and thus this setting is discouraged.

Propagate Session

Define the value of the AuthEngine attribute propagateSession.

• enabled: true is set which makes nevisAuth return the user's session to nevisProxy on AUTH_DONE.
• disabled: false is set - nevisAuth does not return the session.

It is generally recommended to disable this feature and thus we plan to change the default to disabled in a future release.

Session Index

Enables session indexing.

WARNING: Other patterns, such as nevisAdapt Instance may overrule this configuration.

This is required by ThrottleSessionsState.

Set Session Index Attribute if you need to index a non-default attribute.

Session Index Attribute

Enter the name of a session variable for the session index.

Differing Resource Startover

Define the value of the AuthEngine attribute differingResourceStartover.

• enabled: true is set.
• disabled: false is set.

Do not change this unless you know what you are doing.

ID Pregenerate

Define the value of the idPregenerate attribute.

• enabled: true is set.
• disabled: false is set.

Do not change this unless you know what you are doing.

Server Configuration

Set Server Configuration properties (nevisauth.yml).

Examples:

server.max-http-header-size: 16384

Custom Resources

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

Additional Settings

Assign an add-on pattern to customize the configuration of nevisAuth.

nevisAuth KeyObject

The pattern represents a nevisAuth KeyObject XML element.

KeyObject ID

Set the XML attribute id of the KeyObject XML element. The id must be unique within the nevisAuth instance. If not set the sanitized name of this pattern will be used.

Type

Select key store when a private key is needed. Select trust store for providing trusted certificate (e.g. for signature validation).

Key Store

Reference a key store provider pattern or leave empty to let nevisAdmin establish a key store. This reference property is considered when type key store is selected.

Trust Store

Reference a trust store provider pattern or leave empty to let nevisAdmin establish a trust store. This reference property is considered when type trust store is selected.

nevisAuth Log Settings

Configure log levels and retention of nevisAuth logs.

Assign to a nevisAuth Instance via Log Settings.

In classic VM deployment nevisAdmin 4 does not restart the nevisAuth instance when only log configuration is changed. New log configuration is reloaded within 60 seconds after deployment.

Default Log Level

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

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

Log Levels

Set log levels.

The default is:

Category	Level
EsAuthStart	INFO
org.apache.catalina.loader.WebappClassLoader	FATAL
org.apache.catalina.startup.HostConfig	ERROR

The default gives you log messages during startup but is rather silent during runtime.

A good setting for troubleshooting is:

Category	Level
AuthEngine	INFO
Vars	INFO

When using nevisAuth Database with MariaDB the category org.mariadb.jdbc can be set. The levels behave as follows:

• ERROR: log connection errors
• WARNING: log query errors
• DEBUG: log queries
• TRACE: log all exchanges with server

Check the documentation for other important trace groups.

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

Rotation Type

Select log rotation type.

Choose between:

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

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

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

Max Backup Files

Maximum number of backup files to keep in addition to the current log file.

Max File Size

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

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

Note: not relevant when rotation type is time.

Rotation Interval

Rotation interval after which log files are rolled over.

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

Choose between:

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

Log Format

Log4j 2 log format for the default SERVER logs.

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

Syslog Format

Log4j 2 log format for the SERVER SYS logs.

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

Hidden Variables

Enter variables that should be hidden in logs.

The special option auto hides the following variables:

• variables used for GUI elements of type pw-text
• dyncert.key
• connection.HttpHeader.Authorization
• client_secret

The wildcard * may be appended (but not prepended). This way, every variable that starts with a certain string will be hidden from the log. For instance, passw* will hide password and passwd.

Regex Filter

If set, messages for esauth4sv.log which match the given regular expression won't be logged.

The regular expression must match the entire line. For instance, you may use the following format to match some text:

.*some text.*

Audit Log

Enable audit logging capability of nevisAuth.

Log Format

Log4j 2 log format for the AUDIT logs.

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

Syslog Format

Log4j 2 log format for the AUDIT SYS logs.

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

Event Log

Enable event logging capability of nevisAuth.

Log Format

Log4j 2 log format for the EVENTS logs.

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

Syslog Format

Log4j 2 log format for the EVENTS SYS logs.

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

Custom Log Fields

Set to add additional fields to the nevisAuth events log.

Enter field names (with optional format JSON) to nevisAuth expressions.

Examples:

Field	Expression
unitDisplayName	${sess:ch.nevis.idm.User.unit.displayName}
unitHierarchy:JSON	${StringUtils.strip(sess['ch.nevis.idm.User.unit.hname'].replace('/',','),',')}

Based on this CustomField elements with name, value, and optional attribute format, are created in esauth4.xml.

Log Targets

Select the type of log4j appender.

This property is relevant for classic VM deployments only.

In Kubernetes the main logs are written to system out so that log messages appear in the docker logs.

Choose between:

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

Syslog Host

Defines where to send logs to via syslog.

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

The syslog facility is localhost3 and the threshold is INFO.

nevisAuth Radius Facade

The pattern sets up a Radius facade which acts as entry point for an Authentication Realm.

See the following chapters in the nevisAuth technical documentation to understand how the Radius facade works:

• Radius facade
• Configuring the RADIUS facade

There are some limitations:

• The Radius UDP ports are not configurable.
• The pattern does not validate whether you have defined an appropriate response for each step in your authentication flow. You have to configure Custom Radius Responses if your flow requires user interaction apart from simple username and password authentication.

For testing the Radius facade on a Linux server, use Radtest.

Authentication Realm

Assign a nevisAuth Realm which shall be exposed via Radius.

Radius Secret

Enter a secret to be used for this facade and all Radius clients.

Request Attribute Mappings

Define how attributes from Radius requests are mapped to input arguments (inargs) for nevisAuth.

There are some well-known input arguments which you may have to provide:

• isiwebuserid - entered user name
• isiwebpasswd - entered password
• mtanresponse - used in mobile TAN patterns

Examples:

Radius Attribute	Input
User-Name	isiwebuserid
User-Password	isiwebpasswd, mtanresponse
State	sessionid

Depending on your authentication flow it may be required to provide additional input arguments.

Additional Radius Responses

Configure additional Radius responses depending on your authentication flow.

For instance, configure Access-Challenge responses if your authentication flow is interactive.

Response rules configured here are evaluated first. You can therefore overrule the default rules added by this pattern.

No configuration may be required for basic username / password login as username and password can be sent by the Radius client in the initial Access-Request message.

nevisAuth Radius Response

Use in nevisAuth Radius Facade to declare Additional Radius Responses.

The nevisAuth Radius Facade pattern adds basic response rules for nevisAuth AUTH_DONE and AUTH_ERROR responses out-of-the-box.

However, explicit configuration is required if your Radius clients require additional attributes to be returned, or your authentication flow consists of steps which require user interaction.

Radius Response Type

The Radius message type.

For instance, use Access-Challenge to prompt the user for input.

Condition

An expression which defines when this response is generated.

For instance, use ${response:status:0} to return this Radius response for all AUTH_CONTINUE responses. Likewise, you can use 1 for AUTH_DONE and 2 for AUTH_ERROR responses.

In complex authentication flows consisting of multiple steps it can be tricky to find a good expression which matches for one step only. Please contact your integration partner if you need support.

Radius Attributes

Adds additional attributes to this Radius response.

Which attributes are required depends on the Radius Response Type.

For instance, in an Access-Challenge it is often required to add a Reply-Message which can be shown to the user. Also a State must be added some that the authentication can continue.

You may use expressions for the attribute value. For instance, use a ${litdict: expression to return a translated text.

Examples:

Prompt: No-Echo
Reply-Message: ${litdict:mtan.prompt}
State: ${sess:Id}

nevisLogrend Connector

Use to connect to an existing nevisLogrend instance.

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

Connection URL(s)

Enter hostname:port of the nevisLogrend instance.

Kubernetes

This setting is used when deploying to Kubernetes only.

Choose between:

• disabled: instance running on a VM.

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

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

• other_cluster: service running in another cluster.

Namespace

Enter the Kubernetes namespace.

Configuration is required when Kubernetes is set to other_namespace.

nevisLogrend Instance

Configures a nevisLogrend Instance.

TCP Service Port

Enter the port the nevisLogrend shall listen on.

Instance Name

Enter the instance name.

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

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

HTTPs

Choose between plain HTTP, normal HTTPs and mutual (2-way) HTTPs. If enabled a Key Store is required. If set to mutual, a Trust Store is required as well.

Log Settings

Add logging configuration for nevisLogrend.

Frontend Key Store

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

Frontend Trust Store

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

Memory Limit

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

VM Deployment

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

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

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

Kubernetes Deployment

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

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

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

Initial Memory Ratio

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

This setting applies to classic VM deployments only.

Instance Rename Detection

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

If instance rename is detected the current instance is stopped.

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

This setting is relevant for classic VM deployment only.

Start Inactive

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

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

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

Check Minimum Version

Select enabled to perform basic version checks.

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

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

This check can be disabled for testing purposes.

Open Telemetry

OpenTelemetry is used for several use cases:

• cross-component tracing in logs
• exposing metrics

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

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

Bind Host

The host name that this nevisLogrend instance will bind to. nevisProxy will connect to the same host name.

Base Path

Set a custom path for nevisLogrend resources (e.g. CSS). The path will be made accessible in nevisProxy.

You must change the path when using multiple nevisLogrend instances on the same virtual host.

Configuration: logrend.properties

Add or overwrite properties in logrend.properties.

You can use the following expressions (format: ${...}):

• ${protocol} - depends on HTTPs setting
• ${host} - depends on Bind Host setting
• ${port} - will be replaced with TCP Service Port
• ${instance} - contains the instance name

This is an advanced setting which should be used in complex setups only. If you have to configure anything here we are looking forward for your use case.

Additional Settings

Assign an add-on pattern to customize the configuration of nevisLogrend.

nevisLogrend Log Settings

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

Default Log Level

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

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

Log Levels

Configure log levels.

See nevisLogrend Technical Documentation, chapter Logging configuration for details.

Hint: If you only change log levels nevisAdmin 4 does not restart the component in classic VM deployment. The new log configuration will be reloaded within 60 seconds after deployment.

Examples:

ch.nevis.logrend.beans.LoginBean = DEBUG

Rotation Type

Select log rotation type.

Choose between:

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

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

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

Max Backup Files

Maximum number of backup files to keep in addition to the current log file.

Max File Size

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

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

Note: not relevant when rotation type is time.

Rotation Interval

Rotation interval after which log files are rolled over.

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

Choose between:

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

Log Format

Log4j 2 log format for the default SERVER logs.

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

Syslog Format

Log4j 2 log format for the SERVER SYS logs.

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

Regex Filter

If set, messages for nevislogrend.log which match the given regular expression won't be logged.

The regular expression must match the entire line. For instance, you may use the following format to match some text:

.*some text.*

Example: drop messages caused by the Kubernetes liveness checks

.*GET /nevislogrend/health.*

Log Targets

Select the type of appender.

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

Choose between:

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

Syslog Host

Defines where to send logs to via syslog.

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

The syslog facility is localhost3 and the threshold is INFO.

nevisProxy Login Renderer

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.