Authentication API (SOAP and REST)

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)

Returns a string:

authenticateResponse

This is an object with the following properties:

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

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

Returns:

authenticateWithIpResponse

This is an object with the following properties:

public string authenticateReturn;

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

Mandatory parameters:

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

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"

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>

Alternative response format in json:

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

Possible error codes

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

Mandatory parameters:

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

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":""}

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

Mandatory parameters:

&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 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":""}