Introduction
Below will be detailed the SOAP request for sign, change password ecc...
All the methods described are on interface:
https://<IP-APPLIANCE>:8080/SignEngineWeb/sign-services?wsdl
The SOAP request examples are generated using SoapUI, you can use this guide to configure SoapUI on your pc.
In this guide will be described the example of Soap Requests.
Credentials Object
All methods for sign require the ojbect Credentials is used to specify the device signature are you using for sign. This object is composed by this variables:
<credentials>
<username>?</username>
<password>?</password>
<idOtp>?</idOtp>
<otp>?</otp>
<securityCode>?</securityCode>
<sessionKey>?</sessionKey>
</credentials>
According the device signature (automatic or remote) are you using you should populate different fields.
Automatic Signature
Below the example of Credentials :
<credentials> <username>AHI123456</username> <password>13572468</password> </credentials>
Fileds required:
- username
- password
Remote Signature
If you sign with the remote there are two ways:
- specify "idOtp" and "otp"
- specify the sessionKey
Example with "idOtp" and "otp":
<credentials> <username>RHIP1234567</username> <password>13572468</password> <idOtp>501719</idOtp> <otp>150259</otp> </credentials>
Example with "sessionKey"
<credentials> <username>RHIP1234567</username> <password>13572468</password> <sessionKey>sadlijhdfkjslherpoufdblkhesljherihbfdoihejheroihger</sessionKey> </credentials>
If you decide to sign with idOtp and OTP you must obtain the OTP code for sign (from SMS, App and Token) and idOtp.
How obtain the idOtp and OTP code
Below will described with SOAP request how obtain idOtp (with method getOtpList) and OTP code.
Obtain the idOtp
You can obtain the idOtp with method getOtpList. Below the example of SoapRequest. In this example we are using the devicename: "RHIP20102336019765":
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
<soapenv:Header/>
<soapenv:Body>
<ser:getOTPList>
<credentials>
<username>RHIP20102336019765</username>
</credentials>
</ser:getOTPList>
</soapenv:Body>
</soapenv:Envelope>
In output the SOAP response will be:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:getOTPListResponse xmlns:ns2="http://service.ws.nam/">
<return>
<idOtp>501719</idOtp>
<serialNumber>20210113-091031RJ2L1</serialNumber>
<type>SMS</type>
</return>
<return>
<idOtp>537430</idOtp>
<serialNumber>20210305-163726L0PYF</serialNumber>
<type>OTP GENERATOR</type>
</return>
<return>
<idOtp>537433</idOtp>
<serialNumber>20210305-163726F0I75</serialNumber>
<type>OTP PUSH</type>
</return>
</ns2:getOTPListResponse>
</soap:Body>
</soap:Envelope>
During the signing process, it is possible to choose between these two idOtps: 501719 (associated with OTP SMS) and the idOTP: 537430 (associated with OTP GENERATOR).
It is not possible to use OTP PUSH, they are used for other purposes, not for signing.
For the signature we can choose two types of idOTP: 501719 or 537430.
Obtain the OTP code
With OTP SMS we can obtain the code using the method "sendOtpBySMS" like in this SOAP request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
<soapenv:Header/>
<soapenv:Body>
<ser:sendOtpBySMS>
<credentials>
<username>RHIP20102336019765</username>
</credentials>
</ser:sendOtpBySMS>
</soapenv:Body>
</soapenv:Envelope>
If everything is ok, in output response will be:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:sendOtpBySMSResponse xmlns:ns2="http://service.ws.nam/"/>
</soap:Body>
</soap:Envelope>
On your mobile phone, you will receive an SMS containing the OTP code (composed of 6 numbers) for signature. Now, for example, we have received the code: “214196”.
While with OTP App and Token you don't require the method of SWS because you can read the OTP code on Token display or on your smartphone display (if you are using the App).