One Time Password Server OTP Server Client API Microsoft.NET with Sample Code for C# and Visual Basic.NET Date: 2010-12-03
Table of Contents One Time Password Server OTP Server Client API Microsoft.NET About Nordic Edge Overview 1 Getting Started 1.1 Minimum Requirements & Dependencies Windows OTP Server 1.2 Installation 2 Application Development 2.1 Using the API with Microsoft Visual Studio.NET 2.2 API Methods 2.2.1. Constructor 2.2.2. Connect to the OTP Server 2.2.3. Get the Magic Number 2.2.4. Validate the OTP 2.2.5. Close the Server Connection 2.3 Source Code 2.4 OTP Server Error Codes 3 Other 3.1 Troubleshooting & support 3.2 API Version History
About Nordic Edge Nordic Edge is a leading provider of trusted Identity and Access Management (IAM) solutions that enable organisations to secure and manage their digital identities. With Nordic Edge s solutions, organisations can improve business processes and meet regulatory compliance requirements. The offering includes two-factor authentication, role based delegated user administration, synchronization and provisioning. More than 10 million identities are being administered by Nordic Edge s solutions and over 1 million users securely login with Nordic Edge s products each month. Nordic Edge was founded 2001 in Sweden and has customers in more than 25 countries. Overview Nordic Edge One Time Password Server adds an extra security layer to protect your applications. When the user id and password is successfully verified, a One-Time Password is sent to the user s mailbox or mobile phone through SMS (Short Message Services). This One-Time Password will be verified and only then will the user be authenticated to the application.
1 Getting Started 1.1 Minimum Requirements & Dependencies This section describes what you need to take full advantage of the functionality offered in the Nordic Edge OTP Server API for Microsoft.NET Framework. Windows OTP Server Windows Clients as XP, Vista, 7 or Windows Server etc. Microsoft.NET Framework 2.0 or later OTP Server 1.6 (Build 2471) or later OTP Server has to be configured before the API can be used. Have a look at the OTP Server Administration Manual for more information. 1.2 Installation Extract the file Nordic_Edge_OTP_Server_MS_NET_Client_API.zip to an appropriate location on your hard drive. Files/Directories Nordic Edge OTP TestTool.NET.exe NordicEdgeOTP.dll OTP MS.NET Client API.chm \\Sample Code\\OTPServerWebTestApp \\Sample Code\\OTP Client API Test C# \\Sample Code\\Nordic Edge OTP TestTool.NET \\Sample Code\\OTP Client API Test VB Description A tool for test purposes The client API The client API help file Sample code for Microsoft C# ASP.NET using the Client API. The sample code is a complete Visual Studio ASP.NET 2008 project. Sample code for Microsoft C#.NET using the Client API. The sample is a complete Visual Studio 2008 project. The source code for Nordic Edge OTP TestTool.NET using all of methods in the Client API. The sample is a complete Visual Studio 2008 project. Sample code for Microsoft Visual Basic.NET using the Client API. The sample is a complete Visual Studio 2008 project.
2 Application Development 2.1 Using the API with Microsoft Visual Studio.NET Using the Client API in Microsoft Visual Studio: 1. Start Visual Studio.NET 2. Select File > New > Project 3. In the Project Type column, select the project type to create a Visual C# or Visual Basic project 4. In the Template column, select a project template (like Console Application, Windows Application) 5. Enter a name for your project 6. Click OK to create your new project 7. Select Project > Add reference > Browse 8. In Browse, select NordicEdgeOTP.dll from the location you copied the files to in an earlier step Figure 1: Adding a Reference 9. Click OK to Add Reference
2.2 API Methods The most important methods in the API are shown below. To test and get the whole picture, have a look at the included code samples written in C# and VB.NET. 2.2.1. Constructor Create an instance of the Nordic Edge One Time Password Server.NET API. This code should execute once upon application initialization. C#.NET using Se.Nordicedge; OTPClient otpclient = new OTPClient(); 2.2.2. Connect to the OTP Server To establish a OTP Server connection, supply the OTP Server IP address (or a DNS address). C#.NET string otpserverip = "127.0.0.1:3100"; bool isconnected = otpclient.connect(); 2.2.3. Get the Magic Number A successful user authentication with the method RequestAuthAndOTP will return a so called magic number which later is used to confirm the OTP that is sent to the user. C#.NET magicnum = otpclient.requestauthandotp(username, password); 2.2.4. Validate the OTP When the user enter the OTP into the application, it has to be validated with the method CheckChallenge. C#.NET bool isvalidate = otpclient.checkchallenge(magicnum, otp, username);
2.2.5. Close the Server Connection Close the OTP Server connection after method calls. C#.NET otpclient.closeconnection(); 2.3 Source Code In Nordic_Edge_OTP_Server_MS_NET_Client_API.zip there are a couple of complete Visual Studio projects showing how to use the methods included in the OTP Client API. 1. The OTPServerWebTestApp is written in C# and is a complete ASP.NET Web Application.
Figure 2: The OTP Server Web Test Application 2. The Nordic Edge OTP TestTool.NET shows how to use all of the methods included in the OTP Client API.
Nordic Edge OTP TestTool.NET Figure 4: The 3. In the package there is a simple Windows Form Application in two versions, one for C# and the other one written in Visual Basic.NET.
Figure 5 & 6: The sample application 2.4 OTP Server Error Codes The One Time Password error codes: 1. The given user name doesn't exist in the database 2. Multiple user names 3. The user is not authenticated 4. The mobile attribute is empty 5. The OTP could not be sent 6. DB not accessible 7. The user is excluded from OTP (No OTP is sent to the user, user name and password is good enough) 8. The user account is locked 9. The call was not correctly formatted 10. OTP Mobile 2.0 verified OK 11. Remote password configuration error 12. Remote password has not been set 13. The password for the user account (in Active Directory) has to be changed
3 Other 3.2 API Version History Version Date Description 1.0.0 1st may 2008 Initial version 1.2.0 14th june 2009 New methods added: CheckChallange_VB() and GetAllConfig_VB (overloaded methodes because VB is't case sensitive.) 1.2.1 19th october 2009: Bug fix: The SetPort method did not work. Corrected and now working (like a charm ) 1.2.2 3rd februari 2010: New methods added: Overloaded RequestUpdateOATHKey and the new method setclientname
1.2.3 20th februari 2010 Bug fix: If international (swedish) characters was included in the user name or in the user password, the OTP Server wasn't able to read them. Corrected in the EncodeBase64() to encoding iso-8859-1 Update: Code page for base64 encoding may be changed in the registry (string value). Example: [SOFTWARE\\Nordic Edge\\OTP Server], "Code page"="utf-8". (default code page is iso-8859-1). 1.2.5 2nd december 2010 The methods GetAssemblyVersion() and GetAssemblyName() added Fix: The methods EncodeBase64 and DecodeBase64 was changed. These will only be used for user names and passwords if the registry value ([SOFTWARE\\Nordic Edge\\OTP Server], "Code page"="") is set to a value, for example "Code page"="iso-8859-1". Changed because the OTP Server now allows setting the code page else then default value.