Authentication

• Overview
• Authentication at login
• Groups and Licenses
• Four Scenarios
• Partial Guest Access
• Authentication Modules
• Configuring Authentication Modules
  • Default Module
  • All Authent
  • Single Password
  • Text Authent
  • Kerberos
  • LDAP
  • Windows NT
  • SQL
  • KS NDS
  • Unix
• Using Active Directory for authentication
• Modules Compared
• Run-time Examples

Overview

Authentication is one of the most powerful features offered by the KeyServer Package, but it is also one of its most complex. While it can greatly enhance control of programs, authentication can also make the configuration process more involved. Before using the authentication features of KeyServer, carefully read this page.

Authentication can accomplish two basic functions. First, it can be used to allow or disallow users from connecting to the KeyServer at all. Second, it can allow group membership to be determined by a name and password, rather than simply location or the identity of specific computers. These groups can in turn be used to control who can use each license.

For most purposes, license control and reporting based on the computer ID is completely adequate. Before you consider adding an authentication requirement (e. g. changing the default from "All Authent" to one of the modules below), check the documentation on how to define Divisions and Groups based on computer ID alone without authentication.

Authentication at login

Depending on your environment and the licenses you are managing, you may wish to restrict access to the KeyServer. For example, a KeyServer might be configured to restrict access to users who type their individual name and password, or it might provide service to anyone who types in a single KeyServer password known by all the valid users.

The process a user follows to gain access to your KeyServer is called authentication. Once the user has passed the required test (e.g., typed the proper password), the user is authenticated. A user is not authenticated if they fail to satisfy some requirement of the active authentication module (e.g., fail to type an acceptable password). By default, KeyServer will deny access to users who are not authenticated, but you can grant partial access to unauthenticated users by allowing “guest” logons.

• Passwords are always conveyed from KeyAccess to KeyServer in encrypted form with KeyAccess versions 5.1 or better. KeyServer may convey the password to the designated authentication service either in encrypted or clear text format, depending on the module chosen and the capabilities/configuration of the authentication service. When clear text is the only supported module, it will be mentioned in the documentation. In this case you should host the KeyServer process and the authentication process on the same host, or at least on hosts using a network connection secured against eavesdropping.

Access to KeyServer and individual licenses can also be based on the IP address of the client computer. Use the Locations Window in KeyConfigure to set up location-based access restrictions. Note that if a user tries to connect to the KeyServer from a location which is not allowed to connect, they will not even get as far as the authentication step. The location restrictions are applied first, even if guest access has been turned on in the authentication configuration. If you want to not only allow guests to connect, but also to allow them to connect from anywhere, you must configure KeyServer to allow access from any location in the Locations Window.

Groups and Licenses

Some authentication modules support groups, which means that one user can be distinguished from another by their group membership, which can then be used to restrict access to licenses. Therefore, authentication can be used to control who can use a particular license. This is analogous to a file server, where access to certain objects on the file server is restricted to users who enter a valid name/password combination.

With KeyServer, you can restrict usage of a license to a particular group. Membership in a group is determined in two ways: via the settings you make in the Group Details Window for any particular group, and via the active authentication module. The Group Details window lets you control membership by exact computer, computer Division, network address, or a filter on additional properties of the computer. Thus, you can control license usage even without using authentication (see Group Details Window for more on group configuration). However, if you need a more flexible and integrated way of determining group membership, you can use an authentication module which supports group membership for users. Authentication also lets you distinguish between two users of the same computer.

Four Scenarios

Allow everyone to connect, and don't use authentication for group membership.
Use the default authentication module, All Authent.

Restrict who can connect, and don't use authentication for group membership.
Use any authentication module besides the default module, All Authent. The module may or may not support groups. Make sure that guest access is disabled.

Allow everyone to connect, but use authentication for group membership.
Use an authentication which supports groups, but enable guest access so that even those who do not have a name and password can still connect (but will not be authenticated into any groups).

Restrict who can connect, and use authentication for group membership.
Use an authentication which supports groups, and make sure guest access is disabled, so that only those who are successfully authenticated can connect.

Partial Guest Access

You can also allow guests to connect, but only if they meet the location or node list requirements for a certain group. To do this, check the Restricted to: checkbox just below the Allow “Guest” Logon checkbox, and select a group from the dropdown menu. This is useful if you want to let everyday “on campus” users have transparent access to the KeyServer, but want logon attempts from outside the specified group (i.e., non-guest and therefore “off campus”) to be prompted for authentication credentials.

Authentication Modules

The KeyServer will always be using one and only one of the following authentication modules at any given time:

• All Authent. All users are automatically authenticated and logged in to KeyServer. KeyAccess is all a user needs to ensure access. This module does not define any groups.
• Single Password. Users become authenticated by typing in a password, which you choose. The password is the same for all KeyServer users. This module does not define any groups.
• Text Authent. User names, passwords, and groups are specified in a text file. A user becomes authenticated for KeyServer use by typing a correct name and password. Users may be members of multiple groups, and thereby gain access to licenses.
• Kerberos. To gain access to the KeyServer, users must authenticate with a Kerberos server. Kerberos does not directly support groups. This authentication module requires a Kerberos server on your network.
• LDAP. To gain access to the KeyServer, users must type their name and password as it exists on the specified LDAP server. Once authenticated, users are given access to licenses based on membership in groups defined on the LDAP server.
• Windows NT. To gain access to the KeyServer, users must type their name and password as it exists in the specified NT Domain, Active Directory, or on the Windows NT computer that is running KeyServer. Once authenticated, users can be given access to licenses based on their membership in groups as defined in the authentication database. This authentication module is only available for the Windows NT KeyServer, although clients on all platforms are supported.
• SQL. User names, passwords, and groups are defined in a database that supports SQL. This authentication module is only available for the Windows NT KeyServer, although clients on all platforms are supported.
• KS NDS. To gain access to the KeyServer, users must type their name and password as it exists in the NDS tree. Once authenticated, users are given access to licenses based on membership in groups defined in NDS. This authentication module is only available for the NetWare KeyServer, although clients on all platforms are supported.
• Unix. To gain access to the KeyServer, users must type their name and password as it is defined on the Unix computer running the KeyServer process. Once authenticated, users can be given access to licenses based on their membership in groups as defined in the authentication database. This authentication module is only available for the Mac OS X Server, Linux, and Solaris KeyServers, although clients on all platforms are supported. Linux, Solaris, and Mac OS X can use PAM to relay the unix authentication to a broad variety of authentication service choices (e.g. LDAPv3). When KeyServer is hosted on Mac OS X Server, all the flexibility of Apple's Open Directory architecture is also available for KeyServer authentication.

Sassafras is always developing new authentication modules, so contact Sassafras technical support if you do not see an authentication module that meets your requirements.

Configuring Authentication Modules

Authentication modules are defined in libraries which are in the Authentication Modules folder within the KeyServer Data Folder.

Authentication modules are configured through the Authentication item in the Admin menu. When you choose this command a dialog box appears that contains options specific to the active authentication module. The pop-up menu at the bottom of the dialog box lets you choose from the available modules.

Only one module may be active at a time. If you switch authentication modules while the KeyServer is running, the new module is initialized and takes effect when the initialization is complete. This process may take a minute, depending on the module, so its status is displayed in the upper right corner of the Authentication dialog box.

The Authentication dialog is different for every authentication module.

Default Module

The default module is active when no other module is chosen, or when a module that you chose could not load. All Authent is the default module.

All Authent

The All Authent module authenticates every user, and does not place users in any particular groups. In effect, when you use All Authent you are turning the authentication features of KeyServer off. Because of its simplicity, this module does not require any configuration.

Single Password

Single Password is so named because it maintains one global password for all users of the KeyServer. Users who know this password are given full access to the KeyServer, regardless of their names. As with the All Authent module, users are not placed in any additional groups.

At the KeyServer level, you configure Single Password by specifying the password that users must type. This password can be up to eight characters in length, and can contain any characters. Users must type the password exactly as you entered it, including the upper and lower cases of each letter.

Text Authent

With Text Authent authentication module, users are authenticated based on their name and a corresponding password. Unlike the Single Password module, each user may have his or her own password, and users can belong to any number of groups. All of the names, passwords, and groups are stored in a text file named “Authent List” in the KeyServer Data Folder.

To change users' names, passwords, or group memberships, you must have direct access to the Authent List file on the KeyServer machine. Use any text editor to change the Authent List file. It may be convenient to use an editor that can make the tab and return characters visible.

You can modify the Authent List file at any time, even when the KeyServer is running, and any changes automatically take affect within ten minutes. If you want the changes to take affect sooner, choose the Authentication command from KeyConfigure's Admin menu, and click OK. This tells the Text Authent module that you have made some changes.

Each line in the Authent List file is of the following form:

	user name tab password tab group1, group2, group3, ...

The user name, password, and individual group names can contain spaces, but cannot contain tab characters or any of the reserved characters:

	*	!	@	#	,	;	{	}

Only the first eight letters of the password are used, the rest are ignored. The list of groups (which may be empty) specifies which groups the user belongs to.

The character “*” has a special meaning when it appears alone in the name or password field. If the password for a user is simply “*”, the user may type any password, and will be authenticated (of course the user must type the exact name). This can be useful if you want to have an account for a user named “guest” that does not require a password.

If a user types a name that is not recognized, then the Text Authent module searches for an entry with “*” for the user name. The corresponding password is then used for this unknown user. Note that only one “*” user should be in the Authent List file. If there is more than one, then the first one is used. The “*” user is useful if you want to give access to unknown users (users with any name and any password), or if you want to mimic the Single Password authentication module. You can also allow any user access to the KeyServer by including the entry:

	*	*

This effectively says “an unknown user may type any password.” You can then restrict these unknown users by excluding them from all groups (i.e., don't type any group names after the “* *” entry). Note that if you do not specify any groups, then a “* *” entry is equivalent to allowing guest access. However, if you do specify one or more groups, it is different - it gives you membership in all groups simply because of your name and password.

The “*” also has a special meaning when it appears in the group list. Any user who belongs to the “*” group belongs to all groups. Thus, the user

	root	leaves	*

belongs to all groups, and therefore cannot be denied a license because of group restriction. It is not necessary to list any other groups when the “*” group is listed. However, you may wish to explicitly exclude the user from one or more groups. To do this, list each group with an exclamation point (“!”) preceding it, and then list the “*” group last. For example,

	John Doe	s2Cr5t	!keysentry, !admin, *

specifies that the user named John Doe belongs to all groups except the keysentry group and the admin group. The “*” group must be the last group listed.

Be careful when you use the “*” in the name, password or group fields. You can actually turn authentication off (mimic the All Authent module) with the following entry:

	*	*	*

This entry tells the Text Authent module that an unknown user who types any password is in all groups. In fact, this is even worse than All Authent, because any user gets membership to all groups. This essentially overrides the group definitions for location and computer - they are rendered useless because any user can get membership in any group.

Text that is ignored or commented begins with a ";", and continues to the first return character. Make sure you type a return to end every line of your Authent List file; automatic word-wrap does not suffice as an end marker for comments, and does not separate users.

Below is a summary of the format and rules of the Authent List file:

• Lines contain a user name, password, and optional group list. These three components are separated by the tab character.
• Users must spell their names correctly, as they appear in the Authent List file. Upper and lower case do not matter.
• User must type their password exactly as they appear in the Authent List file. Upper and lower case do matter.
• Group names are listed optionally. Group names are separated by commas.
• User names, passwords, and group names cannot contain tab characters or any of the reserved characters: * ! @ # , ; { }
• The “*” character has special meaning in the user name, password and groups.
• The exclamation point (“!”) excludes a user from a group.
• Comments begin with “;” and end at the following return character.

Because of the complexity of this authentication module, there are a few things to watch out for. The following list answers the most common questions. If you are having trouble, read these questions and answers first, and see if you can figure out the problem. Sometimes it helps to remove all of the comments from the Authent List file, and then see if the problem goes away. It might also help to edit your users file with a text editor that supports formatted text to organize users and groups.

One important note: if you use a word processor to edit your Authent List file, make sure you save the file as text. There is usually a “Save As Text Only” option in the Save As dialog box. Also, be sure that the file is named simply “Authent List”. Even on Windows, it should NOT be named “Authent List.txt”.

One of my users can never get authenticated.
Is the user's name in the Authent List file? Is there a corresponding password? Are the name and password separated by a tab? Are there any illegal characters in the user name or password? Is the user typing the name and password exactly as they appear in the file? Are there any invisible characters that may be mis-typed? Is the caps lock key down? Are there two entries for the user? (There shouldn't be.) Is the user commented out by a leading “;”? Is there a return character at the end of each line?

A user who is supposed to be in a particular group is not.
Can the user get authenticated? (The user's name should not appear italicized in KeyConfigure's Users window.) Is the group in the user's group list spelled exactly the same as it is in the Limits pane of the License Details window for the license in question? Are there two entries for the user? (There shouldn't be.) Is the group name in the user's group list preceded by an exclamation point? (It shouldn't be.) Is the user commented out?

If you have eliminated the cases explained above, and you are still having problems, contact Sassafras technical support.

Kerberos

Sites that have a Kerberos authentication server can use it for authenticating users to KeyServer. In order to gain access to a “kerberized” KeyServer, users must type their name and password as it is known by the Kerberos server. Because a Kerberos server provides only authentication services, it cannot directly support group memberships for users.

To use this authentication module, you should already be familiar with the basic configuration and maintenance of a Kerberos server. You should at least know the terminology that is used, and how to add items to your Kerberos server.

Configuration of the Kerberos authentication module is done both in KeyConfigure and on your Kerberos server. First, on the Kerberos server, you must create a new principal that will be used in the authentication process. Once the principal has been created on the Kerberos server, you must install a "keytab" file on the computer running KeyServer. This file contains information about the principal, and is used by the Kerberos authentication module when verifying users' identities. Details on creating and installing this file depend on the Kerberos server you are using.

With the principal created and the keytab file installed, configure the Kerberos authentication module by entering the principal name in the Authentication dialog. Do not include the realm with the principal name, since that value is retrieved from the keytab file.

The Kerberos authentication module can also be configured to use an LDAP server to provide user groups. To use LDAP for authorization, read the next section describing the LDAP authentication module. Configuration for the LDAP portion of the Kerberos module is the same as for the LDAP module.

LDAP

With the LDAP authentication module you can use any LDAP compatible directory server for your source of users, passwords and groups. This includes the original LDAP server from University of Michigan, its successor OpenLDAP, Netscape Directory Server, NetWare Directory Services (with LDAP support enabled), and Active Directory.

To use this authentication module, you should already be familiar with the configuration and maintenance of the LDAP-compatible server you are using.

The LDAP authentication module currently supports LDAP version 2 and 3, as well as secure (SSL) communication between KeyServer and the LDAP server. If you want the connection to the LDAP server to be secure, check the option named "Try to establish secure connection to LDAP server". With this option checked, the authentication module will first try to create a secure connection to the LDAP server, but if that fails an insecure connection will be used. Make sure that your server and the KeyServer host computer are correctly configured so that secure communication is possible. You should first test with a standard LDAP client tool (such as ldapsearch) to verify that the KeyServer host can create a secure connection to the specific LDAP server you will be using. When a secure connection cannot be made, all passwords will be visible as clear text when conveyed between KeyServer and the LDAP server.

Configuration for the LDAP authentication module consists of specifying the network location of the LDAP server, providing the DN and password of a directory object with sufficient permission to search for users and check group membership, indicating the base DN within which all searches will be performed, giving the object classes for user, computer, and group objects, and giving the attribute type for group members. Each of these is described in more detail below.

The Host and Port fields contain the network address where the LDAP server is located. The Host field can be either the DNS name of the LDAP server or the dotted IP address. Leave the Port field set to 0 to use the default (389), or set a specific value if necessary. Note that it is unnecessary to specify port 636 (the Secure LDAP port) in this field, as a different mechanism is used to secure the connection.

Depending on how permissions are set on your LDAP server, you might need to provide a specific “Bind DN” and password. The Bind DN should have permission to search for users and groups and check for membership in a group. If all these can be done by an anonymous user, then you can leave the Bind DN and Bind Password fields empty.

The LDAP module searches for users, computers, and groups within the subtree given in the Base DN field. This value should contain (either directly or in the subtree) objects for all users that will be logging into the KeyServer, all groups that you will be using to control access to licenses, and any computers that belong to these groups.

The User Object Class, Computers Object Class, and Group Object Class fields specify the object classes that users, computers, and groups must have. The Group Member Attribute field specifies the attribute type that contains group members. The object classes and attribute type will be used in searches when authenticating users or determining group memberships. If you do not want to use LDAP to determine group memberships, leave the Group Member Attribute field blank. If you do not want to check for group memberships of computers, leave the Computers Object Class field blank.

When verifying a user's password, the LDAP authentication module first searches for the user in the Base DN subtree, and then attempts an LDAP “bind” operation with the resulting DN and the password. When searching for the user, the “cn”, “uid” and “sAMAccountName” attributes are checked to see if they contain the user name (The “sAMAccountName” attribute is included for support of short login names in Active Directory, and is only included in the query if the "Use sAMAccountName Attribute" option is checked). For example, if “John Doe” is attempting to log onto KeyServer, then the following search filter is used, starting from the Base DN and using a subtree search (assuming that User Object Class is “person”):

	(&(objectclass=person)(|(cn=John Doe)(uid=John Doe)(sAMAccountName=John Doe)))

Once the user's full DN has been found in the directory, the LDAP module checks the password using an LDAP bind operation.

To check if a user is a member of a group, the LDAP module searches for the group in the Base DN subtree and then verifies that the user is a member of that group. The first search uses the same filter as given above. To check membership, a search filter like the one below is used (assuming the group is named “Some Group”, the Group Object Class is “groupOfNames”, and the Group Attribute is “member”). A subtree search is done in the Base DN subtree:

	(&(objectclass=groupOfNames)(cn=Some Group)(|(member=<user DN>)(member=<user name>)(memberuid=<user name>)))

where <user DN> is replaced by the user's DN determined in the first search, and <user DN> is replaced by the user's name as known to KeyServer (“John Doe” in the example above).

If the group membership test for the user fails, and if you have specified the Computers Object Class, then the LDAP module checks if the client computer is a member of the group. First the client computer name (e.g., “JOHNS_PC”) is looked up:

	(&(objectclass=computer)(cn=JOHNS_PC))

then a search filter like the one below is used (assuming the same settings as above). A subtree search is done in the Base DN subtree:

	(&(objectclass=groupOfNames)(cn=Some Group)(|(member=<computer DN>)(member=<computer name>)))

The table below suggests some values for the object class and attribute names for some common LDAP servers. Note that LDAP servers are customizable, so you should check with your LDAP server administrator that these values are applicable in your environment.

		OpenLDAP		NetWare (NDS)		Active Directory		Mac OS X Server
User Object Class		person or  organizationalPerson or  inetOrgPerson		person or  organizationalPerson or  inetOrgPerson		person or  organizationalPerson or  user		apple-user or  posixAccount or  inetOrgPerson
Computer Object Class		computer		computer		computer		machine
Group Object Class		groupOfNames		groupOfNames		group		apple-group or  posixGroup
Group Member Attribute		member		member		member		member

If you want the list of LDAP groups to appear in KeyConfigure's Groups window, check the option named "Gather Group List". When this option is checked, the LDAP module will perform a search query that might generate a large result set, placing a (temporary) burden on your LDAP server. Because this search can be expensive, the LDAP module will cache the group list. Changes to the group list on the LDAP server will not appear in KeyConfigure for up to an hour. The following search filter is used, starting from the Base DN and using a subtree search (assuming that Group Object Class is “member”):

	(objectclass=member)

Note that the "Gather Group List" option is not necessary in order to use groups within KeyServer's license pools. Gathering the group list is only a convenience so you do not have to type the group names into license pools. If you choose not to have the LDAP module gather the group list, you can still use the groups in license pools by typing the group names as they appear on the LDAP server. Case is not important, and you should not include the attributes (e.g., "cn=").

Further customization of the LDAP module is possible if the standard queries will not work with your LDAP server. Contact Sassafras technical support if you cannot get LDAP to work using the standard configuration options described above.

Windows NT

Sites that use Active Directory or Windows NT domains to organize their users can use the Windows NT authentication module to configure KeyServer to use the same set of names and passwords. All group membership information defined in the Active Directory for the Windows domain will be available to the KeyServer process for use in controlling application access.

To use this authentication module, you should already be familiar with the basic Active Directory configuration and maintenance for NT Domains.

Because KeyServer must access the information directly from a Windows Domain or Active Directory, this authentication module is only available when the KeyServer process is hosted on a Windows computer. If your KeyServer runs on Mac OS, Linux, or Solaris and you wish to access your users and groups in Active Directory, consider using the Kerberos or LDAP authentication modules.

In order for KeyServer to be able to access the names and passwords, it must operate with the user right “Run as part of the operating system”. This advanced user right can be enabled via the User Manager program. If your KeyServer runs as a service in the LocalSystem account, that account already has the necessary user rights.

Enter the name(s) of the domain(s) from which users will be authenticated in the NT Domain List field. If you leave this field blank, the local domain of the KeyServer machine is used. Users may specify the domain they belong to when they login using the standard notation: DOMAIN\name. If the user does not provide a domain, all domains listed in the authentication module configuration dialog will be searched in the order given.

There are four options for password verification:

1. Passwords not required
   With this option, users will not be prompted for passwords. The current user name is assumed to be correct and authentic, and will be used when checking group memberships.
2. Use Compatible Authentication
   Use this only if you must support old KeyAccess clients, 5.0.5 or older! This is not recommended because the password will be conveyed in clear text all the way from client to KeyServer to authentication server. Users will be prompted for their password by KeyAccess once per login.
3. Use Secure Authentication
   KeyAccess versions 5.0.5 or older will not be able to use KeyServer with this option nor with option 4. Users will be prompted for their password by KeyAccess once per login.
4. Use NTLM Authentication
   NTLM Authentication supports “single sign-on” for Windows 98 and Windows NT 4 and higher. These operating systems can store certain information during user login that can be used to authenticate to network services (like KeyServer) without prompting for a password after initial user logon. For older clients, and for clients on other platforms, this option falls back to using Secure Authentication, so users on such systems will be prompted for a password by KeyAccess once per login.

If the Windows NT Guest account is enabled on your NT domain server, any user will be able to logon to KeyServer using any name and password. It is recommended that the Guest account be disabled on your NT server, since this account creates a large security hole for your NT server and for other services that depend upon it. This may require two steps. First, turn the guest account off in the User Accounts Control Panel. Then use the “Local Security Policy” Administrative tool, and edit Security Settings -> Local Policies -> Security Options -> Accounts: Guest Account status. Set this item to Disabled if it was set to Enabled.

Access can be restricted to members of a particular group, as well. If a group name is specified in the “Restrict to Group” field, access will only be granted to users who enter their correct name and password and who also belong to this group.

There are also a few options for how KeyServer determines whether a user is a member of a group. By default, KeyServer will look for groups in both the Local groups (groups stored on the computer that runs KeyServer) and the Domain groups (groups stored in AD or on an NT Domain server). You can disable either or both of these options by checking Ignore Local Groups or Ignore Domain Groups.

Typically, group membership is determined based on the name of the user who is logged in to KeyServer. In addition, the Windows NT authentication module can check for group membership based on the name of the computer from which the user is logged in. To enable this option, check the option "Check Computer Members".

It is recommended that, if possible, you use Active Directory for determining group memberships. Check Use Active Directory and enter the IP host name or IP address of the Active Directory server, as well as the name and password of an object on the server that has permissions to check group memberships (this means the object must have read rights to the “member” attribute of a group object). The object MUST be qualified with the NT domain, as in "DOMAIN\accountname", or must be in one of the domains listed in the "NT Domain List". This account does NOT have to have admin level privileges.

If your Active Directory server runs only in “native” mode and not “mixed” mode, this authentication module cannot retrieve the list of groups from the server. However, you can still use the groups on your AD server simply by typing them into the Group field in any licenses. The group name must be entered as it appears on the AD server (just the group name, not the fully qualified name). After entering a group name in a license be sure to test launch a program in that license under an account that is a member of the group so you can be sure that the group name was typed correctly.

When specifying group names in License Detail windows, you can “qualify” the group name with a domain name using the standard notation: DOMAIN\name. This tells KeyServer to look only in that Domain Group for the user. If the group is unqualified (i.e., no Domain is given), then KeyServer will look in each listed domain for a group of that name, and if the group exists, it will be checked for the user.

Active Directory allows for "nested groups", where if group A is a member of group B, then all members of group A are also members of group B. This feature can simplify management of users and groups with Active Directory, but it is also more computationally intensive for programs to check for group membership. Therefore, support for nested groups is disabled by default in this authentication module. If you use nested group in your Active Directory, you can enable KeyServer support for them by checking the "Use Nested Group Check" option. This option is only available when you are using Active Directory to determine group memberships. Lastly, the "AD Login" account described above must have sufficient permission to read the "memberOf" attribute for users and groups.

SQL

Sites that maintain a database of users in an SQL database can set up KeyServer to use that database for authentication and authorization. This authentication module uses ODBC to connect to the database, so any ODBC data source that supports SQL can be used. However, since there is no convention for storing and retrieving passwords in an SQL database, passwords sent from Keyserver to the SQL server will likely be sent over the network as clear text when you are using this authentication module (depending on the specific implementation of the ODBC driver). Unless you must support KeyAccess versions 5.0.5 or older, be sure to check the Use Secure Authentication option so that passwords will be securely transmitted from KeyAccess to KeyServer.

To use this authentication module, you should already be familiar with SQL and your chosen RDBMS, and you must know how to set up an ODBC Data Source.

To configure the SQL authentication module, you must first set up the ODBC data source that is to be used. This can be done within the ODBC Data Source control panel on Windows. Once the data source is set up, enter the data source name (not the name of the database -- that was specified when setting up the data source), and the login name and password if they are required (sometimes these can be specified when you set up the data source). KeyServer will only need read (select) access to the database. In the example above, the data source was named “KeyServer Users”, although you can give the data source any name you wish. You can also use an existing data source if that is appropriate.

For example, consider the simple database design pictured below. This database has three tables: one containing user names and passwords, with a unique numeric “user ID” as the primary key; one containing group names and a unique “group ID” as the primary key; and the third being a “junction table” that defines a many-to-many relationship between users and groups. This third table defines each group's set of member users. Note that your database does not need to have this same structure. Your database can have any structure you wish, as long as you can form SQL queries that return the information needed by KeyServer, in the formats described below.

Simple SQL database design

When KeyServer verifies a user's password, it submits an SQL query that must return exactly one row, with the first column containing the password. KeyServer compares this column to the password that the user provides. In our example, this query will require only the “Users” database, using the SQL query:

	SELECT password FROM Users WHERE name = '$u'

In the above query, the “$u” will be replaced by the name provide by the user. This query must return exactly one record, otherwise the authentication will fail. Since KeyServer only checks the password in the first column, that is the only column that is requested in the query.

When KeyServer needs to check if a user is a member of a group, it submits an SQL query that must return at least one row, although the data in the row can be anything. In our example, we use a complex query that uses the Users and Groups tables to look up the user and group IDs, and then the Memberships junction table to check for membership. The SQL query looks like this:

	SELECT uid FROM Memberships
			WHERE uid = (SELECT uid FROM Users WHERE name = '$u')
			  AND gid = (SELECT gid FROM Groups WHERE name = '$g')

In the above query, the “$u” will be replaced by the user name and “$g” will be replaced by the group name. KeyServer checks that this query returns at least one row. The “uid” column is returned, but this is ignored and could be anything.

If your RDBMS is not able to do sub-selects, then you can most likely work around this with a slightly more complex query. For example, the above member query could be re-written as:

	SELECT Memberships.uid FROM Memberships,Users,Groups
			WHERE Memberships.uid = Users.uid
			  AND Users.name = '$u'
			  AND Memberships.gid = Groups.gid
			  AND Groups.name = '$g'

Some additional values can be used in queries (some of these are only available with version 6.2.0.2 or newer of the SQL authentication module):

• $u - user name
• $c - computer name
• $i - computer id
• $d - computer id starting with second character (e.g. the MAC address portion of a MAC address based id)
• $e - portion of computer id starting after first slash, if it contains one
• $g - group name

When forming a query, remember that your RDBMS might be case sensitive on table names and/or column names. To be safe, always use the same capitalization in your queries as is used in the table definitions in your RDBMS.

When entered in the Authentication dialog box, the Password Query is limited to 127 characters and the Member Query is limited to 255 characters. If your queries need to be longer than this, you can direct the SQL authentication module to read a query from a text file. To do this, enter “@” as the first character of the query, followed by the name of the file in which the query is stored. The file must be stored in the Authentication Modules folder within the KeyServer Data Folder. The entire contents of the file will be used as the query, and separate files must be used if you choose to store both the Password and the Member Query in files.

If you do not want KeyServer to require a password, leave the Password Query field empty. If you do not want KeyServer to check for group memberships, leave the Member Query field empty.

KS NDS

Sites that use NetWare Directory Services to organize their users can configure KeyServer to use the same information. With the KS NDS authentication module, users get access to programs based on access permissions that are set up in the NDS tree. At the administrator's option, users are required to type the name and password that they type to login to the NDS tree. Because KeyServer must access the information directly from the NDS tree, this authentication module will only work when KeyServer is running on a NetWare server.

The KS NDS authentication module is only supported when KeyServer is running on NetWare 5.0 or higher.

Configuration of the KS NDS authentication module is done mainly in the various NetWare and NDS administrator programs (like NW Admin). In KeyConfigure, you need to enter values that are used to locate users and groups within the NDS tree, as explained below. Unless you must support KeyAccess versions 5.0.5 or older, be sure to check the Use Secure Authentication option so that passwords will be securely transmitted from KeyAccess to KeyServer!

Authentication dialog for KS NDS module

The Server Object field should contain the name of an object that has Read and Compare rights to user objects and KS "group" objects. The Server Password field is the password associated with the Server object. NOTE: The Server object and password are not used in the current implementation, so you can leave them blank.

In the Attribute field, enter the name of the attribute that is used when checking authorization. Leave this blank to use “[Entry Rights]” (recommended). The KS NDS auth module merely checks that it has access to this attribute, and does not examine its contents (for “[Entry Rights]”, the auth module just verifies that the needed access is allowed and does not examine the object).

Choose one of the Compare/Browse, Read/Add, Write/Delete, and Self/Rename rights to be the right that users must have to a KS “group” object/attribute for authorization. We recommend Read/Add or Compare/Browse. This right is used in conjunction with the Attribute field described above.

The User Prefix and User Suffix values are used to locate users in your NDS tree. KS group objects are used to determine who is allowed to run KS-controlled programs. The prefix, user name, and suffix are concatenated to form the full “distinguished name” of the user. Note that this means your users must all be within the same NDS container!

Let's say you want to control access to a program named “ABCDraw”. In the License Details window you would configure a group restriction. Let's say the group name is “CanRunABCDraw”. (Note that this notion of “group” is separate from an NDS group.) Next, you need to create an NDS object with the name “CanRunABCDraw” within your NDS tree (all “group” objects used by KS should be placed in the same container). You then need to grant Compare/Browse “[Entry Rights]” to the users who are allowed to run CanRunABCDraw. You can do this in any way that NDS allows, for example: (a) put the users in a group and then grant that group (and its members) proper rights to the CanRunABCDraw object, or (b) assign the proper rights to individual users, or (c) any other method that you find convenient.

Now, when a logged-on user launches ABCDraw, KS checks that the user has Compare/Browse rights to the CanRunABCDraw object. If so the user is granted a license, otherwise not.

Unix

If you are running KeyServer on Unix, you can set up KeyServer to use the names, passwords and group affiliations that are set up on your Unix system. The name, password, and group information can be in a simple unix password file, or the access can be re-directed through a PAM module or Open Directory Services (when hosted on Mac OS X).

Authentication dialog for Unix module

Configuration of the Unix authentication module is done using the various Unix administrator utilities.

Using Active Directory for authentication

Active Directory Authentication is supported using either the Windows NT or the LDAP module. There is no special Authentication module needed for Active Directory. If your KeyServer is running on a Windows computer, it is easiest to use the Windows NT module (although you can use the LDAP module). If your KeyServer is not running on Windows, you must use the LDAP module. See the relevant sections above for configuration details.

Modules Compared

The table below compares the standard authentication modules, listing what is required in order for a user to be authenticated and how KeyServer determines whether a user has access to each program's preferred licenses.

Module name	Authentication criterion	Groups support	Availability
default module	all users are automatically authenticated	users are not placed in additional groups
All Authent	all users are automatically authenticated	users are not placed in additional groups
Single Password	users must type a password to obtain a KeyServer login session	users are not placed in additional groups
Text Authent	users must type a name and a password specific to that name to obtain a KeyServer login session	users are placed in groups by typing group names by their names in the Authent List file
Kerberos	users must type a name and a password specific to that name to obtain a KeyServer login session	users access to applications can be controlled by group membership defined in the LDAP directory
LDAP	users must type a name and a password specific to that name to obtain a KeyServer login session	users access to applications can be controlled by group membership defined in the LDAP directory
Windows NT	users must type a name and a password specific to that name to obtain a KeyServer login session	users access to applications can be controlled by group membership defined in each NT domain or the Active Directory
SQL	users must type a name and a password specific to that name to obtain a KeyServer login session	users access to applications can be controlled by group membership defined in the SQL database
KS NDS	users must type a name and a password specific to that name to obtain a KeyServer login session	users access to applications can be controlled by access permissions in the NDS Tree
Unix	users must type a name and a password specific to that name to obtain a KeyServer login session	users access to applications can be controlled by group membership defined on the Unix system

Run-time Examples

Understanding when and why KeyServer performs its authentication routines can sometimes be difficult. The situations outlined below may help clarify KeyServer's actions.

When a client computer starts up, KeyServer asks for a password.
The active authentication module requires a password. If the proper password is typed, the user is authenticated; otherwise, service is denied. Like some file servers, KeyAccess can be configured to remember the name and password of an authenticated user. This way, authentication is established without the intrusion of the password dialog.

When a KeyServer-controlled program is launched, KeyServer asks for a password.
If the client was disconnected from the network when it started up, and then later a KeyServer-controlled program is launched after the client computer is reconnected, the user must first establish an authenticated session with the KeyServer. When the active module requires a password, the user is asked to type it in before the controlled program continues.

When a KeyServer-controlled program is launched, KeyServer asks for a password, even though the user is already authenticated.
The Force Password option is set for the License, so that every time the program is launched, a password must be typed.

User A gets notified that a license is available before User B, even though User B got in line first.
User A has access to a license pool that User B does cannot access. The license that was returned (and hence is available for use) is from this pool, so User B cannot use it.

There is a license available, but someone is still waiting to be notified of its availability.
Similar to the previous case, the user does not have access to the pool that the returned license came from. The user will be notified when a license is returned to a pool that is accessible.

Related Topics