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.0.0 RC4 Feature Release

...in which I present an overview of CAS 6.0.0 RC4 release.

Apereo CAS 6.0.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.0.x Deployment - WAR Overlays

Learn how to configure and build your own CAS deployment via the WAR overlay method, get rich quickly, stay healthy indefinitely and respect family and friends in a few very easy steps.

Apereo CAS - Jib at CAS Docker Images

Learn how you may use Jib, an open-source Java containerizer from Google, and its Gradle plugin to build CAS docker images seamlessly without stepping too deep into scripting Dockerfile commands.

Apereo CAS 6 - Administrative Endpoints & Monitoring

Gain insight into your running Apereo CAS 6 deployment in production. Learn how to monitor and manage the server by using HTTP endpoints and gather metrics to diagnose issues and improve performance.

Apereo CAS - SAML2 Metadata with MongoDb

CAS distributed SAML2 metadata management using MongoDB, where you learn how to store metadata documents inside MongoDB for CAS as a SAML2 identity provider and all other registered SAML2 service providers.

Apereo CAS - Slurp Configuration with Groovy

Learn how CAS configuration may be consumed via Groovy to simplify and consolidate settings for multiple deployment environments and profiles.

Apereo CAS - Configuration Management with MongoDb

CAS distributed configuration management using MongoDb, where you learn how to store and secure CAS configuration settings and properties inside MongoDb.

Apereo CAS - Integration with HashiCorp Vault

CAS distributed configuration management using HashCorp Vault, where you learn how to store and secure CAS configuration settings and properties inside Vault.

CAS 6.0.0 RC3 Feature Release

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