OAuth is a protocol which allows you to retrieve user data without needing to store credentials such as usernames and passwords. A user must authorise this themselves the first time the data is requested (which will involve them logging into the application that you are trying to retrieve the information from), but each subsequent access can be achieved without re-authentication or re-authorisation by the user (unless the access token has expired or has been revoked).

The sso-client.jar (from version 1.69 onwards) provides mechanisms to allow applications to authorise access to your data by wrapping APIs in a filter which allows tokenised access. It does not require your application to be an OAuth Service Provider - Websignon will handle this.

The OAuth stack is as follows:

1. An external application (or OAuth Consumer) requests a request token from websignon with a scope parameter set to your provider ID.
2. The user is asked to authorise the request token, allowing the application to access their data.
3. The authorised request token is converted to an access token (typically with a 1 year expiry) which is stored by the consumer for future accesses.

When the consumer wants to access a protected resource, they send an OAuth authorisation header with the access token in and this is verified by websignon.

sso-client.jar simplifies this process greatly by abstracting away most of this process. For developers, the only implementation steps are:

• Add a new <oauth> configuration into the SSO XML Config specifying the location of the websignon oauth service which will manage this information.
• Wrap resources that you want to protect with OAuth in the uk.ac.warwick.sso.client.oauth.OAuthFilter (note: this must follow IMMEDIATELY after SSOClientFilter in your filter configuration in web.xml)

Modifying the SSO XML Config

An example <oauth> section can be seen as follows:

<oauth>
    <enabled>true</enabled>

    <!-- Location of the OAuth service -->
    <service>
      <location>https://websignon.warwick.ac.uk/origin/oauth/service</location>
    </service>
</oauth>

Modifying web.xml

All we need to do is add the OAuthFilter around the URLs that we want people to be able to access via OAuth.

  <filter>
    <filter-name>SSOClientFilter</filter-name>
    <filter-class>uk.ac.warwick.sso.client.SSOClientFilter</filter-class>
  </filter>
  <filter>
    <filter-name>OAuthFilter</filter-name>
    <filter-class>uk.ac.warwick.sso.client.oauth.OAuthFilter</filter-class>
  </filter>

  <filter>
    <filter-name>SSOClientFilter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter>
  <!-- NOTE: ONLY WRAP THE OAUTH FILTER AROUND PARTS OF YOUR APPLICATION 
   THAT YOU WANT APPLICATIONS TO BE ABLE TO ACCESS VIA OAUTH -->
  <filter>
    <filter-name>OAuthFilter</filter-name>
    <url-pattern>/api/*</url-pattern>
  </filter>