one time password server -...

Nordic Edge One Time Password Server - SOAP Web Service Client API

One Time Password Server

WEB SERVICE Client API (SOAP)

with sample code for Java, .NET and Ruby Latest Version Date: 2012-02-19

Table of Contents One Time Password Server

WEB SERVICE Client API (SOAP)

Table of Contents

1 Overview


1.1 Introduction

1.2 Prerequisites

2 One Time Password Server Configuration

2.1 Setup

3 Integration

3.1 Code Generation from WSDL file

3.2 Integrating with the API with xml data

3.3 Programming Language in this document

4 SOAP Operations

4.1 getCommands

4.1.1 The SOAP request message for the getCommands operation:

4.1.2 The SOAP response message for the getCommands operation:

4.2 getOTPObject

4.2.1 Java: getOTPObject

4.2.2 Example of a SOAP request message:

4.2.3 Example of a SOAP response message:

4.3 OtpWsRequest object

4.3.1 Fields of OtpWsRequest object

4.3.2 Example: OtpWsRequest object described in xml

4.4 OtpWsResponse object


4.4.2 Example: OtpWsResponse object described in xml

5 Commands

5.1 Required fields / xml elements

5.1.1 Required Fields for all commands

5.2 requestAuthAndOTP

5.2.1 KeyValuePair / xml elements

5.2.2 Example of the SOAP request message with userName and password:

5.2.3 Example of the SOAP response message:

5.3 verifyOTP


5.3.2 Example of the SOAP request message with userName, magicNr and otp:



5.4 authenticateUser



5.4.3 Example of the SOAP response message with result: ok:

5.4.4 Example of the SOAP response message with errorCode and errorDescription:

5.5 getUserAttributeValue


5.5.2 Example of the SOAP request message with userName and attributeName:


5.6 storeData


5.6.2 Example of the SOAP request message:


5.7 fetchData




6 Developing the client code

6.1 Code example in Java

6.2 Code example in C#

6.3 Code example in Ruby

7 Other

7.1 Troubleshooting & support

7.2 API Version History

#h.5797f20b22f7

#h.5797f20b22f7

#h.5797f20b22f7

#h.5797f20b22f7


1 Overview

1.1 IntroductionThis document is a brief overview of the One Time Password Server functions that are available through

Web Services. Nordic Edge One Time Password Server exposes client functionality, corresponding to the

One Time Password Native Client API, as SOAP services. For more detailed information and help with

application integration please contact Nordic Edge directly.

If there is a disagreement with this document and the WSDL file, the WSDL should be assumed to be

correct.

1.2 Prerequisites

● A working knowledge of Web Services and the WSDL format.

● A client capable of communicating with a SOAP server.

● Nordic Edge One Time Password Server version 3.1

2 One Time Password Server Configuration

2.1 SetupMake sure the embedded http server is started and configured accordingly.


In order to use the Web Service API you need to set up a Web Service SOAP Client in the OTP Server Configurator as shown below.


The important thing is to set a WS Client Name and a WS Client Password for each specific Web Service Client. This will be used by the API when validating incoming requests.


3 Integration

3.1 Code Generation from WSDL fileMany Web Services platforms include support for automatically generating either complete client

functionality or stub versions of the SOAP messages described in the WSDL file. For the Java platform

please see either the AXIS project at the Apache Foundation, or JAX-WS RI for examples of such

implementations.

The provided WSDL file (the WSDL that the Web Service will generate) is in the document/literal

wrapped syntax. This is currently the interoperability leader and is supported by the majority Web

Services clients (Metro, AXIS, gSoap, Websphere, .NET, etc.).

The WSDL for these services may be downloaded from the following URL:

https://yourhost.yourdomain/neotp/otpws?wsdl

3.2 Integrating with the API with xml dataIf no code generation is possible you can integrate with the API at a lower level: sending the SOAP

message directly over HTTP.

3.3 Programming Language in this document


When describing the functionality from a developers view, this document focuses on the Java platform.

The Web Service itself is language agnostic. SOAP message examples are added when appropriate.

4 SOAP OperationsThis section describes the SOAP operations of the Web Service. For a more thorough description of the API, please see the java documentation at http://download.nordicedge.se/download/otpserver/javadoc_wsapi/ The OTP Server Web Service API has two operations:

● getCommands

● getOTPObject

4.1 getCommands

Get available commands for the OTP Server Web Service API

Returns: Array of Strings containing available commands to send to the OTP Server WS API.

4.1.1 The SOAP request message for the getCommands operation:

<?xml version="1.0" ?>

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Body>

<ns2:getCommands xmlns:ns2="http://ws.nordicedge.se/"/>

http://download.nordicedge.se/download/otpserver/javadoc_wsapi/


















</S:Body>

</S:Envelope>

4.1.2 The SOAP response message for the getCommands operation:

<?xml version="1.0" ?>

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Body>

<ns2:getCommandsResponse xmlns:ns2="http://ws.nordicedge.se/">

<command>requestAuthAndOTP</command>

<command>requestOTP</command>

<command>verifyOTP</command>

<command>authenticateUser</command>

<command>requestAuth</command>

<command>getErrorDescription</command>

<command>storeData</command>

<command>fetchData</command>

<command>removeData</command>

<command>verifyOATHOTP</command>


<command>requestPrefetchedOTP</command>

<command>requestAdminPrefetchedOTP</command>

<command>getAvailableUserAttributes</command>

<command>getUserAttributeValue</command>

<command>requestUserOATHKey</command>

<command>updateOATHKey</command>

<command>reloadServerConfiguration</command>

<command>resyncOTPMobileCounter</command>

<command>setConfiguration</command>

<command>getConfiguration</command>

<command>getCharset</command>

<command>setCharset</command>

<command>getWSVersion</command>

<command>getClientVersion</command>

<command>getServerVersion</command>

</ns2:getCommandsResponse>

</S:Body>


</S:Envelope>

4.2 getOTPObject

The main operation of the API. This method is used for all interactions with the OTP Server.

For a more thorough description of the getOTPObject method, please see the java documentation at http://download.nordicedge.se/download/otpserver/javadoc_wsapi/

getOTPObject takes a complex type as parameter.

4.2.1 Java: getOTPObject

Parameter Type Description

obj OtpWsRequest An object containing all information needed for a specific

command.

Returns: Object of type OtpWsResponse

Depending on what command you ask for, the response object will contain different data. Different commands is

described in section 5.

4.2.2 Example of a SOAP request message:

1. <?xml version="1.0" ?>



















2. <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

3. <S:Body>

4. <ns2:getOTPObject xmlns:ns2="http://ws.nordicedge.se/">

5. <otpWsRequest>

6. <clientName>webServiceClientName</clientName>

7. <clientPassword>webServiceClientPassword</clientPassword>

8. <command>requestAuthAndOTP</command>

9. <keyValueParameter>

10. <key>userName</key>

11. <value>ddarrell</value>

12. </keyValueParameter>


14. <key>password</key>

15. <value>secret</value>



18. <key>message</key>

19. <value>Your OTP : $$OTP$$</value>


21. </otpWsRequest>

22. </ns2:getOTPObject>

23. </S:Body>

24. </S:Envelope>

As seen on row 8, the command for the OTP Server is requestAuthAndOTP , this command requires parameters such as userName and password. See the java documentation for further details

4.2.3 Example of a SOAP response message:



3. <S:Body>

4. <ns2:getOTPObjectResponse xmlns:ns2="http://ws.nordicedge.se/">

5. <otpWsResponse>

6. <magicNr>HP1c8z</magicNr>

7. <errorCode></errorCode>

8. <errorDescription></errorDescription>

9. <message></message>

10. <status></status>


11. </otpWsResponse>

12. </ns2:getOTPObjectResponse>

13. </S:Body>

14. </S:Envelope>

As seen on row 6, the magicNr is the only value returned for the requestAuthAndOTP command.See the java documentation for further details


4.3 OtpWsRequest object

The request object for the getOTPObject operation/method. This object contains the following fields.


Field Type Description

clientName String The Web Service Client name

clientPassword String The Web Service Client password

command String The command to be executed in the OTP Server

keyValueParameter KeyValuePair [ ] KeyValuePair object contains two fields: key and value, both of type String.Contains the necessary information needed by the requested command

4.3.2 Example: OtpWsRequest object described in xml

<otpWsRequest>

<clientName>webServiceClientName</clientName>

<clientPassword>webServiceClientPassword</clientPassword>

<command>requestAuthAndOTP</command>

<keyValueParameter>

<key>userName</key>

<value>ddarrell</value>

</keyValueParameter>

<keyValueParameter>

<key>password</key>

<value>secret</value>


. . .</otpWsRequest>


4.4 OtpWsResponse object

The response object for the getOTPObject operation/method. This object contains the following fields.



magicNr String The magic number (state). Used to verify the OTP

errorCode String Numerical error code (if something went wrong)

errorDescription String Error description in plain text

message String General Message sent from the OTP Server (currently not used)

status String Status Message sent from the OTP Server (currently not used)

keyValueParameter KeyValuePair [ ] KeyValuePair object contains two fields: key and value, both of type String.Contains the information sent back from the OTP Server

4.4.2 Example: OtpWsResponse object described in xml

<otpWsResponse>

<magicNr></magicNr>

<errorCode></errorCode>

<errorDescription></errorDescription>

<message></message>

<status></status>

<keyValueParameter>

<key>result</key>

<value>UTF-8</value>


. . .

</otpWsResponse>


5 Commands

A selection of commands for the getOTPObject operation are described below. For a more thorough description of the API, please see the java documentation.


5.1 Required fields / xml elements

For all requests to the Web Service, three fields are required

5.1.1 Required Fields for all commands


clientName String The Web Service Client name

clientPassword String The Web Service Client password

command String The command to be executed on the OTP Server

* Optional field is the keyValueParameter, which is described for each command below.

5.2 requestAuthAndOTPRequest Authentication And Issuing an OTP from OTP-Server


















Three possible ways of using this command:1. Send the userName, password and attribName

2. Send the userName, password and message

3. Send the userName and password


Name (key)

Optional

Type

Description

userName

String

The userName (as KeyValue object with key

userName)

password String

The users password (as KeyValue object with key password)

attribName

yes String

The attribute name that holds the users challenge value (example: mobile, mail etc) (as KeyValue object with key attribName)

message yes String

The message to send to the client. Use $$OTP$$ to insert the OTP (as KeyValue object with key message)

Returns: the magic number as seen in 5.2.3 row 6.





3. <S:Body>


5. <otpWsRequest>



8. <command>requestAuthAndOTP</command>









17. </otpWsRequest>



19. </S:Body>

20. </S:Envelope>




3. <S:Body>


5. <otpWsResponse>

6. <magicNr>HP1c8z</magicNr>







13. </S:Body>

14. </S:Envelope>


5.3 verifyOTPVerifies if an otp is correct Two possible ways of using this command:

1. Send the magicNr, otp and userName

2. Send the magicNr and otp ( if no userName was sent in the previous request, see command: requestOTP )


Name (key)

Optional

Type

Description

magicNr String

The magic number received from previous

request

otp String

The OneTimePassword (otp) the user received

userName

yes String

The userName

Returns: true if successful, otherwise false. See 5.3.3 row 13.

5.3.2 Example of the SOAP request message with userName, magicNr and otp:



3. <S:Body>


5. <otpWsRequest>



8. <command>verifyOTP</command>







14. <key>magicNr</key>

15. <value>HP1c8z</value>



18. <key>otp</key>

19. <value>7256</value>


21. </otpWsRequest>


23. </S:Body>

24. </S:Envelope>





3. <S:Body>


5. <otpWsResponse>

6. <magicNr></magicNr>






12. <key>result</key>

13. <value>true</value>




17. </S:Body>

18. </S:Envelope>


5.4 authenticateUser

Authenticates username and password5.4.1 KeyValuePair / xml elements

Name (key)

Optional

Type

Description

userName

String

The userName

password String

The password

Returns: String "ok" if the user is authenticated, otherwise the errorCode and errorDescription

See 5.4.3 row 13 and 5.4.4 row 7,8.




3. <S:Body>


5. <otpWsRequest>



8. <command>authenticateUser</command>









17. </otpWsRequest>


19. </S:Body>

20. </S:Envelope>


5.4.3 Example of the SOAP response message with result: ok:



3. <S:Body>


5. <otpWsResponse>








13. <value>ok</value>




17. </S:Body>

18. </S:Envelope>


5.4.4 Example of the SOAP response message with errorCode and errorDescription:



3. <S:Body>


5. <otpWsResponse>


7. <errorCode>3</errorCode>

8. <errorDescription>User failed authentication</

errorDescription>





13. </S:Body>

14. </S:Envelope>


5.5 getUserAttributeValue

Get an attribute value from a user5.5.1 KeyValuePair / xml elements

Name (key)

Optional

Type

Description

userName

String

The userName for the user

attributeName

String

The attribute name

Returns: the user attribute value if available, otherwise an empty String. See 5.5.3 row 13

5.5.2 Example of the SOAP request message with userName and attributeName:



3. <S:Body>


5. <otpWsRequest>



8. <command>getUserAttributeValue</command>







14. <key>attributeName</key>

15. <value>mail</value>


17. </otpWsRequest>


19. </S:Body>

20. </S:Envelope>




3. <S:Body>


5. <otpWsResponse>









13. <value>[email protected]</value>




17. </S:Body>

18. </S:Envelope>

5.6 storeData

Store data in the OTP-Server5.6.1 KeyValuePair / xml elements


Name (key)

Optional

Type

Description

userName

String


data String

The data to store

persistant

String

If the data should be stored persistantantly (true or false)

Returns: the magic number, "0" if failure. See 5.6.3 row 6




3. <S:Body>


5. <otpWsRequest>



8. <command>storeData</command>







14. <key>data</key>

15. <value>Some data to be stored</value>



14. <key>persistant</key>

15. <value>true</value>


17. </otpWsRequest>


19. </S:Body>

20. </S:Envelope>




3. <S:Body>



5. <otpWsResponse>

6. <magicNr>7Xs4PW</magicNr>







13. </S:Body>

14. </S:Envelope>

5.7 fetchData

Fetch stored data from the OTP-Server5.7.1 KeyValuePair / xml elements

Name (key)

Optional

Type

Description

userName

String


magicNr String

The magic number


Returns: the data, an empty String if failure. See 5.7.3 row 13




3. <S:Body>


5. <otpWsRequest>



8. <command>fetchData</command>






14. <key>magicNr</key>

15. <value>7Xs4PW</value>



17. </otpWsRequest>


19. </S:Body>

20. </S:Envelope>




3. <S:Body>


5. <otpWsResponse>








13. <value>Some data to be stored</value>




17 </S:Body>

18. </S:Envelope>


6 Developing the client code

Basic client code examples for Java and C# are found below. Depending on what WS engine (JAX-WS, Axis2 etc) you use to create the code stubs, the output will be different.

6.1 Code example in JavaThe stubs used in this example are generated with the java wsimport tool. Example for the command: requestAuthAndOTP

OtpWsImplService service = new OtpWsImplService();

OtpWs port = service.getOtpWsImplPort();

OtpWsRequest req = new OtpWsRequest();

req.setCommand("requestAuthAndOTP");

req.setClientName("webServiceClientName");

req.setClientPassword("webServiceClientPassword");

/** userName **/

KeyValuePair userNameKV = new KeyValuePair();

userNameKV.setKey("userName");

userNameKV.setValue("ddarrell");

req.getKeyValueParameter().add(userNameKV);

/** password **/

KeyValuePair passwordKV = new KeyValuePair();

passwordKV.setKey("password");

passwordKV.setValue("secret");

req.getKeyValueParameter().add(passwordKV);

/** REQUEST THE OTP - GET THE MAGIC **/

OtpWsResponse res = port.getOTPObject(req);

String magicNr = res.getMagicNr();


6.2 Code example in C#The stubs used in this example are generated with Visual Studio 2010. Example for the command: requestAuthAndOTP

OtpWsImplService port = new OtpWsImplService();

otpWsRequest ows = new otpWsRequest();

ows.clientName = "webServiceClientName";

ows.clientPassword = "webServiceClientPassword";

ows.command = "requestAuthAndOTP";

/** userName **/

keyValuePair userKv = new keyValuePair();

userKv.key = "userName";

userKv.value = "ddarrell";

/** password **/

keyValuePair passwordKv = new keyValuePair();

passwordKv.key = "password";

passwordKv.value = "secret";

/** add the keyValuePairs **/

keyValuePair[] pairs = new keyValuePair[2]{userKv, passwordKv};

ows.keyValueParameter = pairs;

/** REQUEST THE OTP - GET THE MAGIC **/

otpWsResponse res = port.getOTPObject(ows);

String magic = res.magicNr;

6.3 Code example in RubyThe ruby client is using the SOAP abstraction library Savon. Visit http://www.savonrb.com for more information on Savon. Example for the command: requestAuthAndOTP

http://www.savonrb.com








require "savon"

# Default namespace for savon is 'env', OTP Web Service uses 'S'

Savon.env_namespace = :S

# Create client form WSDL

@client = Savon::Client.new "https://yourhost.yourdomain/neotp/otpws?wsdl"

@client.http.auth.ssl.verify_mode = :none

# Web Service Parameters

client_name = "webServiceClientName"

client_password = "webServiceClientPassword"

ws_command = "requestAuthAndOTP"

# KeyvalueParameters

keyvalue_parameters = [ { :key => "userName", :value => "ddarrell" }, { :key

=> "password", :value => "secret" } ]

# Execute request for OTP and store response

response = @client.request :ns2, "getOTPObject" do

soap.body = {

:otp_ws_request => {

:client_name => client_name,

:client_password => client_password,

:command => ws_command,

:keyValueParameter => keyvalue_parameters

},

:attributes! => {

:otp_ws_request => { "xmlns:ns2" => "http://ws.nordicedge.se/" }

}

}

end

# Get the magic from the response

magic = response.to_hash[:get_otp_object_response][:otp_ws_response]

[:magic_nr]


7 Other

7.2 API Version History

Version Date Description1.0 2011-10-28 Initial version

1.1 2012-02-19 Added code sample for Ruby. Minor text changes/corrections

one time password server -...

Documents