Authentication Documentation

WSKey Overview

The primary method used for authenticating and authorizing interactions with web services which are part of the OCLC WorldShare Platform is via WSKey, otherwise known as a Web service key.

To request a WSKey—for use either in the Platform test environment or in a production context —you'll need to access the OCLC Service Configuration module, for which you'll need an OCLC user account.  If you don't currently have an OCLC account, it's easy to get set up.  Note that before any type of key is provided to an individual, his or her standing to access an institution’s data must be strongly validated and he or she must explicitly verify that they have read the Terms & Conditions that are in place between OCLC and the institution for which they are acting.

There are presently two different levels of authenticating and authorizing. The functionality the service provides dictates the level required.

• WSKey V1 - used by services which perform read-only actions.
• WSKey V2 - used by services which perform read and write actions or deal with patron information.

WSKey V1

WSKey V1 requires that the Client identifier (an 80 character string called the wskey) be passed either:

• on the URL, as a parameter called wskey
• in the HTTP request header named wskey

This method is simple enough that no client is provided.

WSKey V2

Web services that use WSKey V2 require a more complex form of authentication. Developers accessing web services using WSKey 2 are issued the following:

1. Client identifier – a public identifier, 80 character string.
2. Secret Key – a random string that we share with the Client Host that they can use to prove who they are.

WSKey V2 Requests

WSKey V2 requires that an Authorization HTTP header be included in each request. Its format is:

Authorization: schemeURL clientId="myClientId", timestamp="myTime", nonce="myNonce", signature="mySignature"

where
schemeURL is the url used to label what v2 scheme is being used  - currently developers should use http://www.worldcat.org/wskey/v2/hmac/v1
myClientId is the wskey for the client
myTime is the current time as a POSIX timestamp
myNonce is a number that can only be used once (typically a random number)
mySignature is the request signature

Here is an example request:

GET https://circ.sd00.worldcat.org/pulllist/914751?inst=914751&principleID=660ecd7d-3d1b-4433-abcd-ae843b716ec0&principleIDNS=urn:oclc:wms:da
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 
clientId="K3DcGJULpuA0ftXY10a1scYeehwMiffRbzjNYMROlQ2VsgXO1ohbN1uHn2blbed2lLp9Nf26CRY80vaA",
timestamp="1323035554",
nonce="591dfe4f",
signature="06rFGLa2qsGVtXuryFxuFEHX6ffmAd+NMY9Kb4YEg68=" 

NOTE: the Authorization header value is actually all one line; it is broken into multiple lines in the example above to make it readable.

Building a signature for the Authorization Header

To build the signature developer should

1. normalize the request string by concatenating together the following elements each followed by a new line
   1. The WSKey
   2. The timestamp value calculated for the request.
   3. The nonce value generated for the request.
   4. The request entity-body hash if one was calculated and included in the request, otherwise, an empty string.
   5. The HTTP request method in upper case. For example: "HEAD", "GET", "POST", etc.
   6. www.oclc.org
   7. 443
   8. /wskey
   9. The query component of the web service request URI normalized as described in Section 3.3.1.1 of HTTP MAC authentication scheme.
2. HMAC-SHA-256 hash the normalized request string using the secret
3. Base_64 encode the hmac-sha-256 normalized request

WSKey V2 Responses

When an authorization error occurs, a header named WWW-Authenticate is added to the HTTP response. http://tools.ietf.org/html/draft-ietf-oauth-v2-11#section-6.2 describes its format.
Here is an example WWW-Authenticate header:

WWW-Authenticate: WSKeyV2 error="invalid_token" error_description="request is not unique"

The HTTP status codes used in WSKey V2 on authorization errors are

• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden