Skip to main content
Version: 8.2505.x RR

Configuration - Ninja Authentication Filter

Functionality​

The NinjaAuthenticationFilter is a Java ServletFilter that can enforce authentication or optional authentication, depending on its configuration. It provides the following functionality (for details see the chapter: Ninja Features):

  • Secure Token Verification: The filter validates incoming SecTokens to establish an identity.
  • SAML Assertion Verification: The filter can validate SAML Assertions to establish an identity in the same way as SecTokens.
  • Servlet Authentication: The filter establishes a container identity according to the Java Servlet Specification (by injecting a UserPrincipal into the request instance).
  • JAAS Authentication: The filter can, if configured, establish a JAAS authentication (using the Subject.doAs() method).
  • Container Session Invalidation: The filter can be configured to invalidate sessions upon receiving requests on a particular URL path. It can respond to that by redirecting or by dispatching to an internal resource.
  • Multiple Signer Certificates: The filter can verify token signature trust using multiple configured certificates.
  • Optional Authentication: The filter can be configured to forward requests with unauthenticated sessions to the application, even if no token is provided.
  • Development Mode: This filter supports development mode (see the chapter: Development Mode)
  • JWT Bearer Token Authentication (Preview): The filter can verify JWT bearer tokens in addition to Nevis SecTokens and SAML assertions. See JWT Authentication for details. Note that Nevis Configuration Patterns can generate the nevisAuth JWTToken authstate configuration, but nevisProxy still relies on the Nevis SecToken for its own session handling. Native end-to-end JWT support in nevisAuth and nevisProxy is planned for a future release.

Authentication Filter Configuration​

The NinjaAuthenticationFilter supports all common configuration properties. In addition, the following options can be configured:

filter.header​

Legacy name: Header

Sets the HTTP header in which the filter expects the authentication token. If this is set to Authorization, then a Basic Authentication scheme is assumed and decoded.

Syntax: <header>

Default: Authorization

filter.realm​

Legacy name: Realm

If filter.header=Authorization is configured and the filter sends a WWW-Authenticate challenge, this setting defines the realm for which authentication is requested.

Syntax: <realm>

Default: Nevis

filter.authentication-optional​

Legacy name: AuthenticationOptional

Enables optional authentication that lets requests without tokens of unauthentic sessions pass. Used for scenarios where both authentic and anonymous access shall be allowed. Note that requests of unauthentic sessions with invalid tokens will always be blocked.

Syntax: true | false

Default: false

filter.cache-principal​

Legacy name: CachePrincipal

If set to true, the Principal will be stored in the session (i.e. it will be cached). Subsequent requests skip cryptographic token re-validation (signature verification and claims checks), which provides a potential performance optimization. The token expiry (exp) is still checked on every request regardless of this setting. If set to false (the default), the full token is re-validated on each request, which is the more secure approach.

When CachePrincipal is enabled, the filter automatically sets the HTTP session's idle timeout to the remaining lifetime of the authentication token. For JWT this uses the exp claim; for classic SecToken it uses the absolute expiry computed from the token's lifetime at verification time. This ensures that idle sessions expire when the token does, without relying solely on the container's default <session-timeout>. The session timeout is always bounded by the operator-configured <session-timeout> in web.xml — it is never raised above that ceiling. On re-authentication (a new token presented within an existing session), the timeout is recalculated against the original operator ceiling, so a longer-lived replacement token can restore the session up to that ceiling. If the token carries no expiry claim, the container's session timeout continues to apply unchanged. Note that active sessions (clients that keep sending requests) are not affected by this idle-timeout cap; the filter re-checks token expiry on every request in that case.

Syntax: true | false

Default: false

filter.logout-uri​

Legacy name: LogoutURI

URI path (relative to server host and application context) on that logout (session termination) should be initiated. Use this option for applications without dedicated logout facilities.

Syntax: <URL-path>

Default none

filter.on-logout​

Legacy name: OnLogout

Instruction for how to handle logout if an authentic request was detected accessing the filter.logout-uri. If filter.on-logout is not configured, the filter will respond with the simple text/plain-encoded response "session terminated".

Syntax:

  • redirect: <URL> (respond with a redirect to an fully-qualified or relative URL)
  • dispatch: <URL-path> (respond by dispatching request to a resource before invalidating the session)

Default: none

filter.on-login​

Legacy name: OnLogin

Instruction for how to handle requests of unauthentic sessions not carrying any tokens. If not set, the filter will either let the request pass (if filter.authentication-optional is enabled), with a BasicAuth challenge (if filter.header=Authorization) or respond with a 401 "Unauthorized".

Syntax:

  • redirect: <URL> (respond with a redirect to an fully qualified or relative URL)
  • dispatch: <URL-path> (respond by dispatching request to a resource)

Default: none

filter.jaas-authentication​

Legacy name: JAASAuthentication

Enables propagation of user identity with JAAS means (Subject.doAs()).

Syntax: true | false

Default: false

Integration​

Configuring applications to use Nevis Authentication Filter​

To activate the NinjaAuthenticationFilter, define the filter in the application web.xml as follows:

<filter>
<filter-name>NinjaAuthenticationFilter</filter-name>
<filter-class>ch.nevis.ninja.filter.NinjaAuthenticationFilter</filter-class>
<init-param>
<param-name>sectoken.signer.cert</param-name>
<param-value>.../path/to/truststore.jks</param-value>
</init-param>
<init-param>
<param-name>filter.logout-uri</param-name>
<param-value>/sessions/logout</param-value>
</init-param>
<init-param>
<param-name>filter.on-logout</param-name>
<param-value>redirect:/portal/logout-confirmation.html</param-value>
</init-param>
</filter>

<filter-mapping>
<filter-name>NinjaAuthenticationFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

The sample configuration defines /sessions/logout as the logout URI. The logout URI is prefixed with the application context root, and you can configure it as filter.logout-uri in nevisProxy to destroy the HttpSession when the global SSO session is terminated. For further information, see nevisProxy Reference Guide on LogoutURI.

The code for NinjaAuthenticationFilter is distributed both in the ninja-filter and in the ninja-uber packages. Distribute the JAR therein in the application web archive, or add it to the container class path. When using ninja-uber, no further JARs are needed. However, in case of ninja-filter package, the ninja-commons and all other dependencies are to be provided also.

Integration with nevisProxy​

To integrate with NinjaAuthenticationFilter, BasicAuth identity propagation needs to be configured in nevisProxy. Ninja expects the secure token as the password, while the user name must match the userid in the token.

Add the following filter to the web.xml of your nevisProxy instance and map it to the path of your application:

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

<filter-mapping>
<filter-name>DelegationFilter</filter-name>
<url-pattern>/myapp/*</url-pattern>
</filter-mapping>

Further Integration Use Cases​

The NinjaAuthenticationFilter can be used in several use cases. The following sections describe some of those scenarios and how to deploy NinjaAuthenticationFilter to enable them.

Multiple Authentication Mechanisms​

In this scenario, an application needs to allow two different authentication methods for the application resource URLs. Optional X509 client certificate authentication shall be attempted first and Ninja shall be used to perform token-based authentication as a fallback. We assume that there is a filter named CertLoginFilter that performs a login if the request is associated with a trusted and valid transport-layer client certificate and that it forwards the request without action if no such certificate is present.

The NinjaAuthenticationFilter is configured to perform JAAS authentication:

<filter>
<filter-name>NinjaAuthenticationFilter</filter-name>
<filter-class>ch.nevis.ninja.filter.NinjaAuthenticationFilter</filter-class>
<init-param>
<param-name>sectoken.signer.cert</param-name>
<param-value>...../cert.der</param-value>
</init-param>
<init-param>
<param-name>identity.role-getters</param-name>
<param-value>TokenRoleGetter</param-value>
</init-param>
<init-param>
<param-name>filter.jaas-authentication</param-name>
<param-value>true</param-value>
</init-param>
</filter>

… and the filter is mapped on all paths of the application after the CertLoginFilter:

<filter-mapping>
<filter-name>CertLoginFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
<filter-name>NinjaAuthenticationFilterSimple</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

For this simple example, this is enough to implement support for two authentication schemes.

Mixed Anonymous/Authentic Application with Dynamic Enforcement​

While many applications are designed to be either public or protected from the start, there are also situations where applications need to allow both anonymous and authentic (non-anonymous) access. Often, the anonymous parts of the application should also be informed about the user identity if the user is known (i.e. authenticated). So each sub-location of the application falls into one of the following three categories:

  • Anonymous sub-locations, where anonymous access is allowed and where requests of authentication do not need to be injected with the context of the user identity. Often, static resources or very simple query services fall under this classification.
  • Semi-anonymous sub-locations, where anonymous access is allowed, but where the access should be in the context of the user identity if the session has been authenticated. There are no declarative rules based on which a login can be enforced because only the application knows whether the request would trigger a switch from an anonymous to an authenticated session. Most pages of shop-like applications are in this category because browsing in anonymous access should be allowed, but once the user is known, additional information should be displayed.
  • Protected sub-locations, where anonymous access is never allowed and where anonymous access attempts always trigger a login-process. In a shop-like scenario, the user-profile and the checkout functionalities are examples for this behaviour.
note

The above classification applies for sub-locations which are recognizable by their request paths. If that is not the case, then the configuration must fall back to the most secure mode that permits the required functionality and the application must dynamically trigger logins where necessary. For example this could be done by the application redirecting to a protected login page.

To enable mixed authentication on an application, nevisProxy needs to be instructed to pass through unauthentic requests. This means that the IdentityCreationFilter can not be mapped on that sub-location.

<filter>
<filter-name>NevisIdmAuthenticationFilter</filter-name>
<filter-class>ch::nevis::isiweb4::filter::auth::IdentityCreationFilter</filter-class>
...
<init-param>
<param-name>StateKey</param-name>
<param-value>MyStateKey</param-value>
</init-param>
...
</filter>

<filter>
<filter-name>OptionalNinjaDelegationFilter</filter-name>
<filter-class>ch::nevis::isiweb4::filter::delegation::DelegationFilter</filter-class>
<init-param>
<param-name>DelegateBasicAuth</param-name>
<param-value>
AUTH:user.auth.UserId AUTH:user.auth.SecToken
</param-value>
</init-param>
<init-param>
<param-name>DelegateSource</param-name>
<param-value>MyStateKey</param-value>
</init-param>
</filter>

<filter-mapping>
<filter-name>AuthenticationFilter</filter-name>
<url-pattern>/myapp/protected/*</url-pattern>
</filter-mapping>

<filter-mapping>
<filter-name>OptionalNinjaDelegationFilter </filter-name>
<url-pattern>/myapp/*</url-pattern>
</filter-mapping>

The above configuration sets up a protected sub-location on /myapp/protected but allows optional authentication on all other sub-locations of /myapp/*. This is done by not mapping the IdentityCreationFilter in any non-protected sub-locations and by configuring the DelegationFilter to fetch data with MyStateKey even if a request did not pass through an IdentityCreationFilter. The DelegationFilter will not block requests, for which it can not find an authentication state, so that such requests are passed on to the application without BasicAuth header and with token.

Once the nevisProxy configuration is ready, the application can define anonymous, semi-anonymous and protected sub-locations by configuring NinjaAuthenticationFilters accordingly. The configuration example below assumes that the application has a context root of myapp so that the nevisProxy configuration shown above is matched:

<filter>
<filter-name>ProtectedLocationFilter</filter-name>
<filter-class>ch.nevis.ninja.filter.NinjaAuthenticationFilter</filter-class>
<init-param>
<param-name>sectoken.signer.cert</param-name>
<param-value>...../cert.der</param-value>
</init-param>
<init-param>
<param-name>filter.authentication-optional</param-name>
<param-value>false</param-value>
</init-param>
</filter>
<filter>
<filter-name>SemiAnonymousLocationFilter</filter-name>
<filter-class>ch.nevis.ninja.filter.NinjaAuthenticationFilter</filter-class>
<init-param>
<param-name>sectoken.signer.cert</param-name>
<param-value>...../cert.der</param-value>
</init-param>
<init-param>
<param-name>filter.authentication-optional</param-name>
<param-value>true</param-value>
</init-param>
</filter>

<filter-mapping>
<filter-name>ProtectedLocationFilter</filter-name>
<url-pattern>/protected/*</url-pattern>
</filter-mapping>

<filter-mapping>
<filter-name>SemiAnonymousLocationFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

The above enforces a protected sub-location on protected/ and allows for both anonymous and authenticated access to all other locations. To enforce the authentication of a previously anonymous session, the application might redirect to a sub-location such as /protected/login at which point nevisProxy will trigger an authentication. Or if the user has performed an authentication somewhere else within the SSO-realm already, then the user's identity will become known to all sub-locations of myapp due to the configuration of DelegationFilter and the use of the SemiAnonymousLocationFilter.