Authentication Modules

Authentication modules are implemented as library files stored in the Authentication Modules folder within the KeyServer Data Folder. Module selection and the corresponding configuration options are specified in the setup dialog presented from KeyConfigure's Config menu. Select either the Client Authentication... or Admin Authentication... menu item depending on which purpose you are configuring.

Client authentication can be used to "Assign Divisions automatically" – that is to automate the placement of client computers into a KeyServer Division based on group membership data that is available from an external authentication service (e.g. Active Directory). It can also be used when defining a Policy scope in order to control usage of a product based on client computer or user login credentials.

Admin Authentication lets you configure an external authentication service to manage administrative logons to KeyServer. This includes logons using KeyConfigure for configuration and reporting as well as logons for reporting using a web browser (via the the KeyReporter web service). Just like the internally defined administrative accounts, various configuration options and report views can then be made available to specific externally authenticated accounts.

The same module can be used for both Client and Admin authentication. In this case, the module's connection settings can be entered just once in the client auth setup – then as a convenience, the Copy Client Auth option can be used when setting up the module for Admin Authentication.

Note: the check box for "Assign Division automatically" is always displayed in the Client Authentication configuration dialog even when this option doesn't make sense. For example, the "Single Password" module has no access to data specifying computer group membership – there is no way it could automate the placement of a client computer into a Division.

Several modules are designed to request a password from a user on a client computer. By default, KeyServer disables communication from KeyAccess 6.0 and older– on newer clients,Passwords are always conveyed to KeyServer in encrypted form. 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 format supported by a 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.

Click the links below to jump directly to the specific configuration parameters for each module.

  • Disabled. The authentication feature is disabled, so Administrative accounts can only be defined internally within KeyServer using the Admin Access window. Client group membership (used for scope limitations) can still be defined based on network location or computer id but not based on any other data source.
  • 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 policies.
  • Kerberos. To gain access to the KeyServer, users must authenticate with a Kerberos server. Kerberos does not directly support groups but can be access group data from LDAP. 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 can be given access to policies 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 policies based on their membership in groups as defined in the authentication database. For most purposes, this module has been superceded by the Active Directory module. This authentication module is only available for the KeyServer hosted on Windows NT, although clients on all platforms are supported.
  • Active Directory. Typically sites using Active Directory are configured so that users and computers authenticate to active directory at computer logon. With KeyServer configured to use the Active Directory module, either for Client or Admin authentication, the credentials verified at logon are relayed to KeyServer without requiring authentication a second time. When used for Client authentication, in addition to being available for Policy scopes, this module can automatically populate KeyServer divisions based on AD organizational units. This authentication module is only available for KeyServer hosted on Windows, 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 KeyServer hosted on Windows, although clients on all platforms are supported.
  • CAS. This module is useful for taking advantage of CAS's single sign-on functionality when configuring Admin authentication for K2's web reports. Logons directly to KeyServer using KeyConfigure can also use CAS authenticated accounts if your CAS service supports the REST API.
  • 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 policies based on their membership in groups as defined in the authentication database. This authentication module is only available for KeyServer hosted on Mac OS X Server, Linux, and Solaris, although clients on all platforms are supported. Linux, Solaris, and Mac OS X can use PAM to relay the unix authentication from 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.

Disabled

When no other module is chosen, or when a module that you choose can not load, authentication defaults to the Disabled method. With Client Authentication is disabled, KeyServer authenticates every user so groups based on user names are not available. With Admin Authentication disabled, only internally defined KeyConfigure administrative logons are available.

all auth

Authentication dialog for Disabled module

Single Password

Single Password is so named because it maintains one global password for all users of the KeyServer. 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. Users who know this password are given full access to the KeyServer, regardless of their names.

single passwd

Authentication dialog for Single Password module

As with the Disabled module, there are no user based groups defined by this module so the Assign Divisions option for clients is meaningless. But you could allow guests logons for some group – perhaps a group defined by location. This module is useless for Admin Authentication since internal admin account and password credentials can already be defined from the Admin Access window.

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. Although this method could also be used for admin authentication, the only point would be in order to re-use group and password info that was already entered for client authentication – there is no additional functionality beyond what is already available from the Admin Access window.

All of the names, passwords, and groups are stored as clear text in a file named “Authent List” in the KeyServer Data Folder. Use any text editor direct access to the Authent List file on the KeyServer machine to enter and edit the Authent List file. It may be convenient to use an editor that can make the tab and return characters visible. Make sure you save the file as text and don't change the file name – it is “Authent List”, not “Authent List.txt”.

text auth

Authentication dialog for Text Authent module

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 Client Authentication option from KeyConfigure's Config Menu, and click OK.

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 all policies will apply, however the scope is defined. 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 Disabled 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 Disabled, 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.
  • Each distinct user name can only appear on a single line.
  • 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.

The Text Authent module will not Assign Divisions automatically.

Kerberos

Since Kerberos only provides authentication services, the setup screen for the Kerberos module also includes fields (as described below) for connecting to an LDAP server for group definitions. Using Kerberos for authentication together with LDAP for authorization (group membership) has the advantage of a more secure authentication phase compared to LDAP authentication – but the LDAP connection information is optional here unless group membership information is needed.

To use this authentication module, you should already be familiar with the basic configuration and maintenance of a Kerberos server including the terminology that is used and the procedure for adding items.

kerberos

Authentication dialog for Kerberos module

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 Kerberos Principal name in the setup dialog. Do not include the realm with the principal name, since that value is retrieved from the keytab file. The rest of the fields are only relevant if you need to access group definitions from an LDAP server.

Divisions can be assigned automatically if you specify a "Division Mapping Attribute"

LDAP

In order to setup the LDAP module module, you should already be familiar with the configuration and maintenance of the LDAP-compatible server you are using. With the LDAP authentication module you can use any LDAP compatible directory server for your source of users, passwords and groups. But as noted above, Kerberos provides more secure authentication of name and password so you may want to use the information in this section for LDAP details, but configure the actual LDAP connection using the Kerberos module.

LDAP version 2 and 3 using the original LDAP server from University of Michigan, OpenLDAP, Netscape Directory Server, NetWare Directory Services (with LDAP support enabled), and Active Directory are all supported. Communication between KeyServer and the LDAP server can be configured to use secure (SSL) when available by checking the option named "Try to establish secure connection to LDAP server". But if the secure connection is unsuccessful, an insecure connection will be used so make sure that your server and the KeyServer host computer are correctly configured so that secure communication is possible. Test with a standard LDAP client tool (such as ldapsearch). 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.

ldap

Authentication dialog for LDAP module

The Host field contains 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. 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 policies, 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 macOS 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
Division Mapping Attribute ou ou ou ou

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 Policies. Gathering the group list is only a convenience so you do not have to type the group names into Policy Detail windows. If you choose not to have the LDAP module gather the group list, you can still use the groups in policies 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=").

Divisions can be assigned automatically if you specify a "Division Mapping Attribute"

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 manage user accounts and privileges can configure KeyServer to relay its authentication queries to this same service using the Windows NT authentication module. 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. 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 user and group information from Active Directory, consider using the Kerberos or LDAP modules.

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

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 Windows User Manager tool. If your KeyServer runs as a service in the LocalSystem account, that account already has the necessary user rights.

 

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. Make sure that this item is set to Disabled.

With the Windows NT method selected, 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.

win NT

Authentication dialog for Windows NT module

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 of the computer login account is assumed to be correct and authentic, and will be used when checking group memberships.
  2. Use Compatible Authentication (legacy)
    Use this only if you must support very old KeyAccess clients, 5.0.5 or older! By default, such old clients are not permitted to logon to KeyServer. 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
    Users will be prompted for their password by KeyAccess when it logs on to KeyServer. To take advantage of “single sign-on” when available, choose the NTLM authentication option instead.
  4. Use NTLM Authentication
    NTLM Authentication supports “single sign-on” for Windows OS versions – Windows 98 , Windows NT 4, and better. These operating systems retain authenticated user account login information so that KeyAccess can make use of the previously validated credentials without itself prompting for a password. For Mac or Linux clients (or old KeyAccess versions), this option falls back to the Secure Authentication behavior – users will be prompted by KeyAccess for a password when it logs on to KeyServer.

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 DNS 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 Scope field in any policies. 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 policy be sure to test launch a program in that policy 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 Policy 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.

The Active Directory and Windows NT authentication methods use OUs to determine what division to place a computer in. Within these modules you can choose between using the first, last, or all OUs for for divisions. For example, if a computer has the distinguished name (dn) "cn=computername,ou=sales,ou=northeast,dc=company,dc=com", then:

  • Choosing "Use first OU" would result in a division name of "sales"
  • Choosing "Use last OU" would result in a division name of "northeast"
  • Choosing "Use all OUs" would result in a division name of "sales.northeast"

Note that computers must be in OU containers in order to be mapped to a division. The default configuration of Active Directory places most computers into the Computers container, which is not an OU container. You must create OU containers in your Active Directory and place computers into these containers in order for them to be mapped to Divisions within KeyServer.

Active Directory

Sites that use Active Directory can use this module to give KeyServer access to the AD names and passwords. All group membership information defined in the Active Directory domain will be available to the KeyServer process for use in controlling application access, auto-populating divisions, and authenticating K2 admin logins. To use this authentication module, you should already be familiar with the basics of Active Directory configuration and maintenance.

Because KeyServer must access information directly from Active Directory, this authentication module can only be used from a Windows host computer that is itself a member of the domain forest you want to authenticate against. If your KeyServer runs on Mac OS, Linux, or Solaris and you wish to access your users and groups data in Active Directory, consider using the Kerberos or LDAP authentication modules. In any case, KeyConfigure running on Mac or Windows can be used to set up or maintain the Authentication settings without any domain membership requirement.

This page describes basic use of the Active Directory authentication module. For more detailed instructions and screenshots you can refer to the Active Directory Integration — Admin Authentication and Active Directory Integration — Client Authentication pages.

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 of the computer login account is assumed to be correct and authentic, and will be used when checking group memberships.
  2. Use Secure Authentication
    Users will be prompted for their password by KeyAccess when it logs on to KeyServer. To take advantage of “single sign-on” when available, choose the Kerberos (or NTLM) authentication option instead.
  3. Use NTLM Authentication
    NTLM Authentication supports “single sign-on” for Windows OS versions – Windows 98 , Windows NT 4, and better. These operating systems retain authenticated user account login information so that KeyAccess can make use of the previously validated credentials without itself prompting for a password. For Mac or Linux clients (or old KeyAccess versions), this option falls back to the Secure Authentication behavior – users will be prompted by KeyAccess for a password when it logs on to KeyServer. Choose the
  4. Use Kerberos Authentication
    With correctly configured Kerberos access to Active Directory, this authentication module can support “single sign-on” for KeyAccess running on Windows, Macintosh, and Linux. You will need to specify a Principal and setup some configuration options on the Windows server in order to allow KeyServer to use Kerberos (more details later).

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.

AD

Authentication dialog for Active Directory module

With the Active Directory module, Active Directory group definitions are accessible to KeyServer but groups defined in the Local computer operating system are not. If you want KeyServer to also include Local OS groups, you should instead use the “Windows NT” authentication module. Note: with or without any authentication module, groups defined within KeyServer itself are always accessible.

With the Active Directory module, KeyServer will only look in Active Directory for group membership. If you want KeyServer to also include Local groups (defined on the KeyServer host computer itself), you should instead use the “Windows NT” authentication module.

Typically, group membership is determined based on the name of the user who is logged in to KeyServer. In addition, the Active Directory 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". This option must be enabled in order to use the "Assign Division automatically" option for Client Authentication.

You must enter the DNS 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 either 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 must be defined in Active Directory. It cannot be defined locally on the computer running KeyServer. It 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 Scope field in any policies. 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 policy be sure to test launch a program in that policy 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 Policy 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. Lastly, the "AD Login" account described above must have sufficient permission to read the "memberOf" attribute for users and groups.

In order to use the “Kerberos Authentication” option, you will need to do some additional configuration:

  1. Create an account in Active Directory which will run the KeyServer process - e.g. “KeyServer”
  2. In the Services control panel on the computer running KeyServer, edit the KeyServer service and configure it to Log On as the account you have just created
  3. On the domain controller (where the Active Directory is installed), register a Service Principal Name for the account you made, using the setspn command, e.g.:
    setspn -A KeyServer/DOMAIN.ORG KeyServer
  4. In the KeyConfigure Authentication dialog, fill in the Principal field with the string you used for the setspn command, but with an '@' character instead of a '/' - e.g. “KeyServer@DOMAIN.ORG”

The Active Directory and Windows NT authentication methods use OUs to determine what division to place a computer in. Within these modules you can choose between using the first, last, or all OUs for for divisions. For example, if a computer has the distinguished name (dn) "cn=computername,ou=sales,ou=northeast,dc=company,dc=com", then:

  • Choosing "Use first OU" would result in a division name of "sales"
  • Choosing "Use last OU" would result in a division name of "northeast"
  • Choosing "Use all OUs" would result in a division name of "sales.northeast"

Note that computers must be in OU containers in order to be mapped to a division (and as mentioned above, the "Check Computer Members” option must be enabled). The default configuration of Active Directory places most computers into the Computers container, which is not an OU container. You must create OU containers in your Active Directory and place computers into these containers in order for them to be mapped to Divisions within KeyServer.

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.

SQL

Authentication dialog for the SQL module

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.

The SQL module will not Assign Divisions automatically.

CAS

If you are running a CAS server to provide Central Authentication Services, you might consider using this method for externally authenticating Administrator accounts. This module supports CAS's single sign-on functionality for browser logons to KeyReporter (assuming the default configuration: KeyReporter is co-hosted with KeyServer). In order to use CAS for KeyConfigure logons, the CAS server must support the CAS REST API.

cas

Authentication dialog for CAS module

To configure CAS authentication, enter the CAS URL (this is the URL that other CAS-enabled network services are configured to use). The Service URL must be configured with the KeyServer/KeyReporter host name and appropriate port, if non-standard. For example, if you are running KeyReporter on keyserver.sample.net, using the custom port 8443 for secure HTTPS service, the Service URL would be https://keyserver.sample.net:8443/cas.

If your CAS server supports the CAS REST API, it is possible to use it for Client authentication but it is better to use a more efficient authentication method if available. CAS does not support group membership so it cannot be used to "Assign Divisions".

Unix

If you are running KeyServer on Unix, you can set up KeyServer to use the names, passwords, and groups. The unix authentication information can be sourced from a simple unix password file, or access can be re-directed through Open Directory Services or a PAM module (when hosted on Mac OS X). Note that if OS X is using PAM, you will have to configure PAM to allow the KeyServer process to use it. Configuration of the Unix authentication module is done using the various Unix administrator utilities. Check the unix manual pages for pam details.

When configured for Client authentication, even though group information is available for some purposes, the Unix module cannot assign computers into Divisions.

unix

Authentication dialog for Unix module

Modules Compared

The table below summarizes some properties of the standard authentication modules.

Module name Groups support Single sign-on Assign Divisions Automatically KeyServer Host
Single Password No         
Text Authent Group membership can be defined in the Authent List text file         
Kerberos Group membership defined in the LDAP directory can be made accessible         
LDAP Group membership defined in the LDAP directory is accessible         
Windows NT Group membership defined in each NT domain or in Active Directory For Windows Clients Yes
Active Directory Group membership defined in Active Directory is accessible Yes Yes
SQL Group membership defined in the SQL database s accessible    
CAS No Yes       
Unix Group membership defined in the Unix system s accessible