Nevis Components
As outlined in High-Level Architecture, Nevis Mobile Authentication depends on Nevis components to provide FIDO UAF authentication functionality. This section describes the involved Nevis components in more detail.
nevisProxy
nevisProxy serves as an authentication gateway in the Nevis Mobile Authentication solution.
Endpoint Protection
In nevisProxy the protection of an endpoint is done by configuring an IdentityCreationFilter for this endpoint.
This filter makes sure that whoever accesses this endpoint must be authenticated according to the rules defined in this specific nevisAuth configuration.
This typically means that you add the following configuration blocks:
- Definition of the
IdentityCreationFilter. - Mapping of the
IdentityCreationFilterto a certain nevisProxy endpoint.
Request Dispatching
Incoming FIDO requests must be dispatched from the incoming URL path to the nevisFIDO server with a specific URL path to the use case (for example registration).
This means that the followings must be defined:
- An
HttpsConnectorServlet. - Mapping of the
HttpsConnectorServletto a certain nevisProxy endpoint.
SecToken Delegation
Nevis Mobile Authentication use cases involve sending requests to the nevisFIDO server. Typically, requests must pass through the nevisProxy component, which does the dispatching of the incoming request to nevisFIDO.
However, simply redirecting the incoming request to nevisFIDO is not enough if the user session has already been issued a SecToken by nevisAuth (for example in Registration and Deregistration).
Thus nevisProxy must be configured to pass along existing SecToken together with the incoming request (DelegationFilter). Otherwise nevisFIDO is not aware of the complete context.
For more details see the nevisFIDO Reference Guide nevisProxy configuration section.
nevisFIDO
The nevisFIDO component is responsible for conducting all server-side processing related to the FIDO UAF Protocol. That is, within Nevis Mobile Authentication nevisFIDO functions as a FIDO UAF Server.
In addition, nevisFIDO provides services that augment the FIDO UAF Protocol properly. For example, the notion of tokens and token endpoints allows implementation of flows where one leg of a FIDO UAF conversation happens out-of-band.
FIDO UAF Processing
As a FIDO UAF Server, the primary task of nevisFIDO is specification-conformant processing of FIDO UAF messages.
The complete reference for FIDO UAF version 1.1, can be found in the FIDO UAF specificationn t The entire specification contents apply to nevisFIDO, with the qualifications noted in Functional Adaptations of the FIDO UAF Specification.
FIDO UAF processing being the main task of nevisFIDO, the authentication policy, metadata, AppId and Facets are defined in the nevisFIDO configuration.
In addition to the messages and endpoints prescribed in the FIDO UAF Specification, nevisFIDO exposes a few proprietary HTTP endpoints and extensions to cover extended use cases. These are documented in full detail in the nevisFIDO Reference Guide.
Authenticator Custom Credentials
The nevisFIDO component does not itself manage authenticator registrations containing the public key material. It delegates storage concerns to the nevisIDM component.
However, the authenticator data model, as used during FIDO UAF processing, must be agreed on between nevisFIDO and nevisIDM, and so a nevisIDM custom credential is introduced in Nevis Mobile Authentication.
In terms of setup and configuration, the custom credentials requires an additional setup step in the nevisIDM database, where the FIDO custom credential must be made available.
nevisAuth
Within Nevis, nevisAuth is responsible to orchestrate authentication flows, perform authentication and issue tokens as proof of authentication (known as SecTokens). Participating in Nevis Mobile Authentication is no different – except that handling of the FIDO UAF Protocol messages is delegated to nevisFIDO. From a UAF Protocol's perspective, nevisAuth is responsible for dispatching UAF protocol messages to nevisFIDO and processing its results.
In a FIDO UAF authentication scenario, nevisAuth authenticates the end user with the help of nevisFIDO. This is implemented by the FidoUafAuthState which is released as part of nevisFIDO. It abstracts certain aspects of UAF message handling and coordinates with nevisFIDO regarding the FIDO operations. The FidoUafAuthState basically acts as a bridge between the FIDO authentication operations in nevisFIDO and the traditional Nevis world. In addition to FIDO authentication, the FidoUafAuthState also supports transaction confirmation scenarios.
The FidoUafAuthState is capable of connecting to a single nevisFIDO instance. If a certain use case requires the configuration of multiple nevisFIDO instances, each will require different nevisAuth instances respectively (or different realms in the same instance). FidoUafAuthState establishes a connection with nevisFIDO using the HTTP facade of nevisFIDO. It is expected that the FidoUafAuthState and nevisFIDO establish a secure TLS connection since the integrity of the authentication operation heavily relies on it.
Within Nevis Mobile Authentication, nevisAuth is also involved if authentication for certain endpoints of nevisFIDO is required. As an example, legacy authentication is required from the end user to be able to initiate a FIDO registration process. This is to avoid that an attacker could initiate and successfully complete registrations on behalf of an arbitrary user. For an exhaustive list of endpoints that need to be protected, refer to the Default HTTP API Endpoints chapter.
Only nevisAuth is able to issue authentication tokens within a Nevis environment. Thus, all authentication driven FIDO operations must interact with nevisAuth at some point.
For a detailed guide on how the configuration of nevisAuth within a Nevis Mobile Authentication solution works, refer to the Use Cases and Best Practices section of this document.
nevisIDM
nevisIDM is the component in charge of managing the identities. Nevis Mobile Authentication allows these identities ( notably the users) to authenticate using their mobile devices (where the relying party client application is installed). So, it can be considered that nevisIDM extends its authentication capabilities thanks to Nevis Mobile Authentication. Every application using the identities stored in nevisIDM to authenticate, benefits from this new capabilities.
From another perspective (notably regarding nevisFIDO) nevisIDM is acting as a persistent storage for the registered authenticator credentials. nevisFIDO will create, remove and modify these credentials.
It is assumed that the user is already defined in nevisIDM, before FIDO credentials can be created (e.g. nevisFIDO will not perform itself any user enrollment in nevisIDM).
FIDO UAF Credentials Data Model
The following figure outlines the high-level data model of nevisIDM for handling FIDO credential objects. Note that this model is a simplification of the internal nevisIDM data structure.
Responsibilities
In terms of who is responsible for the data to be supplied, the previously described data structure can be split into two categories:
| Expected to be supplied | Handled by nevisFIDO |
|---|---|
|
|
Detailed Data Model Information
A client represents a separated population of users. From a nevisFIDO point of view, the client is not very important apart from the possibility to configure it. Some customers use nevisIDM in multi-client mode.e core about multi-client mode and its limitations can be found in the FIDO Application and Nevis Components section.
A user represents a person or person's account.
In all FIDO use cases throughout the whole process, the user is identified by extId which is the external numeric identifier (not to be confused with the human-readable user_id). Therefore, from a FIDO point of view, extId is the only important attribute from the user entity.
A credential is a piece of data (of various types) which can be used to authenticate a user during a login process. There are two types of credentials from a nevisFIDO point of view:
- Credentials used in the legacy login (not handled by nevisFIDO).
- Credentials generated during a registration operation, allowing the user to authenticate with a FIDO UAF Authenticator.
In the nevisFIDO context, the second credential type is of interest: the credential mainly stores the public key generated by the Authenticator.
For more details on the exact nevisIDM data model, see the nevisIDM reference guide.
Out-of-band Dispatching Data Model
nevisIDM stores dispatch targets in a dedicated entity, the Dispatch Target. The following figure outlines the high-level data model of nevisIDM for handling the Nevis Mobile Authentication dispatch target objects. Note that this model is a simplification of the internal nevisIDM data structure.
A FIDO UAF credential references the dispatch target of the app installation it was registered with. One dispatch target can be used by several FIDO UAF credentials of the same user, and a FIDO UAF credential can also exist without a dispatch target. Both entities additionally carry the deviceId attribute, which identifies the device. The mobile client application supplies it during registration. For more details, see the chapter Change Device Information in the Mobile Authentication Client SDK documentation.
Earlier releases stored dispatch targets and iOS App Attestation data as nevisIDM generic credentials. nevisFIDO no longer supports them. Existing generic credentials must be migrated before nevisFIDO is upgraded, see Migrating Dispatch Target From Generic Credentials to Dedicated Entities.
Responsibilities
The dispatch target information supplied is solely the responsibility of a third party application or a Nevis Mobile Authentication Client. nevisFIDO creates, modifies and deletes the Dispatch Target entities in nevisIDM on behalf of the client, through the Dispatch Target Service and the FIDO UAF registration.
Detailed Data Model Information
As the concepts of Client and User have been described in the above chapter, they will be omitted.
A dispatch target identifies a "receiver" of out-of-band messages and is directly bound to a known user. A dispatch target represents an installation of a mobile application on a device, for example the Access App on a physical mobile device.
The following attributes of the Dispatch Target entity are relevant for Nevis Mobile Authentication:
| Attribute | Notes |
|---|---|
| extId | The external identifier of the Dispatch Target entity in nevisIDM. FIDO UAF credentials reference the dispatch target with this value. |
| identification | The dispatch target identifier generated by nevisFIDO. This is the dispatch target ID that the nevisFIDO HTTP APIs use. |
| name | Human readable name of the device, for example Pixel 9 of Jane. |
| appId | The FIDO UAF AppID of the nevisFIDO instance that created the dispatch target. |
| deviceId | The optional identifier describing the device. The same value is stored in the FIDO UAF credentials registered on the device. |
| target | The target identifier of the channel. This is only used for the FCM push token. The attribute contains the value user-disabled in case the user opted out of receiving push messages. |
| dispatcher | The name of the dispatcher used to reach the device. It must match the type of a dispatcher configured in nevisFIDO, for example firebase-cloud-messaging for the FCM Dispatcher. |
| encryptionKey | The public key (JWK) of the mobile application. nevisFIDO uses it to encrypt the token before sending it through the dispatcher. The private key stays on the device. |
| signingKey | The public key (JWK) of the mobile application. nevisFIDO uses it to verify the signature of requests that the mobile application signs, for example to update the dispatch target. The private key stays on the device. |
| userAgent | The user agent of the Nevis Mobile Authentication SDK used by the mobile application. |
| state | active or disabled. |
On iOS, when App Attestation is used, nevisFIDO stores the attestation data as the App Attestation of the dispatch target. A dispatch target has at most one App Attestation.