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. When traditional authentication methods are in use, the user presents their credentials to the web service (basic authentication) or the application (web form authentication). When federating a service, 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.

Federation Authentication Interaction

In summary, the basic authentication interaction for a Shibboleth Service Provider (SP) in a federation is:

A user visits the application and is intercepted by the SP component.
Shibboleth redirects the user to the AAF Discovery Service (DS).
A user selects their home institution from the list.
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).
The IdP authenticates the user and resolves their attributes.
The IdP generates a SAML Assertion, which identifies the user and redirects the user to the SP.
The SP receives the SAML Assertion, verifies the cryptographic signature and establishes the user session.
The SP redirects the user back to the application and injects the user's attributes into the web environment.

The SP handles the communication and verification of the user for federated authentication, so the application can trust the injection of user attributes without needing to verify user credentials. This process simplifies application development and permits the addition of components which may inject attributes and their values as if they originate from the 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 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 Service Provider 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 an 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 authentication interaction now becomes:

User attempts to visit the application, and is intercepted by the Application Request Filter.
The Application Request Filter redirects the user to the Rapid Connect Endpoint. This endpoint is set up at Rapid Connect registration and simplifies deployment of the endpoint which is also easily configurable in the app.
Rapid Connect directs the user to the DS as detailed above. The user locates their home institution and performs a normal login at their home IdP.
The IdP generates a SAML Assertion, which identifies the user and redirects the user to the Rapid Connect.
Rapid Connect receives the user's attributes and generates a signed JWT containing the attributes, which is sent to the application's Callback URL via HTTP POST.
The Callback URL receives the JWT, verifies that it is valid per the Rapid Connect registration and establishes a user session.
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.

User Registration and User Attributes

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 user 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.

The following 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. Do not rely on any specific format for displayName. 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 of the AAF attributes available.

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.

Consuming attributes injected by the SP

There are two basic models for implementing a Shibboleth Service Provider (SP)

Directly protect all the content with the SP
Protect a "login" endpoint with the SP, and use that endpoint to establish a session with the application

The second of these is more common and much more flexible but requires a little more work.

Directly protecting content with the SP

This model best suits static content, or web applications with no need to maintain session state (e.g. displaying a user's name purely for personalisation). In this model, the flow of a request is quite simple:

For each request, Shibboleth will verify the user's session with the SP and pass the attributes through to the application. When the user's session expires, they will be transparently authenticated again and be able to continue. This approach is supported out-of-the-box by the SP by simply requiring a Shibboleth session for the entire website.

Managing user sessions

In this model, the request flow is a little more complex but affords greater control:

These are examples of potential setups with endpoint names and specific details for illustrative purposes. In this scenario, when the user attempts to access the Protected Content without an active session, they would be directed to a login selection page (which is Unprotected Content), where the user could choose to log in via the AAF or any other mechanisms that are available. From there, the user's browser would be sent to the login mechanism chosen:

/auth/aaf which accepts attributes from Shibboleth SP and creates a session which can be inspected later to verify the user has authenticated. It is intuitive that a Rapid Connect Callback URL could replace /auth/aaf if Rapid Connect was in use instead of a Shibboleth SP.
/auth/other that provides an alternate login mechanism for users who are not part of the federation, or for special use cases such as an administrative login. In a real app, there can be as few or as many login mechanisms as necessary with any endpoint naming scheme.

On establishing session management control, the developer can launch other processes or flows such as auto-provisioning of new users, updating attributes of returning users or forcing users through a one-time “Terms of Service” page for the service. The Application Request Filter detects any unauthenticated sessions and redirects the user to the login selection page. The establishment of a user session permits access to the Protected Content by the Application Request Filter.