Notify User of Login From New Device or Location

1. Introduction

In this tutorial, we’re going to demonstrate how we can verify if our users are logging in from a new device/location.

We’re going to send them a login notification to let them know we’ve detected unfamiliar activity on their account.

2. Users’ Location and Device Details

There are two things we require: the locations of our users, and the information about the devices they use to log in.

Considering that we’re using HTTP to exchange messages with our users, we’ll have to rely solely on the incoming HTTP request and its metadata to retrieve this information.

Luckily for us, there are HTTP headers whose sole purpose is to carry this kind of information.

2.1. Device Location

Before we can estimate our users’ location, we need to obtain their originating IP Address.

We can do that by using:

• X-Forwarded-For – the de facto standard header for identifying the originating IP address of a client connecting to a web server through an HTTP proxy or load balancer
• ServletRequest.getRemoteAddr() – a utility method that returns the originating IP of the client or the last proxy that sent the request

Extracting a user’s IP address from the HTTP request isn’t quite reliable since they may be tampered with. However, let’s simplify this in our tutorial and assume that won’t be the case.

Once we’ve retrieved the IP address, we can convert it to a real-world location through geolocation.

2.2. Device Details

Similarly to the originating IP address, there’s also an HTTP header that carries information about the device that was used to send the request called User-Agent.

In short, it carries information that allows us to identify the application type, operating system, and software vendor/version of the requesting user agent.

Here’s an example of what it may look like:

User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 
  (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36

In our example above, the device is running on Mac OS X 10.14 and used Chrome 71.0 to send the request.

Rather than implement a User-Agent parser from scratch, we’re going to resort to existing solutions that have already been tested and are more reliable.

3. Detecting a New Device or Location

Now that we’ve introduced the information we need, let’s modify our AuthenticationSuccessHandler to perform validation after a user has logged in:

public class MySimpleUrlAuthenticationSuccessHandler 
  implements AuthenticationSuccessHandler {
    //...
    @Override
    public void onAuthenticationSuccess(
      final HttpServletRequest request,
      final HttpServletResponse response,
      final Authentication authentication)
      throws IOException {
        handle(request, response, authentication);
        //...
        loginNotification(authentication, request);
    }

    private void loginNotification(Authentication authentication, 
      HttpServletRequest request) {
        try {
            if (authentication.getPrincipal() instanceof User) { 
                deviceService.verifyDevice(((User)authentication.getPrincipal()), request); 
            }
        } catch(Exception e) {
            logger.error("An error occurred verifying device or location");
            throw new RuntimeException(e);
        }
    }
    //...
}

We simply added a call to our new component: DeviceService. This component will encapsulate everything we need to identify new devices/locations and notify our users.

However, before we move onto our DeviceService, let’s create our DeviceMetadata entity to persist our users’ data over time:

@Entity
public class DeviceMetadata {
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;
    private Long userId;
    private String deviceDetails;
    private String location;
    private Date lastLoggedIn;
    //...
}

And its Repository:

public interface DeviceMetadataRepository extends JpaRepository<DeviceMetadata, Long> {
    List<DeviceMetadata> findByUserId(Long userId);
}

With our Entity and Repository in place, we can start gathering the information we need to keep a record of our users’ devices and their locations.

4. Extracting our User’s Location

Before we can estimate our user’s geographical location, we need to extract their IP address:

private String extractIp(HttpServletRequest request) {
    String clientIp;
    String clientXForwardedForIp = request
      .getHeader("x-forwarded-for");
    if (nonNull(clientXForwardedForIp)) {
        clientIp = parseXForwardedHeader(clientXForwardedForIp);
    } else {
        clientIp = request.getRemoteAddr();
    }
    return clientIp;
}

If there’s an X-Forwarded-For header in the request, we’ll use it to extract their IP address; otherwise, we’ll use the getRemoteAddr() method.

Once we have their IP address, we can estimate their location with the help of Maxmind:

private String getIpLocation(String ip) {
    String location = UNKNOWN;
    InetAddress ipAddress = InetAddress.getByName(ip);
    CityResponse cityResponse = databaseReader
      .city(ipAddress);
        
    if (Objects.nonNull(cityResponse) &&
      Objects.nonNull(cityResponse.getCity()) &&
      !Strings.isNullOrEmpty(cityResponse.getCity().getName())) {
        location = cityResponse.getCity().getName();
    }    
    return location;
}

5. Users’ Device Details

Since the User-Agent header contains all the information we need, it’s only a matter of extracting it. As we mentioned earlier, with the help of User-Agent parser (uap-java in this case), getting this information becomes quite simple:

private String getDeviceDetails(String userAgent) {
    String deviceDetails = UNKNOWN;
    
    Client client = parser.parse(userAgent);
    if (Objects.nonNull(client)) {
        deviceDetails = client.userAgent.family
          + " " + client.userAgent.major + "." 
          + client.userAgent.minor + " - "
          + client.os.family + " " + client.os.major
          + "." + client.os.minor; 
    }
    return deviceDetails;
}

6. Sending a Login Notification

To send a login notification to our user, we need to compare the information we extracted against past data to check if we’ve already seen the device, in that location, in the past.

Let’s take a look at our DeviceService.verifyDevice() method:

public void verifyDevice(User user, HttpServletRequest request) {
    
    String ip = extractIp(request);
    String location = getIpLocation(ip);

    String deviceDetails = getDeviceDetails(request.getHeader("user-agent"));
        
    DeviceMetadata existingDevice
      = findExistingDevice(user.getId(), deviceDetails, location);
        
    if (Objects.isNull(existingDevice)) {
        unknownDeviceNotification(deviceDetails, location,
          ip, user.getEmail(), request.getLocale());

        DeviceMetadata deviceMetadata = new DeviceMetadata();
        deviceMetadata.setUserId(user.getId());
        deviceMetadata.setLocation(location);
        deviceMetadata.setDeviceDetails(deviceDetails);
        deviceMetadata.setLastLoggedIn(new Date());
        deviceMetadataRepository.save(deviceMetadata);
    } else {
        existingDevice.setLastLoggedIn(new Date());
        deviceMetadataRepository.save(existingDevice);
    }
}

After extracting the information, we compare it against existing DeviceMetadata entries to check if there’s an entry containing the same information:

private DeviceMetadata findExistingDevice(
  Long userId, String deviceDetails, String location) {
    List<DeviceMetadata> knownDevices
      = deviceMetadataRepository.findByUserId(userId);
    
    for (DeviceMetadata existingDevice : knownDevices) {
        if (existingDevice.getDeviceDetails().equals(deviceDetails) 
          && existingDevice.getLocation().equals(location)) {
            return existingDevice;
        }
    }
    return null;
}

If there isn’t, we need to send a notification to our user to let them know that we’ve detected unfamiliar activity in their account. Then, we persist the information.

Otherwise, we simply update the lastLoggedIn attribute of the familiar device.

7. Conclusion

In this article, we demonstrated how we can send a login notification in case we detect unfamiliar activity in users’ accounts.

The full implementation of this tutorial can be found over on Github.