User Agent or Mobile Pattern

In many other OAuth implementations you will see two flows, one for client-side web application use cases (Javascript) and second for mobile app use cases. For example, Google’s OAuth 2 implementation splits User Agent and Mobile into separate flows and labels them Client Application and Installed Application.

Our implementation treats them as a single flow. But the distinguishing feature is that the client application that needs to get data from OCLC’s web services cannot keep the WSKey’s secret secure. This can happen because all communication happens in a client like a web browser that you or on an end user’s mobile device. And in either case, you as the developer of the application cannot control the environment in which the API key is operating.

Mobile Authentication Flow

Note: This diagram simplifies the interaction to the client application perspective and removes the details what happens at the OCLC Authorization Server.

Getting an Access Token

Unlike the Explicit Authorization Code Flow, getting an Access Token using the User Agent or Mobile Flow is a single step process. The client must request an AccessToken by building a url to the OCLC's Authorization Server authorization code endpoint. Then the client must redirect the user’s web browser to this URL. Once the user is redirected they are presented with a login screen in which they must give a valid username and password combination. If the user successfully logs in then the WSKey Server will redirect the user’s web browser back to the specified redirect URL and pass the information about the Access Token to the client via a URL hash.

Clients can specify which user the should be authenticated at via the authenticatingInstitutionId. If no authenticatingInstitutionId is specified then the user is redirected to a Where Are You From (WAYF) screen to select an institution to authenticate at.

Base URL:

User Agent / Mobile Parameters

Name Description Required? Expected / Sample Values
client_id The grant type designates the type of OAuth grant the client is requesting. This value is fixed for this pattern.
Yes client_credentials
authenticatingInstitutionId The WorldCat Registry ID for the institution responsible for authenticating a user when principal information is included on the request. No 128807
contextInstitutionId The WorldCat Registry ID for the institution whose data the client is requesting to access or modify.
No 128807
redirect_uri The url WSKey should redirect the user to on success or failure Yes
response_type The type of response the server should return.
Yes token
scope A space separated list of the services for which the client is request access. Yes
  • WorldCatMetadataAPI
An opaque value to represent the application's state when the user chose to login. The parameter can be used to prevent
cross-site request forgery

Example URL - Your Application Redirects User To Login via the Authorization Server

Example - Authorization Server Redirects User to Your Application's Redirect Uri
&token_type=bearer&expires_in=1199&expires_at=2013-08-23 18:45:29Z

Notice the redirect URI has the Access Token properties appended as part of the URL fragment (the portion preceded by the '#' character). The properties are appended this way so that they are accessible to JavaScript.

Example - Authorization Server Redirects User to Your Application's Redirect Uri with Error

Name Description
token_type Type of token. In our implementation this will always be "bearer"
access_token The value of the Access Token. This is what the client will need to send to the web service.
expires_in Number of seconds in which the Access Token will expire
principalID The user id of the user who logged in
principalIDNS Principal identity namespace the user's principalID is in
contextInstitutionId WorldCat Registry institution ID of the institution's data the Access Token has rights to access
expires_at Timestamp when the Access Token will expire.

Why would I use this flow?

There are two possible scenarios in which you might use the User Agent/Mobile flow. The first scenario is if you were building a Javascript form that allowed a user to request a book be purchased. In this case you’d want to log the user in to capture their identity and then pass this in as part of the request. This could be done via the User Agent flow.

The second scenario is if you were building a native mobile application that allowed a user to view their checked out items, place holds or renew materials. Like the book request application, this app needs to log a user in to your application. To do this the app needs to open a web browser and redirect the user to the appropriate login page. Once the user is logged in then the app will retrieve the user’s account information and display it.