Authentication and Authorization

Request & Manage WSKeys

OCLC achieves authentication and authorization using several components in concert, these include: User Authentication and developer keys (WSKey).

Our User Authentication System lets you identify the current user via SAML even when their institution does not directly support SAML. The result of integrating with and invoking the User Authentication System is primarily the acquisition of a user identifier (pair) that is understood by both client and OCLC systems.

We use our WSKey System to authenticate institutions and partner organizations, not individuals. Once WSKey has established a ‘secure pipe’ between strongly authenticated institutional identities, that pipe is used to pass the User information established by the Authentication.

When User information is passed down a ‘pipe’ secured by WSKey it is done so in the form of ‘principalID’ and ‘principalIDNS’ in the Authorization Headers of the requests.

WSKey: Application Authentication and Authorization

Application Level Authentication and Authorization is performed by WSKeys. WSkeys can be used in three different ways to Authenticate.

  • WSKey Lite: a WSkey is passed to the web service for authentication purposes
  • HMAC Signature: a WSkey and secret are used to build an HMAC signed Authorization header which is passed to the web service for authentication purposes
  • Access Tokens: a client requests an access token from our OAuth 2.0 Authorization Server that can be used on the Authorization header of requests made to a web service

WSKeys belong to a specific user and typically limit access by

  • institution data
  • service

Principal Information: User Level Authentication and Authorization

In addition to application level authentication and authorization, some OCLC web services perform verification at the user level. Clients can identify users by sending principalID and principalIDNS parameters as part of an HTTP request to a web service. The principalID represents a username and the principalIDNS, or principal identity namespace, is a context for who authenticated a user. Clients will obtain principalID and principalIDNS values as a result of authenticating users against the User Authentication System.

A client can send principal information as URL parameters, but the preferred way to send principal information is through key value pairs on the request headers as in the examples below.

A user represented by a principal ID and namespace will have associated roles and permissions in the OCLC identity management (IDM) system. These roles and permissions will be used to make authorization decisions that determine the success for a client’s request to access or modify data.

Example HMAC Signature Authorization Header:

Authorization: http://www.worldcat.org/wskey/v2/hmac/v1
clientId="tsFsoBXToV1uR8GEMJCcxz9NYpVvutsA5cJAD9cnKUc4FGYEntM6UkcIVlYp4ZhYFteVLAxOWJDUV85W",
timestamp="1361306811",
nonce="762343395744465450467911322335",
signature="2DwPAIYqlCOH9xCHM7PSnOBoVKk/PHrHPeIGmmEK/AI=",
principalID="8eaa9f92-3951-431c-975a-d7dfkd9rd131",
principalIDNS="urn:oclc:wms:da"

Example Access Token Authorization Header:

Authorization: Bearer tk_123456789,
principalID="8eaa9f92-3951-431c-975a-d7dfkd9rd131",
principalIDNS="urn:oclc:wms:da"

We are a worldwide library cooperative, owned, governed and sustained by members since 1967. Our public purpose is a statement of commitment to each other—that we will work together to improve access to the information held in libraries around the globe, and find ways to reduce costs for libraries through collaboration. Learn more »