PortSight Secure Access Documentation

Using Secure Access WinForms Controls - ARWSLogonCtrl and ARWSSetPasswordCtrl


You can find the following user controls in the ARWebWerviceClient assembly:


that can be used directly from within your WinForms applications for user log on and for changing the user's password.

 

The following steps will guide through the process of integrating ARWSLogonCtrl user control into your application. Usage of the ARWSSetPasswordCtrl control is similar.

 

    Sample Code

Please refer to the SampleARWSDemoAppVB sample application in the Examples\VB\WinFormsLogonFormSample in the PortSight Secure Access installation folder. It demonstrates the usage of the ARWSLogonCtrl and ARWSSetPasswordCtrl controls.



  1. In your WinForms project, add reference to the following assemblies:
    • ARWebServiceClient.dll
    • ARWebServiceCommon.dll
  2. Create an (empty) form named "LogonForm".
  3. Put ARWSLogonCtrl user control to the LogonForm and set its name to "LogonCtrl".
  4. View the LogonForm code and add the import statements at the beginning of the file:


        Imports PortSight.SecureAccess.WebServices.Client
        Imports PortSight.SecureAccess.WebServices.Common
  5. Now we will put ARWSLogonCtrl user control to the LogonForm and set its name to "LogonCtrl". It cannot be done using Designer, so it will be necessary to modify the code manually using Code Editor.

    Somewhere inside " Windows Form Designer generated code " region declare a variable LogonCtrl of type ARWSLogonCtrl:


        Public WithEvents LogonCtrl As ARWSLogonCtrl

    Put the following lines to the InitializeComponent() method. They will resize the form and LogonCtrl and set the position.


        Me.LogonCtrl = New PortSight.SecureAccess.WebServices.Client.ARWSLogonCtrl()
        Me.SuspendLayout()
        '
        'LogonCtrl
        '
        Me.LogonCtrl.BackColor = System.Drawing.SystemColors.Control
        Me.LogonCtrl.Location = New System.Drawing.Point(16, 16)
        Me.LogonCtrl.Name = "LogonCtrl"
        Me.LogonCtrl.Size = New System.Drawing.Size(264, 96)
        Me.LogonCtrl.TabIndex = 0
        '
        'Form1
        '
        Me.AutoScaleBaseSize = New System.Drawing.Size(5, 13)
        Me.ClientSize = New System.Drawing.Size(310, 120)
        Me.Controls.AddRange(New System.Windows.Forms.Control() {Me.LogonCtrl})
        Me.Name = "LogonForm"
        Me.Text = "Logon Form"
        Me.FormBorderStyle = FormBorderStyle.FixedDialog
        Me.ResumeLayout(False)

    Now it is necessary to set parameters for the ARWSClient object encapsulated in the LogonCtrl object. It is possible to do that from outside the form before its invocation or put the initialization code to the form constructor as shown here (it must be done after calling the InitializeComponent() method):


        Public Sub New()
            MyBase.New()
     
            'This call is required by the Windows Form Designer.
            InitializeComponent()
     
            'Add any initialization after the InitializeComponent() call
            LogonCtrl.LoginName = ""
            LogonCtrl.EncCertKeyID = "62B24669313B953C2AE0FE386068706162EA97F9"
            LogonCtrl.SignCertKeyID = "374BE5DE833CCA912C0525FB2E5122B2D0454335"
            LogonCtrl.EncSymmetricKey = "104FEE68517937764D25651347C0D87BE3846F068A427B28"
            LogonCtrl.AuthenticationMode = ARWSAuthenticationModeEnum.Forms
            LogonCtrl.CatalogID = "Samples"
            LogonCtrl.Url = "http://localhost/ARWebService/ARWSWebService.asmx"
            LogonCtrl.TimeToLive = 60000   ' 60s limit
        End Sub

    Note 1: The following code contains hardcoded parameters but it's recommended that you read them dynamically, e.g. from the application configuration file.

    Note 2: The LogonCtrl.AuthenticationMode = ARWSAuthenticationModeEnum.Forms indicates that user name and password will be required. If you use ARWSAuthenticationModeEnum.Windows mode instead the ARWebService client libraries will use current user domain name without checking the password.

    And finaly add the handlers for the LogonSuccessful and LogonFailed events:


        Private     Sub LogonSuccessful_Event() Handles LogonCtrl.LogonSuccessful
            ' Add your reaction on successful logon
            ' The user's credentials can be obtained from the LogonCtrl.Client object
        End Sub
     
        Private Sub LogonFailed(ByVal result As ARAuthenticationResultsEnum) Handles LogonCtrl.LogonFailed
            ' Add your reaction on unsuccessful logon
        End Sub
  6. Add commands to your application code that will display the LogonForm such as this one:

     
         LogonForm.ShowDialog()
  7. Add the following sections to the App.config file:


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


        <microsoft.web.services>
            <security>
                <x509 storeLocation="CurrentUser" />
                <decryptionKeyProvider type="PortSight.SecureAccess.WebServices.Common.ARWSDecryptionKeyProvider, ARWebServiceCommon" />
            </security>
        </microsoft.web.services>
  8. Compile and run your application. The logon form will look like this one:



    Note

1. ARWSLogonCtrl and ARWSSetPasswordCtrl classes encapsulates ARWSClient class as Client property, so you can use the ARWSClient object from your application without instantiating it.

 

2. ARWSSetPasswordCtrl is automatically displayed by the ARWSLogonCtrl if provided user's password has expired.