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)
NOK:NO_MATCHING_DEVICE	The OTP may be expired		Could not find a device that have generated the OTP

Push request

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

Standard login / password authentication
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:

Your server requests TrustBuilder to notify the user’s device, and gets back a session id.
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":""}