Authentication Options

Since SIF utilises standard REST for all its APIs (data model services or infrastructure services) it also supports the most common authentication methods. These typical authentication methods include Basic and OAuth but also an HMAC/SHA based authentication. As with typical REST APIs the authentication information is provided in the standard HTTP Header called “Authorization”. Details for each SIF supported authenication method are outlined in the sections below.

Basic Authentication

All SIF APIs support the standard Basic Authentication method as specified in in RFC 7617 from 2015, which obsoletes RFC 2617 from 1999. In summary each HTTP request has to provide an HTTP header called “Authorization” and its content must be of the following structure:

Where Basicis a fixed keyword to indicate that basic authentication is used, followed by a space (“ "), followed by the <credentials>. The <credentials> is a base64 encoded string that is created by concatinating the user name, followed by a colon (:) and the password.

Example

User Name: userABC

Password: myp@ssword1

Step 1: Concatinate the user name, a colon and the password: userABC:myp@ssword1

Step 2: Base64 encode the result of Step 1: dXNlckFCQzpteXBAc3N3b3JkMQ==

Final HTTP Authorization header: Authorization: Basic dXNlckFCQzpteXBAc3N3b3JkMQ==

HMAC/SHA1 Based Authentication

While Basic Authentication is a very simple way to enable security it is, as the word indicates, “Basic”. The major disadvantage with Basic Authentication is that the username as well as the password can easily be extracted from the <credential> component of the Authorization HTTP header (i.e. Base64 Decode is all that is required to extract the password). Hence it is not considered very secure and most production systems won’t allow this type of authentication.

The HMAC/SHA1 authentication method that forms part of SIF addresses the issue where the username and password can be extracted from the <credential> component of the Authorization HTTP header. The HMAC/SHA1 authentication method does not transmit the password on the wire at all. It creates a credential token that is decrypted by using a one-way 256 bit strong hash. To utilse the SIF HMAC/SHA1 authentication method each HTTP request has to provide an HTTP header called “Authorization” and its content must be of the following structure:

Where SIF_HMACSHA256is a fixed keyword to indicate that SIF HMAC/SHA1 authentication is used, followed by a space (“ "), followed by the <credentials>. To generate the <credentials> token the following will be required:

• Timestamp: Date/Time in in ISO-8601 format: Example: 2013-06-22T23:52-07)

• Application Key/Session Token (username): Example: RamseyPortal

• Shared Secret (password) to hash the above information: Example: a1b2c398

The steps below outline how the <credential> token is generated based on the above 3 elements/values.

It is important to note that this authentication method also requires the HTTP header called ‘timestamp’ which must hold the exact value that is used in the first step in above table. For the above example a Service Consumer would set the following two HTTP headers in each request to utilise the SIF HMAC/SHA1 authentication method:

If the timestamp HTTP header is not provided then authentication on the Service Provider must fail. The Service Provider must respond with an HTTP Error Status of 401 (Not Authorized).

Another advantage this authentication method offers is that the <credentials> are different for each service consumer request because the timestamp used to generate the <credentials> token should be different for each request. Since the timestamp is also required in a HTTP header the service provider can check if the <credentials> are “exprired” (eg. older than 5 minutes) and return a HTTP Error Status of 401 if it is expired. This will also avoid a “replay” of a request of an unauthorised source in case where an unauthorised source should have gotten hold of the <credentials> token at some stage.

A number of code samples for various programming languages can be found here.

OAuth Authentication

TBC