Integration with Nevis Components
This page covers two integration scenarios: JWT bearer token authentication for the NinjaAuthenticationFilter servlet filter (used with nevisProxy), and direct embedding of Ninja in Nevis components (nevisIDM, nevisMeta, and nevisFIDO).
JWT bearer token authentication
Nevis Configuration Patterns can generate the nevisAuth JWTToken authstate configuration required to produce a JWT after authentication. However, nevisProxy still relies on the Nevis SecToken for its own session and authentication process — the JWT is an additional token forwarded to the backend application alongside the existing SecToken-based flow. Native end-to-end JWT support in nevisAuth and nevisProxy, where the SecToken is no longer required, is planned for a future release.
The internal channels between nevisAuth and other Nevis components (nevisIDM, nevisMeta, nevisFIDO) also continue to use SecTokens during this preview phase. JWT is not yet supported on those paths.
In a Nevis environment, JWT tokens are produced by nevisAuth and forwarded by nevisProxy to the backend application, where the NinjaAuthenticationFilter verifies them. The end-to-end flow is:
- The user authenticates through nevisProxy to nevisAuth.
- nevisAuth runs a
JWTTokenauthstate that creates a signed JWT and stores it in a session output attribute (for exampleout.MyServiceJWT). - nevisProxy forwards the JWT to the backend application as an
Authorization: Bearerheader using aHeaderDelegationFilter. TheDelegateSecTokenparameter on theIdentityCreationFiltermust be set tofalseso that nevisProxy does not also forward the SecToken. - The Ninja filter receives the
Authorization: Bearer <jwt>request, verifies the signature and claims, and establishes the principal.
Signing key patterns
Two signing patterns are in use depending on the scenario:
HMAC shared secret — used when both sides (nevisAuth and the backend Ninja filter) can share a secret out-of-band. The same secret string must be configured in the nevisAuth JWTToken authstate (token.key) and in the Ninja filter (jwt.verify.sig.key.type=hmac, jwt.verify.sig.key.value=<secret>). The secret must be at least 32 bytes (256 bits) when encoded as UTF-8.
RSA asymmetric key — used when the backend can trust the nevisAuth signing certificate without a shared secret (for example, when the backend already has the nevisAuth signer certificate). The nevisAuth JWTToken authstate references the existing DefaultKeyStore/DefaultSigner key and signs with RS256. The Ninja filter is configured with jwt.verify.sig.key.type=pem (or jks) pointing to the authSigner certificate.
Example: HMAC shared secret
nevisAuth esauth4.xml JWTToken authstate:
<AuthState name="MyServiceJwtTokenCreate"
class="ch.nevis.esauth.auth.states.jwt.JWTToken"
final="false">
<ResultCond name="ok" next="AuthDone"/>
<property name="token.key" value="my-service-hmac-shared-secret-v1"/>
<property name="out.issuer" value="nevisauth"/>
<property name="out.subject" value="${request:loginId}"/>
<property name="out.audience" value="my-service"/>
<property name="token.outputAttributeName" value="out.MyServiceJWT"/>
<property name="token.outputAttributeScope" value="outargs"/>
</AuthState>
nevisProxy web.xml delegation filter:
<filter>
<filter-name>MyServiceJwtDelegationFilter</filter-name>
<filter-class>ch::nevis::isiweb4::filter::delegation::HeaderDelegationFilter</filter-class>
<init-param>
<param-name>DelegateToBackend</param-name>
<param-value>Authorization: Bearer AUTH:out.MyServiceJWT</param-value>
</init-param>
</filter>
nevisProxy web.xml authentication filter (note DelegateSecToken=false):
<filter>
<filter-name>MyServiceAuthenticationFilter</filter-name>
<filter-class>ch::nevis::isiweb4::filter::auth::IdentityCreationFilter</filter-class>
<init-param>
<param-name>AuthenticationServlet</param-name>
<param-value>NevisAuthConnector</param-value>
</init-param>
<init-param>
<param-name>LoginRendererServlet</param-name>
<param-value>NevisLoginRenderer</param-value>
</init-param>
<init-param>
<param-name>Realm</param-name>
<param-value>SSO_MY_SERVICE_JWT</param-value>
</init-param>
<init-param>
<param-name>DelegateSecToken</param-name>
<param-value>false</param-value>
</init-param>
</filter>
Ninja web.xml filter (HMAC verification):
<filter>
<filter-name>NinjaAuthenticationFilter</filter-name>
<filter-class>ch.nevis.ninja.filter.NinjaAuthenticationFilter</filter-class>
<init-param>
<param-name>jwt.verify.sig.key.type</param-name>
<param-value>hmac</param-value>
</init-param>
<init-param>
<param-name>jwt.verify.sig.key.value</param-name>
<param-value>my-service-hmac-shared-secret-v1</param-value>
</init-param>
<init-param>
<param-name>jwt.verify.claims.issuer</param-name>
<param-value>nevisauth</param-value>
</init-param>
<init-param>
<param-name>jwt.verify.claims.audience</param-name>
<param-value>my-service</param-value>
</init-param>
</filter>
Example: RSA asymmetric key
nevisAuth esauth4.xml JWTToken authstate (references the existing authSigner key):
<AuthState name="MyServiceJwtTokenCreate"
class="ch.nevis.esauth.auth.states.jwt.JWTToken"
final="false">
<ResultCond name="ok" next="AuthDone"/>
<property name="token.algorithm" value="RS256"/>
<property name="keystoreref" value="DefaultKeyStore"/>
<property name="keyobjectref" value="DefaultSigner"/>
<property name="out.issuer" value="nevisauth"/>
<property name="out.subject" value="${request:loginId}"/>
<property name="out.audience" value="my-service"/>
<property name="token.outputAttributeName" value="out.MyServiceJWT"/>
<property name="token.outputAttributeScope" value="outargs"/>
</AuthState>
Ninja web.xml filter (RSA verification using the authSigner certificate):
<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>/opt/nevis/authSigner_certificate.pem</param-value>
</init-param>
<init-param>
<param-name>jwt.verify.sig.key.type</param-name>
<param-value>pem</param-value>
</init-param>
<init-param>
<param-name>jwt.verify.sig.key.value</param-name>
<param-value>/opt/nevis/authSigner_certificate.pem</param-value>
</init-param>
<init-param>
<param-name>jwt.verify.claims.issuer</param-name>
<param-value>nevisauth</param-value>
</init-param>
<init-param>
<param-name>jwt.verify.claims.audience</param-name>
<param-value>my-service</param-value>
</init-param>
</filter>
Embedded components
The following components embed Ninja directly as their token verification engine.
Nevis components use the Ninja commons library directly, not the servlet filter. This means only the options in the sectoken.*, identity.*, log.*, dev.*, and jwt.* namespaces apply. The filter.* options (such as filter.header, filter.realm, filter.authentication-optional) are filter-level concerns and have no effect here.
The HTTP header from which the component reads the token is determined by the component, not by Ninja. Unlike the servlet filter (which exposes filter.header), embedded components do not expose this through a Ninja property. However, all three components covered here (nevisIDM, nevisMeta, and nevisFIDO) implement their own jwt.header option that allows configuring which HTTP header the JWT bearer token is read from. This is useful when migrating from a non-standard header name to Authorization: Bearer or vice versa.
nevisIDM and nevisMeta
nevisIDM and nevisMeta expose Ninja options under the server.auth.ninja. prefix in their configuration files. Any common Ninja property can be set this way.
The example below shows the signer certificate setting. Refer to the example configuration templates shipped with the component for the full default configuration.
server.auth.ninja.sectoken.signer.cert=/var/opt/keybox/default/truststore.jks
During the current preview phase, the internal communication between nevisAuth and nevisIDM/nevisMeta still uses SecTokens. JWT is not yet supported on this path. sectoken.signer.cert must therefore always be configured, even in deployments where JWT is also used.
nevisFIDO
nevisFIDO configures Ninja through the fido-uaf.authorization block in its YAML configuration. The type: ninja selector activates Ninja as the authorization handler, and the options map is forwarded to Ninja as-is.
fido-uaf:
authorization:
registration:
type: ninja
options:
sectoken.signer.cert: /var/opt/keybox/default/truststore.jks
# AttributeUserGetter returns loginId if present in the token, otherwise
# falls back to the token subject (userid/extId). This matches the
# username-attribute-names: [loginId, userid] behavior from older versions.
identity.user-getter: AttributeUserGetter(source=loginId)
The same block applies independently for registration and authentication. As with the other components, only the key material (and any identity-mapping overrides) typically need to be specified here.
During the current preview phase, the internal communication between nevisAuth and nevisFIDO still uses SecTokens. JWT is not yet supported on this path. sectoken.signer.cert must therefore always be configured, even in deployments where JWT is also used.