Introduction

This article presents a conceptual overview for connecting a web application to the Federation, using AAF Rapid Connect. From the developer’s perspective, it is helpful to comprehend the basic operations of the Shibboleth Service Provider (SP) even if the goal is to deploy Rapid Connect. From the user’s perspective, the user experience will be similar regardless of connection type.


Details

Though every application has diverse requirements, there are common elements which all providers should understand before implementing a custom solution. With traditional authentication methods, the user presents their credentials to the web service (basic authentication) or the application (web form authentication). In a federated environment, the authentication interaction occurs, but not at the web application. Since the web application does not verify credentials explicitly, there is no requirement to secure passwords or maintain secure password storage.


Shibboleth Interaction

In summary, the basic authentication interaction for the Shibboleth SP is:

  1. User visits the application and is intercepted by a Shibboleth SP component.

  2. Shibboleth redirects the user to the AAF Discovery Service (DS).

  3. A user selects their home institution from the list.

  4. The DS redirects the user back to SP which sends an authentication request via the user's web browser to the user’s home institution Identity Provider (IdP).

  5. The IdP authenticates the user and resolves their attributes.

  6. The IdP generates a SAML Assertion, which identifies the user and redirects the user to the SP.

  7. The SP receives the SAML Assertion, verifies the cryptographic signature and establishes the user session.

  8. The SP redirects the user back to the application and injects the user's attributes into the web environment.


The Shibboleth SP handles the communication and verification for federated authentication, so the application can trust the injection of user attributes without needing to verify user credentials. This simplifies application development and permits the addition of components which may inject other attributes as if they originate from the Shibboleth SP. The following conceptual image illustrates the interaction.

 

 


This authentication delegation means that the application will receive, trust and consume user attributes without additional code to verify the origin of the data. In this instance, the Shibboleth SP component completely abstracts that process on behalf of the application. Likewise, application developers only need to interpret the data presented by the Shibboleth component.

To deliver a service using Shibboleth, the following components are necessary:

  • Shibboleth SP application,

  • Apache or Microsoft Internet Information Service (IIS), with the appropriate Shibboleth module,

  • An application capable of receiving attributes from Shibboleth.


See the Shibboleth Documentation for information on the deployment and operation of Shibboleth.


Rapid Connect Interaction

The Rapid Connect service manages the Shibboleth SP component on behalf of the application, simplifying the integration process for developers. The Rapid Connect service provides a SAML end-point, translation between SAML and JSON Web Token (JWT), redirection of requests and validation of the JWT. This simplifies the integration work necessary to connect an application and removes the need to test and deploy a Shibboleth SP component. All other logic remains in the application, enabling the use of cloud services which do not support the addition of Shibboleth directly, such as Heroku and Google App Engine.


The interaction now becomes:

  1. User attempts to visit the application, and is intercepted by the Application Request Filter.

  2. The Application Request Filter redirects the user to the Rapid Connect Endpoint. This endpoint is set up by Rapid Connect at registration and simplifies deployment if the endpoint is also easily configurable in the app.

  3. Rapid Connect directs the user to the Discovery Service as detailed above. The user locates their home institution and performs a normal login at their IdP.

  4. Rapid Connect receives the user's attributes and generates a signed JWT containing the attributes, which is sent to the application Callback URL via HTTP POST.

  5. The Callback URL receives the JWT, verifies that it is valid per the Rapid Connect documentation and establishes a user session.

  6. Now that the session is established, the Application Request Filter permits access to protected content.


The following conceptual image illustrates the interaction.

 


To deliver a service using Rapid Connect, the following components are necessary:

  • An application which is capable of performing redirects and receiving a JWT response


The design goal for Rapid Connect was to ensure as few dependencies as possible to simplify deployment. This requires that user access decisions and interactions all occur within the application.


Additional Notes

User Registration

With federated authentication, there is no requirement for user registration in the traditional sense. Additionally, there is no need for users to store a password within a web application unless non-web access is necessary, such as a desktop application’s access to a web API.


Once session management is under control, additional flow controls can be initiated which can include auto-provisioning, or updating profiles with attributes that have changed, or forcing users through a one-time process such as a “Term of Service” agreement. Developers should consider mechanisms for the auto-provisioning of users on first access, with their details kept up-to-date automatically during subsequent logins.


Effective Use of Attributes

The AAF offers a set of core attributes each with varying uses. Although it is tempting to request a wide range of attributes to capture as much information as possible about users, only consider what is truly necessary to provide a service. 


These attributes are available to Rapid Connect and the AAF recommends:

  • eduPersonTargetedID — This should be used as the primary identifier, to match an incoming user against an existing record in an application's data store. This attribute is guaranteed to never change for a user.

  • displayName — This is the most appropriate name to show in the web interface, to identify the user and show that they are logged in. Note: do not rely on any specific format for displayName. Any attempts to validate names will create problems for those users who do not fit the chosen patterns and; this will invariably occur.

  • mail — Only collect if there is a need to message the user, or use as a secondary identifier. 

  • eduPersonScopedAffiliation — Only collect if there is a need to identify the user's organisation and their affiliation or position within their organisation.


See the Support Portal Attributes page for complete information and definitions.


The AAF strongly recommends that eduPersonTargetedID is chosen as the primary identifier rather than email. Email addresses change on an irregular basis for numerous reasons. When they inevitably do change, users experience service disruption while manual remediation work is undertaken to update primary identifiers. Home institutions will invariably not communicate email addresses updates to external parties.


Though auEduPersonSharedToken is a core attribute, it is not recommended for general use or as a primary identifier. auEduPersonSharedToken is only useful in grid-computing environments, or to share user data or access rules across security domains or separate Service Providers.


Links

AAF Attributes

AAF Rapid Connect documentation

Shibboleth documentation

SWITCH AAI Demo https://www.switch.ch/aai/demo/simple/