User Agent or Mobile Pattern
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.
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: https://authn.sd00.worldcat.org/oauth2/authorizeCode
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.
|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.
|redirect_uri||The url WSKey should redirect the user to on success or failure||Yes||http://library.worldshare.edu/test.php|
|response_type||The type of response the server should return.
|scope||A space separated list of the services for which the client is request access.||Yes||
||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
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=WMS_NCIP&state=myaccount
Example - Authorization Server Redirects User to Your Application's Redirect Uri
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&state=myaccount
Example - Authorization Server Redirects User to Your Application's Redirect Uri with Error
|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?
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.