API Documentation
\
OCLC
Auth

\OCLC\AuthWSKey

A class that represents a clients OCLC Web Service Key.

The WSKey has a key and secret and has access to one or more OCLC Web Services. Optionally, it can include principal information in the form of a principal ID and IDNS that represent an user and a redirect URI to be used in the OAuth 2 login flows. The WSKey class is used to

  • generate HMAC signatures
  • return the login URL for the OCLC Explicit Authorization flow for requesting an AuthCode
  • redeem an authorization code for an access token
  • request an access token via a client credentials grant flow

Summary

Methods
Properties
Constants
__construct()
getKey()
getSecret()
getRedirectUri()
getServices()
setDebugTimestamp()
setDebugNonce()
getSignedRequest()
getLoginURL()
getAccessTokenWithAuthCode()
getAccessTokenWithClientCredentials()
getHMACSignature()
$testServer
$userAgent
No constants found
getAccessToken()
$validOptions
N/A
signRequest()
normalizeRequest()
AddAuthParams()
$key
$secret
$redirectUri
$services
$debugTimestamp
$debugNonce
$testMode
$logger
$logFormat
$user
$bodyHash
$authParams
$signedRequest
N/A

Properties

$testServer

$testServer : \OCLC\Auth\binary

Whether or not the application is interacting with a test server

Type

\OCLC\Auth\binary — static $testServer

$userAgent

$userAgent : string

The user agent to use when sending the request

Type

string — static $userAgent

$validOptions

$validOptions : array

An array of options values valid for constructor

Type

array — static $validOptions

$key

$key : string

The string that represents your API key

Type

string

$secret

$secret : string

The secret used when generating digital signatures

Type

string

$redirectUri

$redirectUri : string

the redirect URI associated with the WSKey that will 'catch' the redirect back to your app after login

Type

string

$services

$services : array

An array of one or more OCLC web services, examples: WorldCatMetadataAPI, WMS_NCIP

Type

array

$debugTimestamp

$debugTimestamp : string

a timestamp for debug purposes

Type

string

$debugNonce

$debugNonce : string

a nonce for debug purposes

Type

string

$testMode

$testMode : boolean

Whether or not to run in test mode

Type

boolean

$logger

$logger : \OCLC\Auth\unknown

The logger object

Type

\OCLC\Auth\unknown

$logFormat

$logFormat : string

The format to log in

Type

string

$user

$user : \OCLC\Auth\OCLC\User

User object used when building an HMAC signature of using client credentials grant

Type

\OCLC\Auth\OCLC\User

$bodyHash

$bodyHash : string

bodyHash of the request

Type

string

$authParams

$authParams : array

an array of Authentication name/value pairs example username/testuser

Type

array

$signedRequest

$signedRequest : string

The signed request

Type

string

Methods

__construct()

__construct(string  $key, string  $secret, array  $options = null)

Construct a new Web Service key for use when authenticating to OCLC Web Services.

Parameters

string $key

the hashed string that represents your API key
string $secret

a string which is the secret used when generating digital signatures
array $options

an array of three possible name/value pairs

  • redirect_uri: a string which is the redirect URI associated with the WSKey that will 'catch' the redirect back to your app after login
  • services: an array of one or more OCLC web services, examples: WorldCatMetadataAPI, WMS_NCIP
  • logger: an object that support a Psr\Log\LoggerInterface
  • logFormat: a string which is the log format

getKey()

getKey() : string

getKey

Returns

string —

the Hashed string that represents your API key

getSecret()

getSecret() : string

getSecret

Returns

string —

the secret used when generating digital signatures

getRedirectUri()

getRedirectUri() : \OCLC\Auth\the

getRedirect_uri

Returns

\OCLC\Auth\the —

redirect URI associated with the WSKey that will 'catch' the redirect back to your app after login

getServices()

getServices() : \OCLC\Auth\an

getServices

Returns

\OCLC\Auth\an —

array of one or more OCLC web services, examples: WorldCatMetadataAPI, WMS_NCIP

setDebugTimestamp()

setDebugTimestamp(string  $timestamp)

Set a timestamp for debugging

Parameters

string $timestamp

setDebugNonce()

setDebugNonce(string  $nonce)

Set a nonce for debugging

Parameters

string $nonce

getSignedRequest()

getSignedRequest() : string

getSignedRequest Get a signed request

Returns

string —

of signed request

getLoginURL()

getLoginURL(integer  $authenticating_institution_id = null, integer  $context_institution_id = null) : string

Return the login URL used with OCLC's OAuth 2 implementation of the Explicit Authorization Flow.

Parameters

integer $authenticating_institution_id
integer $context_institution_id

Returns

string —

The Login URL used with OCLC's OAuth 2 implementation of the Explicit Authorization Flow

getAccessTokenWithAuthCode()

getAccessTokenWithAuthCode(string  $authCode, integer  $authenticatingInstitutionId, integer  $contextInstitutionId) : \OCLC\Auth\OCLC/Auth/AccessToken

Returns an OCLC/Auth/AccessToken object

Parameters

string $authCode

authorization code returned as a query parameter
integer $authenticatingInstitutionId

the WorldCat Registry ID of the institution that will login the user
integer $contextInstitutionId

the WorldCat Registry ID of the institution whose data will be accessed

Returns

\OCLC\Auth\OCLC/Auth/AccessToken —

Returns an /OCLC/Auth/AccessToken object when given

getAccessTokenWithClientCredentials()

getAccessTokenWithClientCredentials(integer  $authenticatingInstitutionId, integer  $contextInstitutionId, \OCLC\Auth\OCLC/User  $user = null) : \OCLC\Auth\OCLC/Auth/AccessToken

Returns an OCLC/Auth/AccessToken object

Parameters

integer $authenticatingInstitutionId

the WorldCat Registry ID of the institution that will login the user
integer $contextInstitutionId

the WorldCat Registry ID of the institution whose data will be accessed
\OCLC\Auth\OCLC/User $user

an /OCLC/User object which contains a valid principalID, principalIDNS and insitution ID for a user

Returns

\OCLC\Auth\OCLC/Auth/AccessToken —

Returns an /OCLC/Auth/AccessToken object when given

getHMACSignature()

getHMACSignature(string  $method, string  $request_url, array  $options = null) : string

Generates a digital signature for a given request according to the OAuth HMAC specification

Parameters

string $method

the HTTP method, GET, POST, PUT, DELETE
string $request_url

the URL the request will be made to
array $options
  • User - OCLC/User User an /OCLC/User object which contains a valid principalID, principalIDNS and insitution ID for a user
    • BodyHash - bodyHash of the request this is optional
    • AuthParams - an array of Authentication name/value pairs example username/testuser

Returns

string —

The HMAC Signature that should be sent in the Authorization Header

getAccessToken()

getAccessToken(string  $grant_type, array  $options, \OCLC\Auth\OCLC/User  $user = null)

Get an Access Token

Parameters

string $grant_type
array $options
\OCLC\Auth\OCLC/User $user

signRequest()

signRequest(string  $key, string  $secret, string  $method, string  $request_url, string  $bodyHash, string  $timestamp, string  $nonce) : string

Create a Signature for a request using

Parameters

string $key
string $secret
string $method
string $request_url
string $bodyHash
string $timestamp
string $nonce

Returns

string

normalizeRequest()

normalizeRequest(string  $key, string  $method, string  $request_url, string  $bodyHash, string  $timestamp, string  $nonce) : string

Normalize the Request by breaking apart the URL

Parameters

string $key
string $method
string $request_url
string $bodyHash
string $timestamp
string $nonce

Returns

string

AddAuthParams()

AddAuthParams(\OCLC\Auth\OCLC/User  $user, array  $authParams) : string

Add the PrincipalID, PrincipalIDNS and any other Authentication Parameters to the Authorization Header

Parameters

\OCLC\Auth\OCLC/User $user
array $authParams

Returns

string