Two-factor authentication in the API

Information

You can download the script for performing two-factor authentication via the API from this link.

How the script works

The script performs authentication via the standard Core Server API. Providers with a one-time password, Passcode, and Windows Password are supported as authentication providers.

To perform authentication via the API, do the following:

1. Call the /api/v5/templateSession/openVerifySession method. On successful execution of the method, a session identifier is returned — the $SessionId variable in the script.

   Note

   As an example, the script uses the PrincipalName name format.

2. The following steps differ depending on the authentication provider used:

If the one-time code is known

If the one-time code is known and does not need to be sent, then authentication is performed using the following algorithm (the SimpleLogon function in the script):

1. Input of the one-time code is requested.
2. Preparation of the authentication template — the /api/v5/templateSession/prepareTemplateData method is called.

The one-time code is passed as Data as a string (line #12 in the script). If the preparation was successful, then a template is created and the /api/v5/templateSession/createTemplate method is called.

The final step is authentication of the user using the /api/v5/logon/authenticate method.

On successful authentication, a token is returned in JSON format.

If the one-time code is not known

If the one-time code is not known, then you first need to initiate its sending using the `LogonByOtp` function in the script.

1. Call the /api/v5/templateSession/prepareTemplateData method. Initially, the value Null is passed as Data.

   The first call is necessary so that the server sends the one-time code, for example sending an SMS. Also, on the initial request the value of the EnoughData parameter will contain false.

2. Input of the one-time code is requested.

3. Preparation of the authentication template — the /api/v5/templateSession/prepareTemplateData method is called.

The one-time code is passed as Data as a string (line #12 in the script). The request will return an object where the value of the EnoughData parameter will contain true. If the preparation was successful, then a template is created and the /api/v5/templateSession/createTemplate method is called.

The final step is authentication of the user using the /api/v5/logon/authenticate method. On successful authentication, a token is returned in JSON format.

Prerequisites

• a working Axidian Access server,
• the presence of an Authentication API license.

Configuration

For the script to work, you need to configure the Config.ps1 file, which is located in the root of the folder with the script.

$serverUrl — URL of the Axidian Access server. Required parameter. $logsOnFile — enabling\disabling logging to a file. Required parameter. Enabled by default. $logsOnConsole — enabling\disabling logging to the console. Required parameter. Disabled by default.
$apiVersion — version of the API used in the script. Required parameter. Default value — v5.

In the main file main.ps1 do the following:

1. In the $ProviderGuid parameter, specify the GUID of the authentication provider that will be used in the script.

   As an example, the script uses the identifier of the Axidian Access SMS OTP Provider — {EBB6F3FA-A400-45F4-853A-D517D89AC2A3}.

2. In the $UserName parameter, specify the user name in UPN format.