Skip to main content

Set up the Authentication widget

This guide describes the following tasks:

  • Make the necessary API calls to create an intent token.
  • Load and instantiate the Authentication Widget (auth.js).
  • Verify and confirm the authentication operation.

Preparation​

You need to have the following information available:

  • Instance ID (see Endpoint documentation)
  • Access Key (see Authentication documentation)

You will also need to include auth.js script for the widget to work, the script URL is: https://<instance-id>.mauth.nevis.cloud/widget/auth.js.

Requesting an Intent Token [Server-side]​

Your backend needs to make the necessary API call to request an intent token for a specific user, and pass it back to the widget so it can perform the action.

Access Key vs. Intent Token

Your Access Key needs to remain securely protected in your backend application and only be used to create ephemeral Intent Tokens that can be exposed to the user's browser via the widget. This setup is necessary to maintain the security of your users and applications.

Do not, under any circumstance, share your Access Key with others or expose it publicly. It provides full access to your Auth Cloud instance.

Create an enrollment intent​

You will need to request an Intent Token for each transaction with the widget. These one-time tokens are specific to each user and each purpose thus increasing security and preventing your API access key from being exposed in the web app. The following REST calls return an intent token that can be used by the widget once, within ten minutes, for the given username and for the given purpose. For details on how to make the necessary API calls, see Intent endpoint.

The logic of your web app needs to determine the username of the end-user and the purpose of their visit: enroll a new user or approve a transaction. It can be supplied by the user or be provided as part of a more complex flow, such as single sign-on. These two pieces of information are required for the intent token request your backend needs to make to the your Auth Cloud instance.

Replace u12345 with the username you have received on your backend
curl "https://$instance.mauth.nevis.cloud/api/v1/intent" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  -H 'Content-Type: application/json' \
  -d "{ \"username\":\"u12345\", \"operation\":\"enroll\" }"

From the received response forward the token attribute to the browser, to create the NevisAuthWidget.

Instantiating the Widget [Client-side]​

The page that creates an Authentication Widget instance needs to do the following high-level steps.

  • Load the auth.js script.
  • Receive a valid Intent Token from the backend for the user's purpose.
  • Create a widget configuration, with a resultCallback function to capture the response.
  • Instantiate a new NevisAuthWidget object with that config.
  • Respond to the result returned by the widget.
  • The following sections explain how to perform each step.

Loading auth.js​

For the widget to work, the auth.js script needs to be loaded in your web app. You can either load it whenever the page loads, or work out a more sophisticated mechanism to only load it when required.

Replace $instance_id with your instance ID
<script src="https://$instance_id.mauth.nevis.cloud/widget/auth.js" async />
info

If you have a Content Security Policy (CSP), see the section on how to set up the Authentication Widget Content Security Policy for details on how to set up and make sure the Authentication Widget is working.

Creating a widget configuration object​

The widget config needs to have the following data items, some of which are static, while others are dynamic.

The resultCallback is the callback function that is called with the result of the operation by the widget once it is finished. You need to create this function as part of your web app. The result contents enable you to decide whether the authentication or the enrollment was successful. The result has the following members: success, code and message and may have an optional token and a data member.

The intentToken is a one-time authorization token for a specific user and a specific operation.

The customization object is static and it has two members. The color specifies the primary brand color of the widget in hex format, secondary and tertiary colors are calculated based on the primary. The logoUri can be a network URL pointing to the desired logo using https, or a data URI containing the logo, in one of the following formats: data:image/png;base64,, data:image/jpeg;base64,, data:image/svg+xml;base64,, data:image/svg+xml;utf8,.

Instantiating the widget in Preview Mode

You can instantiate the widget without an intent token if and only if the operation is specified as preview. This aims to speed up the branding phase of the development. Note that the widget allows for limited branding and not full customization of all visual elements.

Example widget configuration

const myResultCallback = (result) => {
  if (result.success) {
    // result.code ->
    //    "success-001" is a enrollment,
    //    "success-002" is an approval.

    // Send result.token back to your backend to verify!
  }
  else {
    // Handle the error, you can find more details in result.code
    alert("There was a problem: " + result.code);
  }
};

// Assembling the configuration object
const config = {
  resultCallback: myResultCallback,

  // This is the token received from the Auth Cloud via your backend
  intentToken: token,

  // The customisation is the same among all invocations
  customisation: {
    color: '#168CA9',
    logoUri: 'https://my-brand.com/assets/logo.svg',
  }
};
info

For a complete list of all error codes, see the Authentication Widget (auth.js) Reference.

Starting the Widget​

In your web app, you need to create a new NevisAuthWidget object with the previously set configuration. For example, the onClick event of the Register / Log in button would instantiate the widget:

const widget = new NevisAuthWidget(config);`

The user will then go through the selected process and will either successfully authenticate or the process will fail. Once the process is complete and the widget is closed, the result of the transaction, whether or not the enrollment or authentication succeeded, is passed to the resultCallback.

Responding to the Widget Results​

On the client side, the widget will call your resultCallback callback function with the result of the widget action. Your front-end needs to react appropriately to the results: it needs to proceed with the login or the registration on success, or must handle the error gracefully on failure. The result will always contain a message and a status code, and in the case of success, it may have a data member with additional information, such as the userId for a new user registration.

Make sure to forward token to your backend for verification of the operation and complete the operation in your backend.

Structure of the Response Object Your Callback Function will be called with the following:

{
      success: true,
      code: 'success-001',
      description: 'Successful registration.',
      // the token is always present in successful cases, and in some error cases
      token: '<jwt token>',
      // only present in some cases, has case-specific content
      data: {
            userId: '<the id of the new user>',
      },
}

Verify the operation [Server-side]​

To increase the security of authenticating transactions, each successful authentication also returns a token as part of the response that can be used to verify the authenticity of that transaction. This guarantees that the Auth Cloud API provided the response. Check the token against the API before the transaction is executed in your systems.

To perform this check, your frontend needs to send the token to your backend, and your backend needs to validate the token with the Authentication Cloud API. If it is valid, you can finalize the transaction and also confirm to the user that it has been successful.

For more information, visit:

Last updated on