Guides

Account Defense - Login

The NeuroID JavaScript Library is customized for your Site Id and hosted on NeuroID servers. It enables specific versions of the library as per your configuration.

Suggest Edits

Account Defense

The account defense integration should be used on the login flow of your web application, as well as post login flows that should be protected.

Authentication

Basic authentication is used, and your key will be integrated into your configuration, loaded by the JS snippet you're using. For any questions, contact our Implementation Engineering team at [email protected].

Integration Steps

The following steps will walk you through implementing the NeuroID JavaScript Library.

1. Install the JavaScript with the Collection SiteId

If this is the first time you are integrating with the JS library, you must load the collection snippet. If you already have configured a collection snippet on your application, you can skip to step 3.

<!-- The following Snippet is for Test Purposes Only -->
<script type="text/javascript">
  (function(n,e,u,r,o,i,d){
       n.nid=n.nid||function(){(n.nid.q=n.nid.q||[]).push(arguments)};
       o=e.createElement(u);i=e.getElementsByTagName(u)[0];o.async=1;
       o.src=r;i.parentNode.insertBefore(o,i);
  })(window,document,'script','//scripts.neuro-id.com/c/nid-YOUR_COLLECTION_SITEID_HERE-test.js');
</script>

<!-- The following Snippet is for Production -->
<script type="text/javascript">
  (function(n,e,u,r,o,i,d){
       n.nid=n.nid||function(){(n.nid.q=n.nid.q||[]).push(arguments)};
       o=e.createElement(u);i=e.getElementsByTagName(u)[0];o.async=1;
       o.src=r;i.parentNode.insertBefore(o,i);
  })(window,document,'script','//scripts.neuro-id.com/c/nid-YOUR_COLLECTION_SITEID_HERE.js');
</script>

Embed this JavaScript snippet within the <head> section of your webpage. This snippet may be retrieved from the JavaScript Installation Settings page in the NeuroID Portal or copied from here.

2. Update the JavaScript with your Collection SiteId

The Collection SiteId is the siteId used to collect data across all flows of your web application.

If you copy the snippet from here, you must update your JavaScript snippet URL. Your URL will look similar to: //scripts.neuro-id.com/c/nid-abcde123.js.

If you copied your snippet from the NeuroID Portal, please continue to Step 3.

If you receive a siteId from NeuroID in the format form_abcde123, you need to remove form_ prefix before using for example the value e.g. abcde123 in your JS snippet.

📘

A NeuroID siteId uniquely identifies the Application form for which behavioral data is collected. The format consists of the prefix form_ followed by five characters and then three numbers (e.g.,form_abcde123). It is important that you do not reuse a siteId across multiple forms or applications. Each must be unique.

Collection SiteId - The siteId used to collect data across your web application

Use Case SiteId - The siteId used to designate different flows of your application. For example: onboarding, login, navigation, account details.

👍

Your JavaScript snippet URL will look similar to

//scripts.neuro-id.com/c/nid-abcde123.js.

In this example, the siteId would be form_abcde123.

3. Set LinkedSiteId with your Use Case siteId

The setLinkedSiteId command sets data collection for a given use case.

nid('setLinkedSiteId', 'siteId');

4. Store NeuroID sessionId

NeuroID sessionId identifier is automatically generated as soon as the NeuroID JavaScript loads and data collection auto-start.

❗️

Storing NeuroID sessionId

The NeuroID dashboard and alerts use a generated NeuroID identifier as the primary key for user tracking and analytics. You can retrieve this identifier programmatically using the following command:

nid.getUserId();

Additionally, the NeuroID identifier (nid_sid) is stored in the browser's session storage. You can access it directly from there if needed.

To ensure seamless tracking and integration, the NeuroID identifier must be linked to your internal customer identifier. This allows for a unified view across your internal systems and the NeuroID platform.

This identifier is essential for reviewing NeuroID dashboards and alerts.

5. Label Input Fields

Ensure you use descriptive names for your input fields. These will be used during configuration to identify each input field. If you do not have descriptive names, we recommend incorporating unique, stable, and descriptive data-nid-target attributes into your input fields, e.g., data-nid-target="username" if the input field is a username field. Please refer to our data-nid-target documentation for more information.

6. Record Attempted Login

The attemptedLogin command logs both successful and unsuccessful login attempts upon pressing the "Login" button. This command should be used whenever a login attempt occurs.

  nid('attemptedLogin');

An optional value may be passed to record the attempted Id that was used to login. This should correspond to the Id that was attempted, but should not be the exact Id. A cryptographically secure hash is acceptable.

  nid('attemptedLogin', 'attempted_registered_user_id');

If the optional id fails validation, it will be replaced with scrubbed-id-failed-validation. A LOG event will also be sent signaling that the id failed validation.

7. (Optional) Set RegisteredUserId

The RegisteredUserId value is now set via the NeuroID API call instead of through the frontend integration.

Optionally use the setRegisteredUserId command to set a unique identifier to profile a registered users behavior:

  nid('setRegisteredUserId','registered_user_id');

❗️

RegisteredUserId must be in your system after a user authenticates.

A registeredUserId must correspond to a userId in your system, but should not be that exact Id. Do not set the registeredUserId as a true userId, as this can be personally identifiable information. The best practice is to use an existing alternate id that corresponds to a user, or a cryptographically secure hash of the userId.

Additionally the registeredUserId must only be set after a successful authentication has occurred. This may be after a successful one-time password.

❗️

RegisteredUserId must be valid

A customer set registeredUserId must meet all the following requirements:

  • Must be a string value
  • Must consist of only alphanumeric characters, dashes, underscores, or periods
  • A minimum length of 3-characters
  • A maximum length of 100-characters
  • Must not contain any PII

If the registeredUserId fails validation, it WILL NOT be set. A LOG event will be sent to the backend signaling that the registeredUserID failed validation, with the reason that it failed validation.

JavaScript Installation Complete 🎉

Your JavaScript installation is now complete.
Please contact NeuroID at [email protected] to complete your site's configuration.

Visit the Advanced Functions documentation to learn more about NeuroID JavaScript functions not covered here.

Updated about 2 months ago