This chapter guides you step by step through integrating Secure Access Web Service (ARWebService) into your client application.

 

It will be illustrated on a simple console application that allows users to add two numbers. It can be executed only by authenticated users who are in the "Calculator.Mathematician" role.

		Source code
		You can find the source code of this sample application in the "Examples\VB\SampleARWSClientVB" folder in the PortSight Secure Access installation folder. Beside this, we recommend you to explore the sample application in the "Examples\VB\TestARWebService" folder. It is a WinForms application that allows you to experiment with ARWebService by specifying various security parameters.

 

Implementing Authentication and Authorization

 

1. Launch Microsoft Visual Studio .NET and create a new VB.NET project called SampleARWSClientVB using Console Application template.
   

2. Add references to the following Secure Access libraries (you can find them in the "DLLs" folder in the PortSight Secure Access installation folder):
   

ARWebServiceClient.dll

ARWebServiceCommon.dll

3. Add the following code to the Module1.vb code file:
   

1. Import namespaces for Secure Access Web Service client libraries:
   
   

   Imports PortSight.SecureAccess.WebServices.Client Imports PortSight.SecureAccess.WebServices.Common Imports System.Configuration

   
   

2. Create function Add that adds two numbers and checks whether the caller has appropriate rights for executing this function:
   
   

   Function Add(ByVal A As Double, ByVal B As Double, _                          ByRef SAWSClient As ARWSClient) As Double                 ' Test if the current user is authorized to perform math operations.                 If Not SAWSClient.IsInRole("Calculator.Mathematician") Then                     Throw New ApplicationException("Access Denied.")                 End If                         'UNCOMMENT THIS FOR ENABLING X.509 DIGITAL CERTIFICATES USAGE                 '' Test if the previous response from the service is trustworthy                 'If Not SAWSClient.EncCertKeyID Is Nothing AndAlso _                 '   SAWSClient.EncCertKeyID <> SAWSClient.SignOutCertKeyID Then                 '    Throw New ApplicationException("The response is not trustworthy.")                 'End If                 Return A + B         End Function

   
   

3. Add the following code to the Main() method. It creates an instance of the ARWSClient class, sets its parameters and then calls the Add() function.

' Create and configure instance of the Secure Access Web Service Client         Dim SAWSClient As New ARWSClient()         ' Connection to the Secure Access Web Service         SAWSClient.Url = "http://localhost/ARWebService/ARWSWebService.asmx"         SAWSClient.TimeToLive = 60000   ' 60s limit         ' Security         SAWSClient.EncCertKeyID = ""        ' DO NOT ENCRYPT REQUESTS         SAWSClient.SignCertKeyID = "" ' DO NOT SIGN REQUESTS         SAWSClient.EncSymmetricKey = "" ' DO NOT ENCRYPT REQUESTS         'UNCOMMENT THIS FOR ENABLING X.509 DIGITAL CERTIFICATES USAGE         'SAWSClient.EncCertKeyID = "62B24669313B953C2AE0FE386068706162EA97F9"         'SAWSClient.SignCertKeyID = "374BE5DE833CCA912C0525FB2E5122B2D0454335"         'UNCOMMENT THIS FOR ENABLING SYMMETRIC CRYPTOGRAPHY USAGE         'SAWSClient.EncSymmetricKey = "104FEE68517937764D25651347C0D87BE3846F068A427B28"         ' Set user's credentials and the ID of the SA catalog to use         SAWSClient.LoginName = "fido"         SAWSClient.Password = "something"         SAWSClient.AuthenticationMode = ARWSAuthenticationModeEnum.Forms         SAWSClient.CatalogID = "Samples"         ' Perform the desired opperation         Console.WriteLine("1 + 2 = " + Add(1, 2, SAWSClient).ToString())         Console.ReadLine()

      What you did:
    
      You created an instance of the ARWSClient class. The url parameter specifies the address of the 
      ARWSWebService.

      The certificate key ID's describe the certificates that will be used for encryption and signing the message sent to
      the  ARWSWebService. The Symmetric Key is optional and it is used for additional encryption.

      Then you set the loginname and password of the current user. These credentials are used 
      for authentication against Secure Access database through the ARWSWebService. The authentication 
      mode indicates that the user name and password was entered by user (actually, we don't use the 
      logon form control in this sample - instead we put the credentials in the code directly). If you use
      ARWSAuthenticationModeEnum.Windows mode instead, the domain user name of the current user will be
      used without checking user password.

      The catalog ID property indicates which catalog should be used.

 

At the end you call the Add method that checks user name and password and verifies that the user is member of the required role. Then it checks if the ARWSWebService response was really sent from the right server.

 

3. Copy and paste the following lines in the app.config file:
   
   

   <?xml version="1.0" ?> <configuration>     <configSections>         <section name="microsoft.web.services" type="Microsoft.Web.Services.Configuration.WebServicesConfiguration, Microsoft.Web.Services, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />     </configSections>     <appSettings>               <!-- Shared Symmetric Key to be used for decrypting -->               <add key="SecureAccessSymmetricKey" value="104FEE68517937764D25651347C0D87BE3846F068A427B28" />     </appSettings>       <!-- This is the WSE configuration section -->     <microsoft.web.services>         <security>             <x509 storeLocation="CurrentUser" />             <decryptionKeyProvider type="PortSight.SecureAccess.WebServices.Common.ARWSDecryptionKeyProvider, ARWebServiceCommon" />         </security>     </microsoft.web.services> </configuration>

                          

4. Compile the project.
   
5. Create and configure the Secure Access catalog:
   
   
   1. Use Catalog Manager to create a new catalog named "Samples".
      
   2. Open Web Interface for the "Samples" catalog by clicking the "Open Web Interface" button in the Catalog Manager.
      
   3. Log on as administrator/administrator and then:
      
                       i.            Create a new user with user name "Fido" and set password "something" for this user.
      
                       ii.            Create a new application wit alias "Calculator".
      
                       iii.            Create a new role with alias "Mathematician" for the "Calculator" application created in the previous step. Add user Fido" among members of this role.
      
   4. Check that the web.config file of the ARWebService contains the following parameters:
      
                        i.            SecureAccessCatalogsXMLPath - full path to the catalogs.xml file; if not specified, 
         add the following line to the /configuration/appSettings section (update the path
         according to your Secure Access installation):
      
      

      <add key="SecureAccessCatalogsXMLPath" value="C:\Program Files\PortSight SecureAccess\3.0\Catalog Manager\Catalogs.xml" />

      
      

6. Run the project.
   

Securing Communication with ARWebService Using a Symmetric Key

 

1. In the Main() method of the client application uncomment section marked as
   
   'UNCOMMENT THIS FOR ENABLING SYMMETRIC CRYPTOGRAPHY USAGE
   
2. Copy and paste the following lines into to the app.config file:
   
   

   <?xml version="1.0" ?> <configuration>     <configSections>         <section name="microsoft.web.services" type="Microsoft.Web.Services.Configuration.WebServicesConfiguration, Microsoft.Web.Services, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />     </configSections>     <appSettings>               <!-- Shared Symmetric Key to be used for decrypting -->               <add key="SecureAccessSymmetricKey" value="104FEE68517937764D25651347C0D87BE3846F068A427B28" />     </appSettings>       <!-- This is the WSE configuration section -->     <microsoft.web.services>         <security>             <decryptionKeyProvider type="PortSight.SecureAccess.WebServices.Common.ARWSDecryptionKeyProvider, ARWebServiceCommon" />         </security>     </microsoft.web.services> </configuration>

3. Update the symmetric key specified in the code (SAWSClient.EncSymmetricKey = ...) and the symmetric key specified in the App.config (<add key="SecureAccessSymmetricKey" value="..."/>) to be the same as the symmetric key specified in the service Web.config.
   

4. Check that the web.config file of the ARWebService contains the following parameters:
   
   

            i.            SecureAccessSymmetricKey - symmetric encryption key. If it's not specified, add the following line to the /configuration/appSettings section:
   
   

   <add key="SecureAccessSymmetricKey" value="104FEE68517937764D25651347C0D87BE3846F068A427B28" />

   
   

             ii.            SecureAccessCatalogsXMLPath - full path to the catalogs.xml file. If it's not specified, add the following line to the /configuration/appSettings section (update the path according to your Secure Access installation):
   
   

   <add key="SecureAccessCatalogsXMLPath" value="C:\Program Files\PortSight SecureAccess\3.0\Catalog Manager\Catalogs.xml" />

 

Securing Communication with ARWebService Using X.509 Certificates

In the following text we consider using testing X.509 certificates delivered with Secure Access. You can find more details in Appendix F - Included Testing X.509 Certificates.

Instead of the keys specified in the code bellow you can use ID's of your own certificates. Please see Appendix E - Using X.509 Certificates for details.

1. In the Main() method of the client application uncomment section marked as
   
   'UNCOMMENT THIS FOR ENABLING X.509 DIGITAL CERTIFICATES USAGE
   
2. Copy and paste the following lines into to the app.config file:
   
   

   <?xml version="1.0" ?> <configuration>     <configSections>         <section name="microsoft.web.services" type="Microsoft.Web.Services.Configuration.WebServicesConfiguration, Microsoft.Web.Services, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />     </configSections>       <appSettings>               <!-- Shared Symmetric Key to be used for decrypting -->               <add key="SecureAccessSymmetricKey" value="104FEE68517937764D25651347C0D87BE3846F068A427B28" />     </appSettings>       <!-- This is the WSE configuration section -->     <microsoft.web.services>         <security>             <x509 storeLocation="CurrentUser" />             <decryptionKeyProvider type="PortSight.SecureAccess.WebServices.Common.ARWSDecryptionKeyProvider, ARWebServiceCommon" />         </security>     </microsoft.web.services> </configuration>

   
   

3. Install certificates as specified in the Appendix F - Included Testing X.509 Certificates.
   
4. Check that the web.config file of the ARWebService contains the following parameters
   
                   i.            SecureAccessServiceCertKeyID - subject ID of the certificate for the web service; if it's not specified add the following line to the /configuration/appSettings section (the value is for testing certificates delivered with Secure Access):
   
   

   <add key="SecureAccessServiceCertKeyID" value="62B24669313B953C2AE0FE386068706162EA97F9" />

   
    

		Note
		Beside the IsInRole() method, you can use the ARWSWebService.IsAuthorized() method that returns true if the user is authorized to access specified resource with specified permission (relationship type).