Geolocation#

The Geolocation feature enables adaptive authentication using geographical data. More adaptive login methods can be used by leveraging the geographical data provided by the Geolocation component. Using this data, measures can be taken based on the fact that a user is potentially logging in from a country never attempted to login before, a different country since last login, a forbidden country, or has made an impossible journey between two sequential login events. Geographical data can also be used to determine which authentication methods should be available to the user.

Geolocation Database File#

In order to provide geographical data, a locally maintained IP geolocation database is needed. This database will be a separate file that will exist in the filesystem of each Curity Identity Server run-time node. The admin should copy the file to the $IDSVR_HOME/etc folder of each node and the database file should be named geolocation.mmdb. Copying the file on the filesystem is a requirement in order to the Geolocation feature to function as expected. Lack of this database file will result in errors if any geolocation feature is used. New versions of the database file are provided on a regular (weekly) basis, and the file should be updated on each of the running nodes.

To obtain this, go to the Downloads area of the Curity Developer Portal as shown in the figure below:

There, for any particular release greater than or equal to 5.1.0, you can find the geolocation database as an additional file at the bottom of the page. This is depicted in the figure below:

If you do not have a license to use the geo-location database, the Download button will be disabled. In such a case, a license can be obtained by contacting sales.

Because this database changes every week, it is important to setup automated downloads of the database file to each run-time node. This can be done using the API. The API call needed is shown on the Info page and under the downward chevron of the Download button. This API is protected with an API access token. To obtain one that lasts for a prolonged period of time, surf to your profile in the top right corner of the portal. There, you can issue a token that will last for one year. Use it when authenticating to the release API to download the geolocation database in an automated fashion.

Whenever the geo-location database is updated, those changes must be deployed within a month.

Geolocation Actions#

As for the rest of the authentication actions, Geolocation actions present a set of tools for orchestrating what happens after authentication but before the session is committed. For that purpose, each action is providing different geographical data to enforce the admin to configure an authentication action tailored to each use case’s needs.

Geolocation Allow or Deny Country Action#

The Allow or Deny Action can be used to allow or deny authentication based on the country of origin of a request. For more information refer to Geolocation Allow or Deny Action.

Geolocation Changed Country Action#

The Geolocation Changed Country Action can be used to enforce additional measures when the user attempts to login from some other country than they were during their last login. For more information refer to Geolocation Changed Country Action.

Geolocation Impossible Journey Action#

The Geolocation Impossible Journey Action can be used to enforce additional measures when the user attempts to login from another location that is impossible to have travelled from, since their last login. For more information refer to Geolocation Impossible Journey Action.

Geolocation New Country Action#

The Geolocation New Country Action can be used to enforce additional measures when the user attempts to login from another location that they have never logged in before. For more information refer to Geolocation New Country Action.

Set Geolocation Attribute Action#

The Set Geolocation Attribute Action (set-geolocation-attribute) resolves the geographical data (city name and country ISO code) for the requester’s IP address and exposes it as an attribute. Subsequent actions in the pipeline can then read this data.

The location and name of the attribute are configurable:

  • target — the required location where the resolved geolocation is written: SUBJECT_ATTRIBUTES, CONTEXT_ATTRIBUTES or ACTION_ATTRIBUTES.
  • attribute-name — the name of the attribute to write the geolocation to (default geolocation). This is treated as an attribute path, so a name such as requester.geolocation creates a nested attribute.

The attribute is written only when a country can be resolved for the requester’s IP address. Its value is an object with a countryIsoCode string field and a city string field that is included only when a city is available, for example:

{
  "city": "Stockholm",
  "countryIsoCode": "SE"
}

Geolocation authenticator filter#

The Geolocation Authenticator Filter can be configured to allow or deny specific countries to use a configurable list of authenticators. For more information refer to Geolocation Authenticator Filter.

Geolocation authenticator settings#

These settings allow or deny an authenticator to be used, depending on the location of the request. For more information refer to Geolocation Authenticator Settings.

Using Geolocation from a Plugin#

Custom plugins can resolve locations with the same geolocation data that the built-in actions and filters use. The SDK exposes this as the GeolocationProvider service, in the se.curity.identityserver.sdk.service package.

The service needs no configuration of its own, and it is available to every plugin type — authenticators, authentication actions, claims providers, token issuance authorizers and the rest. A plugin obtains it by declaring a getter on its Configuration interface, in the same way as any other plugin service:

package com.example;

import se.curity.identityserver.sdk.config.Configuration;
import se.curity.identityserver.sdk.config.annotation.Description;
import se.curity.identityserver.sdk.service.GeolocationProvider;

public interface ExampleConfiguration extends Configuration {
    @Description("Resolves the location of an IP address")
    GeolocationProvider getGeolocationProvider();
}

Geolocation is a licensed feature, and the database file described above has to be installed. A plugin must therefore check isAvailable() before it looks anything up, and fall back to not using location data when the check fails. A lookup made anyway throws a GeolocationException stating what the installation lacks, which is distinct from a lookup that simply found nothing:

if (configuration.getGeolocationProvider().isAvailable()) {
    Geolocation location = configuration.getGeolocationProvider()
            .getGeolocation(ipAddress);

    String country = location != null ? location.countryIsoCode() : null;
}

A lookup returns null when the address has no known location, and throws a GeolocationException only when the lookup could not be performed at all. Individual details are optional in turn: an address may resolve to a country but not to a city.

Every lookup takes an IP address literal, IPv4 or IPv6. Host names are never resolved, so a value taken straight from a client-controlled source such as an X-Forwarded-For header or a token claim cannot cause a name resolution.

A value that is not an IP address literal is rejected with an IllegalArgumentException, rather than reported as an address with no known location. The two are different facts: the first says the plugin was given something that is not an address, the second says the database does not cover it. A plugin passing on a client-controlled value — an X-Forwarded-For header, a token claim — should either validate it first, or catch the exception and treat the request as location unknown:

String country;

try {
    Geolocation location = provider.getGeolocation(ipAddress);

    country = location != null ? location.countryIsoCode() : null;
}
catch (IllegalArgumentException e) {
    // the value was not an address, so nothing is known about where the request came from
    country = null;
}

A well-formed address that the database does not cover is not an error. Such a lookup returns null. A plugin that makes a security decision must therefore treat a null result as location unknown, and never as proof that the request did not come from a particular country.

The coordinates on a resolved location are not the position of the requester. They are the centre of the smallest area the address could be attributed to — a postal area, a city, a region, or an entire country — and accuracyRadiusKm() states how large that area is. Two addresses in the same city may carry different coordinates, and an address that resolves only to a country carries the centre of that country. A plugin that measures distance must read the accuracy radius as well, and treat a location with no radius, or a radius coarser than the decision needs, as unusable.

For more information about geolocation, refer to the resources section of the Curity Web site and view this video.

Was this helpful?