Using AAF to Streamline Service Delivery

This article will give an overview of some technical aspects of delivering a federated service. There are many ways to approach this problem, but in AAF's experience the approaches highlighted here are simple to develop, robust, and most importantly offer a seamless experience for federated users. We've spent a lot of time ensuring that our services will help you meet these goals.

This document assumes the use of Shibboleth's SP or AAF Rapid Connect. For definitions of any unfamiliar terms, refer to AAF's Glossary page.

It is useful to understand the basic operation of the Shibboleth SP even if you intend to use Rapid Connect, as most of the user experience is identical and only the implementation details are different.

Joining the Federation

See the article titled Subscribe to the AAF which explains the process and benefits of becoming an AAF subscriber.

Delivering a Federated Service

We understand that each service is different, and we are able to provide additional advice to help you with your specific integration challenges. However, there are some common elements which all service providers should understand before trying to build a custom solution.

Federated Authentication Interaction

With traditional authentication mechanisms, the user would present their username and password directly to the web server (e.g. basic authentication) or to your application (web form authentication). In a federated environment this interaction does not take place directly with your web server.

Additionally, because your server will not verify the user's credentials directly, you no longer need be concerned about ensuring you have secure password storage.

The basic interaction is:

  1. User attempts to visit your application, and is intercepted by Shibboleth SP
  2. Shibboleth redirects the user to the DS
  3. User selects their IdP from the list
  4. DS redirects the user to their IdP
  5. IdP authenticates the user and resolves their attributes
  6. IdP generates a SAML Assertion, which identifies the user
  7. SP receives the SAML Assertion, verifies cryptography and uses it to establish a session
  8. SP redirects the user back to your application
  9. SP components inject user's attributes into the web environment

Shibboleth handles all the communication and verification required for federated authentication, so your application can trust the user attributes that are injected without needing to verify anything. This also simplifies development, as you can create your own development component which injects attributes as if they had come from Shibboleth. With this in mind, your application can treat the environment simply as:

This means your application will receive user attributes, and can trust and consume those without being concerned about where they came from.


To deliver a service using Shibboleth, you will need the following components:

  • Shibboleth
  • Apache or IIS, configured to include the Shibboleth module
  • Your application which is capable of receiving attributes in the way Shibboleth provides them

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

Rapid Connect Interaction

When using Rapid Connect, the interaction is all your application's responsibility. While this sounds like more work, it is our experience that adding Rapid Connect authentication to an application is much simpler than testing and deploying with a Shibboleth SP. Additionally, as all the logic lives in your app, it enables the use of cloud services which don't support Shibboleth such as Heroku and Google App Engine.

The interaction is now:

  1. User attempts to visit your application, and is intercepted by your Application Request Filter.
  2. Your Application Request Filter redirects the user to your Rapid Connect Endpoint. This endpoint is provided by Rapid Connect during registration. It will make your life easier if this is easily configurable in your app.
  3. Rapid Connect performs federated authentication as detailed above. This means the user performs a normal federated login.
  4. Rapid Connect receives the user's attributes, and uses them to generate a signed JWT which is sent to your Callback URL via HTTP POST.
  5. Your Callback URL receives the JWT, verifies that it is valid per the AAF Rapid Connect documentation and uses it to establish a session.
  6. Now that the session is established, your Application Request Filter permits access to the Protected Content.


To deliver a service using Rapid Connect, you will need the following components:

  • Your application which is capable of performing the redirect and receiving a JWT response

The goal of Rapid Connect was to ensure as few dependencies as possible are required, to greatly simplify deployment.

Consuming attributes injected by SP

There are two basic models for using a Shibboleth 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 your 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 is best suited to static content, or web applications with no need to maintain session state (e.g. displaying a user's name purely for customisation).

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 your application. When the user's session expires, they will be transparently authenticated again and be able to continue.

This is supported out-of-the-box by Shibboleth SP, by simply requiring a Shibboleth session for the entire website.

Managing your own sessions

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

(Note this is only an example of one potential setup, for illustrative purposes. Endpoint names and other specific details are just a sample.)

In this scenario, when the user attempted to access Protected Content without an active session, they would be directed to a login selection page (in Unprotected Content), where the user could choose to log in via the AAF or via whatever additional mechanisms are available. From there, the user's browser would be sent to one of the login mechanisms:

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

Once you have control over session establishment via whatever mechanism, you can use that to launch extra steps such as auto-provisioning of unknown users, updating attributes that have changed for known users, or forcing users through a one-time "Terms of Service" page for your SP.

The Application Request Filter would be responsible for detecting an unauthenticated session, and redirecting the user to the login selection page. Once a session has been established, access to the Protected Content would be permitted by the Application Request Filter.

User Registration

With federated authentication, there is no need for user registration in the traditional sense. In particular, there is no need for users to be assigned a password within your web application unless it is needed for some kind of non-web communication, such as a desktop application accessing an API.

Instead, consider that you should auto-provision users when they first access the site, and keep their details up-to-date automatically across subsequent logins.

Effective Use of Attributes

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 your users, consider what you truly need to capture to provide your service. AAF recommends:

  • eduPersonTargetedID — This should be used as the identifying attribute, to match an incoming user against an existing record in your application's data store. It is guaranteed never to change for a user.
  • displayName — This is the most appropriate name to show in your web interface, to identify the user and show that they are logged in. Note in particular that you should not rely on any particular format of their displayName, as any attempts to validate a name will create problems for people that don't fit your chosen pattern (and this happens almost invariably).
  • mail — Only if you have a real need to email the user, or to identify them by their email address (AAF strongly recommends eduPersonTargetedID still be the primary identifier, even if you use mail as a secondary identifier. Remember that an email address can change!)
  • eduPersonScopedAffiliation — Only if you need to identify the user's organisation and their position within that organisation.

These attributes are also available when using Rapid Connect.

See the Attributes page on our technical wiki for more information about these.

Note that while auEduPersonSharedToken is a core attribute, it is not recommended for general use. Only request this attribute if you have a real need to share user data across separate federated SPs.


Sometimes it is necessary to offer certain users elevated permissions within part / all of your application. There are many frameworks available for managing permissions, and we don't make any specific recommendations about which to use. There are two general approaches we use for this:

  1. Assign the permissions directly in the application. This implies that the user must log in before the permission can be assigned, and requires some kind of communication exchange where the user lets an existing app administrator know they have logged in, and then the administrator must assign the permissions. This approach can be simpler for apps with a small number of administrators.
  2. Assign the permission to an "invite code" which is communicated to the user somehow. We prefer to do this in the form of a URL which will take them through the authentication process if necessary and then assign the permissions automatically after login is complete. This is the model we have preferred for larger applications with many administrators at different scopes (for example, AAF Virtual Home).

We have considered another model using the eduPersonEntitlement attribute to provide administrative rights, but as we have not achieved this yet, we aren't able to provide any recommendations at this point. We will update this document if/when we have had some success with this idea.

Shaun Mangelsdorf,
Feb 9, 2014, 5:11 PM
Shaun Mangelsdorf,
Feb 9, 2014, 5:11 PM
Shaun Mangelsdorf,
Feb 9, 2014, 5:11 PM
Shaun Mangelsdorf,
Feb 9, 2014, 5:11 PM