Security Features in Intouch 8.

x Page 1 of 6

Tech Note 295

Security Features in InTouch 8.x

All Tech Notes and KBCD documents and software are provided "as is" without warranty of any kind. See the Terms of Use for more information.

Topic#: 001100
Created: January 2003

Introduction

This Tech Note outlines the security features available in InTouch 8.x. InTouch 8.0 introduced script functions and system tags that were not
previously available in InTouch 7.x or earlier. InTouch security includes different aspects that are not necessarily required in all applications.

Securing an InTouch application means different things to different people; InTouch programmers may want to secure the operating system,
audit operators' actions, or secure the InTouch application itself. In some cases the top concern is to limit the operator's access to other
Windows applications or the operating system; there are script functions available to lock the use of keys like <ALT> or <TAB>. Also, there are
ways to configure WindowViewer (View) to always run it maximized or to hide its menu so that operators can't close it. In other instances
security is all about auditing the operator's actions and keeping track of what was done when; InTouch events can account for that, as well as
the "inactivity" system tags. In some other cases security would mean to restrict features of the application based on privileges set forth for the
current user (like a User ID) or the group the user belongs to (like Roles); that functionality is accomplished by setting a visibility or disable link
to the object with limited access (for example, a push button to open another window).

Security in InTouch had remained unchanged for years; a binary file in the InTouch application directory contained a list of users of the
application, their passwords, and access levels. One of the limitations of InTouch 7.x and earlier was the difficulty in handling users and policies
to meet requirements in regulated industries; for example, the specifications established by the Food and Drug Administration (FDA) on CFR 21
Part 11. Meet InTouch 8.0; new security models and system tags have been introduced to take advantage of Windows security as well as the
security features built into the Industrial Application Server (powered by ArchestrA!).

Security Features in InTouch 8.x

As explained above, there are three aspects of security to be considered when using InTouch:

Securing the OS

Auditing

Securing the Application

Securing the Operating System

Many InTouch applications require an operator to constantly monitor processes running 24x7. In these cases it is often desirable to have
InTouch as the only Windows application that operators have access to. The operating system task bar, system files, and other Windows
applications are inaccessible if View is configured properly.

There are different things that can be done to make WindowViewer the only application running in the foreground and to disable <Alt>, <Ctrl>,
or <ESC> keys so users can't switch between windows applications or access the task bar. InTouch 7.x or earlier provided configuration settings
for WindowViewer (see figure1) to disable ALT, ESC, and WIN keys. Disabling the keys in InTouch 7.x required the installation of a keyboard
filter driver that was sensitive to changes in the OS and versions of Windows and sometimes conflicted with other applications such as PC
Anywhere. InTouch 8.0 has the Disable Key options disabled since a new script function called EnableDisableKeys() provides the functionality
to enable/disable the ALT, TAB, or WIN keys in runtime. This function, combined with WindowViewer settings to "Always Maximize" and hide
Menu bar and Windows control options will effectively secure the operating system. Another common practice to hide/show the menu bar in View
is to create a popup style window with its X,Y coordinates set to 0,-40 with a height of 40 pixels and a width equal to the display resolution (i.e.
1024)

mhtml:http://esupport.wonderware.ch/Home/Downloads/Wonderware/Tech Notes/InTouc... 07.12.2012

Security Features in Intouch 8.x Page 2 of 6

Figure 1. WindowViewer properties set in WindowMaker (Special/Configure/WindowViewer)

back to Security Features in InTouch 8.x

Auditing
Keeping track of what the operators do doesn't make an InTouch application more secure but it is an important aspect of security in InTouch.
When users and groups (or roles) are created to be used in an InTouch application, audit trails can tie operators to all alarms/events that occur
during the time that they are logged onto the system. Alarms and events are very similar in nature; a condition has occurred and should be
logged. The difference between the two is that events, unlike alarms, do not require an acknowledgment.

InTouch 7.x included the Distributed Alarm Object (DAO), a grid-like control that lists alarms and events by querying them from memory or from
a database. Starting with InTouch 7.1, alarms and events could be logged to a Microsoft SQL Server or MSDE database management system for
later retrieval.

InTouch 8.0 introduced an alarm object based on ActiveX technologies that also provides easy access to summary and history of alarms. It
exposes a number of properties and methods that simplify configuration both during development and runtime.

Figure 2. Distributed Alarm Object and the New AlarmViewer ActiveX control

back to Security Features in InTouch 8.x

Securing the Application

mhtml:http://esupport.wonderware.ch/Home/Downloads/Wonderware/Tech Notes/InTouc... 07.12.2012

Security Features in Intouch 8.x Page 3 of 6

InTouch provides a number of System tags and script functions that allow InTouch programmers to configure security for the application.
Applying security to your application is optional. The default security setting for InTouch applications is "None." However, by applying security to
your application, you can control specific functions that an operator is allowed to perform by linking those functions to internal tagnames. Once a
user is validated and logged on to the InTouch application, the $Operator and $AccessLevel system tags contain information about the user and
its access level.

To log on to an InTouch application, users can call click on Special/Security/Logon, call a script function to display a logon dialog box (standard),
or log on via a custom logon window.

Note: See the InTouch Reference Guide for a complete documentation on System Tags and script functions

$AccessLevel is the tag that is normally used to secure InTouch applications; it has been in InTouch 7.x and continues to be in InTouch 8 the
main system tag to modify what a user ($Operator) can and cannot do during runtime. For example, to disable a pushbutton just set a
"disable" (or "Visibility") type link to it with an expression like "$AccessLevel < 9000"

Prior to InTouch 8.0, users were authenticated against a binary file (password.bin) that contains information about users, passwords, and access
levels. That is now known as InTouch authentication. In addition to that mode, InTouch programmers can use operating system authentication,
ArchestrA authentication, or no authentication at all.

back to Security Features in InTouch 8.x

InTouch Authentication

The commands used to establish security on an application are located under Security on the Special menu in both WindowMaker and
WindowViewer. The security commands are used to log on and off the application, change passwords and to configure the list of valid user
names, passwords and access levels.

Security is based on the concept of the operator "logging on" to the application, typing his/her name and password. You must configure a user
name, password, and access level for each operator. There is no association between Microsoft operating system security and InTouch security.

When you create a new application, by default, the user name is set to "Administrator" with an access level of 9999 (which allows access to all
security commands). After you add a new user name to the security list and restart WindowMaker or WindowViewer, the default user name is
automatically reset to "None" with an access level of "0" (which prevents access to the Configure Users command in both WindowMaker and
WindowViewer). However, the Administrator account and password remain and can still be used.

You can also link a User Input - Discrete button to the $ConfigureUsers tagname to allow an authorized operator with an access level of equal
to or greater than 9000 to access the Configure Users dialog box to edit the security user name list. When the operator clicks the button, the
value of the $ConfigureUsers tagname is set to 1 and the Configure Users dialog box appears. When the operator closes the dialog box, the
system resets the value to 0. (This is a system discrete tagname intended for write operation only.)

If the Special menu will not be displayed in WindowViewer, you can create a custom logon window (see below) that the operator uses to log on
to the application. You can also link a User Input - Discrete button to the $ChangePassword tagname to show the Change Password dialog box
and allow the operator to change his/her password. When the operator clicks the button, the value of the $ChangePassword tagname is set to
1 and the Change Password dialog box appears. When the operator closes the dialog box, the system resets the value to 0. (This is a system
discrete tagname intended for write operation only.)

The None and Administrator names are reserved and only the password of the Administrator may be changed. Once you have configured user
names for your application, you should change the Administrator name's password since it will more than likely become commonly known to
most users of the system. The Administrator default access level (9999) is the highest and allows access to everything including the Configure
Users menu command.

OS Authentication

With OS authentication, users and groups in the local machine or the domain are assigned different access levels via the AddPermission()
function. The access level given to groups and users has nothing to do with the rights that such groups and users have on the local machine or
the domain. For example, nothing prevents you from giving the Guests group an access level of 9999 or the Administrators group an access
level of 100.

OS Users can be part of one or more groups; if multiple access levels are set to multiple groups, a user logging on to the InTouch application will
get the highest access level assigned to any of the groups he/she is part of.

ArchestrA Authentication

Users and roles can be verified against the ArchestrA security model if the InTouch application is getting its values from the Industrial Application
Server. When ArchestrA authentication is to be used, the Galaxy itself should also be set for ArchestrA authentication.

A galaxy can be configured for different security models; None(default), Galaxy, OS User Based, or OS Group Based. The Galaxy mode uses
local galaxy configuration to authenticate the user against the Galaxy database.

No Authentication

This is the default mode for new InTouch 8.0 applications. When no authentication is used, $Operator and $OperatorName are both set to
"None" and $AccessLevel is 9999. The Special/Security options in the menu bar in View are all disabled. Also, the binary file password.bin does is
not included in the application directory.

Creating a Custom Security Log on Window

mhtml:http://esupport.wonderware.ch/Home/Downloads/Wonderware/Tech Notes/InTouc... 07.12.2012

Security Features in Intouch 8.x Page 4 of 6

$OperatorDomainEntered, $OperatorEntered, and $PasswordEntered are the three tags to be used in case a custom logon dialog box is
required. Just create a popup-type window and set user touch links (user input string) to these tags. If the provided credentials are validated,
$Operator, $AccessLevel, $OperatorDomain will update accordingly. Link the $OperatorEntered, $PasswordEntered and
$OperatorDomainEntered system tagnames to user input objects or use them in a QuickScript to set the "User Name," "Password," and
Domain Name (these are internal message type tagnames that are intended for write operation only.) The $OperatorDomainEntered is
required only if the security mode is operating system-based; make sure it is set to blank for the ArchestrA security mode. Also, if the security
mode is operating system-based and the $OperatorDomainEntered is null, it is treated as pointing to local machine.

After an operator logs on to the application, access to any protected function will be granted upon verification of the operator's password and
access level against the value specified for the internal security tagname will be linked to the function.

System Tags in InTouch 8.x Related to Security

The following system tags are available to deal with security (those marked with * are new to InTouch 8.0)

Tagname Type Valid Values Access

$AccessLevel System Integer 0-9999 Read Only
$ChangePassword System Discrete 1 or 0 Read Write
$ConfigureUsers System Discrete 1 or 0 Read Write
$InactivityTimeout System Discrete 1 or 0 Read Only
$InactivityWarning System Discrete 1 or 0 Read Only
$Operator System Message 16-characters max Read Only
$OperatorName* System Message 131-characters max Read Only
$OperatorDomain* System Message 16-characters max Read Write
$OperatorDomainEntered* System Message 16-characters max Read Write
$OperatorEntered System Message 16-characters max Read Write
$PasswordEntered System Message 16-characters max Read Write
$VerifiedUserName* System Message 16-characters max Read Only

Creating Authority Check Functionality with OS or ArchestrA Security

In regulated industries, there are instances where a change in a value must be authorized by a person other than the operator that is logged in.
This function allows you to implement a "Done by/Checked by" logic in the application. The InvisibleVerifyCredentials() function combined
with the $VerifiedUserName can be used to verify the credentials of a user other than the currently logged on user. $VerifiedUserName
contains the verified user's full name if the call to InvisibleVerifyCredentials() is successful; the return of InvisibleVerifyCredentials() is
the access level set for the user that was verified. If the call fails then $VerifiedUserName tag will be set to null and the return value is -1.

Configuring Inactivity to Automatically Log Off

You can configure your application to automatically log off the operator when there has been no activity for a specified period of time by using
the warning and time out settings.

On the Special menu, point to Configure and then click WindowViewer or in the Application Explorer under Configure, double-click
WindowViewer. The WindowViewer Properties dialog box appears with the General properties sheet active. In the Application Explorer, you can
also right-click WindowViewer and then click Open.

In the Warning box, type the number of seconds that can elapse with no operator activity (mouse clicks or keystrokes) before the system
discrete tagname $InactivityWarning is set to 1 (True). When the Inactivity Warning is set to zero, there will not be an inactivity warning.
Tip: You can use $InactivityWarning in a Condition QuickScript to show a window warning the operator that he/she is about to be logged off
the system. If the operator clicks the mouse, presses a key, or performs an action using any other pointing device before the specified time-out
elapses, they are not logged off. $InactivityWarning and the timer are reset.

In the Timeout box, type the number of seconds that can elapse with no operator activity (mouse clicks, keystrokes, and so on) before the
system discrete tagname $InactivityTimeout is set to 1 (True). When $InactivityTimeout is true, the system equates the logged on operator
name to the reserved name "None" and sets the security tagname, $AccessLevel, to 0.
Tip: You can use $InactivityTimeout in a Condition QuickScript to show a window telling the operator that he/she has been logged off the
application.

You can use the Timeout feature independently of the Warning feature. However, the Timeout value must be greater than the Warning value for
proper use of both system tagnames.

For example, set $InactivityWarning to 30 and $InactivityTimeout to 45. The operator will be logged off 15 seconds after the
$InactivityWarning variable is set to 1.

Script Functions in InTouch 8.x Related to Security

AddPermission()

Sets the Access Level to a particular group or user in the specified domain

Syntax

mhtml:http://esupport.wonderware.ch/Home/Downloads/Wonderware/Tech Notes/InTouc... 07.12.2012

Security Features in Intouch 8.x Page 5 of 6

Remarks

Valid for OS security mode only. An attempt is made to reach the account Account located on domain Domain. If successful, a TRUE is returned and the access
level AccessLevel is assigned to the account in the internal records in InTouch for use during authorization when a user logs on. In all other cases, a FALSE is
returned.

The "Group" parameter can be any valid group or user defined in the specified "Domain" parameter. It is also important to note that the access level set for
each group does not have anything to do with the rights for each group. For example, nothing prevents you from giving the Guests group an access level of
9999 or the Administrators group an access level of 100.

AttemptInvisibleLogon()

Attempts to logon to InTouch using the supplied credentials.

Syntax

Remarks

An attempt is made to logon to InTouch using the supplied credentials (Domain is ignored if the security mode is not OS ). If the logon attempt succeeds, then
TRUE is returned and the system tags $OperatorDomain, $OperatorName, $AccessLevel and $Operator are updated accordingly. If the Logon attempt fails,
then FALSE is returned and the currently logged on user ( if any ) continues to be the current user.

InvisibleVerifyCredentials()

Checks to verify the credentials of the given user without logging the user on to InTouch.

Syntax

Remarks

If the supplied combination of user, password and domain are valid then the corresponding access level associated with the user is returned as an integer, in
all other cases -1 is returned. This call does not change the currently logged on user.

Set the Domain argument to blank if the Authentication Mode is "ArchestrA"

IsAssignedRole()

Used to find out if current logged on user has the indicated role.

Syntax

Remarks

Valid for AppServer security mode only and applies to the currently logged on user. If a user is currently logged on and if he has the role RoleName assigned to
him in Galaxy IDE, then a TRUE is returned. In all other cases a FALSE is returned.

Logoff()

Logs the user off of InTouch.

PostLogonDialog()

Brings up the InTouch Logon Dialog and returns TRUE.

Syntax

Remarks

Brings up the InTouch Logon Dialog and returns TRUE.

QueryGroupMembership()

Syntax

Remarks

mhtml:http://esupport.wonderware.ch/Home/Downloads/Wonderware/Tech Notes/InTouc... 07.12.2012

Security Features in Intouch 8.x Page 6 of 6

Valid for OS security mode only and applies to the currently logged on user. If a user is currently logged on and if he is part of the group Group which is
located on the domain Domain then a TRUE is returned and in all other cases a FALSE is returned.

Note Please refer to the Security Features Demo Application for InTouch 8.x for a demonstration of the above features.

F. Gonzalez

Tech Notes are published occasionally by Wonderware Technical Support. Publisher: Invensys Systems, Inc., 26561 Rancho Parkway South, Lake Forest, CA 92630. There is also
technical information on our software products at www.wonderware.com support mmi

For technical support questions, send an e-mail to support wonderware.com.

back to top

©2012 Invensys Systems, Inc. All rights reserved. No part of the material protected by this copyright may be reproduced or utilized in any form or by any means, electronic or
mechanical, including photocopying, recording, broadcasting, or by anyinformation storage and retrieval system, without permission in writing from Invensys Systems, Inc. Terms
of Use.

mhtml:http://esupport.wonderware.ch/Home/Downloads/Wonderware/Tech Notes/InTouc... 07.12.2012