Skip to main content

Authentication

Once a user has registered a mobile device, that device can be used to authenticate. Nevis Mobile Authentication supports two authentication use cases, and each has its own nevisAdmin 4 pattern.

Which one applies depends on where the user is:

  • If the user is working in a mobile application, and that application calls a protected REST service, use in-band authentication.
  • If the user is working in a web browser, and a web application has to be protected, use out-of-band authentication. The browser and the mobile device are then two separate channels, which is where the name comes from.

In-band authentication​

In-band authentication protects a backend resource that a mobile application calls, typically a REST service. The mobile application usually embeds the Nevis Mobile Authentication SDK.

The flow is as follows:

  1. The user opens the mobile application and accesses a protected resource for which there is no authorization yet.
  2. The mobile application prompts the user to authenticate.
  3. The mobile application sends a request to /auth/fidouaf.
  4. The user is authenticated, and the mobile application can access the protected REST service.

Configuring the realm​

Add an In-band Mobile Authentication Realm pattern to your project. It behaves like a regular authentication realm, but it can protect only REST Service and Mobile Deregistration Service patterns.

The most important settings are:

  • nevisFIDO: assign the nevisFIDO UAF Instance pattern that provides the in-band authentication services.
  • nevisAuth: assign the nevisAuth instance in which the authentication flow is configured.
  • Key Store and Trust Store: configure the client TLS connection from nevisAuth to nevisFIDO. The pattern has further key and trust store fields for the connections from nevisProxy to nevisAuth and to the login renderer.
  • Login Renderer: in Kubernetes deployments the assignment of a nevisLogrend Instance or a Proxy Login Renderer pattern is mandatory. In classic virtual machine deployments a default renderer is created when no pattern is assigned.
  • Application Access Tokens: tokens assigned here can be created after successful authentication. To forward such a token to an application backend, reference the same token from the Additional Settings property of the application.
  • The session timeout fields, Initial Session Timeout, Authenticated Session Timeout and Max Session Lifetime, control how long the user stays authenticated.

Before a user can authenticate this way, the mobile device has to be registered. Set up the registration APIs with the In-band Mobile Registration Service pattern, as described under Registration.

Out-of-band authentication​

Out-of-band authentication protects a web application. The user works in a browser, and the authentication is confirmed on the mobile device.

The Out-of-band Mobile Authentication pattern is an authentication step, not a realm. Add it to the Initial Authentication Flow of the authentication realm that protects the web application.

The step cannot come first

The user has to be determined before this step is reached, so it cannot be the first step of a flow. Place one of the following in front of it:

Configuring out-of-band mobile authentication without a preceding step is not supported. If it were reachable with a username alone, anyone could trigger push notifications to the mobile device of that user.

If you want a flow that starts without a username at all, use the Usernameless Out-of-band Mobile Authentication pattern instead. That step can be the first step, because it shows a QR code and a link rather than asking for a user. See Out-of-Band Usernameless Authentication.

Choosing the channel​

The Channel setting decides how the authentication request reaches the mobile device:

  • Link / QR-Code: nevisFIDO renders a QR code server-side. The user scans it with the camera app or the Access App, or, on a single device, follows a link.
  • Push / QR-Code: the user receives a push notification, and a QR code is shown as a fallback for the case that the notification does not arrive.
  • Link / QR-Code (legacy): deprecated. Use Link / QR-Code instead.

A fetch channel also exists, in which the app pulls pending operations from the backend. For an overview of all of them, see Channels.

If push notifications do not reach the device, the backend can fall back to another channel. See Dispatching for Out-of-Band Operations - Push Notification Fallback.

Push notifications​

Push notifications are delivered through Firebase Cloud Messaging, so a Firebase service account has to be uploaded into the Firebase Push Configuration field of the nevisFIDO UAF Instance pattern. See nevisFIDO Setup for the pattern side.

Whether you use a Nevis-managed or a self-managed Firebase project changes what you have to provide. That decision, and its consequences for the app, is described in Push Support. The provider documentation is the Firebase documentation.

Number matching​

Enable Number Matching to have a four-digit number displayed in the browser that the user has to enter on the mobile device. This confirms that the browser and the mobile device belong to the same session, which is what Out-of-Band Channel Linking describes. It is disabled by default. For the app side, see Number Matching.

Further settings​

  • Virtual Host: assign the virtual host that serves the domain to which the app sends /nevisfido/token/redeem/authentication. That domain is built into the mobile application and 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.
  • nevisFIDO: assign the nevisFIDO UAF Instance pattern.
  • User Name: nevisFIDO uses this value to look up the user in nevisIDM. Depending on how the nevisFIDO UAF Instance pattern is configured, this is either the extId or the loginId.
  • Policy: the name of a policy provided by the assigned nevisFIDO instance. If left empty, the policy default is used. See Policy configuration examples.
  • Authentication Level: applied on success, and relevant only when an authorization policy is assigned to applications.

The step has three failure exits, which you can wire to a fallback authentication:

  • On Cancel, taken when the user clicks cancel.
  • On Client Failure, taken on a timeout, a failed authentication or a client error such as an authenticator that does not comply with the policy.
  • On Dispatch Failure, taken when nevisFIDO cannot hand out a link or render a QR code, or when the dispatch target no longer exists, for example because the credential was deleted in nevisIDM.

To decide at runtime whether a user authenticates with a password or with the mobile device, see Legacy or Mobile Authentication Based on the User Registration Status.

Login templates​

Out-of-band authentication needs browser-side logic, for example to select a mobile device, so the login page has to load the JavaScript that the pattern relies on. The default login template of the authentication realm already includes it, so if you leave the Template Customization field of the authentication realm empty, there is nothing to do.

If you use a custom template, you have to include the same resources yourself. Download the default template in your authentication realm, unpack the archive and search for mauth in the *.vm files to find the places involved.

For what the JavaScript does and how to embed it in your own pages, see Integrating the JavaScript Client Application in Out-of-Band Login Flows.

What the user does on the device​

In both use cases the user confirms the authentication with a FIDO UAF authenticator on the mobile device. Which one is available depends on the device and on the policy configured in nevisFIDO. See Authenticators, Biometric authentication with passcode fallback and PIN authenticator.

Next steps​