Ninja

Concept Description and Technical Architecture

Scope of Ninja

Perimeter Authentication

In a single sign-on environment, user authentication is typically managed by a central reverse proxy (or entry server). Often, the entry server delegates the actual authentication process to a separate authentication service. Regardless of this delegation, all application servers that can be reached through the reverse proxy have to trust the reverse proxy to forward only authenticated requests. Because an application server no longer authenticates the user directly, it must at least be able to extract the user's identity from a request. Most modern application servers offer this feature, and some vendors use the term perimeter authentication for this setup.

Secure Token Delegation

To prove that a user has been authenticated, the entry server adds a so-called secure token to every request - either as a 'basic authentication' header or as a custom HTTP header. Among other things, the secure token contains authentication data about the user; it is digitally signed by the authentication service. In such an environment, the application server must only accept requests containing a valid secure token. Because the information contained in the secure token is digitally signed, any manipulation of this data is detected. After Ninja has verified the token's integrity, it knows for sure that the token has been issued by a trusted authentication service.

To achieve end-to-end security, the secure token should be propagated along the call chain. Each node or service in this chain is responsible for verifying the token.

Nevis Context

Ninja is always active within a J2EE container as part of the protected web application.

The figure below shows the role of Ninja in the Nevis context.

To explain the basic principle of Ninja, the interactions between these components may be simplified as follows:

1. The user's browser sends an HTTP request to the reverse proxy. If not yet logged on, the reverse proxy redirects the browser to a login page.
2. The actual authentication is delegated to the authentication service. Although the authentication process may consist of multiple (interactive) steps, it is simplified as one arrow in the drawing. This is because we are only interested in the result of the authentication. The authentication server returns a secure token to the reverse proxy, and this token is stored in the user's single sign-on session.
3. After successful authentication, subsequent requests of the same user are passed directly to the J2EE container, with one important addition: each request contains the secure token as an additional HTTP header. It is now Ninja's task to verify this token and to reject any invalid request.

What is Ninja?

Ninja is designed to seamlessly integrate a J2EE application platform into a Nevis protected environment. The goal is to protect an existing application without recompiling.

Ninja Commons

Ninja Commons provides the following basic functions:

• SecToken Verification
• Certificate Reader: reads one or multiple certificates from the specified certificate files, supports multiple formats, including JKS and PEM.
• Role Getter: maps and sets container-specific groups. Depending on the container, the terms "role" and "group" are used differently or are even not present.
• User Getter: allows to retrieve the user from the SecToken, for example, to take it out from a custom field.

Ninja Authentication Filter

This is the Ninja implementation as a Java Servlet Filter.

Summary

Component	package	Description
Ninja Commons	ninja-commons	Separate package for the basic functions.Depends on jcan-sectoken library, including all transitive dependencies like jcan-saml.
Ninja Authentication Filter	ninja-filter	See the Ninja Authentication Filter chapter. Depends on ninja-commons.
Ninja zip	ninja	Zip file containing ninja-commons, ninja-filter and their Nevis specific dependencies together with .pom files for all Nevis artifacts.

Ninja Features

• Secure Token Verification: Only requests containing a correct token are accepted and passed to the web application. A token is considered correct if it has been issued by a trusted authenticator and if the contained data has not been tampered with, i.e., the token is authentic.

  Often, the token is verified on the first request only. For subsequent requests, the application server identifies the original caller with the aid of a tracking mechanism (like a HTTP cookie).

• SAML Assertion Verification: Ninja can verify and consume SAML assertions instead of Nevis SecTokens. No configuration change is necessary for this, but all the JARs of the jcan-saml library (available from Nevis, notably: jcan-saml, jcan-saml-xmlbeans) must be placed in the same class path as the Ninja JARs. Alternatively this could be also achieved by using the Ninja uber JAR. Note that even though a SAML assertion (or a SAML response) is consumed, the means of communicating this message depends on Ninja and does not conform to the transport mechanisms of the SAML 2.0 protocol specification.

• Servlet Authentication: This is the simple authentication method defined in the Java Servlet specification. It uses a Principal object to identify users and in turn contains public and private credentials. The central methods for obtaining the principal and doing authorization checks are HttpServletRequest.getUserPrincipal() and HttpServletRequest.isUserInRole(String).

• JAAS Authentication: The authentication modules plug into the application servers authentication framework to support declarative and programmatic security according to the J2EE standards. The authentication results in a JAAS Subject representing the users identity and roles. All further security checks are based on this Subject. The container propagates the Subject to other tiers to achieve end-to-end security.

• Container Session Invalidation: To save valuable resources, and for security reasons, a user's application server session should be invalidated before the single sign-on session terminates (or as it terminates at the latest). Ninja can terminate the user session with an HTTP request. The kill-request is normally either sent by the authentication server or by the reverse proxy (see nevisProxy RefGuide on "LogoutURI").

• Multiple Signer Certificates: Allows the configuration of one or more trusted signer certificates, or even a trusted certificate directory. This is not only useful if the tokens to be verified are issued by more than one authentication service, but also for the transition phase when an issuer certificate expires.

• Optional Authentication: This mode of operation allows applications to respond both to authenticated and non-authenticated (anonymous) requests. A session may run for a time without authentication and then require the user to authenticate at a particular point. This may be triggered by the user accessing a protected functionality (on which optional authentication is disabled) or by the application sending a response that triggers the authentication procedure.

• Development Mode: Maintaining a Nevis environment for application development may not be feasible or wanted. The development mode (DevMode) of Ninja simulates such an integrated environment without the need for any additional components or complex configuration constructs. In DevMode, Ninja will generate a SecToken for a user request and inject user properties as configured. This is transparent to the application so that it can operate as if in an integrated setup and even use SecTokens to communicate with further servers.

Known Restrictions and Pitfalls

• Colons : in user names are not supported when Basic Authentication is used for transport.

  This restriction is caused by the HTTP Basic Authentication. HTTP Basic Authentication uses : as separator between user name and password. HTTP Basic Authentication is defined in RFC 2616.

• Tokens encoded with non-ASCII character-sets may need specific configuration (see TokenEncoding and TokenSourceEncoding) when Basic Authentication is used for transport.

  This restriction is caused by the HTTP Basic Authentication mechanism. HTTP Basic Authentication does not clearly specify the character encoding of the payload. Java by default uses ISO-8859-1 (ISO-Latin) in the methods that are typically used for decoding the Basic Auth payload so that character set can be assumed to be in use for most containers. If the token character encoding is not ISO-8859-1 (e.g UTF-8) then the configuration option "TokenEncoding" and "TokenSourceEncoding" should be set accordingly.

• JAAS login modules cannot be used for optional authentication.

  Due to the binary logic of java application container realms, it is not possible to configure "optional" authentication. If an authentication realm is configured, the authentication must be completed successfully or else no requests will be forwarded to the application.

  Also, once an authenticated identity is established, the login modules will not have contact with it. So establishing an anonymous pseudo-identity for unauthentic access and later on"'upgrading" it to a real identity is not possible.

  For scenarios that require optional or dynamic authentication, use NinjaAuthenticationFilter and its AuthenticationOptional option instead of a JAAS login module. Multiple NinjaAuthenticationFilter with and without optional authentication can be combined within the same application.

• JAAS realms must be configured for specific authentication schemes and cannot combine login modules for different authentication schemes.

  JAAS authentication separates the declaration of realm usage from the realm configuration itself. But strangely, it has the application configure the realm type. This means that an application cannot support multiple authentication methods (e.g. client-certificates and Ninja, or Ninja and Forms-based are not possible).

  For scenarios that require multiple authentication methods, use either multiple deployments (possibly with cross-application dispatching to avoid duplication) or filters instead of JAAS login modules. For example, NinjaAuthenticationFilter could be used in combination with a filter that does optional X509 client-certificate authentication.

• While simple authentication and roles usage do not require Nevis-specific code in the application, some non-trivial use cases will necessitate a few specific adaptations and dependencies on Ninja artefacts.

  Unfortunately, Java's JAAS / principal specification is very rudimentary: it only defines a simple principal name and a method for basic permissions checking. All other functionalities must be done via specialized implementation of the Principal interface.

  In the case of Ninja, this is done with the NinjaTokenPrincipal. This means that applications that require more than the JAAS specification offers need to get the Principal and cast it to NinjaTokenPrincipal to be able to do non-trivial operations (e.g. forwarding the received token to other services or extracting attribute field data).

Other Supported Platforms

Our recommendation for all non-JavaEE-based backends is to migrate to JWT as token format.

Additional documentation and examples are available in the Nevis Authentication Application Integration Guide.