Out-of-Band Authentication
Description
Out-of-band authentication allows users to authenticate on their mobile phones. Thus, a user can authorize sessions on different devices. For example, the user gains access to the e-banking application on his laptop by authenticating via the fingerprint reader on his mobile phone.
Prerequisites
- The user must have two devices at hand. One device is a laptop, where the user must perform a legacy login. The other is a mobile device, where the user authenticates.
- A mobile application is installed on the mobile device. This mobile application must be able to handle the FIDO UAF protocol as well as push notifications.
- The mobile application has to register itself against the backend as the receiver of out-of-band messages. Chapter "Dispatch Target Management" describes this procedure.
- The user has previously registered FIDO Authenticator credentials on his mobile device. Registration can be done via In-Band Registration.
Example with Push Notification
The numbers in the description below correspond with the numbers in the next figure.
- The user opens the e-banking application in the browser on the laptop.
- The e-banking application is protected by Nevis, which renders a login page and asks for a username.
- The user provides his username.
- Now Nevis renders a page in which the user must specify the mobile device to be used for authentication.
- The user selects the mobile device to be used for authentication.
- Nevis sends a push notification to the selected mobile device.
- The user receives a push notification on the mobile device and taps it.
- The mobile application receives the push message and contacts Nevis to proceed with the FIDO authentication.
- Nevis now requests the mobile device to authenticate.
- The user performs an In-Band Authentication using the fingerprint-based FIDO Authenticator in the mobile device.
- The user completes the authentication process on the mobile device.
- Meanwhile, the client on the laptop frequently checks Nevis about the status of the user's authentication. When the user has successfully authenticated on the mobile device, the laptop client takes over again.
- Nevis allows the laptop client to access the e-banking application.
Channel Linking
The channel linking mechanism allows the end user to verify the link between devices that participate in out-of-band authentication. Currently, the visual string channel linking is the only channel linking method supported out-of-the box by Nevis Mobile Authentication.
This is how it works: The system generates a random string in the backend and sends the string to both devices used for the out-of-band authentication. Each device shows the string to the end user. The end user must confirm that the same string is presented on both devices.
The following figure illustrates the process:
The visual string channel linking in Nevis Mobile Authentication is configured in the OutOfBandFidoUafAuthState. For more details, check the nevisFIDO Reference Guide, in particular the "Channel Linking" section of the "OutOfBandFidoUafAuthState" chapter.
Out-Of-Band Mechanisms
One way of transferring authentication information to the mobile device is by means of the Firebase Cloud Messaging service (short FCM service). The example in the Technical Flow section below, for instance, shows how nevisFIDO uses the FCM service to transfer the required authentication information to the user's mobile device via a push notification. An alternative option to transfer authentication information to the mobile device is a QR code. A second alternative is a link that can be used to open the authentication application. This is a suitable option when the web browser runs in the mobile device. Nevis Mobile Authentication provides both alternatives.
You can use these different out-of-band mechanisms on their own or as a fallback for the other mechanism. It may happen, for example, that the FCM service fails because of a temporary network problem between nevisFIDO and the FCM service. In such a case, you can use the QR code approach as a fallback.
info
For more details, check the Dispatching for Out-of-Band Operations - Push Notification Fallback in this guide and the "Authentication Retry/Fallback Example" section of the "OutOfBandFidoUafAuthState" chapter in the nevisFIDO Reference Guide.
Technical Flow
The technical flow in the next figure explains the component interaction in detail. The numbers in the figure correlate with the numbers in table Out-of-band authentication steps below.
The following table describes the steps in the previous figure. The numbers in the table correlate with the step numbers in the previous figure.
| Nr. | Description | Endpoint | References |
|---|---|---|---|
| 1. | The user opens the relying party application in a browser. | - | - |
| 2. | The browser points at the protected relying party resource. nevisProxy detects that the user is not authenticated. | https://<nevisProxy-host>:<nevisProxy-port>/ebanking | - |
| 3. | nevisProxy informs the browser that a login is required and redirects to ?login. | - | - |
| 4. | The browser obtains the login page from nevisAuth. Supplying the user's username (loginid) is the minimum requirement for an out-of-band login with Nevis Mobile Authentication. Refer to the configuration snippets for more detailed information. | https://<nevisProxy-host>:<nevisProxy-port>/ebanking/?login | |
| 5. | The user provides a username (loginId). | - | - |
| 6. | The browser posts the information from the login form to nevisProxy, which forwards the request to nevisAuth. | - | - |
| 7. | The IdmUserVerifyState retrieves the user information based on the provided username in the login form. This user information is required to be able to operate with the internal user identifier in the subsequent nevisAuth AuthStates.After retrieving the user information from nevisIDM, a transition to the next AuthState is executed. | - | nevisIDM Reference Guide: - IdmUserVerifyState |
| 8. | The OutOfBandFidoUafAuthState queries the available dispatch targets in nevisFIDO. | https://<nevisProxy-host>:<nevisProxy-port>/nevisfido/dispatch/targets/ | nevisFIDO Reference Guide:- Chapter "OutOfBandFidoUafAuthState"- Chapter "Query Dispatch Target" |
| 9. | nevisFIDO queries nevisIDM for available dispatch targets for the given user based on the user's userId.A JSON list containing all available dispatch targets is returned to the browser. | - | - |
| 10. | The user selects a dispatch target, if more than one is registered. | - | - |
| 11. | The browser-side application initiates the dispatching by sending the dispatchTargetId of the selected dispatch target to nevisAuth. | https://<nevisProxy-host>:<nevisProxy-port>/ebanking/?login | |
| 12. | The OutOfBandFidoUafAuthState in nevisAuth creates a GetUafRequest for the given username. | - | nevisFIDO Reference Guide: - Chapter "OutOfBandFidoUafAuthState" |
| 13. | The AuthState calls the nevisFIDO endpoint to dispatch a token request and supplies the GetUafRequest together with the dispatchTargetId of the previously selected dispatch target.If channel linking has been enabled, the AuthState generates a random string and sends this random string in the dispatch token request. | https://<nevisProxy-host>:<nevisProxy-port>/nevisfido/token/dispatch/authentication | |
| 14. | nevisFIDO generates a redeem token and stores the corresponding GetUafRequest. The mobile application will redeem the token later on. | - | - |
| 15. | nevisFIDO obtains the dispatch target information, based on the dispatchTargetId, from nevisIDM. | ||
| 16. | nevisFIDO encrypts the data to be sent to the dispatch target with JWE, using the encryption key stored in the dispatch target for the given user. | - | - Chapter Out-of-Band Message Transmission |
| 17. | nevisFIDO sends the encrypted message to the dispatcher configured in the dispatch target (in this example to the Firebase Cloud Messaging Service) | - | nevisFIDO Reference Guide:- Chapter "FCM (Firebase Cloud Messaging) Dispatcher" |
| 18. | nevisFIDO responds to the dispatching operation with a session identifier (sessionId). This session identifier allows checking the session status later on. | - | nevisFIDO Reference Guide:- Chapter "Dispatch Token Service" |
| 19. | The sessionId is cached in nevisAuth to indicate an ongoing operation. | - | - |
| 20. | nevisAuth forwards the response from nevisFIDO to the client application in the browser.If channel linking has been enabled, nevisAuth also returns the random string generated previously (step 13). | - | nevisFIDO Reference Guide: - Chapter "Response Body" |
| 21. | The client application periodically polls the backend for status updates, by sending the sessionId obtained in step 20.If channel linking has been enabled, the client application presents the random string generated in the nevisAuth AuthState to the user. This way, the user can verify that the authentication request received in his mobile device corresponds to the one triggered from the desktop. | https://<nevisProxy-host>:<nevisProxy-port>/?login | nevisFIDO Reference Guide: - Chapter "OutOfBandFidoUafAuthState" |
| 22. | Because a session is in progress (step 19), the OutOfBandFidoUafAuthState queries the nevisFIDO status interface. | https://<nevisFIDO-host>:<nevisFIDO-port>/nevisfido/status | nevisFIDO Reference Guide:- Chapter "Status Service" |
| 23. | nevisAuth forwards the current authentication status, as responded by nevisFIDO, to the client application. This status can be translated into a progress message readable by the user. | - | - |
| 24. | Upon receiving the push message, the OS of the mobile device delegates the handling of the message to the relying party mobile client application (short: mobile client app). | - | - |
| 25. | The mobile client app uses its locally stored encryption key to decrypt the JWE encrypted message payload. | - | - Chapter Out-of-Band Message Transmission |
| 26. | If channel linking has been enabled, the mobile client application presents the random string generated in the nevisAuth AuthState to the user. This way, the user can verify that the authentication request received in his mobile device corresponds to the one triggered from the desktop.If the user does not cancel the authentication, the mobile client app uses the endpoint specified in the push message data payload to redeem the token, which is also included in the push message data payload. | https://<nevisFIDO-host>:<nevisFIDO-port>/nevisfido/token/redeem/authentication | nevisFIDO Reference Guide: - Chapter "Redeem Token Service" |
| 27. | nevisFIDO retrieves the previously stored GetUafRequest (step 14) and validates it against the existing policy. | - | - |
| 28. | A ReturnUafRequest is generated containing the AuthenticationRequest which was inquired by the GetUafRequest. | - | nevisFIDO Reference Guide:- Chapter "Authentication Request Service" |
| 29. | The loop of step 21 repeats, querying the current authentication status. | - | - |
| 30. | See step 22. | ||
| 31. | By now, the current status has changed to clientAuthenticating, indicating that the relying party mobile client application has redeemed the token and obtained an AuthenticationRequest. | - | - |
| 32. | The relying party mobile client application requests the trusted facets from the backend. | https://<nevisProxy-host>:<nevisProxy-port>/nevisfido/uaf/1.1/facets | nevisFIDO Reference Guide:- Chapter "Facets Service"FIDO Specification:- " [Facets] " |
| 33. | The request is forwarded by nevisProxy to nevisFIDO. | - | - |
| 34. | The relying party client application triggers the user authentication by presenting the authenticator(s) specified in the AuthenticationRequest. | - | - |
| 35. | The user is asked to provide the authentication credentials. | - | - |
| 36. | The assertion for the response is generated using the now unlocked private key. | - | - |
| 37. | The relying party mobile application sends the AuthenticationResponse to the backend. | https://<nevisProxy-host>:<nevisProxy-port>/nevisfido/uaf/1.1/request/authentication | FIDO Specification: - SendUAFResponse |
| 38. | nevisProxy forwards the request to nevisFIDO. | - | - |
| 39. | nevisFIDO obtains the FIDO UAF credentials from nevisIDM. | - | - |
| 40. | nevisFIDO responds to the relying party mobile client application with a ServerResponse message containing information about the authentication operation success or failure. | - | - |
| 41. | The relying party client application in the browser polls the current status (see step 21). | https://<nevisProxy-host>:<nevisProxy-port>/ebanking/?login | nevisFIDO Reference Guide: - Chapter "OutOfBandFidoUafAuthState" |
| 42. | See step 22. | ||
| 43. | Because the relying party mobile client application completed the authentication operation in step 37, the status now returned by nevisFIDO indicates authentication success. | - | - |
| 44. | nevisAuth returns the status response from nevisFIDO to nevisProxy. | - | |
| 45. | nevisProxy forwards the status response form nevisAuth to the browser application. In this example we assume the status is "succeeded", which indicates a successful authentication operation in nevisFIDO. | - | - |
| 46. | To finalise the login, the login application in the browser must now redirect to the form action. | https://<nevisProxy-host>:<nevisProxy-port>/ebanking | - |
| 47. | nevisProxy again forwards the request to nevisAuth as authentication is still ongoing. | - | - |
| 48. | nevisAuth executes a transition to the next AuthState (because of the successful authentication operation in nevisFIDO). | - | - |
| 49. | The DirectResponseAuthState sets the response payload as JSON. | - | - |
| 50. | The DirectResponseAuthState is the last AuthState in the flow. It sets the response to "AUTH_DONE". | - | - |
| 51. | The response is forwarded to nevisProxy (including the secToken) | - | - |
| 52. | nevisProxy will issue a final redirect because authentication is done. This occurs because the InterceptionRedirect property of the IdentityCreationFilter is set to "initial". | - | nevisProxy Reference Guide: - Chapter " [IdentityCreationFilter] " |
| 53. | nevisProxy sends the redirect to the browser. | - | - |
| 54. | The browser follows the redirect. | https://<nevisProxy-host>:<nevisProxy-port>/ebanking | - |
| 55. | nevisProxy forwards the request to the relying party backend application. | - | - |
Login Flow
User Agent (Browser) Perspective
The execution of the out-of-band login flow with Nevis requires a JavaScript client application on the user agent (browser) side. The following flow shows the steps taken by the JavaScript client application to conduct the out-of-band login.
The Nevis backend mentioned in the following flow is simplified. Refer to the backend flow in the previous figure for a more detailed view.
| Nr. | Description | Endpoint |
|---|---|---|
| 1. | The user opens a browser to visit an e-banking application. | - |
| 2. | The user agent issues a GET request to the relying party backend. Nevis detects that the user is not authenticated. | https://<nevisProxy-host>:<nevisProxy-port>/ebanking |
| 3. | Nevis returns an HTTP redirect to the browser. | - |
| 4. | The browser issues a GET request to /?login to perform authentication. /?login is the specified form action URL. | /?login |
| 5. | Nevis returns the login form. The form contains an input field requiring the user to provide his loginId. The user's login ID can be, for example, his username. | - |
| 6. | The user provides his loginId. | - |
| 7. | The user agent returns the data in the form to Nevis using the form post mechanism. | /?login (form action) |
| 8. | Nevis returns another form named "ooblogin". This form contains the required information for the out-of-band login as hidden fields. | - |
| 9. | The JavaScript application at the browser side detects the presence of the "ooblogin" form. This activates the out-of-band login client. From this step on, the interaction with the backend takes place between the JavaScript client and the Nevis backend, using AJAX. | - |
| 10. | The client library posts the loginId of the user to the Nevis backend. | /?login (form action) |
| 11. | The Nevis backend returns the dispatch target(s) of the user with the given loginId. | - |
| 12. | If more than one dispatch target is available, Nevis returns a selection list with all available dispatch targets. This allows the user to choose the dispatch target to receive the authentication request, for example his mobile device. | - |
| 13. | The user selects the dispatch target of his choice. | |
| 14. | The selected dispatch target (dispatchTargetId) is sent back to the Nevis backend together with the loginId and additional dispatch information. This additional information consists of a title to be shown in the push message on the mobile device. | /?login (form action) |
| 15. | The Nevis backend returns the dispatch result from the previous step. If channel linking is enabled, the channel linking information is also provided with the dispatch result information. | - |
| 16. | The JavaScript client application now schedules periodic polling to obtain status results and the current authentication status to the user.If channel linking has been enabled, the random string generated in the nevisAuth AuthState is presented to the user. | - |
| 17. | The JavaScript client application sends the fidoUafSessionId obtained in step 15 together with the loginId to the Nevis backend to query the current authentication status. | /?login (form action) |
| 18. | The Nevis backend returns the current authentication status for the given fidoUafSessionId. | - |
| 19. | If the last status query returned "succeeded", the JavaScript client application issues a browser redirect to the specified form action. | - |
| 20. | The browser issues a GET request to the specified form action URL (as a result of step 19). The Nevis backend is now able to recognize the current session as authenticated. | /?login (form action) |
| 21. | The Nevis backend issues a redirect to the URL originally requested by the user (in step 2). | - |
| 22. | The browser follows the redirect to the e-banking application. | https://<nevisProxy-host>:<nevisProxy-port>/ebanking |
Configuration Snippets
Refer to Nevis Component Configuration Examples for sample configuration snippets regarding all involved components.