The OAuth protocol provides a standard way to access protected data on different websites. OAuth is an open protocol that can be implemented on other websites. OAuth is useful if you are building a web application that will let users link information to their Warwick account and access information personal about that user. See http://oauth.net to learn more about OAuth.

This information has been adapted from the information on accessing YouTube data with OAuth.

• Understanding OAuth Tokens
• Setting up OAuth authentication
• Using OAuth
• Signing requests that use OAuth authentication
• Process flow diagram

The web development team have published example code to implement OAuth in Python 3 (with requests_oauthlib) and JavaScript (as a Passport strategy, compatible with e.g. Express):

UniversityofWarwick/python-warwick-sso-oauth-example

UniversityofWarwick/passport-warwick-sso-oauth

The open source community has written Warwick OAuth examples for other languages/frameworks:

omarathon/java-spring-warwick-sso-oauth-example

Understanding OAuth Tokens

OAuth authentication uses two types of tokens:

• A request token ensures that an end user authorises your application to submit API operations on the user's behalf. Web sign-on also uses the request token to verify that you have registered your application with the ITS Web Team.
• An access token enables your application to execute Warwick API operations on a particular user's behalf.

The authentication process has three stages:

1. Your application retrieves an unauthorised request token. Web sign-on verifies that you have registered your application before returning the token. Request tokens are only valid for five minutes (we are currently looking at extending this to one hour).
2. Your application redirects the user to a web sign-on login page. The redirect URL specifies the unauthorised request token value retrieved in step 1 as well as a callback URL.
   
   After the user logs in to their University of Warwick account, web sign-on displays a page that lets the user choose whether to allow your application to perform API operations on their behalf. If the user grants your application this access, the unauthorised token will become an authorised token. (The token value does not change.) The user will also be redirected to the callback URL that you specified.
3. Your application exchanges the authorised request token for an access token. Only authorised tokens can be exchanged, and each request token can only be exchanged one time. The access token is associated with a single user account, and your application should use that token to submit authenticated API requests on that user's behalf.

Setting up OAuth authentication

You must complete the following steps to enable your web application to authenticate users with the OAuth protocol:

1. Register your web application with the ITS Web Team.
   
   Please see the OAuth application registration page for an explanation of the registration process and the requirements for registration.
   
   Note: All requests to obtain or use an OAuth token must be signed. Warwick supports the RSA-SHA1 and HMAC-SHA1 signature algorithms.
   • If your application uses the RSA-SHA1 signature algorithm, you will need to upload a security certificate to us during the registration process.
   • If your application uses the HMAC-SHA1 signature algorithm, leave the certificate field blank when completing your registration. We will generate an OAuth consumer secret value, which will be sent to you after you have completed the registration process. You will then use this value to sign requests.
2. Set up a mechanism to manage OAuth tokens.
   
   After your application obtains an OAuth access token from Warwick, your application will use that token for API requests it makes on behalf of the user associated with that token. As such, your application will need to store tokens and track the user for whom each token is valid. Your application should not try to retrieve a new access token each time the application needs to interact with Warwick services on a particular user's behalf. In fact, tokens should be treated as securely as any other sensitive user information that your application stores.

Using OAuth

As described in the Understanding OAuth tokens section, the OAuth authentication process has three steps. These steps are explained in the following sections:

• Obtaining a request token
• Authorizing a request token
• Obtaining an access token

Step 1: Obtaining a request token

To obtain a request token, send a signed request to https://websignon.warwick.ac.uk/oauth/requestToken. Include the following parameters in your request. Note that the only optional parameter is oauth_version; all other parameters are required.

There are three ways to specify these parameters:

• Include them in the Authorization header of a GET or POST request. The sample request below demonstrates how to specify these values in the Authorization header. Note that the scope parameter cannot be specified in the header. The scope can be specified as a query parameter in the request URL or in the body of a POST request.
• Specify them in the body of a POST request. If you choose this method, you must set the value of the Content-Type request header to application/x-www-form-urlencoded.
• Include them as query parameters in the request URL of a GET request.

For more details, see the OAuth specification, (section 5.2).

Sample Request

The example asks for a request token to access a user's Warwick Blogs and Printer Credits accounts.

POST /oauth/requestToken HTTP/1.1
Host: https://websignon.warwick.ac.uk
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
               oauth_consumer_key="example.com",
               oauth_signature_method="RSA-SHA1",
               oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
               oauth_timestamp="137131200",
               oauth_nonce="4572616e48616d6d65724c61686176",
               oauth_version="1.0"

scope=urn:blogs.warwick.ac.uk:blogbuilder:service+urn:printercredits.warwick.ac.uk:printcredit:service  

About the response

If the request is successful, web sign-on responds with an HTTP 200 response code containing a request token and a token secret. Your application needs to parse the token from the response.

If the request is unsuccessful, web sign-on responses with an HTTP 400 response code (Bad Request). This response may indicate that the request is poorly formed, meaning it may have an unsupported or missing parameter, unsupported signature method or other error in the request format. This response may also indicate that we have reason to believe the requester is not acting in good faith.

The following example shows a response to a successful request for a request token:

oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=ZXhhbXBsZS5jb20  

Step 2: Authorizing a request token

After you retrieve a request token, redirect the user to https://websignon.warwick.ac.uk/oauth/authorise. Add the following query parameters to the URL:

Sample Request

The following example shows a request to authorise an unauthorised token:

https://websignon.warwick.ac.uk/oauth/authorise?
oauth_token=ab3cd9j4ks73hf7g&oauth_callback=http%3A%2F%2Fwww.example.com  

About the response

If web sign-on accepts the request, the user will be redirected to a Warwick login page. After the user logs in, the Authentication service displays a page to inform the user that your application wants to access the user's account (and which services you want to access). The page prompts the user to confirm that your application can access their account.

If the user grants access to your application, they will be redirected to the callback URL specified in your request to authorise the request token. If the user denies access, she will be redirected to a page that displays a link back to your site and a link to Warwick.

The following URL shows the format of a redirect back to the callback URL with an authorised request token. The authorised token has the same value as the unauthorised token sent in the request. The value is a text string, up to 256 bytes.

http://www.example.com/ytapi.html?oauth_token=CKF50YzIHxCT85KMAg  

Step 3: Exchanging a request token for an access token

After authorising the request token for a user, your application can exchange that token for an access token. An access token lets you submit authenticated API requests on a specific user's behalf. Access tokens are valid for one year, after which the process must be performed again.

To exchange an authorised request token for an access token, send a signed POST request to https://websignon.warwick.ac.uk/oauth/accessToken with the following query parameters. Note that all of these parameters except for the oauth_token parameter are also used (and used in the same context) in the request to obtain a request token. In addition, the only optional parameter is oauth_version; all other parameters are required.

Your application can use the same three mechanisms to specify these parameters as it can use to specify parameters when obtaining a request token.

Sample Request

The following example exchanges a request token for an access token:

POST /oauth/accessToken HTTP/1.1
Host:  https://websignon.warwick.ac.uk
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
               oauth_consumer_key="example.com",
               oauth_token="CKF50YzIHxCT85KMAg",
               oauth_signature_method="RSA-SHA1",
               oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
               oauth_timestamp="137131200",
               oauth_nonce="4572616e48616d6d65724c61686176",
               oauth_version="1.0"  

About the response

Web sign-on responds to a successful request for an access token with an HTTP 200 response code that contains an access token and a token secret. The following example shows a sample response containing an OAuth access token:

oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=ZXhhbXBsZS5jb20  

We may reject a token request if it is poorly formed or if we have reason to believe the requester is not acting in good faith. If the request is not successful, web sign-on will return an HTTP 400 (Bad Request) response code.

Signing requests that use OAuth authentication

You must sign all API requests that retrieve or use an OAuth token. This requirement applies to calls to obtain a request token or an access token as well as to any API requests that require authentication, such as getting user information or making a blog post.

The following steps explain how to generate a signature for requests that use OAuth authentication:

1. Use the oauth_signature_method parameter to specify the signature algorithm that the request uses. Web sign-on supports the RSA-SHA1 and HMAC-SHA1 signature algorithms.
2. Construct a signature base string, which consists of three request elements that are concatenated using ampersand (&) characters. Note that all parameter names and values must be encoded as described in the OAuth Specification (section 5.1).
   • The first element specifies the request method (GET, POST, etc.).
   • The second element specifies the base URL for the request. The URL must not include any query parameters. For example, if the request URL is http://blogs.warwick.ac.uk/news/rss?num=100, then the base URL is http://blogs.warwick.ac.uk/news/rss.
   • The third element contains a normalised string of the parameter and parameter values in the request. The string should include any query parameters specified in the request URL as well as all of the OAuth parameters except for the oauth_signature parameter. The OAuth Specification (section 9.1.1) explains how to normalize the string.
3. Generate an oauth_signature using the specified oauth_signature_method.
   • If you are using RSA-SHA1, generate the signature using the private key that corresponds to the certificate that you uploaded to us during the registration process.
   • If you are using HMAC-SHA1, generate the signature using the "consumer secret" value generated during the registration process.

The OAuth Specification (appendix A.5) provides a sample request that can be used to test HMAC-SHA1 signatures. The example includes a signature base string and HMAC-SHA1 key as well as the generated HMAC-SHA1 digest (signature).

Process flow diagram

The following diagram illustrates the steps involved in authenticating a user using the OAuth protocol. Although the diagram refers explicitly to YouTube, it is equally relevant to making requests to Warwick services as the standard is the same.

The image shows the following steps:

1. The user clicks a link on your site to perform an API operation that requires authentication.
2. Your application determines whether you have an OAuth access token stored for the user. If you do have an access token, your application would skip ahead to step 14. If you do not have an access token, your application would proceed to step 3.
3. Your application submits a signed request to obtain a request token from web sign on's OAuth authentication service.
4. Web sign-on responds to your request with an unauthorised request token, which you parse from the response.
5. Your application redirects the user to web sign-on to log in and authorise the token. The redirect URL identifies the unauthorised request token and a callback URL.
6. The user's browser handles the redirect by sending a request to web sign-on's log-in page.
7. Web sign-on displays an Access Consent page, prompting the user to log in to their account and grant or deny the ability for your application to perform API operations for that account.
8. The user logs in and grants account access to your application.
9. If the user grants access, web sign-on redirects the user back to the callback URL that you included in the URL in step 6. The user could also deny account access, in which case web sign-on would display a page with links back to your application and to the Warwick website.
10. The user's browser handles the redirect and sends a request to your callback URL. The redirect URL contains the authorised request token value. (The authorised request token has the same value as the unauthorised request token.)
11. Your application submits a signed request to web sign-on's OAuth authentication service to exchange the request token for an access token.
12. Web sign-on responds to your request with an access token.
13. Your application parses the access token from the response and stores the token value, which is associated with a particular user. In the future, your application will use that same access token to make authenticated requests for the same user.
14. Your application submits an API request using the access token to authenticate the request.

Warwick OAuth Service Scopes

The table below is a non-exhaustive list of the scopes for some Warwick services. Not all APIs for each service are available through OAuth. To generate a token for accessing more than one services, use a + sign between scopes and pass it as a single scope parameter.

For more information on getting user information from Web Sign-on, see this page (access restricted to University members and registered Web Sign-on developers).