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

Access to inWebo API is 2-factor secured. Configuration is done in inWebo 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.

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 inWebo Helium)

Authenticate

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

Returns a string:

authenticateResponse
CODE

This is an object with the following properties:

public string authenticateReturn;
CODE

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

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

Returns:

authenticateWithIpResponse
CODE

This is an object with the following properties:

public string authenticateReturn;
CODE

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

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

  • If the OTP is generated inWebo Authenticator, inWebo 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

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

Mandatory parameters:

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

Optional parameters:

&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"
CODE

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 (inWebo 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:

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

Alternative response format in json:

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

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 (inWebo 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, inWebo provides 2 REST Web Services that enable the push notification.

  • PushAuthenticate → requests inWebo platform to send a Push notification to an identified user’s device. This notification wakes up inWebo 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 inWebo to notify the user’s device, and gets back a session id.

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

PushAuthenticate

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

URL

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

Mandatory parameters:

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

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 inWebo tool type where to send the push. 'ma' = inWebo 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 inWebo Authenticator)

    • On inWebo 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.

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 (inWebo nCode)

  • NOK:NOMA ==> user does not have any inWebo 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:

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

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:

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

Mandatory parameters:

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

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 inWebo 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:

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