Academic Gateway

Owned by Peter Bolha, created
Last updated: Aug 01, 2023 by Pavel Břoušek (Deactivated)
5 min read

About

The Academic Gateway is a tool which provides a single, easy to naviagte environment for logging into (primarily academic) services.

General concept

When a user tries to authenticate to an SP (Service Provider) (for example log in to an information system of their university), there are usually several ways of performing this operation. The user can either:

  • use their local identity

    • for example direct log in to their university’s information system

    • user’s credentials are stored locally in the service and can’t be automatically used to log in to other systems

  • use a federated identity

    • for example log in via an external login page to an identity federation like eduGAIN which provides information about user’s identity to the SP

    • the federation acts as an external IdP (Identity Provider)

    • user’s credentials are stored remotely at the identity federation and can be used to log in to any system supporting communication with the identity federation

  • use a commercial identity

    • for example log in via an external login page to a commercial service like Google, LinkedIn or Facebook which provides information about user’s identity to the SP

    • the commercial service acts as an external IdP

    • user’s credentials are stored remotely at the commercial service and can be used to log in to any system supporting communication with the commercial service

Each of these options typically uses its specific set of plugins and communication protocols in the background and puts users through different kinds of login pages. The Academic Gateway provides a way to unify this proces from the viewpoint of the user by acting as a proxy between the service they’re trying to access and the actual IdPs.

Possible ways of authenticating to an SP as a user

Technical specification

The Academic Gateway acts as an authentication proxy, a sort of intermediary between a service and its identity providers. Say a user wants to log in to a system S. This system acts as an SP and contacts the Academic Gateway, which is an IdP from the viewpoint of system S. The Academic Gateway then presents the user with the options to either log in locally, choose from preconfigured remote IdPs or search for a remote IdP. Subsequently, it delegates the log in procedures to their respective plugins. In case of choosing the remote authentication, the Academic Gateway acts as an SP towards the external IdP as illustrated in the below diagram.

Diagram of roles during the authentication procedure

This communication happens in the background using SAML2 and its intricacies are hidden from the user who only sees a single page with log in options.

The Academic Gateway is build upon SimpleSAMLphp with a couple of custom plugins expanding upon its functionality.

  • campususerpass adds support for Enhanced Client or Proxy Profile (ECP)

    • in short, this allows the user’s browser to send the user’s credentials directly to the external IdP via SAML and receive a response all using a predefined interface

    • it reduces tight coupling with external IdPs thus simplifying integration of various identity providers

  • campusmultiauth provides a fully customizable single log in page which facilitates all the options a user can choose to authenticate

    • this is the core part of the Academic Gateway functionality, therefore it’s the basic minimum that needs to be installed and configured along with SimpleSAMLphp

    • it also acts as a discovery service (a way to discover and select various IdPs)

SimpleSAMLphp along with both plugins can be found in this docker image. This is the simplest way of running the Academic Gateway with its full capabilities.

The Academic Gateway also implements IdP hinting in accordance with AARC-G049 and AARC-G061 specifications. It also implements IdP filtering according to AARC-G062 (a currently upcoming draft).

Configuration and customization

There are numerous configuration options for the Academic Gateway, all of which are described in more detail on the project’s GitLab page in the README section.

Regarding the customization of the login page itself, it can be done on several levels. Originally, the Academic Gateway was designed for academic purposes, more specifically in accordance with the Uniform Visual Style of the Masaryk University. On top of that, the Academic Gateway offers a more versatile Bootstrap 5 template which can eventually be entirely replaced by custom css files to provide completely unique visuals.

Even the most restrictive MUNI template offers some amount of customization to accomodate its use by different institutions. The banner at the top of the page, primary colors and the institution’s logo can be changed. The main log in proceduredures are divided into individual modules:

  • local login allows directly entering credentials and logging in to the implementing institution

  • idividual identities allow users to pick from a list of preconfigured external identity providers

  • searbox allows users to manually search for their identity provider of choice, prevents clutter in the individual identities section

These modules' prominence* can be configured in the MUNI template as illustrated in the screenshots below.

*Which should be the primary way of authentication preferred by the institution?

Overall, the Academic Gateway is designed with mobile first approach with several rounds of user testing, which guarantees it will be user friendly and practical on mobile as well as desktop platforms. Additional information (albeit only in Czech) can be found in the configuration suggestions manual.

In this screenshot, we can see the searchbox set as the primary auth option in the top left corner, individual identities (Google, Apple ID, ORCID) in the bottom left corner and local login on the right set as secondary auth options.

 

The application can also be supplied with custom localization as explained on the GitLab pages of the project.

Docker image

Ready to use Docker image of the project including all the necessary dependencies and build instructions.

https://gitlab.ics.muni.cz/perun-proxy-aai/containers/docker-campusidp

GitLab repository

The official project repository containing the source code and detailed configuration instructions.

https://gitlab.ics.muni.cz/perun-proxy-aai/simplesamlphp/simplesamlphp-module-campusmultiauth

 

Support: perun@cesnet.cz