Authentication

The Perfion API Service support multiple ways of authenticating the user that is calling the service. Currently, the REST endpoint only supports Bearer token authentication. The Web Service endpoint supports both Basic (username/password) or Bearer token authentication.

Basic authentication

Before version 5.0 the Perfion API Service, you need to authenticate using two custom HTTP headers called, “user” and “pwd” respectively. After version 5.0 the API, also supports Basic and Bearer token authentication through the standard Authorization header.

To use Basic authentication (username & password), you have two options: (1) using the user and pwd custom headers or the standard Authorization header. We strongly suggest, for the Perfion API version 5.0 and later, that you use the Authorization header. The user can be any valid Perfion user with the corresponding password.

Authorization header

The format for the Authorization header values is ‘Basic BASE64(“username:SHA256(password)”)’.

var auth = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{username}:{computeHash(password)}"));
request.Headers.Add( "Authorization", $"Basic {auth}" );

Custom headers

To use the user and pwd headers, set the user to username and the pwd header to BASE64(SHA256(password)).

request.Headers.Add( "user", username );
request.Headers.Add( "pwd", computeHash( password ) );

Hashing of password

private static string computeHash( string hashString ) {
  using( System.Security.Cryptography.SHA256 encrypter = System.Security.Cryptography.SHA256.Create() ) {
    byte[] strBytes = Encoding.UTF8.GetBytes( hashString );
    byte[] encryptedBytes = encrypter.ComputeHash( strBytes );
    return Convert.ToBase64String( encryptedBytes );
  }
}

Example

Bearer token authentication

In addition to authenticating towards the Perfion API using tokens issued by the Perfion API itself, the Perfion API also supports Bearer token authentication using tokens issued by a Microsoft Azure AD from version 5.0 and later.

The bearer token is sent to the API via the Authorization header. Format of the value is ‘Bearer <token>’

Perfion API Service issued token

To issue a token from the Perfion API, you can use one of two endpoints

1. GET /token, eg. https://api.perfion.local/token

2. POST /oauth2/token endpoint, e.g. https://api.perifion.local/oauth2/token.

You need to authenticate to the token endpoints using a Perfion username and password. If authentication is successful, the endpoint will return a token that can be used for authentication towards the API Service data endpoints. As described for the Basic authentication above, the password must be encoded via SHA256 and Base64.

GET /token

For the GET endpoint, the username and password needs to be supplied as query string parameters.

POST /oauth2/token

For the POST endpoint, the username and password, following the OAuth2 standard, needs to be sent to the endpoint using three form-urlencoded parameters - username, password & grant_type.

Responses

The endpoints will respond with the following response codes

Response code 200 (OK)

The request was successful. The response body contains is a JSON object formatted as follows:

{
"access_token": "<token>",
"token_type": "Bearer",
"expires_in": <Expires in seconds>,
"expiry_date": "<UTC DateTime>"
}

Tokens will, per default expires after 10 hours. The property values expires_in and expiry_date tells you when the token expires. The date time is in UTC format and the expires_in is in seconds.

Response code 400 (Bad request)

Given parameters was missing or invalid. The response body contains is a JSON object formatted in one of the following ways:

Response code 401 (Unauthorized)

No valid authentication token was supplied!

Response code 500 (Internal server error)

Some unexpected error has occurred. The response body contains is a JSON object formatted as follows:

Azure AD bearer token

Starting from version 5.0 of the Perfion API Services, it supports using Bearer tokens issued by Azure AD B2B. This requires that the Perfion API Services has been configured correctly. Please refer to Perfion API – Installation Guide for details on how to configure this.

Azure AD supports multiple different user flows for issuing tokens, describing these are outside of the scope of this document. Instead, please refer to Microsoft’s documentation - https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols

When using Azure AD bearer tokens, the Azure AD will authenticate the user and issue a token containing the identity of the signed in user. Perfion uses the UPN claim in the token to match the bearer token to a user in Perfion. The user thus needs to have an email configured, for Perfion to do this mapping.

Getting a token via the Perfion Windows client

Open Perfion and go to Administration -> Users and groups:

Select the user you want to generate the token for and open the user properties and select “JSON API Token”

Fill in the URL for your JSON API and select the number of days the token should be active.

The aspire time value can be between 1 day and 3650 days (10 years). Make sure to make the lifetime of the token as short as possible.

When the “Generate” button is clicked, Perfion tries to get a token from the specified API in the URL. Example is shown below.

If something goes wrong, e.g. the API is not found or the selected user is not found, an error will be shown instead!