# Authentication

# Authentication Overview

# Introduction

Akixi Application uses a password-based authentication mechanism. Most Akixi features are only available to authenticated Users - therefore, authentication-related steps normally precede all other Web Services requests.

Please note that Web Services authentication procedure slightly differs from authenticating via a Web Browser, where the corresponding User simply passes correct username and password values via the “Sign In” web page, and signs out by clicking on a corresponding link.

In contrast, the Akixi Web Services authentication procedure, consists of three compulsory operations:

# Creating Session

The CreateSession operation is submitted in order to create a new API session. The request response message returns two session-related parameters that must be read & utilised in subsequent operations. The first is a session identifier value used to track the underlying API session. The second is a nonce value, which must be stored locally in order to subsequently be utilised for generating password hash values when actually submitting authentication requests and other requests which involves sending password values.

# Authentication Procedure

An Authenticate request is submitted to authenticate & associate a particular Akixi administrative User with the API session. If authentication is successful, the client-side’s SessionID will be maintained against the corresponding User’s Akixi account. This will allow the client to perform further Web Service API requests by simply providing a correct session identifier value.

# Signing Out

A SignOut operation must be submitted in order to explicitly end the API session, which immediately frees up server-side resources and also improves security. Naturally, all Web Services related use cases should end with a SignOut operation.

The above steps are summarised within the sequence diagram shown below:

Further details on each authentication operation, the required parameters, and any related security considerations are all provided within the following sub-sections.

# Security

# Recommendations On Security

Akixi User credentials must be treated as confidential & sensitive information. Therefore, developers and users working on/with Web Services client applications should carefully evaluate a password protection schema that will provide a reasonable level of security. For example, you must avoid bad practices like storing Akixi credentials in clear text within unencrypted configuration files, key-stores, and/or database fields, especially if publicly accessible directly or indirectly. All security- related scenarios must be evaluated and tested in order to avoid security breaches caused by client-side vulnerabilities.

Please also note that under no circumstances should you pass your actual password (i.e. the value that your client-side logic uses to authenticate via Web Browser) within any HTTP protocol and/or API request parameter. Always provide the multi-digest value instead. To learn more about multi- digest values, please refer to the corresponding section.

# Brute Force Attack Prevention

If a user authentication attempt fails due to incorrect credentials, you will get 3 attempts before the application will temporarily lock out the corresponding User account for a period of 5 seconds. Subsequent failed password attempts will double the temporary lock out period (i.e. to 10 seconds, 20 seconds, etc.).

# Session Timeouts

Once signed in, your session can either expire due to inactivity, or reach an overall reauthentication timeout limiting the maximum possible duration of an active session.

Therefore when submitting WS API requests, they can potentially fail with specific error codes which indicate the specific session timeout scenario case as defined within the table below:

# Creating Sessions

The CreateSession operation creates a new API session and returns the associated server-side session identifier as well as an authentication nonce. The session identifier value is used to track the underlying API session, whereas the nonce must be appropriately used when generating password hash values in subsequent authentication requests.

To invoke a session creation operation, you must simply send a CreateSession request and include a non-empty InvokeID value.

The structure of the request is provided below:

<Request Operation="CreateSession">
    <InvokeID>00001</InvokeID>
    <OperationPayload>
        <Property Name="Language">en_GB</Property>
    </OperationPayload>
</Request>

By default, the operation’s request body is quite minimalistic: only InvokeID is required to successfully create a session.

However, you can also explicitly specify the locale string that will be used to set all language- related resources of the session (e.g. output messages). This can be done via optional OperationPayload Property. OperationPayload properties of the CreateSession operation are provided below:

The languages supported by the Akixi Application are listed below:

If the request is successful, you will receive two properties within your operation’s payload:

• Session Identifier.
• Session Nonce.

Response example of a successful scenario is provided below:

<Response Result="Success">
    <InvokeID>00001</InvokeID>
    <Success>
        <Property Name="SessionID">EFA4902A7F61D03E42BF3222B0A246BF</Property>
        <Property Name="Nonce">a8aa7a7ea26f9225d1b03ea7e8e6a6ca</Property>
    </Success>
</Response>

Please note that you must parse & store the nonce and session identifier values for further use. Nonce value will be required to generate a multi-digest password hash (see later sub-section “Multi-Digest Password Hash Generation”) and also used as a key when encoding password values in other requests, whereas the session identifier is a mandatory parameter that must be passed within every Web Services request.

You will need to check the Result attribute value of your response before reading session-related values. If the Result value equals to "Success", you can then parse & extract the SessionID and Nonce properties. The session identifier and nonce properties are 32-character alphanumeric text values. They are provided in uppercase and lowercase respectively, and the corresponding character case must be preserved when re-using these values in other Web Services API requests.

The nonce value is an additional security measure used by the Akixi Service in order to ensure that previous authentication requests cannot be reused in replay attacks. Please note that the nonce value is not the same as the session identifier. The nonce is regenerated for every authentication attempt and is used to calculate a multi-digest password value, which would be subsequently calculated by the client-side logic for authentication requests made later.

If the operation was unsuccessful (i.e. if the response message’s Result attribute equals to "Fail"), you will need to read details related to a failure. An example of an unsuccessful response is shown below:

<Response Result="Fail">
    <Error>
        <ErrorCode>10101</ErrorCode>
        <ErrorMessage>Invoke ID is not specified within the request.</ErrorMessage>
    </Error>
</Response>

Some common errors returned by this operation are provided in the table below:

# Authentication Procedure

Most Akixi features are only available to authenticated users. Therefore, you will need to authenticate the session against your credentials before calling any other WS-related requests. Following sub-sections describe the structure of an authentication request and values that are passed within its body.

# Multi-Digest Password Hash Generation

# Multi-digest Password Structure

Before populating the Authentication request, you will need to generate a combination password digest value. A digest value is basically an amalgamation of many different hash combinations that is used in order to securely authenticate the User (without exposing their actual password).

In order to authenticate, you must perfectly reproduce the hash generation mechanism within your client’s logic. To easily replicate the hashing mechanism, Akixi recommends to choose a common programming language that is compatible with libraries/methods providing the following cryptographic and encoding logic:

• SHA-256 hash/digest generation.
• SHA-1 hash/digest generation.
• UTF-8 encoding (Unicode text conversion to byte sequence).
• Binary to hex-text conversion (byte sequence to hex string).

The entire operation can most easily be represented as the following theoretical formula where “+” represents a text concatenation operator and where “&” represents a byte array concatenation operator:

 LowerCase( Hex( SHA-256( UTF8Encode([Nonce]) & SHA-256( SHA-256 ( UTF8Encode([Username])) & SHA1( UTF8Encode( [Password] ) ) ) ) ) )

Where:

Firstly, you will need to hash your credentials. Use the SHA-256 algorithm to hash your username, and SHA-1 algorithm to hash your password.

Please note that the SHA-1 hash operation specifically on the password value is deliberate, but is not in any way a “wacky” attempt to do double hashing or apply an inconsistent algorithm unnecessarily for the purposes of obscurity. Instead, the SHA-1 algorithm is deliberately used to satisfy a requirement related to backward compatibility of server-side password value storage.

On the next step of the multi-digest value generation, Akixi username and password hashes are concatenated together, then hashed once again using the SHA-256 algorithm. The nonce value is then appended to the resultant hash/digest value derived from the user credentials, and the cumulative value hashed once again. The following table displays the required operations in a more readable way (note that “&” character represents byte sequence concatenation):

The final SHA-256 value must be converted to lowercase. Even if your implementation of SHA-256 hashing algorithm’s default output format is lowercase, it is recommended to explicitly convert the output string into lowercase using a corresponding method provided by the programming language of your choice. This will make the output consistent with the Akixi hashing mechanism (therefore, if a default implementation of your hashing library subsequently changes from lowercase to uppercase in future versions, your password hashing implementation will still be valid).

# Multi-digest Password Hash Generation Example

Values provided in the following example can be used to test your implementation of the Akixi password hashing procedure. To test your implementation, you can generate a hash for predefined sample values. If your multi-digest password hash is identical to the hash provided in this example, it means that your procedure correctly replicates the Akixi hashing mechanism. Otherwise, check whether hashing and concatenation operations are executed in the right order.

1. Step: Create a test method that will include sample values from this example.

You will need to generate a multi-digest password hash within your client-side logic. Sample values that will help you to test your implementation are provided below:

2. Step: Generate a multi-digest password hash.

Please ensure that your password hashing mechanism corresponds to the following pseudocode:

LowerCase( Hex( SHA-256( UTF8Encode(“84c3c1e5b58a0039bfc8219169cbe7a6”) & SHA- 256( SHA-256 ( UTF8Encode(“WebServicesAdmin@akixiprovider.com”) ) & SHA1( UTF8Encode(“p@ssword4W3bS3rv1c3s”) ) ) ) ) )

3. Step: Verify the hash.

If the password hashing mechanism has been implemented correctly, it must return the following hash/digest as a text value:

27226e3f7c0a69032ab16c2e98b60de9018c0facda2569406103dc3b90b86fec

If the final hash does not match, please ensure that you have fully replicated the hashing logic. If you are entirely sure that you have met all requirements described in this document, please e-mail support@akixi.com with details related to your implementation for the authentication operation. These can include code/pseudo-code fragments responsible for multi-digest generation, SHA-256/SHA-1 library versions, etc.

# Example Routine In Sample Code

A full password multi-digest generation routine is provided within the sample code by static method com.Akixi.Public.Utils.Security.CSecurity.MultiDigestPasswordGenerate() of the WSClientUtils project. To learn more about the sample code, refer to chapter 10 (“Developing Client Applications”).

# Manual SOAP Message Construction For SoapUI Usage

It is also possible to manually construct a raw SOAP message for the Akixi WS Authentication Request for use in testing tools similar to SoapUI – the required authentication hash value can be calculated using online tools for hashing and text-to-binary-hex conversions such as:

• Hashing conversion tool 1
• Hashing conversion tool 2

However, you must carefully perform the correct sequence of string-hash, binary-hash, and text-to- binary-hex operations. In particular, a hex text value representing the nonce’s binary encoding needs to be generated, and then the credential’s SHA-256 multi-hash value inclusive of both user name & password sub-hash values should be appended to the end of it before performing the final resultant binary-hash operation. Depending on how the corresponding web-site tool depicts the character case of the final value, an upper-to-lower case conversion tool may also be required.

Note that some on-line tools and/or web sites tend to push users a lot of advertisements, can be hosted from locations not necessarily under the jurisdiction of formal international guidelines, nor may such sites legitimately be authorised to provide their functionality free-of-charge depending on the way that licensing notices and/or usage rules have been published.

Therefore, Akixi provides no warranty over the reliability of using any 3rd party utility web site, nor guarantees that users of such tools won’t be liable for any one-off and/or ongoing charges. Accordingly, Developers must check & assess such conditions themselves before usage.

# Authentication Request

Once calculated, the multi-digest hash value should be specified within an Authenticate request (using the Password parameter). Other values used within the Authenticate request are the InvokeID, SessionID and Username elements.

The structure of an Authenticate operation is provided below:

<Request Operation="Authenticate">
    <InvokeID>00002</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
    <Username>WebServicesAdmin@akixiprovider.com</Username>
    <Password>27226e3f7c0a69032ab16c2e98b60de9018c0facda2569406103dc3b90b86fec
    </Password> <!-- Payload containing optional properties. -->
    <OperationPayload>
        <Property Name="SessionContext">Desktop</Property>
    </OperationPayload>
</Request>

The request contains of 4 obligatory parameters: InvokeID, SessionID, Username and Password. Operation-specific parameters are described below:

You can also specify optional authentication-related properties within the Operation Payload. For instance, you can configure client’s session context using the corresponding Property:

Currently supported Session Context types are listed below:

If all parameters are correct, you will receive the following response:

<Response Result="Success">
    <InvokeID>00002</InvokeID>
</Response>

If the operation was successful, you will be able to use the session identifier to access other Akixi Web Services API requests that are only available to authenticated users.

If the request was unsuccessful (i.e. the response’s Result is “Fail”), you will receive a message similar to the one shown below:

<Request Result="Fail">
    <Error>
        <ErrorCode>10101</ErrorCode>
        <ErrorMessage>Invoke ID is not specified within the request.</ErrorMessage>
    </Error>
</Request>

You will need to parse and read the error code and the message. Some common errors returned by this operation are provided in the table below:

# Signing Out

You should immediately sign out if your client-side logic no longer requires an active API session. Signing out will deactivate your session identifier - therefore, you would need to subsequently create a new session and authenticate once again in order to invoke further Akixi requests.

The SignOut request can also be called from the error handling implementation of your client-side logic. For example, if an essential request has failed and you are entirely sure that no further requests are required for an underlying session, you might consider clearing session resources related to your session identifier by submitting a failsafe SignOut request.

You will be automatically signed out if your API session remains inactive for 30 minutes or more, but we strongly recommend that developers explicitly invoke the SignOut request whenever the API session is no longer required.

The structure of the SignOut request is provided below:

<Request Operation="SignOut">
    <InvokeID>00003</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
</Request>

If operation was successful, the “Success” Result value will be returned. A response message example of a successful SignOut request scenario is provided below:

<Response Result="Success">
    <InvokeID>00003</InvokeID>
</Response>

If the request was unsuccessful (i.e. the Result attribute depicts “Fail”), you will need to parse and appropriately handle the error code as well as the corresponding error message.

Some common errors returned by this operation are provided in the table below:

# Check Whether Session Exists

The CheckSessionExists operation checks whether the session is still active on the server side. Sessions are invalidated for the following reasons:

• User manually signed out.
• Session is inactive for longer than a threshold period.

The structure of the request is provided below:

<Request Operation="CheckSessionExists">
    <InvokeID>00001</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
</Request>

The parameters InvokeID and SessionID are mandatory parameters to check whether the session is still active.

If all parameters are correct, you will receive the following response:

<Response Result="Success">
    <InvokeID>00001</InvokeID>
</Response>

If the operation was successful, then it means that the session is still active on the server.

If the request was unsuccessful (i.e. the response’s Result is “Fail”), you will receive a message similar to the one shown below:

<Request Result="Fail">
    <InvokeID>00001</InvokeID>
    <Error>
        <ErrorCode>10302</ErrorCode>
        <ErrorMessage>Unable to validate the session with the specified session ID. The session would have been either
            expired or the session ID specified is incorrect.
        </ErrorMessage>
    </Error>
</Request>

The error code 10302 indicates that the session is not active anymore or the session ID specified is incorrect.

You will need to parse and read the error code and the message. Some common errors returned by this operation are provided in the table below: