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.




Requirements

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).
  • cn - An individual's common name. For the AAF this is defined as the users first name followed by their surname.
  • 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 Attribute Validator 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.


Permissions

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