HELIOS Base UB+ User manual

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), NIS Plus, 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 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 when 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
str
Crypted password
heliospwd
hex str
HELIOS crypted password

The listed information is required, additional information may be used 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 deny access if required.

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.

Issue socket 2008, type help for the command overview and quit to leave.

status

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

user

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

groups

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

entities

Sums up the user and groups information.

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 its 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. If a script is available, 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)

10.1.5 Local host users/groups

The table lists 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. Read also 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 the user authentication. It works via the HELIOS implemented Windows CIFS protocol which communicates with the Windows AD/PDC using TCP/IP port 139 or 445. The Windows AD/PDC server will provide the user name and password. Additional information like group IDs are provided by a template user. Unique user IDs are automatically assigned for each user name and stored in a cache file, to be reused if the same user logs in a second time. A backup AD/PDC server can be configured and will automatically be used if the main server fails.

Supported AD/PDC servers

Windows NT, 2000, 2003

If local UNIX users and AD/PDC users are used in parallel it is required that the authentication order be first Local and then AD/PDC. For maintenance it is required to set up a user with administration group membership on the AD/PDC server, and to specify this user name and password in the authentication server setup (Fig. 91). It is required that the "admin$" sharepoint be active (it is usually always active on Windows).

Groups in groups

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

Note: Verify a login first via the "authutil" login option to check if it works or if you receive errors.
AD/PDC Setup procedure

Fig. 91: HELIOS Admin AD/PDC setup

Set up a user and password with administrator's group membership 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 also exist in NIS or LDAP or AD/PDC.

Verify that a remote Windows client can login and access the "admin$" sharepoint by logging on to the AD/PDC with the user name created in the first step above.

Enter the following URL in "My Network Places":

\\127.0.0.1\admin$

Verify write access by copying a file into the directory. Only if this works, the next step should be completed.

Complete the AD/PDC settings in the HELIOS Admin security menu (Fig. 91):

Select AD/PDC.

Activate the Enable AD/PDC checkbox.

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

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

Specify the user name and password configured on the AD/PDC server in the first step above.

Specify an existing local UNIX user as "template user". This user will provide the group IDs, home directory and shell (the actual user name will replace the template user name in the home directory).

Specify a mapping range used for AD/PDC users (the user ID range needs to be larger than the total number of AD/PDC users).

Verify that the user ID range is not in use by other local users or overlaps them. (Check user ID in "/etc/passwd".)

Likewise, specify a mapping range used for AD/PDC groups (the group ID range needs to be larger than the total number of AD/PDC groups).

Verify that the group ID range is not in use by other local host groups. (Check user ID in "/etc/passwd" and "/etc/group".)

Save the settings.

Restart the authentication server:

srvutil stop -f authsrv
srvutil start authsrv

Now all HELIOS services should work with the AD/PDC user accounts. The simple login can be verified via the HELIOS "authutil" utility (see 10.2 "authutil"). If a login via "authutil" works without error messages the Windows AD/PDC authentication can be used by all HELIOS services.

# authutil login -n username -p password

The authentication server uses group information from an AD/PDC. To use AD/PDC groups, "heliosauthcreate.exe" must be run on the AC/PDC server.

It dynamically maps AD/PDC groups to UNIX group IDs, in the same way AD/PDC user names are mapped to UNIX user IDs. User and group mapping is stored in the "authsrv" cache file "HELIOSDIR/var/conf/authsrv.cache".

10.1.8 heliosauthcreate

The authentication server uses group information from an AD/PDC.

"heliosauthcreate" dynamically maps AD/PDC groups to UNIX group IDs, in the same way AD/PDC user names are mapped to UNIX user IDs. User and group mapping is stored in the "authsrv" cache file "var/conf/authsrv.cache".
To use the AD/PDC groups, the "heliosauthcreate" tool must be run on the AD/PDC server.

This tool creates a network share that contains authentication help files used by the PDC plug-in of the HELIOS authentication server. It must be run on the AD/PDC server in order for the authentication server to be able to obtain PDC group information.

It is also possible to use a computer that is only part of a domain and not the domain controller itself. You may even use a Windows XP system that is neither a PDC nor a domain member. In the latter case only the local groups are used.

"heliosauthcreate.exe" can be run multiple times without harm, e.g. as a scheduled task or manually whenever groups have been added or removed. heliosauthcreate.exe -h shows a help message with all available options.

The "heliosauthcreate" utility is stored in the directory "HELIOSDIR\public\Windows\AuthServer Tools", and must be copied to and run on the AD/PDC server.

Usage:

heliosauthcreate.exe [-h|-v][-n][-d <localdir>]
[-s <share>]
[-g <global|local|all>]
[-p <domctrl>] <create>

The following options can be used with "heliosauthcreate":

-d

Local directory of share
(default: "C:\WINDOWS\heliosauth").

-s

Share name (default "HELIOSAUTH").

-g

What type of groups "heliosauthcreate" should process. "global" are domain groups, "local" those only locally known to the server, "all" both global and local. (default "all").

-p

Get global group information from this domain controller. Default is taken from the current system configuration. It is not recommended to use this option, as it usually indicates a domain controller misconfiguration.

-n

Do not delay program exit even if started from the GUI. Usually this tool can automatically detect whether it runs in a new console window or not. Use this option if it guesses wrong. A typical symptom is an idle "heliosauthcreate". This might happen if it is started from a system process like scheduled tasks.

-h

Display this help file.

-v

Print version and exit.

create

If you wish to create group information, add the parameter "create", which will create a list of all known group names that are stored in "\\<servername>\admin$\PDCLockDir", which is published and used by "authsrv" to learn about all group names.
Windows has many groups, which are usually not used by users; optionally after "heliosauthcreate" has created a list of group files, unwanted groups can be removed to reduce the number of total groups.

Note: Depending of the operating system, the total number of groups may be limited. Known limits are:

OS
n Groups
Comment
Solaris 10
16
Can be changed to max. 32 in total system
AIX 5.3
128
Linux 2.6 kernel
65536
Mac OS X 10.4
16
Verify with sysctl -a | grep ngroups
HP-UX 11
20

10.1.9 LDAP

For information on configuring the authentication server for LDAP users, see the HELIOS LDAP web page.

10.2 authutil

The "authutil" utility is a batch tool for scripts. 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}

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>]

Options:

-n <name> User name
-i <uid> User ID
-r Refresh user information
-q (quiet) Print nothing if user does not
exist, return exit status only
-t <timeout> Timeout in seconds to complete the request

Examples:

Local

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
       admin: Queue
      groups: demouser:503, QueueAdm:502
Note: The "authutil" commands user, group and login return the same output, with one exception:
The line origin: states the used authentication method. This can be either local UNIX, NIS/YP, LDAP or PDC.

An asterisk (*) following the authentication method indicates a verified user, a hyphen (-) an non-verified user (see 10.2.7 "Note on AD/PDC users").

10.2.2 group

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

Usage:

# authutil group [-n ] [-i ] [-r] [-q] [-t]

Options:

-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]

Options:

-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 the password of a user.

Usage:

# authutil login [-n] [-p] [-s] [-q] [-t] [-m] [-d] [N]

Options:

-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

Additional parameters allow specifying different login methods against the authentication server, the default method is cleartext. Additional methods are: LM for LanManager, NTLM for CIFS, RSA for RSA public key crypted passwords.

10.2.5 passwd

Set the HELIOS password of a user. Unless the -X option is set, the given password must be the user's Windows password.

Usage:

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

Options:

-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 option 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 a 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 "HELIOSDIR/var/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 and NIS users. 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/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>

Options:

-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.2.7 Note on AD/PDC users

If AD/PDC is configured, the authentication server will assume every unknown user as AD/PDC user and will reserve a user ID. This is due to technical reasons because a user can only be verified against AD/PDC when performing a login by submitting user name and password.

A non-verified user is marked with a minus in the output of the "authutil user" command: origin: PDC (-). Furthermore, there are no groups displayed, except for the group of the PDC template user:

# authutil user -n pdcdemo
        user: pdcdemo
         uid: 2000
         gid: 504:demouser
   long name: pdcdemo
last refresh: Tue Feb 20 11:36:30 2007
      origin: PDC (-)
     homedir: /home/pdcdemo
      groups: demouser:504

Non-verified users are deleted from the authentication server cache after a while. To verify whether a user really exists, a login needs to be performed. A verified user is permanently added to the cache:

# authutil login -n pdcdemo -p secret

If the AD/PDC login has been successful, the user will now be listed with an asterisk, which marks the user as verified: origin: PDC (*). Furthermore, the AD/PDC groups are displayed:

# authutil user -n pdcdemo
        user: pdcdemo
         uid: 2000
         gid: 504:demouser
   long name: pdcdemo
last refresh: Tue Feb 20 11:37:10 2007
      origin: PDC (*)
     homedir: /home/pdcdemo
      groups: demouser:504, demogrp1:2008, demogrp2:2009

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". For this reason, the configuration entry for the authentication server in the "Preferences" file 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 in "HELIOSDIR/etc" the "ypMakefile" script , which contains the necessary changes required to implement the AFP user list under NIS. Enter the group- and password-related information in the file "/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 authentication server automatically calls "HELIOSDIR/sbin/yp-update" whenever user or group data is changed, in order to update the NIS files. The network connection results in a slight additional time delay when making such changes.

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" and "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".

Configuring the additional NIS map "afppasswd":

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

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

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 "/var/yp/passwd", "/var/yp/group" and "/var/yp/afppasswd".

10.3.3 NIS configuration without separate "passwd" and "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.

To configure the additional NIS map "afppasswd":

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.

Set the ypmapdir preference to "/etc":

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

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

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

ypcat passwd
ypcat group
ypcat afppasswd

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.

© 2008 HELIOS Software GmbH