Authentication and Authorization: User Agent or Mobile Flow

This is the sixth post in our topical series on Authentication and Authorization for OCLC web services. In our previous posts, we discussed Access Tokens and the purpose they serve in OCLC’s web service infrastructure. We enumerated several flows which can be used to obtain an Access Token, and posted most recently on the Explicit Authorization Code flow. This post will focus specifically on another of those flows: the User Agent or Mobile flow.

In many other OAuth implementations you will see 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 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.

Note: This diagram simplifies the interaction to the client application perspective and removes the details of what happens at the OCLC Authorization Server. More on our "Cooperative Authorization server" in a future post.

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 Authorization Server’s authorization code endpoint that contains the following information:

• client_id - WSKey
• authenticatingInstitution ID – the institution that is responsible for authenticating the user
• contextInstitution ID – the institution’s whose data the client is requesting access to
• scope – the services that the client is requesting access to
• redirect_uri – the url the authorization server should redirect the user to after login.
• response_type – this must be set to “token” for this particular flow.

Then client must redirect the user’s web browser to this URL.

Example:

https://authn.sd00.worldcat.org/oauth2/authorizeCode?
client_id=jdfRzYZbLc8HZXFByyyLGrUqTOOmkJOAPi4tAN0E7xI3hgE2xDgwJ7YPtkwM6W3ol5yz0d0JHgE1G2Wa
&authenticatingInstitutionId=128807&contextInstitutionId=128807
&redirect_uri=http%3A%2F%2Flibrary.worldshare.edu%2Ftest.html&response_type=token&scope=platformConfig

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 OCLC Authorization 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.

Example:

http://library.worldshare.edu/test.html#access_token= tk_Kebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqP&token_type=bearer
&expires_in=1199&expires_at=2013-08-23 18:45:29Z&principalID=cpe4c7f6-f5a4-41fa-35c9-9d59443f544p
&principalIDNS=urn:oclc:platform:128807&contextInstitutionId=128807

This includes:

• Token type – Type of token. In our implementation this will always be “bearer” (required by the OAuth specification)
• Access token – the value of the Access Token. This is what the client will need to send with requests to an OCLC 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 – the registry ID of the institution’s data the Access Token has rights to access
• expires_at – date 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.
 

For more information, please take a look at our updated Authentication and Authorization documentation.