HELIOS Base UB User manual
10 The authentication server
The authentication Server is a new foundation service providing login authorization and user credential information for all HELIOS servers and tools. In previous versions HELIOS services worked directly against the UNIX password and group files or with NIS-based group and password maps. Over the time additional ways of storing user settings are provided, e.g. Apple's "netinfo" database, 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, LDAP, NIS 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 and a secondary LDAP Server) and works completely asynchronously to handle multiple requests without blocking concurrent requests. Its built-in server fail safety allows to restart the authentication service without interrupting other services. Central cashing 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 and stay 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 are using 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 files 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 group members
cryptpwd string 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 7.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, 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; user ID; user 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 in "var/authsrv/login.pl". The script can be any kind of application or script but it is required to be executable, e.g. running in 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 uid
$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.
(UNIX, 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 for "/etc/security/passwd" is used. On Mac OS X all user/group information is stored in the "netinfo" database.
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
/var/db/netinfo # Mac OS X user/groups database
10.1.6 AD/PDC
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.
The following AD/PDC servers are supported:
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 UNIX and then AD/PDC. For maintenance it is required to set up the user with administration group membership on the AD/PDC server, and to specify this user name and password in the authentication server setup (Fig. 78). It is required that the "admin$" sharepoint be active (it is usually always active on Windows).
Fig. 78: HELIOS Admin AD/PDC setup

AD/PDC setup:
Set up user and password with group administrators membership on the Windows AD/PDC server.
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. 78):
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 a 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 user ID 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 host users. (Check user ID in "/etc/passwd".)
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

Note: Once "authsrv" is restarted with AD/PDC support on changes of the primary bootserver, Admin user and password within HELIOS Admin are automatically used. No additional restart is required.

Limitations
At present the primary group ID and additional group member IDs are static and will be provided by the template user. This should be supported at a later time frame.
If a Windows 2003 computer is used as AD/PDC server, you must disable the security option "Microsoft network server: Digitally sign communication (always)" in the menu Administrative Tools > Local Security Policy > Security Settings > Local Policies > Security Options.
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}
user
Show information about a user. Either the user name or the user ID must be specified.
Usage:
# authutil user [-n ] [-i ] [-r] [-q] [-t]
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
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 <uid> Group ID
-r Refresh group information
-q (quiet) Print nothing if user group not
exist, return exit status only
-t <timeout> Timeout in seconds to complete the request
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
login
Verify the password of a user.
Usage:
# authutil login [-n] [-p] [-s] [-q] [-t] [-m] [-d]
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
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.
Example:
# authutil login -m RSA -n demouser -p secret
passwd
Set or change the password of a user.
Usage:
authutil passwd [name]
authutil passwd [-n] [-o] [-p] [-qCHMX] [-t] [-m]
Options:
-n <name> User name
-o <passwd> Old password
-p <passwd> 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:

Set HELIOS password:

# authutil passwd -n username -p newpassword

Generate a MD5 password used for virtual WebShare users:

# authutil passwd -M -X -p newpassword
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 -M -C -H -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.

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.

Note: Setting the password with "authutil" under Windows will only set the "HELIOSDIR/var/passwd" file and will NOT change the Windows password. Setting a password via "authutil" under Windows is only required for the use as virtual WebShare user.

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 NIS Master host. You can only change it with HELIOS Admin by logging on to the authentication server on the Master 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 16.8 "Authentication server preference keys"). These preferences only need specifying on the Master host. You can edit the NIS password and group files to set up slave users by use of the standard UNIX NIS tools in the normal way. We would like to point out, however, that 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 system logins, terminated by "+:" in the last line.
The installation includes in "HELIOSDIR/etc" the script "ypMakefile", 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.
© 2005 HELIOS Software GmbH