Connect – Authentication

Table of Contents

• Prerequisites
• Description
• Sample Code
  • Anonymous
  • User Name and Password
  • X.509 Certificate and File Based Certificate Store
  • X.509 Certificate and Windows Certificate Store

Prerequisites

This example does only show different user authentication mechanisms, including certificate based authentification, but not how to create and trust certificates.

To use authentification with certificates, it is needed to create a client certificate first. You can test the variant using the file based certificate store out-of-the-box, because an Application Instance Certificate for the ClientGettingStarted application is created automatically when installing the SDK. For simplicity, the example uses this certificate for authentication as well. Example code for creating a certificate to be used in a file based certificate store is described in Certificate Management – Create Certificate.

Furthermore, it is necessary that client and server already trust each other’s certificate. You can use the Simple Connect or the Advanced Connect example and connect with security. Be sure to check the box “Save Certificate in TrustList” when trusting the server’s certificate.

Description

The following dialog shows an example for implementing different types of user Authentication. Press the button “Show Code” to display the corresponding code, and the button “Help” to show this documentation page.

The example demonstrates four different authentication settings:

Anonymous

Connect as anonymous user

UserName

User name and password based authentication

X509 (Dir)

Authentication using X.509 certificates and a file based certificate store

X509 (Store)

Authentication using X.509 certificates and the Windows certificate store

Check the radio button in front of the authentication method of your choice, fill in the required fields, and press “Connect”.

To test the UserName variant, enter the user name “sue” and password “curly” to the respective input fields.

For the X509 (Dir) variant, press the “…” button and select the certificate for the ClientGettingStarted application (see above). The example requires to select the certificate containing the private key (i.e. the .pfx file, see screenshot). Note that the private key is only used for signing and will not be sent to the server.

To actually establish a connection, client and server have to trust each other’s certificates first (see above).

To use the Windows certificate store instead, choose X509 (Store). The fields “Store Path” and “Certificate” are already filled with standard values, change them to your liking. As in the example above, it is necessary to create a certificate for the ClientGettingStarted application first and client and server have to trust each other’s certificates.

After a sucessful connect, the user identity is shown in the “Session” tab of the .NET Demo Server GUI (see screenshot).

Sample Code

The user token specific code can be found in the method SetUserToken().

Anonymous

To connect as anonymous user, UserIdentityType has to be set to Anonymous.

            if (AnonymousButton.Checked)
            {
                m_session.UserIdentity.IdentityType = UserIdentityType.Anonymous;
            }

User Name and Password

To authenticate with user name and password, set the UserIdentityType to UserName.

            else if (UserNameButton.Checked)
            {
                m_session.UserIdentity.IdentityType = UserIdentityType.UserName;
                m_session.UserIdentity.UserName = UserName_Name.Text;
                m_session.UserIdentity.Password = UserName_Password.Text;
            }

X.509 Certificate and File Based Certificate Store

To authenticate using an X.509 certificate, set the UserIdentityType to Certificate.

UnifiedAutomation.UaBase.SecurityUtils

            else if (X509Button.Checked)
            {
                System.IO.FileStream fs = null;
                try
                {
                    // Load the certificate content.
                    fs = System.IO.File.OpenRead(X509_Certificate.Text);
                    byte[] bytes = new byte[fs.Length];
                    fs.Read(bytes, 0, Convert.ToInt32(fs.Length));

                    // Add the certificate to the user identity.
                    m_session.UserIdentity.Certificate = SecurityUtils.LoadCertificate(bytes);

                    // Set the UserIdentityType.
                    m_session.UserIdentity.IdentityType = UserIdentityType.Certificate;
                }
                catch (Exception ex)
                {
                    ExceptionDlg.Show(this.Text, ex);
                }
                finally
                {
                    // Free resources.
                    if (fs != null)
                    {
                        fs.Close();
                        fs.Dispose();
                    }
                }
            }

X.509 Certificate and Windows Certificate Store

To authenticate using an X.509 certificate, set the UserIdentityType to Certificate.

UnifiedAutomation.UaBase.SecurityUtils

            else if (X509StoreButton.Checked)
            {
                try
                {
                    // Create the certificate store.
                    using (ICertificateStore store = SecurityUtils.CreateStore(X509StorePath.Text.Trim()))
                    {
                        // Load the certificate.
                        ICertificate certificate = store.Find(X509StoreCertificate.Text.Trim(), null, true);

                        // If the certifcate could not be found, try to find the certificate without a
                        // private key. This allows to use a more helpful exception message.
                        if (certificate == null)
                        {
                            certificate = store.Find(X509StoreCertificate.Text.Trim(), null, false);

                            if (certificate != null)
                            {
                                throw new ArgumentException("The Certificate must have an accessible private key.");
                            }
                            else
                            {
                                throw new ArgumentException("The Certificate does not exist.");
                            }
                        }

                        // Add the certificate to the user identity.
                        m_session.UserIdentity.Certificate = certificate;

                        // Set the UserIdentityType.
                        m_session.UserIdentity.IdentityType = UserIdentityType.Certificate;
                    }
                }
                catch (Exception ex)
                {
                    ExceptionDlg.Show(this.Text, ex);
                }
            }