Product guides

Getting started with Account Defender

Suggest Edits

The Account Defender setup process is closely assisted by your personal Solutions Engineer who will go through each step with you and ensure your configuration functions properly.

There are two parts to the setup process:

  1. Implementation: These are the initial steps you need to complete when you first start with HUMAN. This includes setting up your account and integrating your application with the HUMAN sensor and Enforcer.
    1. Set up your HUMAN account
    2. Integrate the sensor
    3. Deploy an Enforcer
  2. Configuration: This is where HUMAN directly adjusts your Account Defender configurations for optimal detection for your organization’s unique system. With this process, Account Defender will have the most accurate possible rate of detection while continuing to distinguish legitimate activity.

You can get started with the steps below.

Prerequisites

  • To integrate the Sensor:
    • Access to the HUMAN console, which has the Sensor’s script.
    • Access your application’s HTML or, at minimum, the <head> tag
  • To deploy an Enforcer:
    • Each Enforcer’s requirements are slightly different, but generally, you should have the necessary permissions to access and edit settings for your Edge or Origin platform. For example, the Fastly Enforcer needs you to generate Fastly API keys.

1. Set up your HUMAN account

To get started, you first need to create an account and log in to the HUMAN console. This gives you access to your application, dashboard, and other information you need for the rest of the onboarding process.

By now, you should have received an email from HUMAN with an invite link to the console. To set up your account:

📘

Note

If you don’t see an email from us, check your spam folder. If it’s still missing, contact us directly to send you a new invite.

  1. Open the email and follow the link.
  2. Log in to the console.
  3. Navigate to Platform Settings > Applications and confirm your application from your trial appears. If it doesn’t, contact HUMAN for help.
  1. If you want to add more users, navigate to Platform Settings > User management.
  2. Click Invite new user and fill out the form that appears.
  3. Click Invite user. They will receive an invite email to join your HUMAN account.

That’s it! Once you confirm your application appears in the console, you can move on to integrating your sensor.

2. Integrate the Sensor

The HUMAN Sensor is fetched by a JavaScript snippet that goes onto the website or application that you want to protect and monitor. The Sensor is an important component of the HUMAN system that collects and sends data, such as a user’s interaction with the site or a device’s behavior, and analyzes the authenticity of the device or application. Based on the legitimacy of each request, the Sensor sends an encrypted risk score to the HUMAN Enforcer. The Enforcer then blocks or allows that request based on the risk score and your policy rules.

📘

Note

While the Sensor gathers and analyzes application data, it does not block or mitigate traffic. Instead, it sends the data to the Enforcer, which blocks traffic based on the risk score. You’ll set up the Enforcer later on in the onboarding process.

Integrate the sensor in a website

  1. From the HUMAN console, navigate to Platform Settings > Applications.
  1. Click on the application you want the sensor to monitor.
  2. Under Application Settings, click Integration details. This will open your integration, Enforcer, and sensor information.
  3. Select your Integration type, either 3rd party or 1st party.
    1. If you select 1st party, ensure that the accessible route that appears is accessible on the web server.

📘

Note

If you’re not sure which type to use, then we recommend asking your Solutions Engineer for the one best suited for your environment and product.

  1. Copy the JavaScript snippet.
  2. Paste the snippet into all the domains you want to protect. We recommend that the snippet be the first script after the <head> tag, but if that’s not possible, then it should be inserted as high up in the HTML as possible.

👍

Tip

We also recommend providing Account Defender parameters via the Sensor during this process, but you can do it later on as well.

Once you’ve added the snippet, it will start sending data to your HUMAN account.

Integrate the Sensor in a mobile application

See our SDK documentation for information on integrating the Sensor on mobile apps.

Wrap up

After a few hours, you can check your Account Defender Dashboard, which should have data coming in from the Sensor. However, remember that this is only collected data and traffic; nothing has been blocked yet! To start blocking traffic, move on to Deploy an Enforcer.

3. Deploy an Enforcer

HUMAN has two methods to integrate an Enforcer:

  • Deploy Tool method: We highly recommend this method. The Deploy Tool is a lightweight kit that walks you through the installation. Your Solutions Engineer will send this kit to you. The Deploy Tool is available for our most commonly used Enforcers.
  • Manual integration: If you already have an Enforcer configuration on your platform or if your preferred platform is not supported by the Deploy Tool, you can always manually integrate your Enforcer.

👍

Tip

We also recommend providing Account Defender parameters via the Enforcer during this process, but you can do it later on as well.

Deploy Tool method

The Deploy Tool is a kit that a Solutions Engineer will send you that takes you through the deployment step by step. Depending on your platform, you may need to complete some prerequisite steps before running through the Deploy Tool. Make sure to reference your CDN’s specific Enforcer article to complete the full integration.

📘

Note

We highly recommend using the Deploy Tool if you use a supported platform. You should only use the manual integration if your platform is not supported or if you already have an Enforcer configuration deployed on your infrastructure.

You can also customize Enforcers that are supported by the Deploy Tool from the HUMAN Dashboard, which means you don’t need to redeploy the Enforcer whenever you want to change its configuration. You can learn more with our Enforcers article.

Manual integration

If your platform either:

  • Is not supported by the Deploy Tool, or
  • Already has an Enforcer deployed

Then you must manually integrate your Enforcer with your platform. Manual integration is available for every Enforcer framework. Each method is unique, and you should reference the appropriate Enforcer’s documentation to learn how to deploy it.

You can learn more with General Enforcer Information, and you can browse your full catalogue of Enforcers with Supported Frameworks.

4. Send Account Defender parameters

If you use Account Defender, you must provide certain parameters via the Sensor or Enforcer for the integration to properly profile and detect user accounts and suspicious activity. These parameters are:

📘

Note

You can provide most of the parameters via either the Sensor or the Enforcer based on your preference. However, you must send the user_id from both.

  • User ID (user_id): The unique identifier your company defines for each user. This can be any string that your company uses in your system, such as a UUID or random characters. This is used to:
    • Associate behavior profiles with specific accounts to detect abnormal behavior per account when it occurs.
    • Build demographic and peer profiles to detect abnormal behavior when new accounts are created.
  • User email address: The partial or full email address associated with the account. Account Defender verifies newly created accounts by checking this email address with reputation databases for abnormal flags. These include recently registered domains, disposable email addresses, or addresses associated with fraud or spam.
  • Account registration date: The registration date helps Account Defender determine whether there was activity on the account before AD was deployed, distinguishing between dormant and new accounts. For accuracy, we recommend using the ISO 8601 date and time format with UTC indication ('2023-11-01T07:35:52.000Z') or the Unix timestamp string ('1639087652'). If this information is not provided, our system will automatically generate it based on the observed account registration. if no registration date is available, the system will assume that the first observed traffic on a specific user account represents the registration date.

Send parameters via the Sensor

We recommend setting the above values as HUMAN custom parameters in the form window._pxParamN = "<paramN_value>" and adding them into the Sensor JavaScript snippet. You can have up to 10 parameters.

For example, to extract the value of my_cookie, you would add a custom parameter like the following:

<script type="text/javascript">
	(function(){
		window._pxAppId = APP_ID;
		// Custom parameters
		window._pxParam1 = getCookie('my_cookie');
		var p = document.getElementsByTagName('script')[0],
		    s = document.createElement('script');
		s.async = 1;
		s.src = '//client.perimeterx.net/APP_ID/main.min.js';
		p.parentNode.insertBefore(s,p);
	}());
</script>

Send parameters via the Enforcer

📘

Note

To provide parameters, you must set up the appropriate custom configurations for your Enforcer. You can reference each Enforcer’s configurations in its documentation. For example, these are the Account Defender configurations for the Cloudflare Enforcer.

User ID

To provide the user ID, the Enforcer must first extract it from the HTTP Request, where it's stored as a JSON Web Token (JWT) in a cookie or header. The Enforcer can extract the JWT fields and user_id and send them in the Risk, Page Requested, and Block activities.

To enable this functionality, you need to configure the Enforcer according to your JWT implementation.

If set on a cookie, the JWT has the following configuration fields:

  • px_jwt_cookie_name: The name of the cookie that contains the JWT token
  • px_jwt_cookie_user_id_field_name: The name of the field that contains the user ID
  • px_jwt_cookie_additional_field_names: A list of additional fields to be extracted from the JWT

If is set on a header, the JWT has the following configuration fields:

  • px_jwt_header_name: The name of the header that contains the JWT token
  • px_jwt_header_user_id_field_name: The name of the field that contains the user ID
  • px_jwt_header_additional_field_names: A list of additional fields to be extracted from the JWT

Other parameters

We recommend providing the remaining parameters as custom parameters (custom_param). You can have up to 10 custom parameters.

5. Configuration

The Configuration phase involves HUMAN directly adjusting your Account Defender configurations for optimal detection for your organization’s unique system. By completing this process, your product installation will have the most accurate possible rate of detection while continuing to distinguish legitimate activity.

📘

Note

If you ever make a significant change to your HUMAN configuration, such as adding a new account, domain, or threat type to detect, we highly recommend contacting our team at [email protected]. We’ll move your configuration back to the Configuration phase to make sure data continues to appear as expected.

If you’re not sure if a change warrants a new calibration, we encourage you to reach out to HUMAN Support.

The Account Defender Configuration phase is primarily completed by the HUMAN team. As part of this phase, the team will ensure your Sensor and Enforcer are properly sending data and that the data that appears is accurate with the Tuning process.

As part of the Tuning process, your SE will ask you for a list of endpoints on your application that are likely to have account takeover or fake account attacks. The SE might ask you for URLs for pages that are used for things like:

  • Logins
  • Updating account info
  • Making purchases
  • Updating payment methods
  • And more

After we have these URLs, we’ll incorporate them into our detection logic so Account Defender can more accurately classify attacks and incidents based on severity. Then, we’ll monitor the data that appears based on this logic and evaluate it for accuracy. At this point, your SE will be in constant communication with you to ensure the number of accounts, incidents, and other data matches your expectations.

Once the HUMAN team reaches the necessary level of confidence in the detection learning mechanism, we will notify you that Tuning is complete. Then, you can switch your Enforcer to active blocking (or monitor) mode, and your Enforcer will start to act upon blocked behavior. Once this happens, you’ve completed your onboarding!

Updated about 15 hours ago