Registration
Before a mobile device can be used in any Nevis Mobile Authentication operation, it has to be registered. Registration creates FIDO UAF credentials on the device and in nevisIDM, and it makes the device a dispatch target so that later out-of-band operations can reach it.
Nevis Mobile Authentication offers two registration use cases, and each has its own nevisAdmin 4 pattern:
- Out-of-band registration, configured with the Out-of-band Mobile Registration Service pattern. For the technical description, see Out-of-Band Registration.
- In-band registration, configured with the In-band Mobile Registration Service pattern. For the technical description, see In-Band Registration.
The two patterns are independent of each other. If you need both registration flows, add both patterns to your project.
Both patterns on this page expose services that an existing web application calls. If you want the self-registration flow itself, including the page that shows the QR code, use the Out-of-band Mobile Onboarding pattern instead. That pattern is an authentication step, so nevisAuth drives the flow and renders the page. See Onboarding.
This page assumes that nevisFIDO is already set up. If it is not, work through nevisFIDO Setup first.
Which registration to choose
| Out-of-band registration | In-band registration | |
|---|---|---|
| Where the user starts | In a web application in a browser | In the mobile application |
| How the device is involved | The web application renders a QR code, or hands over a link | Not applicable, the mobile application drives everything |
| Legacy login | The browser session of the web application | A REST endpoint called by the mobile application |
| Nevis Access App | Supported for production | Supported for testing only |
| Mobile SDK | Supported for production | Supported for production |
Out-of-band registration is the common choice, and it is the only registration flow supported for production use with the standard Nevis Access App. In-band registration is intended for applications built with the Nevis Mobile Authentication SDK. For the ways in which the out-of-band payload can reach the app, see Channels.
Legacy login
Both registration flows must be protected, so that a mobile device is matched onto an existing user account. That protection is usually called the legacy login, as opposed to the mobile login that is being registered.
The legacy login has to authenticate against nevisIDM, because that is where the FIDO UAF credential is stored. Use the nevisIDM Password Login pattern, or another flow that resolves the user in nevisIDM. A flow that authenticates somewhere else, for example the LDAP Login pattern, cannot be used on its own, because the registration services would have no nevisIDM user to attach the credential to.
Out-of-band registration
Add an Out-of-band Mobile Registration Service pattern to your project and fill in its fields:
- Virtual Host(s): assign the virtual host that serves the domain under which the nevisFIDO services are exposed. This domain is built into the mobile application, so it has to be communicated when ordering an Access App. The assigned virtual host is also taken into account when the Frontend Address of the nevisFIDO UAF Instance pattern is calculated.
- Authentication Realm: assign the realm that provides the legacy login. Assign the same realm that protects the web application generating the QR code, otherwise the web application is not allowed to call the registration services.
- nevisFIDO: assign the nevisFIDO UAF Instance pattern that provides the FIDO UAF services.
- Application Access Token: assign a token to propagate the authenticated user to the backend application, for example a NEVIS SecToken for applications using Ninja, or a SAML Token for applications that consume SAML responses.
The pattern exposes the following paths on the assigned virtual host:
/nevisfido/token/dispatch/registration/nevisfido/token/redeem/registration/nevisfido/uaf/1.1/facets/nevisfido/uaf/1.1/registration//nevisfido/status
QR code integration
Out-of-band registration is designed to be integrated into an existing web application. The web application obtains the registration token from nevisFIDO and renders it as a QR code, which the user scans with the mobile application.
The web application that renders the QR code is not provided by Nevis. For the calls it has to make and for ready-made snippets, see Out-of-Band Registration Client Code Examples. For the end-user side of scanning, see QR Code.
To try out the flow before you have written that web application, add an Out-of-band Device Management App pattern. It hosts a small single page application that enrolls a device over the same services. It is a testing aid only and is not ready for production use.
The application is served from the Frontend Path of the pattern, which defaults to /nevisfido/devicemanagement/. To render the device list and enroll a device it calls, in order:
| Call | Protection |
|---|---|
GET /nevisidm/api/principal/v1/me | Authenticated |
GET /nevisidm/api/core/v1/100/users/<userExtId>/generic-credentials/ | Authenticated |
POST /nevisfido/token/dispatch/registration | Authenticated, because it names the user the device is enrolled for |
POST /nevisfido/status | Public |
POST /nevisfido/token/redeem/registration | Public, sent by the mobile application |
GET /nevisfido/uaf/1.1/facets | Public, sent by the mobile application |
POST /nevisfido/uaf/1.1/registration/ | Public, sent by the mobile application |
The pattern exposes the nevisFIDO paths itself, so it also works without an Out-of-band Mobile Registration Service. You can combine it with one on the same virtual host.
The first two calls go to nevisIDM, and this pattern does not expose them. Add a nevisIDM REST Service or a nevisIDM Administration GUI pattern, and assign it the same Authentication Realm as the device management application.
This is not validated when the configuration is generated. Without it the deployment succeeds, the page loads, and the device list stays empty.
bootstrapThe nevisIDM bootstrap user, and any other user holding the nevisIdm.Root role, cannot be used here. The nevisFIDO technical user is not allowed to manage the credentials of root users, so enrollment fails for these accounts even though the configuration is correct.
Create an ordinary test user instead.
The pattern only generates its services if a Link Type is set on the nevisFIDO UAF Instance. If it is missing, generation fails with Set 'Link Type' to 'Deep Link' or 'Custom URI' in the nevisFIDO UAF Instance.
Registration on a single device
If the browser and the mobile application run on the same device, a QR code cannot be scanned. In that case the registration payload is handed over by a link instead. See Link for the end-user side, and Mobile-Only Operations with Deep Links and Custom URIs for the configuration.
In-band registration
Add an In-band Mobile Registration Service pattern to your project and fill in its fields:
- Virtual Host(s): assign the virtual host that serves as the entry point.
- Authentication Realm: assign an In-band Mobile Authentication Realm pattern, or a plain authentication realm. The assigned realm protects the path
/nevisfido/uaf/1.1/request/registration/. The assignment is required. - nevisFIDO: assign the nevisFIDO UAF Instance pattern that provides the FIDO UAF services.
- Client Name: enter the name of the nevisIDM client.
- Application Access Token: assign a token to propagate the authenticated user to the backend application.
Authentication service
Because no browser is involved, the mobile application needs a REST endpoint at which it can perform the legacy login and obtain a session cookie. With that cookie it then starts the registration.
Set Authentication Service to enabled to let the pattern generate a simple username and password flow into the assigned realm, exposed at the Authentication Service Path. This is a convenience feature with two limitations:
- The generated flow cannot be adapted.
- The password has to be active and not expired, because there is no support for an enforced password change.
For production, provide the flow yourself instead. Either expose your own flow on a separate path with a Standalone Authentication Flow pattern, or authenticate the registration through the Initial Authentication Flow of the assigned authentication realm.
For the generated configuration in nevisAuth and nevisProxy terms, see the in-band registration sections of Nevis Component Configuration Examples.
What registration creates
Successful registration creates two credentials in nevisIDM for the user:
- A FIDO UAF credential, which holds the public key of the authenticator that was used on the device.
- A Generic credential, which turns the device into a dispatch target. Out-of-band authentication and transaction confirmation use it to reach the device with a push notification. See Dispatch Target Management.
The name the user gives the device becomes the name of that dispatch target, so it is what an administrator sees in nevisIDM. See Device Name.
A user can register several devices, and the Access App can hold several accounts on one device if the multi-account feature is enabled.
To learn how the FIDO UAF protocol underpins all of this, see FIDO UAF (Universal Authentication Framework).
The Access App can show an Open registration page entry in its settings screen for users without a registered account. Provide the address of your registration web application as the Registration URL when ordering the app.