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

NOTE: In both cases, password must be encoded via the one-way SHA256 hash function to ensure that the password is not sent over the line in clear text, which is especially important if the API is not using HTTPS. To ensure that the value can be sent correctly, the hash value needs to be base64 encoded as well.

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

Password (clear text)	Password (SHA 256)	Password (Base64)
Test	532eaabd9574880dbf76b9b8cc00832c20a6ec113d682299550d7a6e0f345e25	Uy6qvZV0iA2/drm4zACDLCCm7BE9aCKZVQ16bg80XiU=

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

GET /token, eg. https://api.perfion.local/token
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.

GET /token?username=<username>&password=URL_ENCODE(<BASE64(SHA256(<password>))>)

Note that the Base64 encoded password needs to be URL encoded to ensure correct transfer as a query string parameter.

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.

username=<username>&password=<BASE64(SHA256(<password>))>&grant_type=Password

Note that is preferable to use the POST endpoint instead of the GET endpoint if you are running a version of Perfion that supports it. This is to avoid sending sensitive information in a GET request that may be cached.

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:

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 - OAuth 2.0 and OpenID Connect protocols on the Microsoft identity platform - Microsoft identity platform

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!

Validation of Bearer Tokens

Verification of the validity of a bearer token is based on a digital signature contained within the token itself. Tokens issued by Perfion is digitally signed using a private key which from the 2024-R2 release may be re-generated via system settings.