PNAUTHINFO3
Under this scheme, two authorization parameters must be passed along with the scheme. The first parameter is the credential parameter. This parameter contains both the user id of a MyPreferences’ agent and the issued timestamp. The second parameter contains the signature used to verify the identity of the requestor. Both parameters are delimited by a space, as shown in the following example.
GET https://pm.mypreferences.com/api/3/SanchezAssociates/Programs HTTP/1.1 Host: pm.mypreferences.com User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101 Firefox/38.0 Accept: application/json Accept-Language: null Accept-Encoding: gzip, deflate DNT: 1 Content-Type: application/json Authorization: PNAUTHINFO3-HMAC-SHA256 Credential=RickSanchez/2015-08-10T20:11:00 Signature=Lbhe+fKoQPZhzUYWHMVADC4BhqtAMQkfAfpR6Wzbxe0= Connection: keep-alive
Authorization Credential Parameter
This scheme defines two authorization parameters. The first is the credential parameter. It is composed of a user id field and an issued timestamp field separated by a forward slash, as shown below:
Credential=(UserId)/(ISO 8601 Issued Timestamp)
UserId
The UserId field must be a valid user id belonging to the client making the request. In the example above, the UserId “RickSanchez” is an active, valid user for the client “SanchezAssociates”. The UserId will be a component in generating the signature parameter.
ISO 8601 Issued Timestamp
The Issued Timestamp field must be a valid ISO 8601 formatted timestamp and cannot be a future date; this field is used to determine if the authorized request has expired. Future dates are considered invalid and the request will be rejected by the WebAPI. By default, an authorized request will only be valid for 15 minutes from the issued date; however, this can be adjusted on a per client basis by setting the PNE configuration value shown below. Please note that future schemes may migrate this field to another header.
Notes on time zones:
The MyPreferences WebAPI services supports two time zones for the ISO 8601 Issued Timestamp. One is UTC, while the other is EST (UTC-5:00)/EDT (UTC-4:00). It is highly recommended that the ISO 8601 Issued Timestamp is formatted as UTC, as it reduces the complexities of having to adjust for time zone offsets for the local server's time. The example provided in this documentation uses the EST time zone.
| Configuration Name | Supported Value |
|---|---|
| PNAUTHINFO_EXPIRATION_IN_SECONDS | Numerical value that represents the number of seconds. |
Authorization Signature Parameter
The second parameter is the signature. The signature is a keyed or un-keyed message digest based on the crypto algorithm provided in the scheme. The format of the message also varies based on whether the scheme uses a keyed or un-keyed algorithm. Once the message digest is generated, it must be encoded as base 64 encoded before being assigned to the Signature parameter, as shown below:
Signature=Base64Encoding(MessageDigest)
Keyed Algorithm
With the keyed algorithm, the message is composed of the ClientId field supplied from the URL, and the fields provided in the credential parameter, both the UserId and the ISO 8601 Issued Timestamp fields. Please note that future authorization schemes may use a different format and that these fields should NOT be URL encoded when composing the message. Each of these three fields must be concatenated together using a colon as a delimiter as the following shows:
Message=(ClientId):(UserId):(ISO 8601 Issued Timestamp)
Once the message has been generated it is then hashed using the client’s private key and the crypto algorithm specified in the authorization scheme.
MessageDigest=HMAC-CryptoAlgorithm(Message, PrivateKey)
The signature, as shown in the example above, is generated as follows.
Signature=Base64Encoding(HMACSHA256(“SanchezAssociates:RickSanchez:2015-08-10T20:11:00”,“SeemslikearareopportunityMorty!”))
| Field | Value |
|---|---|
| ClientId | SanchezAssociates |
| UserId | RickSanchez |
| ISO 8061 Issued Timestamp | 2015-08-10T20:11:00 |
| Private Key | SeemslikearareopportunityMorty! |
Additionally the client’s private key is stored within the PNE Configuration tables as the APIHashKey.
| Configuration Name | Supported Values |
|---|---|
| APIHashKey | Any string value. |
Non-Keyed Algorithm
The non-keyed algorithm follows the same message format as the keyed algorithm, except it incorporates the private key into the message. This is to provide a small amount of additional security, yet it is still recommended to use the keyed algorithm whenever possible.
Message=(PrivateKey):(ClientId):(UserId):(ISO8601 Issued Timestamp):(PrivateKey)
As seen above, the private key is concatenated to the front and the back of the message, before it is hashed. The message digest is then generated based on the message and the crypto algorithm specified in the authorization scheme.
MessageDigest=CryptoAlgorithm(Message)
Additional Notes on Authorization Signature
Case Sensitivity
The signature is case sensitive to the fields supplied. When including a field like the ClientId in the URL or the UserId and Timestamp from the Credential parameter, it is vital to make sure that the value in those fields have the exact case syntax that was used when generating the signature. For example, if the ClientId that was used to generate the hash was SanchezAssociates, yet the URL has the case syntax of SANCHEZASSOCIATES then the authorization will fail and the request will be rejected.
Spaces and Special Characters in the UserId.
If the UserId field contains special characters or a space then the UserId field should be URL Encoded before using it in the MessageDigest and when using it in the Credential parameter.
Credential=URLEncode(UserId)/(ISO 8601 Issued Timestamp)
Message=(ClientId):(URLEncode(UserId)):(ISO 8601 Issued Timestamp)