Overview

Visitor groups are a way of organizing and classifying visitors to your website. Visitors can be grouped in a variety of ways: IP address (by ranges, organizations, tags, or countries), or by visitor IDs. For example, perhaps you want visitors from Amazon's Web Services to be treated differently than visitors from residential IP addresses. Or perhaps you would like visitors from one country to see different content from visitors from a different country. Or perhaps logged in visitors would be given access to more content than anonymous visitors.

Suppose, for example, that any visitor is allowed to read three articles per month. After that limit, visitors are asked to create a free account, which allows them to read ten articles. If visitors pay for a membership, then they can read an unlimited number of articles. To support this, you might create two new visitor groups in Gatekeeper:

  • Free members
  • Paid members

Gatekeeper has a system visitor group called "any"; if a visitor does not match any other visitor group, that visitor would be classified as "any" (which can be used to represent all of the anonymous visitors).

When a user signs up for a free account, your software can add that user ID to the "Free members" group. When users pay for a subscription, your software can add the corresponding user ID to the "Paid members" group. If the user's subscription expires, your can remove the corresponding user ID from the "Paid members" group.


Visitor types

A visitor type is a category for classifying a visit. Gatekeeper uses visitor types to figure out what which visit information to check when authorizing a visit.

There are several visitor types available:

  • IP
  • Organization
  • Tag
  • Country
  • User ID

This document will cover what each visitor type is, where the data comes from, and how it can be used when creating policies.

IP

The IP type is a basic, but powerful visitor type (fuller discussion). It is difficult for a malicious actor to spoof an IP address, making it a fairly reliable source of information about the visitor. In fact, most information used for other visitor types (e.g., organization, country) is derived from IP address for this very reason.

The visitor IP address should be provided by the client with each visit authorization.

The IP visitor type can be divided into two subtypes: IP address and IP range.

An IP address represents a single user of your application, making it useful for targeted whitelisting or blacklisting.

IP addresses are expressed in IPv4 dot notation. For example, 1.2.3.4 or 99.200.55.3.

An IP range is a group of adjacent IP addresses. IP ranges can be used to quickly "tag" a set of IPs for special handling. For example, if you find that IPs in 1.2.3.0 - 1.2.3.255 are controlled by a single, malicious actor, you may choose to blacklist the entire IP range rather than each IP address individually.

IP ranges are expressed in CIDR notation. For example, a range starting with 1.2.3.0 and ending with 1.2.3.255 would be denoted as 1.2.3.0/24.

Organization

The organization type refers to the organization controlling an IP address. Organizations may be telecom companies, web hosts, governmental institutions, universities, etc.

IP to organization mappings are maintained by the regional Internet registries, who handle distribution of IP addresses.

At the moment, organization names are provided as is, making them somewhat cumbersome to use. For example, Google has 8 different organization names registered, including Google, LLC, Google LLC, google-as, etc. NetToolKit plans to normalize organization names down the road.

Tag

The tag type is a label assigned to the visitor through a variety of means. Generally, tags are applied to an individual IP address or a block of IP addresses.

Some common tags include:

  • anonymizers
  • abuse
  • organizations
  • unrouteable
  • data center
  • ISP

See a full list here.

Tags come from a variety of sources. Some come in the form of IP lists publicized by internet citizens to root out bad actors. Some are published by cloud platforms to help identify users of their services. Others are derived by NetToolKit internally. For example, an IP address may be tagged with abuse after an overenthusiastic bot attempts to crawl a page forbidden in "robots.txt".

Tags can be used to enforce harsher or more lenient rules on different types of visitors. For example, you may want to require a CAPTCHA from data center tagged visitors sooner than you would from ISP tagged visitors.

Country

The country type defines which country a visit originates from.

Like organization, the country is determined by IP address. The IP address to country mapping is maintained by the regional Internet registries.

User ID

The user ID type is used to authorize and track authenticated (i.e., logged in) users of your application.

User IDs may be provided by the client with each visit authorization, if available and applicable.

User IDs can be used to restrict access for unregistered users, whitelist authenticated users so they don't hit rate/CAPTCHA limits, or grant access to certain pages for specific users.


Caveats

Currently, visitor groups are meant to only be created through the web application. Visitor groups can, however, be updated programmatically. If requested, we would certainly consider opening programmatic interfaces so that client software can create visitor groups automatically.


Now that you've learned about group visitors, learn about classifying your content into page groups.