HELIOS Base UB2 User manual (Version 3.0.0)  
 

10 The authentication server

Note:

The HELIOS authentication server is only available for UNIX based operating systems. The “authutil” client tool (10.2 “authutil”) is available for all platforms.

The authentication server is a foundation service providing login authorization and user credential information for all HELIOS servers and tools. In versions prior to UB, HELIOS services worked directly against the UNIX password and group files or with NIS-based group and password maps. Over time, additional ways of reading user settings were provided, e.g. the Apple user/group storage, LDAP databases, Windows PDC (Primary Domain Controller) and AD (Active Directory), shadow password files and so on. For multi-server environments a central server storing user information allows other services to access the information from a master server. Another benefit is that this system allows storing more than the basic user information which goes beyond the standard UNIX password and group file based settings.

The authentication server supports local host users, NIS, LDAP, Mac OS X Password Server and Windows AD/PDC user settings and passwords for all HELIOS services and tools. It is designed to support different databases in parallel (e.g. local UNIX users, LDAP server) and works completely asynchronously to handle multiple requests without blocking concurrent requests. Its built-in server fail safety allows restarting the authentication service without interrupting other services. Central caching of information speeds up lookups and ensures that all services use identical information.

The goal of the authentication server is to integrate well into different systems. Its central service allows enhancing the authentication server, while staying fully compatible with all HELIOS services and tools.

10.1 The authentication server program

10.1.1 Different user authentication needs

HELIOS provides various services which can use different login methods.

To support all these login methods, including passwords up to 64 characters, it is required that the local user database, NIS or LDAP, stores an additional HELIOS crypted password. On a local system the HELIOS crypted password is stored in “HELIOSDIR/var/conf/passwd”. HELIOS products without this additional password are not supported and will not work. The “authutil” tool allows setting and changing passwords for local host users, and provides crypt, MD5 and HELIOS passwords to import these into an LDAP database.

The authentication server works read-only against LDAP and Windows AD/​PDC. The modification of user settings is only supported against local host users or NIS users if the server is the NIS master server. This is straightforward because LDAP and Windows AD/PDC users are managed with other tools.

The following user information is provided from the authentication server to the HELIOS services.

Item Type Description
shortname utf8 str Host shortname of the user
uid int32 Primary user ID for this user
gid int32 Primary group ID for this user
add-gids int32 Additional group member IDs
fullname utf8 str UTF-8 full name (“:” chars are not allowed)
homedir utf8 str Home directory path
shell utf8 str Start shell program
group names utf8 str Name of all groups
cryptpwd string Crypted password
heliospwd hex str HELIOS crypted password

The listed information is required, additional information may be provided in the future. If additional information needs to be verified, the “var/​authsrv/​login.pl” script allows verifying additional settings, e.g. login hours to manage access (see also 10.1.4 “Login notification script”).

10.1.2 PAM Modules

PAM (Pluggable Authentication Modules) are supported on some host operating systems. HELIOS does not need or use any PAM modules. As PAM is not available on all systems and cannot support all required authentication methods (listed in 10.1.1 “Different user authentication needs”) the authentication server works without any PAM support. PAM can be activated in parallel to be used by other services.

10.1.3 Authentication server telnet port

Authentication server statistics can be reported to custom applications by the “authsrv” TCP/IP connection via port “2008”. See 8.6 “socket” for a description of the “socket” utility.

hsymInstruction

Issue socket 2008.

help

Display command overview.

status

List the registered name services (local, NIS, LDAP, MACOSX, PDC).

users

List user information (authorization; number of references; user ID; user name; full name; time in cache).

groups

List group information (authorization; number of references; group ID; group name; time in cache).

entities

Sum up the users and groups information.

quit

Leave the interface.

10.1.4 Login notification script

Each time a user completes a successful login, i.e. user name and password match, the authentication server calls a custom notification script with the user parameters. The script can exit with:

exit 0      Continue login session 
exit 1      Deny login 
exit 10     Account disabled 
exit 11     Password expired

A custom script allows verifying additional parameters such as the remote TCP/IP address, checking if the user is already logged in from a different IP address and denying or allowing the login request. Another idea is to contact an LDAP database, to verify other information of this user account before allowing the login. To use this script it must be stored as “var/authsrv/login.pl”. The script can be any kind of application or script but it is required to be executable, e.g. mode “711”, and the name must be “login.pl”, even if it is not Perl based. We recommend using a Perl script to stay compatible on different platforms. The following very simple script will log all login parameters tab separated into “/tmp/logfile”:

#!/usr/bin/perl 
my $logfile = "/tmp/logfile"; 
open(LOGF,">> $logfile") || die "authsrv: cannot open: $logfile $!\n"; 
foreach (@ARGV) { 
  print LOGF $_, "\t"; 
} 
print LOGF "\n"; 
close(LOGF); 
exit 0;

The “login.pl” parameters are:

Variable Description
$ARGV[0] Host user ID
$ARGV[1] Host user login name
$ARGV[2] Windows (AD/PDC) domain name
$ARGV[3] PID of the server requesting the login
$ARGV[4] Server name requesting the login, e.g. “afpsrv”, “pcshare”, “websharesrv”
$ARGV[5] TCP/IP address of the remote client requesting the login
$ARGV[6] Authentication system providing this user account (local, NIS, LDAP, PDC)
Note:

Changes to the authentication settings require an “authsrv” service restart to take effect.

10.1.5 Local host users/groups

The following list shows the user/group database files used on a server host, e.g. Sun Solaris. Depending on the operating system an additional shadow like “/etc/​security/​passwd” is used. On Mac OS X all user/group information is stored in the Apple user/group storage.

HELIOSDIR/var/conf/passwd # HELIOS crypted password file
/etc/passwd # UNIX user file
/etc/group # UNIX group file
/etc/shadow # Solaris/Linux password file
/etc/security/passwd # AIX password file

The Enable Local Authentication checkbox in the HELIOS Admin Local tab must be activated in order to make local authentication work.

10.1.6 NIS users/groups

The Enable NIS checkbox in the HELIOS Admin NIS tab must be activated in order to make NIS authentication work. See 10.3 “Configuration with NIS”.

10.1.7 AD/PDC users/groups

The authentication server supports Windows AD/PDC (Active Directory or Primary Domain Controller) for user authentication. The Windows AD/PDC server will provide user name and password as well as primary and supplementary group information. A backup AD/PDC server can be configured and will automatically be used if the main server fails. Unique user IDs are automatically assigned for each user name.

AD/PDC template user

The required home directory is provided by a template user. The actual user name will replace the template user name in the home directory path.

The groups of the template user are provided in addition to the AD/​PDC groups.

In case the AD/​PDC server does not provide the primary group the template user's primary group is used. For compatibility reasons, users of previous installations, e.g. HELIOS UB+, always get their primary group from the template user.

Supported AD/PDC servers

Windows Server 2000, 2003, 2008

If local UNIX users and AD/PDC users are used in parallel, the authentication order must be first Local and then AD/PDC.

It is required to set up a user on the AD/PDC server, to enable the authentication server to connect to the AD/PDC server. This user name and password must be specified in the authentication server setup (Fig. 10.1). The credentials can be of any user that exists on the AD/PDC server, so no administrative privileges are required.

Groups in groups

Groups in groups are supported. Every group in group membership is resolved and the complete list of groups is provided for AD/PDC users.

Requirements

The PDC authentication requires the “HELIOS PDC Logon” (see 10.1.9 “HELIOS PDC Logon”) service to be installed on the Windows host that should act as the PDC to the HELIOS installation. This host need not be a Primary or Backup Domain Controller; any Windows host that is part of the desired domain will do.

AD/PDC setup procedure
hsymInstruction

Set up a user and password on the Windows AD/PDC server.

Note:

Make sure that user & group names over all specified name services are unique. If e.g. a user or group name already exists locally it should not exist in NIS or LDAP or AD/PDC.

Complete the AD/PDC settings via HELIOS Admin (Fig. 10.1):

hsymInstruction

Select AD/PDC.

hsymInstruction

Activate the Enable AD/PDC checkbox.

hsymInstruction

Specify the Primary Server via TCP/IP address or DNS name.

hsymInstruction

Specify the Domain Name used on the AD/PDC server.

HELIOS Admin <code>AD/PDC</code> setup

Fig. 10.1: HELIOS Admin AD/PDC setup

hsymInstruction

Specify Login Name and Password which the authentication server should use to connect to the AD/PDC server.

hsymInstruction

Specify an existing local UNIX user as template user in the Local Template User field.

hsymInstruction

Save the settings.

hsymInstruction

Restart the authentication server:

# srvutil stop -f authsrv 
# srvutil start authsrv

Now all HELIOS services should work with the AD/PDC user accounts. A test login can be verified via the HELIOS “authutil” utility (see 10.2 “authutil”):

# authutil login -n username -p password

If a login via “authutil” works without any errors, the Windows AD/PDC authentication can be used by all HELIOS services.

10.1.8 Migration from UB+

UB2 offers a new PDC (Primary Domain Controller) authentication that has several advantages over the previous UB+ PDC authentication:

The new PDC authentication is active by default. The following steps are necessary for a successful migration:

hsymInstruction

Upgrade UB+ to UB2.

hsymInstruction

On the Windows host, install the “HELIOS PDC Logon” service.

hsymInstruction

On the Windows host, optionally remove the network share including contents created by the previos HELIOS PDC configuration. By default this share resides at “C:\​Windows\​heliosauth”. This share is not used by the new PDC authentication.

hsymInstruction

If PDC user or group names are already listed in the “HELIOSDIR/​var/​conf/​authsrv.cache” cache file from a previous UB+ installation, the new “authsrv” will keep these mappings to UNIX user and group IDs. Thus, the consistency of ID mappings is kept also for old users and groups.

PDC compatibility related “authsrv” preference keys

PDCCompat
Setting this preference activates the old UB+ PDC authentication mechanism by using the “heliosauth” share. See PDCCompat in 19.7 “Authentication server preference keys”.

Note:

If you wish to set this preference, please refer to the HELIOS Base UB+ manual for important information about the assignment of user and group IDs by the authentication server, the related usage and output of the “authutil” command, and the “heliosauthcreate” utility usage.

PDCCompatIDMap
If set, the new PDC authentication looks at the file “HELIOSDIR/​var/​conf/​authsrv.cache” to map PDC names and groups to UNIX user and group IDs of previous HELIOS installations. If this file does not exist or this preference is switched off, all PDC users and groups get a PDC domain specific and unique UNIX ID. This new ID will be different to the ID set in the “authsrv.cache” file. See PDCCompatIDMap in 19.7 “Authentication server preference keys”.

10.1.9 HELIOS PDC Logon

Note:

If you are using a Windows 2000 PDC, the “HELIOS PDC Logon” software must be installed on a different PDC member system running Windows 2003 or higher.

HELIOS PDC Logon is installed as a Windows service by running the “setup.exe” program, which is located in the “HELIOS_APPS” volume, in the “Windows\​AuthServer Tools\​HELIOS PDC Logon” folder.

After installation, the service can be stopped or started using the Windows “Services” utility, or by using the command:
# net [stop/start] heliospdclogon

Note:

The TCP port 2030 needs to be open to allow the HELIOS PDC Logon service.

Group inclusion and exclusion

In Windows domain users can be members of many groups. In contrast some UNIX variants only allow a very limited number of groups per user. Known limits are:

OS Groups Comment
Solaris 8-11 16 Can be changed to max. 32
AIX 5.3 128
Linux 2.6 kernel 65536
Mac OS X 10.4-10.7 16 Verify with sysctl -a | grep ngroups

To overcome this hurdle HELIOS PDC Logon can report to the “authsrv” only a subset of the groups PDC users are member of.

At startup HELIOS PDC Logon tries to read in two files “group-include.txt” and “group-exclude.txt”. These files reside where HELIOS PDC Logon is installed, i.e. in a default installation this would be “C:\​Program Files\​HELIOS PDC Logon”.

As its name suggest, “group-include.txt” specifies allowed group names, i.e. any PDC group not mentioned there is ignored. Likewise “group-exclude.txt” specifies group names that are ignored, i.e. all PDC groups not mentioned there are allowed. The exclude list takes precedence over the include list, i.e. a group name that is in both files is filtered out nonetheless.

Group filter file format

The group files have to be UTF-8 encoded. The files have to start with the magic line: # heliospdclogon filter file. The groups must be listed line-separated.

Note:

The “HELIOS PDC Logon” service needs to be restarted if the group filter files have been changed.

Command line options

The “heliospdclogon.exe” utility can also be used from command line. The available commands are:

heliospdclogon install

Registers “heliospdclogon” as a Windows service.

heliospdclogon remove

Removes “heliospdclogon” as a Windows service.

heliospdclogon dumpgroups

Prints local and domain groups “heliospdclogon” would report to “authsrv”. Can be used as a template for group filter lists. Group names are UTF-8 encoded.

Example:
# cd "C:\Program Files\HELIOS PDC Logon"
# heliospdclogon dumpgroups >group-include.txt

This command writes the complete group list to the file “group-include.txt”, including the required header for a group filter file.

Mapping of Windows SIDs to UNIX user and group IDs

Windows uses SIDs (Security Identifiers) to identify users and groups. HELIOS PDC Logon uses a consistent mapping from SIDs to UNIX user and group IDs:

The UB+ preferences PDCUserFirstId, PDCUserLastId, PDCGroupFirstId and PDCGroupLastId (HELIOS Admin options First User ID, Last User ID, First Group ID and Last Group ID) are no longer used, unless PDCCompat is set.

10.1.10 LDAP

For information on configuring the authentication server for LDAP users, see: www.helios.de/web/EN/support/ldap.html. It includes sample configurations for Mac OS X Server, OpenLDAP, and the Univention LDAP server.

10.1.11 Support

SE004 Authentication server support agreement

The authentication environment can be very complex, and sometimes customers wish to get direct support from HELIOS for planning, configuration, problem analysis and integration of the HELIOS authentication server with the customer NIS, LDAP, AD/PDC setup. For this purpose, a technical support agreement (part no SE004) is available from the HELIOS partner.

Include customer signed “SE004.pdf” form with order.

10.2 authutil

The “authutil” utility is a tool for verifying the user/​group configuration and managing passwords. It allows displaying user and group entries, validating logins or changing and setting passwords for local host users. “authutil” can generate MD5 passwords used for virtual WebShare users (see WebShare manual) or AFP volume passwords. It also allows printing UNIX crypt and HELIOS crypted compatible passwords to be imported in an LDAP database. “authutil” has been designed for the use in scripts or for batch operations, e.g. setting passwords for local host users.

The following commands can be called with “authutil”:

authutil { user | group | guest | login | passwd | batch } ...
authutil -h       (Display help text.)
authutil <cmd> -h (Display help on the command <cmd>.)

10.2.1 user

Show information about a user. Either the user name or the user ID must be specified.

Usage:

authutil user [-n <name>] [-i <uid>] [-r] [-q] [-t <timeout>]

The following options are supported:

-n <name>

User name.

-i <uid>

User ID.

-r

Force refreshing user information rather than using cache data.

-q <quiet>

Print nothing if user does not exist, return exit status only.

-t <timeout>

Timeout in seconds to complete the request.

Example 1:

Querying information on a local user:

$ authutil user -n demouser 
        user: demouser 
         uid: 500 
         gid: 503:demouser 
   long name: Example Demo User 
last refresh: Tue Feb 20 11:32:59 2007 
      origin: local UNIX (*) 
     homedir: /Users/demouser 
      groups: demouser:503, QueueAdm:502

10.2.2 group

Show information about a group. Either the group name or the group ID must be specified.

Usage:

authutil group [-n <name>] [-i <gid>] [-r] [-q] [-t <timeout>]

The following options are supported:

-n <name>

Group name.

-i <gid>

Group ID.

-r

Refresh group information.

-q <quiet>

Print nothing if group does not exist, return exit status only.

-t <timeout>

Timeout in seconds to complete the request.

10.2.3 guest

Display guest user.

Usage:

authutil guest [-q] [-t <timeout>]

The following options are supported:

-q <quiet>

Print nothing if user does not exist, return exit status only.

-t <timeout>

Timeout in seconds to complete the request.

10.2.4 login

Verify user password.

Usage:

authutil login -n <name> -p <passwd> [-s] [-q] [-t <timeout>]
               [-m <method>] [-d <domain>]
authutil login -N

The following options are supported:

-n <name>

User name.

-p <passwd>

User password.

-s

Show user information if login was successful.

-q <quiet>

Print nothing if password was wrong, return exit status only.

-t <timeout>

Timeout in seconds to complete the request.

-m <method>

Encrypt the password before sending it to the authentication server. Available encryption methods are: RSA, LM, NTLM.

-d <domain>

AD/PDC domain name.

-N

Print CIFS/SMB challenge.

10.2.5 passwd

On UNIX, set the HELIOS and UNIX password. On Windows, set only the HELIOS password, but also verify whether the password specified will result in a successful login.

Usage:

authutil passwd [name]
authutil passwd [-n <name>] [-o <oldpasswd>] [-p <passwd>]
                [-qCHMX] [-t <timeout>] [-m <method>]

The following options are supported:

-n <name>

User name.

-o <oldpasswd>

Old password.

-p <newpasswd>

New password.

-q <quiet>

Print nothing if password change failed, return exit status only.

-C

Print UNIX encoded (crypt) password.

-H

Print HELIOS encoded password.

-M

Print MD5 digest of password.

-X

Do not change password (to be used with -H, -C or -M option).

-m <method>

Encrypt the passwords before sending them to the authentication server. Available encryption methods are: RSA.

-t <timeout>

Timeout in seconds to complete the request.

If the -C, -H, -M options are combined, the results are printed in the order crypt, HELIOS, MD5.

Note:

“root” can set passwords without knowing the old password:

authutil passwd -n username -p newpassword
Examples:

Generate an MD5 password used for virtual WebShare users:

$ authutil passwd -M -X -p WSpassword

Generate a HELIOS “hex” crypted password:

$ authutil passwd -H -X -p newpassword

Generate a UNIX “crypt” password:

$ authutil passwd -C -X -p newpassword

The options -M, -H, -C can also be combined, e.g.:

$ authutil passwd -C -H -M -X -p 123

The “echo” mode is helpful when passwords are subject to be imported into a different system, e.g. an LDAP database.

Note:

The MD5 password must be inserted into the “var/​conf/​webshare.passwd” file. It is much easier to set passwords e.g. within the WebShare User Administration window.

At present, a password can only be set for local UNIX users or NIS users on a NIS master server. AD/PDC users must change the password using the AD/PDC tools.

Setting the HELIOS password with “authutil” on Windows only updates the “HELIOSDIR\​var\​conf\​passwd” file and will NOT change the Windows password. This is required, e.g. for WebShare virtual users or if a user is specified for Script Server scripts or Tool Server tools.

10.2.6 batch

Read commands from the file <batchfile>. If <batchfile> is “-”, commands are read from “stdin”. If a command fails, authutil will continue with the next command from <batchfile>, unless option -e is given.

Usage:

authutil batch [-e] <batchfile>

The following option is supported:

-e

Exit immediately if a command failed.

Example:
$ authutil batch cmd.txt

The “authutil” return exit code is always zero on success and non-zero on failures.

10.3 Configuration with NIS

The authentication server was designed to support the UNIX NIS (Network Information Service) system, which, in a network of several UNIX hosts, allows user names, group names, and passwords as well as other configuration details to be stored centrally on the NIS (formerly named “Yellow Pages”) Master host. This considerably simplifies the setup of new users, particularly if they each need access to more than one host. Please note that the user configuration data maintained under NIS is only stored on the Master NIS host. You can only change it with HELIOS Admin if the HELIOS host is the Master NIS host, and not one of the NIS Slaves.

Furthermore, the special NIS password and group files (e.g. “/var/yp/passwd” and “/var/yp/group”) are usually stored on the Master host in a subdirectory of “/var/yp”. If they are stored in a different location, the configuration for the authentication server allows you to specify the location of the NIS password and group files with the ypdir preference (see 19.7 “Authentication server preference keys”). This preference needs to be specified on the Master host only. You can edit the NIS password and group files to set up NIS users by use of the standard UNIX NIS tools in the normal way. We would like to point out, however, that if the HELIOS host is the Master NIS host, then HELIOS Admin is much easier to use for setting up NIS users and groups than the standard UNIX tools. You can use HELIOS Admin to set up both, HELIOS users and regular UNIX users.

The user list (“HELIOSDIR/var/conf/passwd”) can also be used with the NIS system by setting up, on the NIS Master host, a second password file (“afppasswd”) which contains the names of all users of the Master host and its interconnected NIS Slaves. This additional password file is located in the same directory as the NIS password and group files, e.g.: “/var/yp/afppasswd”.

“HELIOSDIR/var/conf/passwd” on the Master host should only contain the “root” and local users who are not to be used on the network, terminated by “+:” in the last line.

The installation includes the “HELIOSDIR/etc/ypMakefile” script, which contains the necessary changes required to implement the HELIOS user list under NIS. Enter the group- and password-related information in “/​var/​yp/​Makefile” according to the information given in “HELIOSDIR/etc/​ypMakefile”.

Note:

You should be familiar with editing such files in order to provide proper operation of NIS administration.

The “HELIOSDIR/var/conf/passwd” file of each host in the NIS system (master and slaves) can optionally include a line containing only “+:” at the position where the NIS user and group map should be included. This usually follows entries for the “root” and the system logins only, to make sure that it is still possible to log on to the host in the case of a failure of the network connection to the Master:

root:8c9373c57a229c7a 
+:

When the NIS system is being used, the HELIOS Admin server automatically calls “HELIOSDIR/sbin/yp-update” whenever user or group data is changed, in order to update the NIS files.

10.3.1 HELIOS services configuration on a NIS Master

The HELIOS services do support NIS. The configuration on a NIS Master needs however a meticulous setup. This section describes the needed tasks for a NIS setup with HELIOS services. NIS can be set up with or without separate “passwd” and “group” files. In both cases an additional NIS map is required to hold the HELIOS passwords.

If your YP directory is not “/var/yp”, set the preference ypdir and replace “/var/yp” with your YP directory in the following instructions.

10.3.2 NIS configuration with separate “passwd”/​“group” files

With this configuration, the YP directory contains separate files (“passwd” and “group”) which are used for the NIS “passwd” and “group” maps. This means that NIS users and groups are different from the local host users and groups in “/etc/passwd” and “/etc/group”.

Configure the additional NIS map “afppasswd”:

hsymInstruction

Edit “/var/yp/Makefile” and add rules for the “afppasswd” map. See “HELIOSDIR/etc/ypMakefile” for an example Makefile.

hsymInstruction

Touch “/var/yp/afppasswd” to create an initial empty map.

hsymInstruction

Call “make” in “/var/yp”, restart NIS, and restart the HELIOS services.

All user/group changes on the NIS Master server via HELIOS Admin are stored in “/var/yp/passwd”, “/var/yp/group” and “/var/yp/afppasswd”.

10.3.3 NIS configuration without separate “passwd”/​“group” files

With this configuration, NIS uses the files “/etc/passwd” and “/etc/group” for the “passwd” and “group” maps. This means that every user/group on the host is also a NIS user/group in the network.

Configure the additional NIS map “afppasswd”:

hsymInstruction

Edit “/var/yp/Makefile” and add rules for the “afppasswd” map. See “HELIOSDIR/etc/ypMakefile” for an example Makefile. In the Makefile, replace “$(DIR)/afppasswd” with “HELIOSDIR/var/conf/passwd”, where HELIOSDIR is your HELIOS installation directory.

hsymInstruction

Set the ypmapdir preference to “/etc”:

prefvalue -k Programs/authsrv/ypmapdir -t str "/etc"
hsymInstruction

Call “make” in the “/var/yp” directory, restart NIS, and restart the HELIOS services.

All user/group changes on the NIS Master server via HELIOS Admin are stored in “/etc/passwd”, “/etc/group” and “HELIOSDIR/var/conf/passwd”.

10.3.4 NIS verification

hsymInstruction

Check that the correct NIS entries are listed with the commands:

ypcat passwd 
ypcat group 
ypcat afppasswd

The command authutil login -n nisuser -p password -s should return no error message and display a user record like:

user: nisuser 
uid: 124 
gid: 30:helios 
long name: HELIOS Software Support 
last refresh: Fri Oct 27 15:30:43 2006 
origin: NIS/YP (*) 
homedir: /home/nisuser 
groups: helios:30, usr:100

Note that the “origin” shows a NIS user.


HELIOS Website © 2011 HELIOS Software GmbH  
HELIOS Manuals May 17, 2013