Check out our upcoming webinars and client office hours calendar here!

How Can We Help?

Search icon

Search Results

Using HMAC Authentication to Access Interfolio APIs

Overview

Interfolio takes data security very seriously. For authentication, Interfolio uses the Hash-based Message Authentication Code (HMAC) mechanism. This is a stringent security standard used by companies such as Amazon Web Services for endpoint authentication. For more information, refer to wikipedia or other public sources. For authorization, Interfolio uses the tenant ID and a permission infrastructure that determines if the user has permission to access a particular set of data.

 

Prerequisites

Before attempting the HMAC authentication, a set of “keys” must be requested from Interfolio support. These keys (a public key and a private/secret key) will be generated by your Interfolio project manager and sent to the appropriate individual at the requesting institution. A single set of keys can be used to access all Interfolio applications. The script also requires the user to know their institutions assigned tenant ID and, if a Faculty Activity Reporting customer, database ID.

Before generating the necessary “signed hash(s)” (see below), the user will need to fully understand, and have planned out, the API calls that they will be making. Elements of the URL called will be needed to build the proper authentication.

 

Sample Scripts

HMAC API Access Control (Multiple Languages)

 

Using the HMAC Authentication

These are step-by-step, language-neutral instructions for properly generating and sending the necessary parameters for the HMAC authentication to Interfolio APIs. Samples of code based upon these instructions are available in a variety of languages including C#, Java, PERL PHP, Python (v2.x & 3.x), and Ruby (see link to sample scripts above).

  1.  Determine what API(s) are to be called and fully write out the necessary calling URL. This will be the “URL string.” The URL string will have 3 parts:
    • Host (including the https protocol statement)
    • Path
    • Query String (everything after, and including, the ‘?’) 
  2. Create a valid timestamp string of the current UTC (GMT) time
  3. Create a “verb string” composed of the concatenation of the following strings:
    • The verb for the request you want to perform ("GET" , "POST", "PUT", "DELETE" )
    • Three American Standard Code for Information Interchange (ASCII) newline characters, ‘/n’
    • The timestamp string
    • Another ASCII newline, ‘/n’ 
  4. From the URL string, extract the full path plus the query string:

    This should be all of the URLs after the fully qualified domain name, Fully Qualified Domain Name (FQDN, ending in “interfolio.com”), including the leading “/”, and, if there is a query string, the “?” and subsequent query string. This URL snippet will be called the “request string”.

     

    If there is no query string, i.e. parameters sent after the "?", then you will include just the path. 

     

    Note that there is a difference in how Faculty180 handles the request string. For HMAC with Faculty180, DO NOT include the query string, just the path.

     
  5. Create the “verb-request string” composed of a concatenation of:
    • The verb string, and
    • The request string 
  6. Create an encrypted string by HMAC_SHA1 encoding your verb-request string, being sure to use your Interfolio-issued secret key for the encoding.
  7. Base64-encode the encrypted string (this is the “signed hash”)
  8. When submitting the API request, explicit HTTP header statements will have to be sent.
    This header will have two statements; an authorization statement and a timestamp statement. These are composed as follows:

Authorization Statement

The keyword “Authorization” followed by:

  • a full colon,
  • a space,
  • the text “INTF”
  • a space
  • An authorization string which is the concatenation of your Interfolio public key, a colon character (":"), and the calculated "signed hash" generated in the prior step.
 
 

TimeStamp statement

The keyword “Timestamp” followed by

  • a full colon,
  • a space
  • timestamp string - preferred format is ISO 8601 Timestamp: yyyy-MM-ddThh:mm:ss (or similar timestamp)
 
 

Interfolio Database Statement

The keyword “INTF-DatabaseID” followed by

  • a full colon,
  • a space
  • the Faculty180 database ID or FS & RPT tenant ID
 
 

Note that the HMAC authorization header will have to be generated and sent with every request.

 

Example

If you want to pull a list of open positions from the Faculty Search API, the URL string would be something like:

https://xxx.interfolio.com/byc-search/220/positions?open=true
  • The timestamp string would look something like: 2018-11-05 10:17:36
  • The “verb string” is then: GET\n\n\n2018-11-05 10:17:36\n
    (where \n is our ASCII newline character)
  • The “request string”, i.e. the path (and possibly query string) extracted from our URL is:
    /byc-search/220/positions?open=true
  • The concatenated “verb request string” is now:
    GET\n\n\n2018­11-05 10:17:36\n/byc-­search/220/positions?open=true
  • When HMAC encrypted using our key the result is:
    \x8A\xCCo[ v\x1AO\x9F@\xB5eYc\xA1\xE2\x17\x15\x02\x9A
  • The signed hash after base64-endcoding is: :isxvWyB2Gk+fQLVlWWOh4hcVApo=
  • The HTTP header to be sent then looks like:

Authorization: INTF V9SW3ZJ50F6X5WMHTB8:isxvWyB2Gk+fQLVlWWOh4hcVApo=

TimeStamp: 2018­11­05 10:17:36 (Where the string “V9SW3ZJ50F6X5WMHTB8” is the Interfolio-issued public key)

 

Was this article helpful?
Give feedback about this article