WAYF for a Multi-institution Application

This solution guide will discuss the process of creating a WAYF (Where are you from) login screen for an application which is available for multiple institutions and requires that users at each institution be able to log in.

Why Would I Use WAYF

The purpose of a WAYF screen is to enable users from different institutions to use the same application with login credentials from their home institutions. This allows the institutions to share the same application infrastructure while maintaining different identity stores.

Let's say a consortia that all uses WorldShare Management Services (WMS) wants to build a mobile website application which allows staff to view pull lists on a tablet. They want to allow staff at any consortia site to log in to use the application to see their local pull list information. The login portion of this application would require a WAYF screen to allow the staff users to select what institution they want to log in to.

Assumptions

  1. The application is web-based
  2. The application is used by multiple institutions
  3. The users are logging into OCLC's OAuth Authorization server
  4. The application's WSkey is configured to access each of the institutions displayed in the WAYF screen

How should it work?

  1. Obtain a list of institutions and their WorldCat Registry identifiers to include in the WAYF screen
  2. Allow the user to choose the institution they want to log in to
  3. Redirect the user to the OAuth Authorization server to log in   
  4. Use the authorization code returned to request an Access Token for that user
  5. Store the Access token in the session, flag the user as logged in, and show the user the appropriate screen for when logged in

Obtain a list of institutions and their WorldCat Registry identifiers to include in the WAYF screen

In order to create a WAYF screen, the application needs a list of institutions and their identifiers in the WorldCat Registry. Such a list can be created in two possible ways:

  • Make a list of institution names and WorldCat Registry IDs configurable in the application
  • If the WAYF is for a consortia that is known within the WorldCat Registry, then the application can call the WorldCat Registry API to draw out the institution names and registry IDs

Allow the user to choose the institution they want to log in to

Based on the list of institutions the application has available, the application needs to allow the user to choose the institution they want to log in to. This could be a drop down list, a bulleted list or any other feature that would allow the user to choose an institution. For a particularly large list of institutions, a search box might even be appropriate. The exact user experience design of this is up to the application developer.

Redirect the user to the OAuth Authorization server to log in

Once the user selects an institution they want to log in to, the application must create the appropriate url for the OAuth Authorization server to redirect the user to. More information on this is available in the Explicit Authorization Flow Authentication documentation. The user will then be presented with a login page that they must input their credentials into.

Use the authorization code returned to request an Access Token for that user

When the user successfully logs in to the Authorization Server, it will redirect the user back to the redirect url passed to the Authorization server via the login url. This redirect url should be a web page which is capable of extracting the authorization code from the query parameter and then making a subsequent request to the Authorization Server for an Access Token using that code.

Access Tokens last 20 minutes. So we recommend developers request a Refresh Token with the Access Token. The Refresh Token will allow the application to be coded so that a user does not need to re-authenticate during that day's session.

Store the Access token and Refresh Token in the session, flag the user as logged in, and show the user the appropriate screen for when logged in

Once the Access token is returned, the application should store it in a session variable for future use. This Access Token will be necessary to make calls to the OCLC web services the application is interacting with. The Refresh Token can be used to obtain new Access Tokens for 24 hours without the user having to re-authenticate.

Things to be mindful of

WSKey use by the application must be set up for every institution the application wants to interact with  

Typically WSKeys are setup to interact with a single institution's data - the data of the institution that "owns" the WSKey. In the scenario where a consortia is running an application shared by multiple institutions, the WSKey for the application must be set up to interact with every institution that wants to use the application. If your consortia is interested in building this type of application, please contact us so that we can help facilitate enabling access to the data for the various institutions.

Reference Implementation

In order to help developers create their own version of this functionality, we've provided a reference implementation in PHP. The reference implementation uses our PHP Authentication code library to create urls for logging in and making requests to the Authorization server.