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 as part of an HTTP request to a web service either:
principalID and principalIDNS values.
an Access Token.
PrincipalID and PrincipalIDNS
What are principalID, principalIDNS and Authenticating Institution?
The principalID represents a user id and the principalIDNS, or principal identity namespace, is an identifier for the system the user identity comes from. The authenticating institution is the WorldCat Registry ID for the institution that the user is associated with. Clients do not need to send this value as it is pre-associated with the WSKey or Access token the client sends.
These three values are used together to identity a specific user. A user represented by a principal ID, namespace and institution 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.
How do I obtain a principalID and principalIDNS?
Clients can obtain principalID and principalIDNS values via several methods.
- Authenticating users against OCLC's Authorization Server.
Clients can authenticate users via OCLC's OAuth Authorization Server which will return principalID and principalIDNS values for the user who logged in. The IDs provided via these flows are designed to be used ONLY with OCLC's APIs and systems.
- Authenticating users against a local User Authentication System.
If a client has a local User Authentication System that it has integrated with IDM, then the client can authenticate users via this system and obtain local identifiers (Correlation IDs) representing a specific user to be passed to the web service.
- Looking up values for a specific user in WorldShare Management Services.
Within the Admin Tab, you can search for a particular user. Once you locate a user you can obtain a valid set of principalD and principalIDNS values from the user record. We do not recommend using this method unless absolutely necessary as it means the client will be “hard-coding” these values into the web service request and each transaction will be associated with a single user. This information is listed under "Diagnostics". The principalID and the namespace is provided in this section.
How do I send the user's identity to the web service?
Access Tokens
The preferred way to send user information is via an Access Token. Access Tokens and their usage is described in detail on the Access Token documentation page. From a user authentication and authorization standpoint, because an Access Token can be associated with a particular user, user information can be sent to an OCLC web service by passing a valid Access Token associated with a user. When an Access Token is associated with a specific user than the client only needs to send that Access Token to the web service for the user information to be passed.
Example Access Token Authorization Header:
Authorization: Bearer tk_123456789
Specifying a PrincipalID and PrincipalIDNS in the Request
If an Access Token is not being used or not associated with a user, then the user identity can be specified by sending the principalID and principalIDNS as a set of key value pairs on the request headers as shown in the examples below.
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="8eab9f92-3951-431c-975a-d7dfkd9rd131", principalIDNS="urn:oclc:wms:da"