Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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
titleUser 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
titleTsecurity 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
titleSecuring 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:

  1. The custom client queries the user for his username, domain, and password.

  2. The client makes a call into the Tsecurity system to authenticate this username, domain, and password.

  3. The Tsecurity system responds, indicating whether or not the password is correct.

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

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

  6. 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
titleOverview

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:

  1. Use the TsecurityCfg [LINK] application to setup and configure the Tsecurity service.

  2. Use the ASCFEditor [LINK] to create and configure a Tsecurity application.

...

Expand
titleTsecurity 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
titleRegistry 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
titleConfiguration

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
titleSample 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
titleTsecurity 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
titleASCF Editor Screen

The ASCF Editor screen displays all Tsecurity Applications owned by the currently logged in user (or all Tsecurity Applications configured on the host, in the case of the Tsecurity Administrator). 

The display uses a tree format to present all of the configuration parameters for each of the Tsecurity Applications.  This format both provides the user with a complete view of all of the Tsecurity Applications as well as allowing him to drill down to any configuration parameter he wishes to view. 

Effectively this is simply a visual front end for displaying and modifying data and parameters contained in Application Security Configuration Files (ASCF); for more information about these parameters refer to the Application Security Configuration Files section.

Each of the root nodes in the tree corresponds to an individual Tsecurity Application (and corresponding ASCF) owned by the current user.  Beneath each root ASCF node are three subnodes:

Subnode

Description

Application Owners

Lists each of the owners of this Tsecurity Application.

Application Privileges

Lists each of the privileges defined by this Tsecurity Application.

Application Privilege Classes

Lists each of the application privilege classes defined by this Tsecurity Application.  Note that these privilege classes exist only within the Tsecurity Application itself; any resemblance in name to actual domain groups listed in the Active Directory is purely coincidental.

Domain Members

Lists each of the domain members (domain user accounts and domain user groups) referenced within this Tsecurity Application.  In this case, each of these items must correspond to a real user account or user group defined either on the local Tsecurity host or in the Active Directory.

In addition, the tree indicates all cross-links between objects in the Tsecurity Application configuration.  For instance, if a user is associated with a particular application privilege class, that user will be listed under the Domain Members for the application privilege class, and also the application privilege class will be listed under the Application Privilege Class Memberships for the domain member. 

Info

“A-” as

Expand

Modifying a Tsecurity Application Configuration

Most simple changes to a configuration, such as changing the Explicit SAK associated with a given application privilege class, can be made simply by left-clicking on a parameter value.  The parameter value itself will become an editable field, which the user can modify appropriately.

More complicated configuration changes, such as configuring a user for a Tsecurity Application, as well as many more options, are available by right-clicking at various locations within the display.  Depending on where the user right-clicks, a context-dependent menu is presented with a variety of options.

Each of the available menu options is described in the following table.

Menu Item

Description

New Application

Create a new Tsecurity Application.  This menu item is only available to Tsecurity Administrators.

Save Application

Save a Tsecurity Application configuration to the Tsecurity host.  If a Tsecurity Application has been changed but not yet saved to the host, its name will be marked with an asterisk (*).

Delete Application

Permanently delete the highlighted Tsecurity Application.  This menu item is only available to Tsecurity Administrators.

Add Owner

Add an owner to the highlighted Tsecurity Application.  Selecting this item will invoke the Find and Select User or Group form for choosing a new owner from a directory.  This menu item is only available to Tsecurity Administrators.

Remove Owner

Remove the selected owner from the Tsecurity Application.  This menu item is only available to Tsecurity Administrators.

Change Owner

Change the selected owner to another individual.  Selecting this item will invoke the Find and Select User or Group form for choosing an alternate owner from a directory.  This menu item is only available to Tsecurity Administrators.

Edit Privileges

Edit the list of named privileges defined in the highlighted Tsecurity Application.

New Privilege Class

Create a new application privilege class in the highlighted Tsecurity Application.

Delete Privilege Class

Delete the selected application privilege class from the Tsecurity Application.

Select Privileges for Privilege Class

Add and/or remove named privileges from the selected application privilege class.  Selecting this item will invoke the Select Membership form for selecting membership.

Select Domain Members for Privilege Class

Add and/or remove domain members (users and user groups) from the selected application privilege class.  Selecting this item will invoke the Select Membership form for selecting membership.

Remove Domain Member from Privilege Class

Remove the selected domain member from the current application privilege class.

Add Domain Member

Add a domain member to the Tsecurity Application.  Selecting this item will invoke the Find and Select User or Group form for choosing a user or user group from a directory.

Remove Domain Member

Remove the selected domain member from the Tsecurity Application.

Change Domain Member

Change the selected domain member to a different domain member.  Selecting this item will invoke the Find and Select User or Group form for choosing an alternate user or user group from a directory.

Select Privilege Classes for Domain Member

Add and/or remove membership in the available application privilege classes for the selected domain member.  Selecting this item will invoke the Select Membership form for selecting membership.

Remove Privilege Class from Domain Member

Remove the selected application privilege class membership from the current domain member.

Get Security Access Key

Retrieve the SAK for the selected user or user group.  If a user name and/or password is required to retrieve the SAK (i.e. the selected item is a user for whom Use Explicit Membership Only is false, or the selected item is a user group), the Authenticate User form will be displayed.

Lookup Full User Names in Directory

Search through the directory to try to find full user names for any domain members.

Generate User Access Report

Generate a text report listing each of the domain members explicitly specified in each of the Tsecurity Applications.  For each domain member the report will list the member’s privilege classes, his composite security access key, and the named privileges granted to that member.

Refresh Application

Refresh the current Tsecurity Application from the host.  This will discard any unsaved changes to the highlighted Tsecurity Application.

Refresh Applications

Refresh all Tsecurity Applications from the host.  This will discard any unsaved changes to any Tsecurity Applications.


Find and Select User or Group Form

The Find and Select User or Group form is used to help locate directory objects for adding user accounts and user groups to Tsecurity Applications.  This form is analogous to the native tools provided by Windows for managing users and groups within its own security infrastructure.

The very top portion of the form provides an entry box for the ID and full name of the desired directory object and a set of options to define how this object should be treated, i.e. as a directory user or as a user group defined on the directory.  Once the appropriate choices have been specified, the Accept button can be pressed to make the changes to the application configuration and close the form.  Alternatively, the Cancel button can be pressed to cancel any choices and leave the configuration unchanged.

 

In order to help eliminate typing mistakes, the middle section of this form provides a set of controls for searching for existing users and user groups either on the local Tsecurity host or in the Active Directory.  This tool is used as follows:

  1. First, in the Credentials for Directory Access box the user must supply credentials for searching through the directory.  These credentials must correspond to a user with browse rights for the desired search domain.

  2. Next, in the Search for Users and Groups box the user must specify the domain to be searched.  This is a drop-down display of all of the domains to which the Tsecurity host has access.  In addition, a search name filter can be specified to help speed the search results; only users and groups that begin with this string will be returned.  A blank search name filter will return all users and groups found in the specified domain.  Note that searching without a filter in very large domains can be very time consuming, so specifying a search filter is highly recommended.

  3. Finally, the user should click the Find Now button to initiate a search.  If the search takes too long the user may click the Stop button to cancel the search and reconfigure a new one.

Below the search configuration section is a list box to display the results of the search.  Once the search has completed the results will be displayed here. 

Single clicking on an entry in the results list will display the selection at the top of the form, including the name of the user account or user group and the selection as to whether this object should be treated as a user account or a user group.  The user can then click on the Accept button to make the selection official and close the form.  Alternatively, simply double clicking on an entry in the results list will automatically accept the selection and similarly close the form.

Note that if the Find and Select User or Group form was invoked to choose an owner for a Tsecurity Application, only user accounts will be displayed in the search results and the option to identify the selected object as a user group will be disabled.  This is because Tsecurity Application owners must be individual user accounts; they cannot be user groups.


Adding Privileges to Application Privilege Classes and Vice Versa

Once an application security group has been created in a Tsecurity Application, and a privilege has been added to the same Tsecurity Application, an association can be made between the two.  Right-clicking on an application privilege class presents the Select Privileges for Privilege Class option in the displayed context-dependent menu.  Choosing this option invokes the Select Membership form, which allows the user to make the desired selections simply by checking and unchecking memberships as desired.

Pressing the Accept button makes any changes to the memberships official, while pressing the Cancel button cancels any changes made within this form.

Alternatively, a privilege can be associated with an application privilege class simply by dragging and dropping one object over the other within the tree view of the Tsecurity Application: left-click-and-hold on the privilege name and move the mouse up over the desired application privilege class.  Releasing the left mouse button will drop the privilege into the application privilege class so that it is now listed as one of the Privileges for that application privilege class. 


Adding Domain Members to Application Privilege Classes and Vice Versa

Once an application security group has been created in a Tsecurity Application, and a user has been added to the same Tsecurity Application, an association can be made between the two in several different ways.  First, right-clicking on an application privilege class or on an application user presents the Select Domain Members for Privilege Class and Select Privilege Classes for Domain Member options, respectively, in the displayed context-dependent menu.  Choosing either of these options invokes the Select Membership form, which allows the user to make the desired selections simply by checking and unchecking memberships as desired.

Pressing the Accept button makes any changes to the memberships official, while pressing the Cancel button cancels any changes made within this form.

Alternatively, a domain member can be associated with an application privilege class simply by dragging and dropping one object over the other within the tree view of the Tsecurity Application. 

To add a domain member to an application privilege class left-click-and-hold on the domain member name and move the mouse up over the desired application privilege class.  Releasing the left mouse button will drop the domain member into the application privilege class so that he is now listed as one of the Domain Members for that application privilege class.  At the same time, the application privilege class will be automatically added to the list of Application Privilege Class Memberships for the user object.

By the same token, to add an application privilege class membership to a given domain member, left-click-and-hold on the application privilege class name and move the mouse down over the desired domain member. Releasing the left mouse button will drop the application privilege class into the domain member so that it is now added to the list of Application Privilege Class Memberships for the domain member.  At the same time the domain member will be automatically added to the list of Domain Members for the privilege class.


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.


Saving a Tsecurity Application Configuration

Any time a Tsecurity Application has been modified, it must be saved back to the host before the changes will be made official. If a Tsecurity Application has been modified but not yet saved, its name is displayed followed by an asterisk (*).  A Tsecurity Application can be saved to the host by right-clicking on the Tsecurity Application name and selecting the Save Application menu item.

...