2.7.2.2 Security Token

The API links calling the download tool can be protected from being manually copied and used by a different user under the existing SessionID.

Token based security is used to protect a call to download tool.

Token is encrypted by an application calling Thru API using a secret key shared with Thru.

The token it passed to the Thru server and is decrypted using the shared key.

Security token structure for download tool is represented in JSON with following fields:

{
“Version” ,
“FilePublicID”, “Email”,
“AllowedIP”,
“TimeStamp”
}

Where the parameters are:

Version : version of token object. Supported value: 1.

FilePublicID : download ID of the file AccessID returned by the call RetrieveUploadInfo()

Email : email of a user to record in audit records with operation. Could be different from a user account which opened a Thru server.

AllowedIP : IP address allowed to perform the download, will be checked by Thru server. If the IP address of connecting browser does not match AllowedIP, operation is blocked.

TimeStamp : time of token creation, used for token validation to protect against token replay. Thru server will check that token is not beyond expiration time interval defined in Thru server.

Note : Date should be strictly in the format MM/DD/YYY H:MM PM

Sample Token:

{
“Version”:“1”,
“ FilePublicID”:“0F540NC8ZAMQO”,
“Email”:“external-download-test@thru.com”,
“AllowedIP”:“64.95.64.190”,
“TimeStamp”:“10/04/2013 11:05:11”,
}

The following methods and options should be used by calling application to encrypt the token :

  • Encryption algorithm: Advanced Encryption Standard (AES-256) symmetric algorithm.

  • Encryptor specified key: shared key in base64string format

  • Initialization vector (IV): shared key in base64string format

Security token for URL should use base64string format.

Sample of token encryption parameters:

  • Encryptor specified key: AFA3wdfEuCrdFw8QaHFzN6LRXaBoCTHxcWnqNImp7g3=

  • Initialization vector (IV): JHnmhMkTjkl8fHqYx/l7bA==

  • Encrypted token in base64string format:

jGldNNh7rMjT/fLL27vyQDPXUl/UjBKKfgrzLAxmopIxotP/T20Mz5J180jhG3Soqkz8bB1AV6rz3NMcyYtmm3mdo+CLeD0FDfgJZ6cw1Iqs9V+R79KsJ1mzfUKGrgQmrOq1NlosLcBtzmoVLK4+Cqkt+bkNBdYoYw8DITFkHd/VsEHCnk5pjPd89mDATyjTu4xMCXFVH20lP7tTOU75k61LLSj3×6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPIThjeO==