Skip to main content
Version: 3.8.x.x RR

Authentication Cloud

The Nevis Authentication Cloud provides authentication as a service. It extends your infrastructure with passwordless authentication and transaction signing services.

In terms of the SDK, several integration scenarios are possible depending on your specific use case. The SDK supported use cases of registration, authentication, transaction confirmation and deregistration can all be achieved with the mobile application as the trigger of the operation, or with one of these operations initiated from another backend system.

Tokens explained​

The authentication cloud returns several different tokens for different purposes, you'll need to have a basic understanding regarding the purpose of the tokens as you will encounter them in the integration scenarios.

The two tokens of most importance you will encounter in the mobile authentication integration scenarios are the status and transaction tokens.

  1. Status token

    The status token allows you to "track" the status of registration or approval operations. It is returned by the Auth Cloud registration endpoint as enrollment.statusToken and the Auth Cloud approval endpoint as statusToken.

    The status token serves two purposes, it is used to poll the Auth Cloud status endpoint to verify the status of the original operation and to obtain the transaction token from the same status endpoint.

  2. Transaction token

    The transaction token contains the verifiable result of the current status. It is returned by the Auth Cloud status endpoint as token.

    Use this token with the Auth Cloud introspect endpoint after the status endpoint reports the desired state as final verification.

In-app scenarios and the Authentication Cloud​

From a conceptual point of view, the Authentication Cloud only supports out of band scenarios. However, the SDK provides convenience APIs for registration, which behave as if the operation was executed in-band by encapsulating the calls required for registration against the Authentication Cloud HTTP API.

In-app registration​

The in-app registration scenario describes how a user registers the mobile application to use FIDO UAF-based authentication. As registration requires an authenticated user, the scenario involves the user first authenticating using an existing means of authentication.

  1. The first HTTP API call to the cloud backend is done against the Auth Cloud registration endpoint. This endpoint is usually called by another backend application, for example a custom backend to start a user enrollment. The user enrolment is necessary to create the user in the backend before an actual mobile authentication registration can be performed.
  2. Your backend passed the enroll response back to your mobile application. The SDK will use this to perform the actual registration. It makes sense to temporarily store the enrollment.statusToken for verifying the enrolment status at the very end.
  3. You use the SDKs Auth Cloud API registration operation to start the actual registration process. The process will involve asking the user to provide biometric, PIN or device passcode authentication information.
  4. After the SDK notifies that the registration completed successfully, the app must send the enrollment.statusToken to the custom backend which in turn uses the token to call the Auth Cloud status endpoint to obtain the transaction token.
  5. The token (transaction token) returned by the status endpoint is now used to obtain the introspection result from the Auth Cloud introspect endpoint to verify whether the operation was really executed and completed successfully by your Authentication Cloud instance.
tip

  • Concept

    For more information regarding the registration concept, see the SDK Concept Guide chapter.

  • Mobile SDK Developers

    For hands-on information on how to use the SDK to achieve in-app registration, see the Developer Guides Operations chapter.

  • Authentication Cloud API

    For more information regarding the Authentication Cloud API, visit Register Your Mobile App.

In-app authentication​

After registration, the user is able to authenticate in-app using FIDO UAF-based authentication. First, the mobile application initiates the authentication flow by contacting the backend. This is usually done through a custom backend, such as a custom application or API gateway.

  1. You use the SDKs authentication operation to start the authentication process. The process will involve asking the user to provide biometric, PIN or device passcode authentication information.
  2. After a successful authentication, the SDK will return a JWT containing the transaction token. To validate the token, call the Auth Cloud introspect endpoint.
  3. The custom backend should add measures to prevent replay attacks, for example only accepting tokens issues in the last 30 seconds or keeping a list of already checked tokens.
tip

Out-of-band registration​

  1. The first HTTP API call to the cloud backend is done against the Auth Cloud registration endpoint. This endpoint is usually called by another backend application, for example a custom backend to start a user enrollment. The user enrolment is necessary to create the user in the backend before an actual mobile authentication registration can be performed.
  2. The Nevis Authentication cloud returns the enroll response to your backend. The enrollment.appLinkUri contains the link required for the registration process. The enrollment.statusToken can be used to check the enrollment progress.
  3. The appLinkUri link can be displayed to the user as clickable link in cases the user operates on a mobile device or rendered in a QR code to allow the user to scan the code using the mobile application or the mobile phones' camera app.
  4. The statusToken obtained in step 2 is used to poll the Nevis Authentication cloud backend using the Auth Cloud status endpoint. By polling the status, your custom backend and web application will be able to determine when the registration was completed successfully and proceed afterwards with your scenario, like showing the user a success message or redirecting them.
  5. During an ongoing registration, the status API will return pending, indicating that the registration has not been completed yet and has not failed so far.
  6. You use the SDKs out of band registration operation to start the actual registration process. The process will involve asking the user to provide biometric, PIN or device passcode authentication information. The SDK requires the appLinkUri for this, which the app needs to pass after the link has been clicked or the QR code scanned.
  7. After the user completed the out-of-band registration in the mobile application, the Auth Cloud status endpoint will return succeeded alongside the transaction token.
  8. The token (transaction token) returned by the status endpoint is now used to obtain the introspection result from the Auth Cloud introspect endpoint to verify whether the operation was really executed and completed successfully by your Authentication Cloud instance.
tip

  • Concept

    For more information regarding the registration concept, see the SDK Concept Guide chapter.

  • Mobile SDK Developers

    For hands-on information on how to use the SDK to achieve out-of-band registration, see the Developer Guides Operations chapter.

  • Authentication Cloud API

    For more information regarding the Authentication Cloud API, visit Register your mobile app.

Out-of-band authentication​

  1. The first HTTP API call to the cloud backend is done against the Auth Cloud approval endpoint. This endpoint is usually called by another backend application, for example a custom backend to start a user authentication. The channel defines how the message should be transmitted.
  2. The Nevis Authentication cloud returns the approval response to your backend. The appLinkUri contains the link required for the authentication process. THe qrCode contains a base64 encoded image which can be rendered. The statusToken can be used to check the enrollment progress.
  3. The appLinkUri link can be displayed to the user as clickable link in cases the user operates on a mobile device, otherwise the qrCode can be rendered to allow the user to scan the code using the mobile application or the mobile phones' camera app.
  4. The statusToken obtained in step 2 is used to poll the Nevis Authentication cloud backend using the Auth Cloud status endpoint. By polling the status, your custom backend and web application will be able to determine when the authentication was completed successfully and proceed afterwards with your scenario, like showing the user a success message or redirecting them. The response also contains the token which can be used with the Auth Cloud introspect endpoint.
  5. During an ongoing authentication, the status API will return pending, indicating that the authentication has not been completed yet and has not failed so far.
  6. You use the SDKs out-of-band authentication operation to start the actual authentication process. The process will involve asking the user to provide biometric, PIN or device passcode authentication information. The SDK requires the outOfBandPayload for this which the app needs to pass either after the link has been clicked or the QR code scanned.
  7. After the user completed the out-of-band authentication in the mobile application, call the Auth Cloud introspect endpoint using the statusToken received in step 2. The introspect endpoint will reply with active indicating the successful authentication. Additionally, the backend should add measures to avoid replay attacks, like only accepting tokens issues in the last 30 seconds, keeping a list of tokens already checked or similar measures.
Status vs introspect endpoint
  • The status endpoint provides information of an ongoing operation. In addition, it returns the token which can be used to query the introspect endpoint.
  • The introspect endpoint is used to check whether a token is valid, and whether the token was actually issued by your Authentication Cloud instance.

The custom backend should call either the status or the introspect endpoint depending on the scenario progress.

tip

  • Concept

    For more information regarding the out-of-band authentication concept, see the SDK Concept Guide chapter. Be aware that link, QR code or push messages are available for out-of-band authentication.

  • Mobile SDK Developers

    For hands-on information on how to use the SDK to achieve out-of-band authentication, see the Developer Guides Operations chapter.

  • Authentication Cloud API

    For more information regarding the Authentication Cloud API, visit Mobile App.

  • Authentication Cloud Concept

    For more information about available authentication methods, visit the Authentication methods comparison chapter.

Transaction confirmation

The FIDO transaction confirmation is technically the same as a FIDO authentication, but additional information is present in the authentication information request, which gives the user details of the transaction.

For this reason, this chapter does not separately list the transaction confirmation flows. See the Concept Operations chapter for additional details.

Last updated on