UA Directory Services Users’ Guide
Introduction
Overview
OPC UA provides a scalable architecture that is designed for everything from small ad-hoc networks to large enterprise systems. OPC UA is built on standard technologies in order to allow software vendors and users to leverage the IT infrastructure they already have while maintaining OS and platform independence.
In order to facilitate the management of networks of applications OPC UA has standardized number of key interfaces including a Discovery interface which is used to find Servers running on a single machine and standard schemas for use in LDAP or UDDI directories. To better support large networks of systems v1.02 of the OPC UA specification introduces a standard interface to a Directory Service. This interface is designed to automate common security related tasks such as certificate distribution and revocation and to provide a searchable registry for factory equipment and services based on the OPC UA information model. This Directory Service is called the UA Global Directory Service (GDS) and is shown in Figure 1.
Figure 1 – The Relationships between the GDS and other System Components
Scope
This document is a user manual for the reference implementation of the Global Directory Service (GDS) that is bundled with the OPC UA SDK and distributed by the OPC Foundation. This reference implementation is intended to provide a framework for developing and testing OPC UA applications that use a GDS. It is expected that different vendors will develop their own enterprise class GDS by implementing the information model that is defined in Part 12 of the OPC UA specification.
Audience
This document is intended for end users and developers who test and deploy OPC UA applications. The reader must be familiar with OPC UA concepts.
Software Overview
Distribution
The reference implementation for the Global Directory Service (GDS) is packaged in a Merge Module called ‘OPC UA SDK 1.1 Discovery Services’. This Merge Module includes the GDS, a client application called the ‘GDS Local Agent’ and the Local Discovery Server (LDS). The ‘GDS Local Agent’ is an application that is installed on every machine with OPC UA applications is use to administer GDS and the applications installed on the machine. It replaces the ‘UA Configuration Tool’ that was part of earlier releases of the SDK.
All OPC UA SDK installers incorporate the Merge Module and install the LDS and the GDS Local Agent. The ‘OPC UA SDK 1.1 Directory Services’ or ‘OPC UA SDK 1.1 Redistributables’ installer packages can install the GDS Server application. It is expected that only one GDS Server will reside on each network.
Installation
The ‘OPC UA SDK 1.1 Discovery Services’ Merge Module uses the UA_USE_GDS installer property to determine what gets installed. The property contains an integer value which must have one of the values shown in Table 1.
Table 1 – Values for the UA_USE_GDS Property
|
Value |
Description |
|
0 |
Only install the Local Discovery Server (LDS). |
|
1 |
Install the Local Discovery Server (LDS) and the GDS Local Agent. |
|
2 |
Install the LDS, the GDS Local Agent and the GDS Server. |
If the UA_USE_GDS property is not set then option 1 is selected.
The ‘OPC UA SDK 1.1 Directory Services’ or ‘OPC UA SDK 1.1 Redistributables’ installer packages run they will display a dialog with each of those choices. Note that in production environment GDS Server should only be installed on one system on network, however, for testing and development a GDS Server can be installed on as many machines as necessary.
When the install program runs it does the following:
· Installs program files in ‘%ProgramFiles%\OPC Foundation\UA\v1.1\GDS’.
· Installs the configuration files in ‘%CommonApplicationData%\OPC Foundation\GDS’.
· Places a link to the GDS Local Agent the Start Menu under ‘OPC Foundation | UA’.
The GDS Server creates a number of files which are critical to the security of the system. These files are place in a subfolder called ‘ProtectedData’ and can only be accessed by Administrators or the Windows SYSTEM account.
Configuration
The GDS Server and Local Discovery Server are OPC UA Server applications built with the OPC UA .NET SDK. They rely on an XML configuration file with a schema defined in ApplicationConfiguration.xsd. This schema defines various parameters that control the operation of the applications. The location of the files and the purpose of specific parameters are discussed in the sections describing the individual applications.
GDS Server
Overview
The GDS Server is an OPC UA Server which implements the GDS information model shown in Figure 2. The details of the information model are defined in Part 12.
Figure 2 – The GDS Information Model
The GDS Server fills two major roles: it manages the Certificates issued to the Applications in the system and it allows Clients to browse the topology of the system and search for Applications.
The GDS Local Agent provides a user interface which can conveniently access the certificate management features. Any OPC UA Client can browse the topology and discover the OPC UA Servers on the network.
The certificate management features are described completely in the section on the GDS Local Agent.
Topology
By default the GDS exposes a flat topology with a SystemElement to represent each machine with Servers on the network. Users can extend this topology by manually updating the XML file used as a database. The best reference for how to do that is the source code for the GDS Server.
Vendor supplied implementations should provide more user friendly interface that allows users to add and remove nodes in the topology.
Database
The GDS Server requires a database which stores the system topology, registered applications and any issued certificates. The default implementation uses an XML file to store this information but could be adapted to use a SQL DB if required.
The database is stored in the ‘%CommonApplicationData%\OPC Foundation\GDS\ProtectedData’ directory.
Security
The GDS Server allows any Client with a valid Certificate to connect which means it is not necessary to manage the trust lists. However, the GDS does require that the Client use encryption and signing when accessing security sensitive features.
Different features of the GDS Server are only available to authorized users. The GDS uses the Username Identity Tokens provided by the Client to determine what features a Client has access to. This implementation expects Clients to use Windows user accounts on the machine where the GDS Server is installed. These accounts could be domain accounts.
The mapping from Windows accounts to access privileges is handled with semaphore files in the ‘%CommonApplicationData%\OPC Foundation\GDS\User Roles’ directory. The GDS Server will impersonate the Windows user and attempt to access the file in a directory. If access is permitted the Client is allowed to access the User Role represented by the file. Different features can be accessed by different User Roles. At this time there are two User Roles supported:
· GdsAdministrator – Can access all features;
· ApplicationAdministrator – Can Register Applications and Request Certificates;
If a Client cannot access any of the named User Roles it is treated the same as an anonymous user.
Access to some features may be permitted if the Client Certificate is a Certificate issued by the GDS and the Client is trying to access a feature related to that application such as renewing a Certificate or requesting the Trust Lists. The same access is granted to the GDS Local Agent application that registered the Application.
GDS Local Agent
Overview
The GDS Local Agent is an OPC UA Client application that interacts with the GDS Server and updates the configuration of other OPC UA Applications running on the machine where it is installed. The main screen of the GDS Local Agent is shown in Figure 3.
Figure 3 – The GDS Local Agent Main Window
The top list view displays all of the OPC UA applications known to the GDS Local Agent. Applications will appear automatically in this view if they place a copy of their security configuration in a file in the ‘%CommonApplicationData%\OPC Foundation\GDS\Applications’.
This file must be an XML document that complies with the SecuredApplication schema defined in Part 6. The name of the file should be the default name of the application.
The bottom view is a log that reports results of actions the application has performed in response to the user. Any errors will appear here.
The columns displayed in the application list view are discussed in Table 2.
Table 2 – The Columns in the Application List View
|
Name |
Description |
||||||||
|
Name |
The name of the application (the ApplicationName in the SecuredApplication schema). |
||||||||
|
Registered |
Whether the application has been registered with a GDS server. |
||||||||
|
Application Type |
The type of application (the ApplicationType in the SecuredApplication schema). |
||||||||
|
Configuration Type |
The type of configuration. See section below for an explanation of the different configuration types.
|
||||||||
|
Certificate Type |
The type of certificate held by the application. Possible values are:
|
Certificate Management
The GDS Local Agent allows the user to use the GDS as a Certificate Authority which issues Certificates to all Applications registered with it. The process which the agent implements is shown in Figure 4
Figure 4 – The Certificate Management Process
Configuration Types
The GDS Local Agent needs to be able to change the configuration of other applications installed on the machine. To do this the GDS Local Agent needs to know something about how they are configured. There are three possible configuration mechanisms: Xml, ImportExport and Manual.
Xml
An application that supports XML configuration must use a file that contains an element following the ApplicationConfiguration schema. All applications built with the OPC UA .NET SDK do this by default. Other applications can support this syntax.
To configure an application using XML configuration the user must provide the location of the XML configuration file. Whenever the configuration is updated the GDS Local Agent will write to this file which may require that the application be restarted.
ImportExport
An application that supports ImportExport configuration must provide a utility that read/writes an XML document conforming to the SecuredApplication schema.
To configure an application using ImportExport configuration the user must provide the location of the utility executable file and set of parameters to use for the import and export operations.
Whenever the configuration is updated the GDS Local Agent will call this utility with a set of parameters provided for the import operation and path to the input file (always at the end of the parameter list).
When the GDS Local Agent needs to read the configuration it will GDS Local Agent will call this utility with a set of parameters provided for the export operation and path to the output file (also always at the end of the parameter list).
Manual
An application that does not support any of the other configuration mechanisms must be manually configured. This means the user is responsible for updating manually updating the application configuration file after it has been changed by the GDS Local Agent.
That said, if the application uses files on disk to store the certificates and shared certificate stores the GDS Local Agent can update these files/directories automatically without user intervention.
Creating a New Application
Right clicking on the application list will bring up a context menu with a ‘New…’ option. This starts the Application Wizard. The first page is shown in Figure 5.
Figure 5 – The First Page of the Application Wizard
Selecting XML and clicking ‘Next’ will prompt you to provide the location of the configuration file. Clicking ‘Next’ again will read the XML configuration file and bring you to the page shown in Figure 6.
Figure 6 – The Last Page of the Application Wizard
The fields in this page are shown in Table 3
Table 3 – The Fields in the Application Wizard
|
Name |
Description |
|
Application Name |
The name of the application. Used as the BrowseName of the Node in the GDS. Can be used to search for the application with the QueryServers Method. |
|
Application URI |
The URI of the application. Uniquely identifies the instance of the application running on the local machine. Will be assigned automatically if left blank. Must be globally unique and should include the machine name. Must follow the URI or URL syntax. Can be used to search for the application with the QueryServers Method. |
|
Machine Name |
The name of the machine. If used as the BrowseName for the SystemElement containing the Application Node in the GDS. Can be used to search for the application with the QueryServers Method. |
|
Subject Name |
Additional fields for the Certificate Subject Name (e.g. OU=Engineering/O=Acme, Inc.) ‘/’ are used to separate fields. A Common Name (CN=) must not be included. |
|
Product URI |
The URI of the product. Must be globally unique. Must follow the URI or URL syntax. Can be used to search for the application with the QueryServers Method. |
|
Application Type |
The type of Application (Server, Client, ClientAndServer or DiscoveryServer). |
|
Application Certificate Store |
The location of the certificate store used for the application certificate. The agent will place new certificates in this store. If left empty the agent will not update the application certificate. Not available for Manual configuration. |
|
Certificate Public Key |
The file which contains the public key in DER format. This is only used for Manual configuration. The agent will over write this file when it receives a new certificate from the GDS. The old key is saved with a ‘.bak’ extension. |
|
Certificate Private Key |
The file which contains the public key in PEM or PFX format. This is only used for Manual configuration. The agent will over write this file when it receives a new certificate from the GDS. The old key is saved with a ‘.bak’ extension. |
|
Trust List |
The location of the trust list for the application. The agent will update this store with the trust list provided by the GDS. If left empty the agent will not update the trust list. |
|
Issuer Certificate List |
The location of the store containing additional certificates used to verify signatures. The agent will update this store with the issuer list provided by the GDS. If left empty the agent will place the issuer certificates in the trust list. This means that all certificates issued by that issuer will be trusted. An issuer list should be provided if this behavior is not desired. Older versions of applications will not support an issuer list. |
|
Security Profiles |
The list the security profiles enabled for the application. This can be used to enable/disable the no-security endpoints for an application. Not available for Manual configuration. |
|
Base Addresses |
The list of endpoints supported by the application. The summary view only shows the protocol and port. Clicking on the button will bring up the full list. This field may be left empty for client applications. |
Clicking ‘Done’ will save the settings and the GDS Local Agent will attempt to update the application’s configuration (for XML and ImportExport configurations).
Managing Applications
Selecting an application in the application list view will bring up a context menu which several commands that depend on the state of the application. All of the commands are described in Table 4.
Table 4 – Application Command
|
Name |
Description |
|
Edit |
Restarts the application wizard. Reloads information from the application configuration file if possible. |
|
Delete |
Deletes the application. |
|
View Trust Matrix |
Shows trust relationship between the selected application and all other applications. Can be used to detect security and fix issues. Any certificate validation errors are shown. |
|
Create Self Signed |
Creates a new self-signed certificate and installs it. Discards any existing certificate. |
|
Set Permissions |
Shows a dialog with the firewall ports that have been opened for an application. Allows the user to specify the application executable path. Allows the user to restrict access to the private key for the application. Also sets HTTP URL access permissions. |
|
Install/Update HTTPS CAs |
Installs the HTTPS Certificate Authorities on the machine. This will add certificates to the trusted root authority certificate store. This allows HTTPS clients to connect to servers with certificates issued by the GDS. |
|
Restart Service |
Restarts applications which are services. Only appears if a service exists with the same name as the Application Name. |
|
Register |
Registers the application with the GDS. Requires a username/password for the GDS with ‘ApplicationAdministrator’ privileges. Calling it again for registered applications will update the record in the GDS. Changing the Application URI will force the creation of a new Application record in the GDS. |
|
Request Certificate |
Requests a new Certificate from the GDS. Requires a username/password for the GDS with ‘ApplicationAdministrator’ privileges. The operation must be completed by calling the ‘Check Certificate Status’ command. |
|
Request HTTPS Certificate |
Requests a new HTTPS Certificate from the GDS. Requires a username/password for the GDS with ‘ApplicationAdministrator’ privileges. The operation must be completed by calling the ‘Check Certificate Status’ command. HTTPS certificates have the Machine Name as the Common Name (CN=). They are always installed in the ‘LocalMachine\My’ certificate store. The CA is always installed in the ‘LocalMachine\Root’ certificate store. |
|
Check Request Status |
Checks if the Certificate Request has been approved by the GDS Administrator. If approved the new certificate is download and the application is updated. The CA certificates are installed in the trust list and/or issuer list. |
|
Abandon Certificate Request |
Abandons a Certificate Request. Allows the user to request a new one. |
|
Update Trust Lists |
Retrieves the trust lists and certificate revocation lists from the GDS. When an application is registered it receives a trust list identifier. All applications with the same trust list identifier can share the same certificate stores. The agent will ask the user if they want to delete all existing certificates. This option should be chosen if all applications using the store have the same trust list identifier. The current implementation of the GDS only supports one trust list for all applications. |
|
Revoke Certificate |
Revokes the current certificate. Should be used if the agent has reason to believe the certificate was compromised. |
|
|
|
Main Menu
GDS Menu
This menu interacts has commands that interact with the GDS. They are described in Table 5.
Table 5 – The GDS Menu
|
Name |
Description |
|
Connect |
Prompts the user to enter URL for the GDS. This URL is saved for use next time. |
|
Disconnect |
Disconnects from the GDS. |
|
Login as User |
Prompts the user to enter a username/password that is used to access the GDS. |
|
Logout |
Logs out of the GDS and reverts to the ‘Anonymous’ user. |
|
Browse |
Displays a dialog that allows the user to browse the system topology. |
|
Search |
Displays a dialog that allows the user to search for applications. |
|
Exit |
Exits the program. |
View Menu
This menu interacts has commands that provide access to different views. They are described in Table 6.
Table 6 – The View Menu
|
Name |
Description |
|
Local Certificate Stores |
Displays a window that allows the user to browse and edit Certificate Stores on the local machine. The user can use this window to manually edit trust lists. |
|
Certificate Requests |
Displays a window that shows the active GDS certificate requests. The user will be able to approve certificate requests if the user is logged into the GDS as a GDS Administrator. |
|
COM Pseudo Servers |
Displays a window with the COM pseudo-servers registered on the host. Allows the user to browse for UA applications on the network and create new COM pseudo-servers. |
|
HTTP Access Rules |
Displays window that allows the user to edit the HTTP access rule on the machine. |
|
SSL Bindings |
Displays window that allows the user to edit the SSL Bindings on the machine. |
|
Show Message Pan |
Toggles the display of messages at the bottom of the window. |