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 RC3 Feature Release

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

CAS 6.0.0 RC2 Feature Release

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

Apereo CAS - dotCMS SAML2 Integration

Learn how to integrate dotCMS, a Content Management System and Headless CMS, with Apereo CAS running as a SAML2 identity provider.

Effective Software Troubleshooting Tactics

A collection of what hopefully are obvious troubleshooting tactics when it comes to diagnosing software deployment issues and configuration problems.

Notes from Better by Design 2018

Be interested in humans and human success.

Apereo CAS - Authentication Lifecycle Phases

Tap into the Apereo CAS authentication engine from outside, and design extensions that prevent an unsuccessful authentication attempt or warn the user after-the-fact based on specific policies of your choosing.

CAS 6.0.0 RC1 Feature Release

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

Apereo CAS Delegated Authentication with ADFS

Learn how your Apereo CAS deployment may be configured to delegate authentication to Microsoft ADFS.

Apereo CAS Swag with Swagger

Enable Swagger integration with your Apereo CAS APIs.

Get Productive with Shell Aliases

A collection of useful shell aliases, gathered over the years to help increase one's productivity and developer happiness.