Onboarding

Onboarding lets a user set up mobile authentication themselves. The user sees a QR code in the browser, scans it with the mobile application, and the application registers a FIDO UAF credential. Configure it with the Out-of-band Mobile Onboarding pattern.

Unlike the other use cases in this section, this pattern is an authentication step. It renders the page that shows the QR code and then continues the flow through its On Success step, so it fits directly into an authentication flow rather than exposing services for another application to call.

For the protocol flow behind it, see Out-of-Band Registration.

Onboarding or registration

Both this page and Registration result in a registered FIDO UAF credential. They differ in who drives the flow.

	Onboarding	Registration
Pattern	Out-of-band Mobile Onboarding	Out-of-band Mobile Registration Service or In-band Mobile Registration Service
Pattern type	Authentication step	Service exposure
Who renders the page	nevisAuth, through the login renderer of the assigned authentication realm	Your own web application
How the flow continues	Through the configured On Success step	Your application decides
Use it when	You want a self-registration flow without building a web application for it	You already have a web application that should own the user experience

Choose onboarding when the user has no mobile credential yet and you want Nevis to render the flow. Choose a registration service when an existing application should call the nevisFIDO services itself.

Prerequisites

The user must already be known

This pattern looks the user up in nevisFIDO, so a user must be present in the session before the step runs. Resolve it with nevisIDM User Lookup, with nevisIDM Password Login, or with your own step.

This requirement is not validated when the configuration is generated, because there are too many valid ways to set the user. If it is missing, onboarding fails at runtime and nevisAuth logs the error out-of-band mobile onboarding failed. missing username.

A link type is required

Set Link Type on the nevisFIDO UAF Instance pattern to either Deep Link or Custom URI Link. Without one of them the scanned code cannot reach the mobile application.

Prefer a deep link for onboarding. Onboarding usually happens before the application is installed, and a deep link falls back to the browser in that case, which lets you show installation instructions. A custom URI leads nowhere when the application is missing. See Mobile-Only Operations with Deep Links and Custom URIs and Link.

Adding the pattern

Add an Out-of-band Mobile Onboarding pattern to your project and fill in its fields:

• nevisFIDO: assign the nevisFIDO UAF Instance pattern that provides the onboarding services.
• Virtual Host: assign the virtual host that serves the domain the mobile application calls. That domain is built into the application and is fixed when the application is ordered. The assignment also contributes to the frontend address calculation described below.
• On Success: the step that runs once the credential is registered.
• On Cancel: the step that runs when the user abandons the flow. Configure it so that users are not left on a dead end. The label of the cancel button is cancel.button.label, which you can translate in your realm.
• User Name: whether nevisFIDO looks the user up by extId or by loginId. This has to match how the assigned nevisFIDO UAF Instance is configured.
• Policy: the name of a policy that the assigned nevisFIDO instance provides. The default is default. See Policies.
• Key Store and Trust Store: the TLS material for the connection from nevisAuth to nevisFIDO. When both sides use automatic key management, trust is established automatically and there is nothing to configure. If you assign your own key store instead, you must also configure Frontend Trust Store on the associated nevisFIDO UAF Instance, otherwise nevisFIDO does not trust the client certificate.
• Gui Title: the label shown above the QR code. The default is the property title.signup.mauth, which you translate in the translations of your authentication realm.
• Profile ID Source: where the nevisIDM profile identifier comes from. The default works after nevisIDM Password Login or nevisIDM User Lookup.

Choosing the channel

The Channel field selects how the browser hands the onboarding data to the mobile application.

• Link / QR-Code renders the QR code server side, as a PNG produced by nevisFIDO.
• Link / QR-Code (legacy) renders the QR code in the browser with JavaScript.

The practical difference is whether a tappable link is shown next to the QR code on mobile devices, which matters when the browser and the application are on the same phone. Support for that link differs between pattern versions, so check the help text of the Channel field in your nevisAdmin 4 installation before deciding, and prefer the option that offers the tappable link if you support mobile-only onboarding.

How the frontend address is resolved

When the channel is Link / QR-Code, nevisFIDO needs its own frontend address to build the redeem URL it puts into the QR code. It is resolved in this order:

1. The Frontend Address set on the assigned nevisFIDO UAF Instance or nevisFIDO UAF Connector is used directly.
2. Otherwise the HTTPS frontend address of the single associated virtual host is used.

Automatic detection fails when no virtual host is assigned, and when more than one is assigned. In both cases, set the frontend address explicitly on the nevisFIDO pattern.

Wiring the pattern into a flow

There are two ways to reach the onboarding step.

As part of an authentication realm

Add the step to a self-registration sub-flow of your authentication realm. The realm already provides the login renderer and the template, so the generated QR code page adopts the look and feel you configured there. Customize the page through the login renderer and the translations of the realm, not through this pattern.

On a separate path

Use the Standalone Authentication Flow pattern to expose the onboarding step on its own frontend path. This suits a dedicated enrollment entry point. The flow is always executed, even when the user already has an authenticated session.

Completing a standalone flow can authenticate the caller

A successful standalone flow may authenticate the caller in the realm it is assigned to. If the flow is not meant to establish an authenticated session, assign it to a separate realm.

What happens at runtime

1. The generated page shows a QR code, rendered with the login template of your authentication realm.
2. The user scans it. If they use the camera application rather than the mobile application, a deep link takes them to a page where you can offer installation instructions.
3. The mobile application creates the credential on the device.
4. The mobile application makes sure the matching credentials exist in nevisIDM.
5. The flow continues with the configured On Success step.

Behavior in the Nevis Access App

• For how the scanned code is handled, see QR code and Link.
• Which authenticator the user ends up with depends on the policy you select. The Access App does not implement every authenticator that the SDK offers, so verify that your policy matches the application you deploy. See Authenticators.

Related topics

• Registration, for the service patterns used by an existing web application
• Policies, to control which authenticators onboarding may use
• Out-of-Band Registration, the technical background