Apereo CAS - MaxMind Geo2IP ISP Integration


Collaborate
The blog is managed and hosted on GitHub. If you wish to update the contents of this post or if you have found an inaccuracy and wish to make corrections, we recommend that you please submit a pull request to this repository.

I have been consulting on a CAS project with the main requirement of doing an integration with MaxMind GeoIP2 services.

According to the MaxMind website:

MaxMind GeoIP2 offerings identify the location and other characteristics of Internet users for a wide range of applications including content personalization, fraud detection, ad targeting, traffic analysis, compliance, geo-targeting, geo-fencing and digital rights management.

There certainly is an existing integration already with MaxMind and CAS, which is primarily giving CAS the ability to cross-check a browser-provided IP address against the MaxMind database to geolocate the request and perform additional processing later on, such as auditing the event with richer information or executing risk-based authentication decisions.

Our particular use case here was a bit different. We were presented with a MaxMind database file that contained a list of IP addresses known to be linked to VPN services and anonymous service providers. Our objective was to examine the request for the provided IP address, cross-check against the MaxMind database and ultimately present a warning to the user if a match is found. Our initial assumption was that such a warning is presented to the after the primary authentication event inclusive of any and all multifactor authentication flows such as Duo Security.

This sort of use case can easily be done in form of webflow interrupts.

CAS has the ability to pause and interrupt the authentication flow to reach out to external services and resources, querying for status and settings that would then dictate how CAS should manage and control the SSO session. Interrupt services are able to present notification messages to the user, provide options for redirects to external services, etc.

This sounds exactly like what we could use. We just need to provide our own particular interrupt services that handle the cross-examination of the IP address with MaxMind and we should be good to go. Let’s do it.

Collaborate
If you want to learn more about webflow interrupts, please see this post.

Our starting position is based on the following:

Configuration

First, we need to prepare the CAS overlay with the right set of dependencies to enable interrupt functionality and get access to the MaxMind APIs:

<dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-support-interrupt-webflow</artifactId>
  <version>${cas.version}</version>
</dependency>

<dependency>
    <groupId>com.maxmind.geoip2</groupId>
    <artifactId>geoip2</artifactId>
    <version>2.12.0</version>
</dependency>

Next, we can create our own configuration component and design the declaration of our interrupt service, tasked to talk to MaxMind APIs:

@Configuration("SomeConfiguration")
@EnableConfigurationProperties(CasConfigurationProperties.class)
public class SomeConfiguration {

    @Value("${our.maxmind.isp-file:file:/etc/cas/config/maxmind/GeoIP2-ISP.mmdb}")
    private Resource ispDatabase;

    @Bean
    public InterruptInquirer interruptInquirer() {
        return new MaxmindInterruptInquirer(ispDatabase);
    }
}

Note that out particular MaxmindInterruptInquirer gains access to the MaxMind ISP database file to be used for cross-examination of IP addresses. Obviously, we need to design the MaxmindInterruptInquirer itself:

public class MaxmindInterruptInquirer implements InterruptInquirer {
    private final DatabaseReader ispDatabaseReader;

    public MaxmindInterruptInquirer(final Resource ispResource) {
        try {
            File ispFile = ispResource.getFile();
            ispDatabaseReader = new DatabaseReader.Builder(ispFile).build();
        } catch (final Exception e) {
            throw new RuntimeException(e);
        }
    }

    @Override
    public InterruptResponse inquire(Authentication authentication,
                                     RegisteredService registeredService,
                                     Service service,
                                     Credential credential) {
        HttpServletRequest request = WebUtils.getHttpServletRequestFromExternalWebflowContext();
        String address = request.getRemoteAddr();
        /*
            Check the address in Maxmind database and return back the proper response
        */
        ...
    }
}

Here is what happens:

After all authentication flows have completed, the interrupt webflow kicks in and picks up our MaxmindInterruptInquirer component. It begins to examine the IP address linked to this request and does a look-up to find a match in the MaxMind database. If and when found, it will pass a response back up which would then get translated and stuff into the webflow available to the warning page for your user’s pleasure.

That’s it.

I should note that our requirement later on changed to present the same sort of warning before any of the authentication flows have commenced. An interesting nuance indeed, as the user must face the warning page before CAS presents the login screen and family in the browser, and one we might cover in a separate blog post.

Finale

I hope this review was of some help to you and I am sure that both this post as well as the functionality it attempts to explain can be improved in any number of ways. Please feel free to engage and contribute as best as you can.

Misagh Moayyed

Related Posts

CAS 6.1.0 RC3 Feature Release

...in which I present an overview of CAS 6.1.0 RC3 release.

Apereo CAS 6.1.x - Credential Caching & Proxy AuthN

Learn how you may configure Apereo CAS to capture and cache the credential's password and the proxy-granting ticket in proxy authentication scenarios, pass them along to applications as regular attributes/claims. We will also be reviewing a handful of attribute release strategies that specifically affect authentication attributes, conveying metadata about the authentication event itself.

Apereo CAS 6.1.x - Attribute Repositories w/ Person Directory

An overview of CAS attribute repositories and strategies on how to fetch attributes from a variety of sources in addition to the authentication source, merge and combine attributes from said sources to ultimately release them to applications with a fair bit of caching.

Apereo CAS 6.1.x - Building CAS Feature Modules

An overview of how various CAS features modules today can be changed and tested from the perspective of a CAS contributor working on the codebase itself to handle a feature request, bug fix, etc.

CAS 6.1.0 RC2 Feature Release

...in which I present an overview of CAS 6.1.0 RC2 release.

Apereo CAS - Riffing on Attribute Release Policies

Learn how to release the kraken of attributes to CAS clients, relying parties and service providers using a variety of attribute release policies and authentication protocols, sampled and collected here to fun and profit.

Apereo CAS - Delegated Authentication to SAML2 Identity Providers

Learn how your Apereo CAS deployment may be configured to delegate authentication to an external SAML2 identity provider.

Apereo CAS - Custom Login Fields w/ Dynamic Bindings

Learn how to extend the Spring Webflow model to add custom fields to the CAS login form and the authentication process and take advantage of the additional user-provided data in customized authentication handlers.

Apereo CAS as an OAuth2 Authorization Server

Learn how to configure CAS as an OAuth2 Authorization Server and configure Spring Boot client app to work with it

Apereo CAS - SAML2 Identity Provider Integration w/ Gitlab (also staring HAProxy and LDAP)

Learn how Apereo CAS may act as a SAML2 identity provider for Gitlab and run everything locally on a workstation with Docker and Java.