Page Comparison

The Tsecurity system provides authentication and authorization services to custom applications running on the Windows platform. It extends the native authentication services provided by Windows to allow these custom applications to authenticate users defined either on the local machine or in the Active Directory (AD). In addition, it manages lists of users to be provided privileges to these applications and exposes methods for access to these lists.

...

Expand

title	User Authentication Flow Chart

Following is a flow chart of the sequence of events during authentication:

Further information about the various timeout periods described in the above flow chart can be found in the Tsecurity Service Configuration [LINK]section of this manual.

Expand

title	Tsecurity Applications

Simply put, a Tsecurity Application is merely the definition of the associations between various domain members and the special subset of privileges that they are given. The term application in this sense does not necessarily refer to a single executable program; although it may be the case that the Tsecurity Application only governs a single executable program, it is better to think of a Tsecurity Application more generally as a set of rules used by a piece of software to control access to itself.

As an example, consider a group of custom-built screens for a rolling mill control system. The system owner would want his mill operators to be able to control the schedule through the Preset screen. Maintenance personnel would also be able to adjust the schedule, but should additionally be able to run various tests from the Diagnostics screen. And above all, engineers should be given rights to both the Preset and Diagnostic screens, as well as being able to adjust any system tuning parameters from the Tuning screen.

Following are definitions of some key terms used within a Tsecurity Application:

A privilege is a single right that can be given to an application user.
A domain member is refers to either a user defined on a domain or a group of users defined on a domain. A domain can be either the local domain or an Active Directory. The names of domain members are specified in a domain\username format.
An application privilege class, or more simply a privilege class, is the combination of a group of privileges with a group of domain members. Each of the domain members contained in a privilege class are given each of the privileges associated with that privilege class. A privilege class exists only within the definition of a Tsecurity Application.

Continuing the rolling mill example from above:

In order to manage security for the rolling mill applications, the system owner would define a Tsecurity Application named RollingMillScreens. Within this application there would be three privilege classes defined: Operators, Maintenance, and Engineers. In addition, there would be three privileges defined: ModifyPreset, RunDiagnostics, and TuneSystem. Privileges would be assigned to application privilege classes as follows:

Application Privilege Class	Privileges Granted to Application Privilege Class
Operators	ModifyPreset
Maintenance	ModifyPreset, RunDiagnostics
Engineers	ModifyPreset, RunDiagnostics, TuneSystem

Once the privilege classes and associated privileges have been defined, the system owner would need to add domain members to each of the appropriate privilege classes. For instance, Joe the Operator would be added to the list of members of the Operators group, Jane the Maintenance Tech would be added to the list of members of the Maintenance group, and Bob the Engineer would be added to the list of members of the Engineers group.

Alternatively, if there is an Active Directory group already defined that contains of all engineers for the rolling mill, this AD group could be added to the Engineers application privilege class in the RollingMillScreens Tsecurity application and any domain user contained in that group in the Active Directory would be given all three of the above rights specified for the Engineers application privilege class.

This complete set of information, including the privileges, application privilege classes, domain members, and each of their interrelationships, comprises a Tsecurity Application. The definition for each Tsecurity Application is stored on the host in a separate XML file called an Application Security Configuration File (ASCF). These are described in detail in Application Security Configuration Files [LINK].

Expand

title	Securing Software

It is important to point out that under the Tsecurity framework the Tsecurity system itself is not responsible for preventing unwanted access to resources; rather it is a tool that allows other custom software to quickly, easily, and reliably determine if a given user should be provided access to some resource within that custom software. Given that a Tsecurity Application is merely a definition of user access rules within a set of software, it is important to realize that the software itself is ultimately responsible for managing its own the security.

Generally speaking, a custom Tsecurity client would use Tsecurity in the following fashion:

The custom client queries the user for his username, domain, and password.
The client makes a call into the Tsecurity system to authenticate this username, domain, and password.
The Tsecurity system responds, indicating whether or not the password is correct.
If the password is not correct, the client denies the user access and requires a valid login. If the password is correct, the client then makes a second call to the Tsecurity system to retrieve the list of privileges provided to this user within a given Tsecurity Application. This Tsecurity Application must already be defined on the Tsecurity system.
The Tsecurity system then responds with either the appropriate list of privileges or an indication that the supplied user does not have any rights to the Tsecurity Application.
The client then uses the returned list of user privileges to modify its behavior accordingly. For instance, it may enable or disable various displays and inputs depending on whether or not the user has rights to those resources.

...

Expand

title	Security Access Keys

Within the Tsecurity Application environment, each individual privilege is assigned to a single bit within a 64-bit integer. Consequently, the entire set of privileges granted to a user can be represented as a single 64-bit integer corresponding to the bitwise-OR of each of the individual privileges assigned to that user. This 64-bit integer is called the Security Access Key (SAK) for that user.

In the rolling mill example provided above, for instance, the privileges may be assigned bits as follows:

Privilege	Associated Bitmask
ModifyPreset	0x0000000000000001
RunDiagnostics	0x0000000000000002
TuneSystem	0x0000000000000004

The SAK for each privilege class would therefore be the bitwise-OR of the bitmasks corresponding to each of the privileges granted to that privilege class. As a result, the SAK for each privilege class would be as follows:

Application Privilege Class	Privileges Granted to Application Privilege Class	Privilege Class SAK
Operators	ModifyPreset	0x0000000000000001
Maintenance	ModifyPreset, RunDiagnostics	0x0000000000000003
Engineers	ModifyPreset, RunDiagnostics, TuneSystem	0x0000000000000007

The highest-order bit of the SAK is reserved to indicate an error. Consequently, there is a maximum of 63 distinct privileges that can be specified in a Tsecurity Application

Expand

title	Evaluating User SAKs

Generally speaking, when a Tsecurity client wishes to retrieve the SAK for a specified user within a given Tsecurity Application, the Tsecurity host must perform the following steps:

Find all privilege classes of which the specified user is a member.
Bitwise-OR the SAKs specified for each of these privilege classes into a composite 64-bit SAK for the user.
Return this composite SAK and the associated privilege names to the calling client.

In the simplest Tsecurity Applications, where all of the domain members of all of the privilege classes listed in the Tsecurity Application definition are actual domain users, the first step above is quite simple. In this case all application privilege class memberships are explicitly specified in the Tsecurity Application definition.

Using the above example, privilege class membership for a Tsecurity Application may be specified as follows:

Application Privilege Class	Application Privilege Class Members
Operators	MyDomain\Joe the Operator
Maintenance	MyDomain\Jane the Maintenance Tech
Engineers	MyDomain\Bob the Engineer

Consequently, when a Tsecurity client requests the SAK for Joe the Operator, the Tsecurity host can very quickly determine that Joe is only a member of the Operators application privilege class and return the appropriate SAK.

However, consider a more complicated Tsecurity Application, which in addition to explicitly specifying Windows users as members of its application privilege classes, also specifies an entire Active Directory user group as a member of one of its application privilege classes. In this case, in order to evaluate application privilege class membership for a specified domain user, the Tsecurity host must query the Active Directory to determine group membership within the Active Directory. Depending on network connectivity and availability, this query may be relatively quick (~1 second) or it may take quite a while to complete or time out.

Following from the above example, suppose all domain engineers were also specified as members of the Engineers application privilege class:

Application Privilege Class	Application Privilege Class Members
Operators	MyDomain\Joe the Operator
Maintenance	MyDomain\Jane the Maintenance Tech
Engineers	MyDomain\Bob the Engineer, MyDomain\Domain Engineers Group

In this case, when a Tsecurity client requests the SAK for Joe the Operator, the Tsecurity host knows immediately that Joe is a member of the Operators application privilege class, but the Tsecurity host must also query the Active Directory to determine if Joe is also a member of the MyDomain\DomainEngineersGroup domain user group.

Because specifying domain groups in a Tsecurity Application definition will significantly slow SAK retrieval for all users for that Tsecurity Application, a special flag is provided for each user listed in a Tsecurity Application definition to specify how his SAK should be calculated. This flag is defined as:

ExplicitMembershipOnly = True (Default)
The user’s SAK should be calculated based only on the application privilege class memberships explicitly specified by the Tsecurity Application definition.

In the example above, if this flag is set true for Joe the Operator and a request is made to retrieve his SAK, the Tsecurity host would only indicate that he is a member of the Operators application privilege class.

ExplicitMembershipOnly = False
The Active Directory should be queried to find all domain group memberships before determining membership for the various application privilege classes.

In the example above, if this flag is set false for Joe the Operator and a request is made to retrieve his SAK, the Tsecurity host would take the time to query the Active Directory to determine if he is also a member of the MyDomain\Domain Engineers Group before calculating his SAK.

...

Expand

title	Overview

The Tsecurity system comes in two different installation packages. First, Tsecurity is included as an integrated piece of a full TSENTRY installation. Alternatively, Tsecurity can be installed as a standalone package. However, both the standalone version of Tsecurity and the integrated version installed with TSENTRY cannot both be installed on the same system at the same time. If a host must be converted from a TSENTRY system to a plain Tsecurity host, or vice versa, the original software should first be uninstalled before installing the new version. In either case, the latest installation files can be obtained from the support section of the TSENTRY web site: http://www.tsentry.com.

Once Tsecurity has been installed (either as part of a TSENTRY installation or as a standalone package) there are two additional steps that must be completed before the system will be fully operational:

Use the TsecurityCfg [LINK] application to setup and configure the Tsecurity service.
Use the ASCFEditor [LINK] to create and configure a Tsecurity application.

...

Expand

title	Tsecurity Service

The installation process registers the Tsecurity service on the local host. This service is configured to automatically start with Windows and executes under the Tsentry account, which is a local account on the Tsecurity host also created by the installation process.

This service is described in more detail in the Tsecurity Service [LINK] section.

Expand

title	Registry Changes

The following registry changes are made by the installation process:

Registry Key

Type

Description

HKLM\SOFTWARE\

TelePro\Tsecurity\

Directory

REG_SZ

Defines installation path of Tsecurity system.

HKLM\SOFTWARE\

TelePro\Tsecurity\

Version

REG_SZ

Defines latest installed version of Tsecurity system.

HKLM\SOFTWARE\

TelePro\Tsecurity\

InstallPackage

REG_SZ

Defines type of installation. Possible values are "Tsentry" (indicating an installation as a part of Tsentry) or "Tsecurity" (indicating a standalone Tsecurity installation).

...

Expand

title	Configuration

The Tsecurity service is fully configurable via a configuration file named Tsecurity.exe.config located in the same directory as the Tsecurity service binary executable. This is an XML file consistent with the application config file format specified by Microsoft .NET applications.

For detailed information about the configuration of the Tsecurity service, refer to the TsecurityCfg [LINK] section of this manual.

Expand

title	Sample Tsecurity.exe.config File

Following is a sample Tsecurity.config file:

Code Block

<?xml version="1.0" encoding="Windows-1252"?>
<!-- Configuration file for Tsecurity Service -->
<configuration>
  
  <configSections>
    <!-- Do not edit this section -->
    <section name="TsecuritySettings"
     type="TPRI.Tsecurity.TsecuritySettingsSectionHandler,TPRI.Tsecurity" />
    <section name="TsecurityDomains"
     type="TPRI.Tsecurity.TsecurityDomainsSectionHandler,TPRI.Tsecurity" />
  </configSections>
    
  <appSettings>
  </appSettings>

  <TsecuritySettings>

    <!-- ASCF folder path -->
    <add key="ASCFFolder" value="D:\tpriNtRt\Tsecurity\ASCF" />

    <!-- Port number for TCP listener -->
    <add key="PortNumber" value="8080" />

    <!-- Debug level for Event logging -->
    <add key="DebugLevel" value="30" />

    <!-- Maximum time (in milliseconds) to wait before timing out
         authentication requests -->
    <add key="AuthenticationTimeout" value="20000" />

    <!-- Amount of time (in milliseconds) to delay before deferring
         authentication requests to the info stored in the user cache -->
    <add key="UserCacheDelayPeriod" value="0" />

    <!-- Amount of time (in minutes) after user info in the
         cache file has been verified before it should be
         verified again -->
    <add key="UserCacheVerifiedPeriod" value="10" />

    <!-- Expire time (in minutes) for user info in the cache file -->
    <add key="UserCacheExpiredPeriod" value="1440" />

    <!-- Wait time (in milliseconds) to allow executing directory 
         operations to finish before timing out pending operations -->
    <add key="DirectoryMutexTimeout" value="30000" />

    <!-- Browse user ID and password for specified domains -->
    <browseUser Domain="MYDOMAIN1" UserID="MYDOMAIN1\MyUser1"
     Password="44913F40A6806B9719B52B670731704685056EE4B60B8598" />

  </TsecuritySettings>
   
  <TsecurityDomains>
    <!-- If enabled, always include any domains listed in the -->
    <!-- 'AlwaysInclude' section below in the list of domains -->
    <!-- presented to the user.  The first domain marked with -->
    <!-- 'default=true', if any, will be the one initially    -->
    <!-- selected for the user.                               -->
    <AlwaysInclude enable="True">
      <domain name="DOMAIN1" default="True" />
      <domain name="DOMAIN2" />
    </AlwaysInclude>

    <!-- If enabled, filter the list of available domains so that    -->
    <!-- it includes only those listed in the 'FilterAvailable'      -->
    <!-- section (in addition to the 'AlwaysInclude' domains above). -->
    <!-- The first domain marked with 'default=true', if any, AND    -->
    <!-- found in the list of available domains, will be the one     -->
    <!-- initially selected for the user (assuming no domain in the  -->
    <!-- 'AlwaysInclude' list is also marked as the default).        -->
    <FilterAvailable enable="False">
      <domain name="DOMAIN2" default="True" />
      <domain name="DOMAIN5" />
    </FilterAvailable>
  </TsecurityDomains>

</configuration>

...

Expand

title	Browse Users

The Browse Users page is used to specify credentials that can be used to browse the active directory structure. These users are only required in certain situations as described below.

The Under normal circumstances, when a client wishes to retrieve the SAK for a given user from a Tsecurity host the client must provide the user’s password. This password is required if all of the following circumstances are true:

Domain user groups are listed as members of one or more of the application privilege classes for the Tsecurity Applications.
The user is either not explicitly listed in the Tsecurity application configuration or the user is defined with the ExplicitMembershipOnly parameter set to false.
The user is not a local user defined on the Tsecurity host system.

In this situation the Tsecurity host must query the Active Directory to retrieve the list of groups in which the user is either explicitly or implicitly (via nested groups) a member. In order to gain access to the Active Directory the Tsecurity host must have a valid set of credentials. Hence, the Tsecurity host uses the credentials of the user himself to gain access.

However, there are cases where the client wishes to retrieve the SAK for a user for whom it does not have the password. In this case the client passes an invalid reference (NULL in C/C++ or Nothing in VB.NET) for the password. Still, though, the Tsecurity host must have a valid set of credentials to use while querying the Active Directory. Consequently, the Tsecurity host must be provided a set of credentials for a browse user in each of the domains in which the host must locate users without a password passed from the client. Only one browse user can be specified for each domain, though a single browse user can be specified for multiple domains. The browse user need not actually be a member of the domain, though he must have browse rights to that domain.

The browse user credentials are stored in the <TsecuritySettings> section of the Tsecurity.exe.config file. Passwords are encrypted so that they are not stored in plain text.

Expand

title	Tsecurity Administrators

The Tsecurity Administrators page is used to define the list of Tsecurity Administrators for the Tsecurity host.

As described in the Managing Security Applications [LINK] section, a Tsecurity Administrator has full control of the Tsecurity system. Only a Tsecurity Administrator has the ability to create and destroy Tsecurity Applications and is responsible for specifying the owners of individual Tsecurity Applications.

The name of each Tsecurity Administrator is listed as an owner of the special Tsecurity Tsecurity Application, which is stored in the Tsecurity.xml file in the ASCF folder specified on the System Parameters page.

...

Expand

title	A-Retrieving Security Access Keys and the Authenticate User Form

Once a domain member and an application privilege class have been associated with one another, the association can be tested by right-clicking on the user name and choosing the Get Security Access Key menu item. If the user object corresponds to a real user account (Object Type is specified as User), and that user is configured to use explicit membership specified in the ASCF only when calculating his SAK (the Use Explicit Membership Only flag is set to True), the SAK can be calculated directly.

If the selected user object corresponds to a real user account, but rather than only using explicit membership in the ASCF, it is configured to use implicit membership in domain groups when calculating his SAK (i.e., the Use Explicit Membership Only flag is set to False), then the Authenticate User form will be displayed to query how the SAK should be calculated.

In this case, the password for this user must be supplied to access the group membership in the directory. This is because the Tsecurity host does not necessarily have the credentials necessary to browse the directory for this information. Alternatively, if the Do Not Supply Password box is checked, the Tsecurity host will be instructed to check Active Directory group membership using the any available domain browse accounts that it has been configured to use. Refer to the [LINK] Tsecurity Service Configuration section for more information about configuring the Tsecurity host to use domain browse accounts.

In all other circumstances choosing the Get Security Access Key menu item allows the SAK to be retrieved for any arbitrary user. In this situation the Authenticate User form is displayed to retrieve the user name, password, and domain.

The above will be the case when the selected user object corresponds to a user group (Object Type is specified as User). In this case a specific user for whom the SAK should be calculated has not been specified, and so the Authenticate User form must be displayed to retrieve this information.

...

Versions Compared

Old Version 8

New Version Current

Key