Skip to main content
Version: 4.32.x.x LTS

Concept Description

This chapter describes the main concepts on which nevisAuth is based.

What is it about

nevisAuth overview

nevisAuth implements strong user and system authentication for the Nevis identity and access management solution. The product complements nevisProxy, Nevis' entry gateway and web application firewall. Where nevisProxy filters the content of user requests to protect your company's online applications against internal and external threats, nevisAuth focusses on the user's identity. Its task is to verify whether the user is who he claims to be, to prevent unauthorized users from accessing your applications.

In this context, identification, authentication and authorization play a central role. Identification means claiming that you are user X, e.g., by entering your username "userX". Authentication is how the system proves if you really are user X. For this, the system can use up to three authentication factors, either separately or combined: something you know (e.g., password or PIN), something you own (e.g., grid card or a third-party token) and something you are (refers to biometrics, e.g., your fingerprint or your typing habits). Authorization takes place after the system has successfully identified and authenticated you as really being user X. It is the step that determines what you are allowed to do in the application, your roles and permissions.

nevisAuth covers the whole process of identification, authentication and authorization. If the authentication was successful, nevisAuth copies all relevant security data on a signed security token, the SecToken. This token is the user's Proof of Authentication towards nevisProxy and the business applications in the back end.

To be able to perform its tasks, nevisAuth works closely together with nevisProxy. For the verification of the user credentials and retrieval of user roles and permissions, the ideal partner of nevisAuth is nevisIDM, Nevis' product for identity management. However, nevisAuth can also cooperate with LDAP-based directory servers or other authentication services. Also, a request to authenticate a user must not necessarily enter nevisAuth via nevisProxy. nevisAuth provides several other interfaces (APIs), such as the RADIUS or the WS-Trust API, to integrate VPN gateways or specific Microsoft services.

Additionally, nevisAuth supports other token formats besides Nevis' proprietary SecToken, such as the SAML assertion, the X.509 user certificate or the JWT claim (OpenID Connect). Thus, nevisAuth enables identity federations with external networks or security domains.

Main features

  • Modular and customizable setup
  • Support of a wide range of authentication methods, such as user name/password authentication, X.509 client certificates, security questions, challenge/response procedures, one-time passwords
  • Integration of identity federation protocols, such as SAML2, WS-Federation and OpenID Connect
  • Support of various token formats, e.g., SAML assertion, the X.509 user certificate or the JWT claim (OpenID Connect)
  • Availability of flexible interfaces, e.g., RADIUS and the WS-Trust facade, to easily integrate external systems
  • Possibility to create realms/domains to enable single sign-on
  • Dynamic adjustment/upgrade of authentication strength to improve security
  • Facility to include user roles and permissions to establish a detailed and fine-grained authentication system

Authentication process including GUI generation

nevisAuth authentication process

The core task of nevisAuth is user identification and authentication. Its goal is that no unauthorized user will access your web applications. In this context, the burden of proof lies with the user. That is, the user must provide information to prove that he is who he claims to be.

This is how it works. A user wants to access a web application protected by Nevis (no.1 in the.

GUI generation The GUI descriptor is an XML file describing the content of the page to be returned to the user. It includes all user interface elements, such as text, input fields or submit buttons, required to obtain all user information that nevisAuth needs. Which user information is needed depends on the authentication method. Nevis supports a wide range of authentication mechanisms, both single- and multi-step procedures, such as user name/password authentication, X.509 client certificates, security questions, challenge/response procedures, one-time passwords, and so on.

nevisAuth does not generate the login page itself. Instead, it sends the GUI descriptor to nevisProxy, which in turn directs it to nevisLogRend, Nevis' rendering service (no.4). nevisLogRend is responsible for the design of the login page. It translates the XML elements of the GUI descriptor into an HTML based login page and forwards this page via nevisProxy to the user (no.5).

The user enters the missing login credentials and submits them to nevisProxy, which in turn sends the credentials to nevisAuth (no.6 and 7). It is nevisAuth' job to verify whether the user credentials are complete and correct. Therefore, nevisAuth calls its authentication back ends, such as nevisIDM or LDAP-based directory services (AD) (no.8). Depending on the request, nevisAuth may at the same time make an inquiry for the user's roles and permissions regarding the requested application.

After successful authentication, nevisAuth generates a security token (the SecToken) for this user request (no.9). The token contains all information relevant for the user's authentication, such as the user's login ID, the user's roles or the strength of the authentication. It is used towards nevisProxy and the application(s) in the back end as proof that the user was successfully authenticated (no.10).

If the authentication was not successful, Nevis can ask the user to reenter his credentials. It depends on the settings how often a login retry is allowed before nevisProxy denies the user access to the application.

Step-up Another use case is that the user does not have the required role for a certain application or resource, despite a successful authentication. In this case, nevisAuth, via nevisProxy/nevisLogRend, may ask the user for additional security information to "give" him the desired roles and permissions. This is called a step-up. If the user also passed this additional authentication, nevisAuth copies the information about the upgrade onto the SecToken.

Proof of authentication

After a successful authentication, nevisAuth needs a means to propagate the user's identity towards nevisProxy and the applications in the back end. Such a proof of authentication can be Nevis' proprietary SecToken. Other alternatives are an X.509 user certificate or the SAML assertion.


A main feature of nevisAuth is the ability to generate an authentication token, the SecToken, upon successful authentication. The SecToken is a structured and cryptographically signed piece of information. It holds all important user security data such as the user ID and the roles.

The SecToken is used for identity propagation between nevisAuth, nevisProxy and the applications in the back end that are protected by Nevis. It enables the receivers of the token to verify the identity of the user and to extract the user's roles and permissions, without having to perform an authentication themselves. Also, the token prevents the user from having to authenticate repeatedly.

The SecToken is Nevis proprietary. Usually, the token does not go to the user/client device or any other external service. During a user session with multiple requests and responses going back and forth between the client device and nevisProxy, the SecToken remains with nevisProxy. Its content is stored in the session cache.

nevisAuth SecToken

The lightweight SecToken includes the following information (among others):

  • user ID, referring to the user's data in the authentication back-end services,
  • login ID, referring to the ID that the user used to identify,
  • roles of the user,
  • strength of the authentication method (weak, strong),
  • reference to the issuing nevisAuth instance,
  • reference to the application/realm the user wants to access, and
  • the time of creation and the expiration time (time-to-live) of the SecToken.

The SecToken is secured using a Public-Key-Infrastructure mechanism. nevisAuth signs the token with a secret or private key. nevisProxy verifies the signature with the corresponding public key.

For a detailed technical description of the SecToken, see Nevis SecToken.

X.509 user certificate

Another option to delegate the user's identity is to provide a (dynamically generated) X.509 certificate. If you use this option, nevisAuth will issue an X.509 certificate containing the user's identity upon successful authentication. nevisAuth sends the certificate to nevisProxy, which in turn uses it to establish a secure channel to the back-end application. Common server infrastructures (like Java servers and Microsoft IIS) accept these certificates and use them as an identity principal.

Some considerations

  • Besides the user's identity, you cannot propagate additional authentication context with the X.509 certificate.
  • The X.509 certificate is only secure if it is directly used by the issuer of the certificate or propagated via a trusted environment to the using party. For further details about X.509 user certificates, see chapter Dynamic X.509 certificate generation AuthState.

SAML assertion

The SAML (2.0) assertion is very similar to the Nevis SecToken, but with the following differences:

  • It is a standard, defined by( and supported by major vendors (e.g., Oracle WLS 10.3, IBM WAS 6.1).
  • It additionally allows encryption and uses corresponding standards (XML signature and XML encryption, as defined by(
  • It can be federated to a different domain if used in conjunction with the SAML 2.0 protocol.
  • XML overhead is huge compared to the Nevis SecToken. The SAML assertion is therefore not suitable for per-request propagation. Instead, use SAML for non-interactive SSO session transfer.

The SAML assertion is appropriate in a federated architecture, where Nevis works together with external third-party services. Together with these external services, Nevis builds an identity federation. These are some possible use cases:

  • nevisAuth issues a SAML 2.0 assertion as an identity provider (IdP), to allow secure hand-over of the user's identity to an external trusted party.
  • As a consumer or service provider (SP), nevisAuth accepts a SAML assertion issued by an external trusted party as the user's proof of authentication. nevisAuth uses the assertion to establish an authentication session in the local environment and to allow the user access to applications in the back end.

For further details about SAML tokens and plug-in, see SAML AuthStates.Session management

Upon the start of the authentication nevisAuth creates a session. This is an initial session as long as nevisAuth did not yet finish the user authentication. Whenever a user is successfully authenticated, nevisAuth upgrades the initial session to an authenticated session. It also issues the SecToken. If the authentication failed, the initial session is discarded.

The session data is stored in a session cache, together with the data on the SecToken (or another proof of authentication). To track the authenticated user, Nevis sends a cookie to the client browser, which the browser must submit on any subsequent request. By means of the cookie as well as all information on the SecToken and in the session cache, the session management facilities of nevisAuth and nevisProxy can detect inactivity of the user and trigger a re-authentication. It is possible to terminate the session as well, e.g., if the SecToken is expired.

Single sign-on

nevisAuth also facilitates single sign-on (SSO). Single sign-on means that the user has to log in only once to be able to access multiple web applications in the back end.

To set up single sign-on within Nevis, you have to group your applications into something we call an SSO realm. The authentication happens per SSO realm. If a user is granted access to one application in a realm, he has access to all applications within this realm.

This concept not only allows the user to have to authenticate just once. It also supports upgrading of the authentication strength, such that the authentication method used for the realm is stronger than the in

Nevis recognizes the applications belonging to a realm by their URLs (internet addresses). See.

nevisAuth single sign on

To authenticate the user, nevisAuth only needs the user's password for the realm Extranet. Upon successful authentication, the user has access to all three applications app1, app2 and app3. But because of the application path "…/app1" in the URL, Nevis knows that the user wants to use application app1. Thus, nevisProxy is able to forward the user's request to the right application within the realm.


To access the authentication service of nevisAuth, Nevis offers various secure interfaces or APIs (Application Programming Interface).

Most requests to authenticate a user enter nevisAuth via nevisProxy and the Nevis Authentication Interface, which is a SOAP service (see the. SOAP stands for Simple Object Access Protocol and is a network protocol to exchange data.

nevisAuth APIs

But there are several other possibilities to access nevisAuth directly. For example, Microsoft clients using the WS-Trust protocol may access nevisAuth through the WS-Trust facade. Clients within a virtual private network (VPN) that uses the RADIUS protocol may access nevisAuth through the RADIUS facade. The API concept of nevisAuth makes the implementation of the above examples and many other use cases possible.

Architecture – how does it work?

nevisAuth's core responsibility is to process authentication requests. Basically, nevisAuth consists of a broad range of plug-ins, the AuthStates. The AuthStates are the building blocks of the authentication process and can be combined in all kinds of variations and sequences. This allows you to implement exactly the kind of authentication you need to protect your applications in an optimal way: as strong as required and as user-friendly as possible.

During the authentication process, the user's login data passes different AuthStates. Each AuthState has one particular responsibility, e.g., to authenticate a user against a certain authentication back end, to manipulate a request, to store information, etc. The AuthState also forwards the data to the next step in the authentication process.

Basically, each AuthState receives input, processes it and produces output (which is the input for the next AuthState). This goes on and on, until the last AuthState within the authentication process is reached.

A specific combination of AuthStates with an entry AuthState, a last AuthState and several AuthStates in between, builds a domain (see. A domain may perform the authentication process for just one application in the back end, or for several applications at once. The latter case facilitates single sign-on. Here, the domain resembles the SSO realm.

nevisAuth architecture

An authentication process starts as soon as an authentication request enters nevisAuth via nevisProxy, or via one of the other interfaces/APIs. The Authentication Engine, or AuthEngine, is responsible for dispatching the request to the first AuthState, as well as transitioning the request from one AuthState to the next. The AuthEngine also identifies whether an AuthState requires more information from the user.

Eventually, the AuthEngine constructs a response for nevisProxy. There are three types of responses:

  • AUTH_CONTINUE The AuthEngine requires more input from the user to continue processing. This results in the generation of a new GUI descriptor and page, which is sent to the user.
  • AUTH_DONE The AuthEngine could finish the authentication successfully. This results in the issuing of a SecToken.
  • AUTH_ERROR The AuthEngine detects an error. No user input can circumvent this error. nevisAuth stops the authentication process. This results in an error message.

Authentication events

The authentication process of nevisAuth consists of the following authentication events:

  • authenticate The authenticate event includes the initial login procedure that associates a user and his credentials with a global session. The user can also be associated with a set of security roles. This event is triggered by nevisProxy or by a client that accesses nevisAuth through an API, such as the WS-Trust webservice API.
  • stepup The stepup event occurs if the user does not have a required security role for the application he wants to access. Establishing the step-up can take place with or without user interaction. Just as the authenticate event, also the stepup event is triggered by nevisProxy or by a client that accesses nevisAuth through an API, such as the WS-Trust webservice API.
  • unlock The unlock function provides a minimal re-authentication procedure that offers a minimal screen saver functionality on an established user session. This event is triggered by nevisProxy when a session exists, but the re-authentication interval is reached. Also a client that accesses nevisAuth through an API can trigger an unlock event.
  • logout In case of the logout event, the system terminates the global session and notifies all session members to remove resources associated with the global session or user. This event is triggered by nevisProxy when a user explicitly performs a logout.

Note that the termination of a session due to a time-out is no authentication event.

Additional functionality

Besides its core function of processing authentications, nevisAuth provides additional functionality (or resources, see:

  • Token assembler The task of the token assembler is to generate SecTokens. It is possible to configure different token assemblers for different authentication processes (domains). Which fields are stored on the SecToken, e.g., user roles, authentication level, token expiration time, signature key, depends on the token assembler's configuration.
  • Key management SecTokens, SAML assertions and other types of tokens are cryptographically signed. The signing of such tokens happens with a private key, whereas the verification takes place with the corresponding public key. To refer to such public and private keys, nevisAuth gives each private and public key an ID. nevisAuth uses these short IDs on the SecToken and in AuthStates, instead of the keys' own long and complex directory- and file names.
  • Audit and log files Nevis logs all authentication related audit events like login ok, login failure, logout, time-out or killed in an audit log. It is possible to log each operation of the AuthEngine, AuthStates and other parts of nevisAuth in the audit log or in a debug log file. If desired, the system forwards both log files to central log and audit servers.
  • Shared out-of-context data In certain scenarios, it is necessary to keep user and authentication data for a longer period of time than just one session, e.g., in a setup with authentication tokens from third parties, such as SAML assertions. SAML assertions are valid for a longer period of time. To prevent that a SAML assertion is used more than once, e.g., by an attacker, nevisAuth stores the assertion in the out-of-context data store upon first usage, until the assertion expires. For each incoming SAML assertion, nevisAuth performs a look-up in the out-of-context store. If the assertion was already used, access is denied.