Skip to main content
Skip table of contents

Authentication API (SOAP and REST)

This document describes the list of Web Services forming TrustBuilder MFA authentication API. The SOAP API is described by the following WSDL files: Authenticate.wsdl used for authentication requests.

Access to TrustBuilder MFA API is 2-factor secured. Configuration is done in the Administration Console:

  • Restrict authorized IP addresses allowed to submit SOAP requests

  • Implement SSL client certificate authentication

Some API methods are also proposed in REST format.

For sealing transactions, please refer to Transaction sealing API (SOAP and REST).

Authentication with SOAP API

There are 2 possible authentication methods: authenticate and authenticateWithIP.

  • Authenticate → will validate a login and an OTP.

  • AuthenticateWithIp → will allow to verify the source IP Address of the end-user ( only for authentication with Helium)

Authenticate

CODE 
authenticate(string login, string serviceId, string token)

Returns a string:

CODE 
authenticateResponse

This is an object with the following properties:

CODE 
public string authenticateReturn;

This function allows validating a One-Time Password for a given login. The string returned is a code which can be “OK” (success) or “NOK:<cause>” (error).

AuthenticateWithIp

CODE 
authenticateWithIp(string userId, string serviceId, string token, string ip)

Returns:

CODE 
authenticateWithIpResponse

This is an object with the following properties:

CODE 
public string authenticateReturn;

AuthenticateWithIp provides an additional MITM detection for OTP generated by TrustBuilder. The behavior of this function is as follows:

  • If the OTP is generated by Helium, TrustBuilder server first compares the IP address with the one it knows, then verifies the OTP

  • If the OTP is generated by TrustBuilder Authenticator, TrustBuilder server ignores the IP address

The string returned is a code which can be “OK” (success) or “NOK:<cause>” (error).

Authentication with REST API

authenticateExtended

URL

CODE 
https://api.myinwebo.com/FS?action=authenticateExtended + parameters

Mandatory parameters:

CODE 
&serviceId= <id of the service> //integer
&userId=<login name> //string
&token=<otp generated> //string

Optional parameters:

CODE 
&format=json //allows to get the API response in json format instead of XML format
&expectnopin=1  // when using helium with the option withoutpin="1"

Response:

By default, the API response is in XML format

The response contains the following information:

  • err: the authentication result (“OK” or “NOK:<cause>” or “NOK” (=other errors))

  • name: name of the device that performed the authentication

  • alias: alias of the device that performed the authentication

  • version: version of the application that performed the authentication

  • platform: platform of the device (can be helium / windows / mac / android…)

  • type: type of the device - can be ma (mobile app) / ca (Helium) / mac (an application using maccess)

If the service ID sent in the URL does not reference a valid service ID, the value of “err” will be “NOK:srv unknown”.

If the login name sent in the URL does not match a valid service login name, the value of “err” will be “NOK:account unknown “.

Default response in XML:

XML 
<authenticateExtended>
    <err></err>
    <name></name>
    <alias></alias>
    <version></version>
    <platform></platform>
    <type></type>
    <timestamp></timestamp>
</authenticateExtended>

Alternative response format in json:

CODE 
{"timestamp":"",""platform":"","alias":"","name":"","err":"","type":"","version":""}

Possible error codes

'err' values 

Reject Reason

Message displayed in admin console

Description

OK

Authenticate OK

OK

Authentication Successful

NOK:no device found 

OTP does not match any of the user's devices

KO bad OTP format

Invalid OTP (expired, replay, random, …)

NOK:NOLOGIN 

User has not activated a token yet

KO user pending

user not activated

NOK:account unknown 

Unknown user

KO unknown user

user doesn't exist

NOK:account disabled 

User is blocked

KO user locked

user has been administratively blocked by an operator

NOK:ACCESS 

Wrong pin

KO wrong PIN code

user's pin is wrong

NOK_BLOCKED

Device is locked

KO tool locked

user's tool is locked

NOK:no secret 

Device needs to be synchronized

KO tool is desynchronized

user's tool is desynchronized

NOK:SN 

Syntax Error

KO syntax error

Syntax error. One parameter is missing or incorrect

NOK:TIMEOUT 

Request timeout

No message displayed

User didn't respond the request within 1 minute

NOK:Access Forbidden

Client certificate is absent/not valid or IP not whitelisted

-

Client certificate is absent/not valid or IP filtering is activated and the IP address is not in the whitelist (see your service parameters)

NOK 

Ooops

KO

Other error. Retry

NOK:HSMERROR

Internal server error

-

Internal server error (TrustBuilder side)

Push request

This method is used to add a security layer to an existing login / password authentication. For the user, the steps are:

  1. Standard login / password authentication

  2. Then, multi-factor authentication (MFA) on the mobile, woken up by a Push notification

To achieve this, TrustBuilder provides 2 REST Web Services that enable the push notification.

  • PushAuthenticate → requests TrustBuilder platform to send a Push notification to an identified user’s device. This notification wakes up TrustBuilder Authenticator application and prompts for Authorization (using a PIN or not).

  • CheckPushResult → allows your server to verify whether MFA for this session was successful or not.

As it is not possible to predict how long the user will take to authenticate, we have implemented an asynchronous procedure:

  1. Your server requests TrustBuilder to notify the user’s device, and gets back a session id.

  2. Your server verifies periodically with TrustBuilder platform the authentication result of the session.

PushAuthenticate

This requests TrustBuilder platform to send a Push notification to an identified user’s device.

URL

CODE 
https://api.myinwebo.com/FS?action=pushAuthenticate + parameters

Mandatory parameters:

CODE 
&serviceId= <service id> //integer
&userId=<login of the previsously authenticated user> //string

Optional parameters:

  • &withoutpin=1 → when set to 1, push is sent without asking for PIN (overriding global PIN policy). In this case CheckPushResult must also be invoqued with 'withoutpin=1'. Default value: 0.

  • &format=json → allows to get the API response in json format instead of XML format

  • &tooltype=[ma | mac ] → allows to specify the TrustBuilder tool type where to send the push. 'ma' = TrustBuilder Authenticator. 'mac' = mAccess device(s).

  • &toolalias=<alias of the tool> → allows to specify the tool where to send the push, if several tools have been enrolled by the user. 'toolalias' can be obtained with 'loginQuery' request.

  • &context=<context information> or &context=auto → allows to send a context information in the push notification. It is then possible to display the context information on the mobile device (mAccess and TrustBuilder Authenticator)

    • On TrustBuilder Authenticator the display of the context information is only available on Android and iOS

    • In text mode, the context information must be limited to 128 characters. The context content must respect the following regular expression: ^[\d$%€&@# \.\+\-_\w\p{L}]+$

    • In automatic mode this context consists of a 4 digit string randomly generated. This generated string is available in the response of the API call

Security Recommendations

To protect users from attacks such as MFA/Push Bombing, we highly recommend using the context parameter. This links the authentication request to the response. The person making the authentication request should check whether the information context displayed in the login screen matches the information context displayed on his mobile device.

A context information “From WebExemple - 1.2.3.4 Paris” is displayed in the login screen

The context information “From WebExemple - 1.2.3.4 Paris” in the push notification matches the context information displayed in the login screen

Response:

By default, API response is in XML. It contains:

  • err: the notification result (“OK” or “NOK:<cause>” or “NOK” (=other errors))

  • name: name of the device that performed the authentication

  • alias: alias of the device that performed the authentication

  • version: version of the application that performed the authentication

  • platform: platform of the device (can be iphone, android, wp8 in case of Authenticator)

  • type: will be “ma” (mobile app) or “mac” (your application developed with mAccess)

  • sessionId: the 32-char-long Session Id that will allow you to check Authentication result (to be used in checkPushResult)

  • context: the context information provided (field only exists if a context has been passed to the initial call)

Possible error codes:

  • NOK:NOPUSH ==> user’s mobile app does not support Push (TrustBuilder nCode)

  • NOK:NOMA ==> user does not have any TrustBuilder mobile app available

  • NOK:NOLOGIN ==> user does not exist, or is still pending activation

  • NOK:SN ==> syntax error in input parameters

  • NOK:srv unknown ==> serviceId is wrong

  • NOK  ==> Temporary error. In such a case, try to reiterate the API call.

JSON response format:

CODE 
{"timestamp":"","platform":"","sessionId":"","alias":"","name":"","err":"","type":"","version":"", "context":""}

Note that the context field is available only if the call has been made with the context query parameter.

 If your mobile is on a filtered network (WiFi by example), please ensure the following ports are opened to be able to register for push notifications and also to receive them:

  • Android (Google):  outbound TCP ports 5228 to 5230.

  • iOS (Apple): outbound TCP port 5223 

CheckPushResult

This call is used to get the authentication result of a specific session.

URL:

CODE 
https://api.myinwebo.com/FS?action= checkPushResult + parameters

Mandatory parameters:

CODE 
&serviceId= <service id> //integer
&sessionId=<session id> //string
&userId=<login> //string

Optional parameters:

  • &format=json → allows to get the API response in json format instead of XML format

  • &withoutpin=1 → if PushAuthenticate is invoqued with 'withoutpin=1', CheckPushResult must also be invoqued with 'withoutpin=1'

Response:

By default, API response is in XML. It contains:

  • err: the authentication result (“OK” or “NOK:<cause>” or “NOK” (other errors))

  • name: name of the device that performed the authentication

  • alias: alias of the device that performed the authentication

  • version: version of the application that performed the authentication

  • platform: platform of the device (can be iphone, android, wp8 in case of Authenticator)

  • type: will be “ma” (mobile app) or “mac” (your application developed with mAccess)

Possible error codes:

  • NOK:WAITING ==> Request is pending, try again later (in 0.5 sec for instance)

  • NOK:REFUSED ==> user refused authentication

  • NOK:NOMA ==> user does not have any TrustBuilder mobile app available

  • NOK:TIMEOUT ==> user did not authenticate in time (1 minute)

  • NOK:SN ==> syntax error in input parameters

  • NOK:srv unknown ==> serviceId is wrong

  • NOK ==> sessionId does not exist or has expired.

JSON response format:

CODE 
{"timestamp":"","platform":"","alias":"","name":"","err":"","type":"","version":""}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close