Page tree
Skip to end of metadata
Go to start of metadata

External Connectivity

While OmniStar is an all-in-one product that allows for the management of grants, ethics and research applications and projects across their complete lifecycle, we find that these systems are rarely implemented in isolation. As such, there is significant business value in exposing different functionality to both other systems within the main organisation as well as trusted third parties.

OmniStar provides this capability through a number of distinct APIs and integration points:

All of these deal with potentially sensitive data and so all are authenticated based on the requirements that consumers are likely to have.

Authentication

Multiple different authentication methods are provided for the external connectivity functionality. These include:

  • HMACSHA256 based signed requests;
  • Client certificate based authentication.

OmniStar authenticates browser-based users with an encrypted authentication cookie sent on each request. While the API generally does allow for access via this method, it is generally not recommended. Similarly, other methods are in place for other functionality (e.g. Kerberos for local services, signing certificates for SAML IdPs etc.) but are outside of the scope covered here.

HMAC Authentication

HMAC-based authentication is provided across the Omni external connectivity points. This authentication method involves signing each HTTP request with a pre-shared secret key (and including a corresponding access key along with the request).

At a high level, generating a request involves the following process:

  • Adding signature metadata (version/cypher).
  • Providing a timestamp. OmniStar will check this timestamp and if outside of a predefined clock skew will reject the request;
  • Calculating the hash-based message authentication code from a pre-shared secret signing key.
  • Adding the signature to the request via the Authorization header.

When OmniStar receives a request, it performs validation steps to ensure that the request is genuine – looking at the timestamp, request structure, finally generating an authentication code from the same request. Once that’s done, the system ensures that the generated authentication code matches the one provided in the original request.

This approach is in line with industry practice (mirroring approaches used by organisations like Amazon for access to protected S3 resources). The cyphers used are well known, secure and battle tested. The use of canonicalized timestamped requests and encrypted data being transferred minimises the potential attack surface even if the secure channel is compromised.

System Configuration

Before calling the OmniStar APIs, use the OmniStar internal portal to create one or more system access keys. Visit Administration > System Access Keys as a user with sufficient permissions (i.e. system admin). Add a System Access Key that applies to the type of information you plan to retrieve from the system using the APIs.

For more information on HMAC Access Key Purpose, refer to HMAC Access Key Purpose.

Select “Add system access key” from the Action menu:

Please note that the system automatically generates random Access key and Access secret when adding a new key:


Authentication Details

If your application is accessing OmniStar remotely, then it needs to authenticate itself by including the Omni Authentication header with all requests. Version1 of the signature can be generated as follows:

  1. Create the raw string to sign. This is the concatenation of multiple request parts:
    1. System Access Key
    2. HTTP method (eg "POST")
    3. Request URI (lowercase, absolute URI including action path)
    4. A request timestamp (seconds since the UNIX epoch)
    5. A random nonce (e.g. a guid)
    6. The request content's MD5 hash as a Base64 string.  In the case of a HTTP GET or other operation without content, this piece is excluded.
  2. Compute the hash using HMACSHA256 (with the system access key's secret as the initialisation bytes).  To convert this from unprintable bytes, encode this with Base64.
  3. Attach an Authentication header based on the concatenation of the following:
    1. "Omni " (the scheme, followed by a space)
    2. System Access Key
    3. : (a colon)
    4. Encoding of the signature computed in 2
    5. : (a colon)
    6. The nonce
    7. : (a colon)
    8. The request timestamp

Example Script

The following script block can be used by tools such as Telerik Fiddler and demonstrates the algorithm end-to-end.

Omni Signature
var accessKey = "Your Access Key Here";
var secretKey = "Your Secret Key Here";

var requestUri = oSession.fullUrl.ToLower();
var method = oSession.RequestMethod;

var epochStart = new DateTime(1970,01,01,0,0,0,0, DateTimeKind.Utc);
var now = DateTime.UtcNow;
var timeSpan = now - epochStart;
var requestTimestamp = Convert.ToUInt64(timeSpan.TotalSeconds).ToString();

var requestSignature = "";
var nonce = Guid.NewGuid().ToString("N");

var requestBodyBase64 = "";
if (oSession.requestBodyBytes != null && oSession.requestBodyBytes.Length > 0)
{
	var md5 = System.Security.Cryptography.MD5.Create();	
	var hash = md5.ComputeHash(oSession.requestBodyBytes);
	requestBodyBase64 = Convert.ToBase64String(hash);
}

var signatureRawData = accessKey + method + requestUri + requestTimestamp + nonce + requestBodyBase64;

var secretKeyBytes = Convert.FromBase64String(secretKey);
var signature = System.Text.Encoding.UTF8.GetBytes(signatureRawData);

var hmac = new System.Security.Cryptography.HMACSHA256(secretKeyBytes);
var signatureBytes = hmac.ComputeHash(signature);
var requestSignature = Convert.ToBase64String(signatureBytes);

oSession.oRequest["Authorization"] = "Omni " + accessKey + ":" + requestSignature + ":" + nonce + ":" + requestTimestamp;


Practical Usage

The Base.Interop library (F1Solutions.OmniStar.Base.Interop.dll) provided as part of OmniStar software contains functionality to perform the steps listed above transparently when using a .NET HttpClient. If you wire in F1Solutions.OmniStar.Base.Interop.HmacClientHandler with valid keys, it should be possible to call API methods without needing to handle authentication separately.

Example – Retrieving a sign in token (via the Registration and Authentication API)

Here is a PowerShell example that demonstrates how to create the authentication header using the Base.Interop library.

$omniUrl = Read-Host -Prompt 'Omni URL (eg https://omnistar.oregon.local)'
$accessKey = Read-Host -Prompt 'Access key'
$accessSecret = Read-Host -Prompt 'Access secret'
$username = Read-Host -Prompt 'Username'
$password = Read-Host -Prompt 'Password'

Add-Type -Path '<Path>\Base.Interop\bin\debug\F1Solutions.OmniStar.Base.Interop.dll'
Add-Type -Path '<Path>\packages\Newtonsoft.Json.8.0.3\lib\net45\Newtonsoft.Json.dll

$url = $omniUrl + '/api/Account/GenerateSignInToken'
$hmacHandler = New-Object F1Solutions.OmniStar.Base.Interop.HmacClientHandler -ArgumentList $accessKey, $accessSecret
$hmacHandler.InnerHandler = New-Object System.Net.Http.HttpClientHandler
$httpClient = New-Object System.Net.Http.HttpClient -ArgumentList $hmacHandler
$request = New-Object F1Solutions.OmniStar.Base.Interop.Account.SignInRequest
$request.Username = $username
$request.Password = $password
$serialisedRequest = [Newtonsoft.Json.JsonConvert]::SerializeObject($request)
Write-Host $serialisedRequest
$content = New-Object System.Net.Http.StringContent($serialisedRequest, [System.Text.Encoding]::UTF8, "application/json")

$response = $httpClient.PostAsync($url, $content).Result
$sc = $response.StatusCode

Write-Host "Status: $sc"
$responseBody = $response.Content.ReadAsStringAsync().Result
Write-Host $responseBody

Sample run of that script:

PS > .\TestSignIn.ps1
Omni URL (eg https://omnistar.oregon.local): http://omnistarlocal
Access key: MjM2LDQ0LDUsMTY5LDEzNSw5MSwxODYsMTY5LDEyNyw5
Access secret: MjYsMTc0LDEyMSwxNjEsNTgsMjQ4LDk3LDIzOSwxNzksOSwyMzEsMTE4LDI1NSw0NCwxMTgsMTcsMTcxLDIxNSwyNTAsNTQ=
Username: administrator
Password: *****
{"Username":"administrator","Password":"*****","SkipAgreement":false}
Status: OK
{"TokenIssueUrl":"http://omnistarlocal/Account/SignInToken?token=bBaZu975_MzEvvFr8LJkh
8tJ6BKq6AmC52quKMAWI_Em5rqWXonTn
kYU0391PC7AKnpmyy9NpqWrJe5eybYjlIdKnmYZAdArGfXDquJcBy9QTprazJgz7MfPV16vNkkoqpI6ZGzatMW
YRZ/5uRsRIJOSxYG93BnBT6m3BSlHDVx7h
TQR9nnqNYk_P8SbcLRPqHkut3cApqH0wyel70WWt4LcTQiYqFIqm2HzGdpURzs="}
PS >

This example pulls in the HmacClientHandler, attaches it to a new HttpClient and performs a POST request of the expected request payload to the authentication endpoint. The endpoint returns a JSON response.

Client-based Certificate Authentication

Application Interop is provided via WS-* WCF-based endpoints. These endpoints provide two-way security. Details on the configuration of client-based certificate authentication can be found in OmniStar Net Applications Interop.

Related Topics


Contents