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.
HELIOS provides various services which can use different login methods.
Clear text login
UNIX crypt login
Random number login
LanManager login
NTLMv1 login
NTLMv2 login
DHX128 login
DHX2 login
RSA crypted login
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”).
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.
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
.
Display command overview.
List the registered name services (local
,
NIS
, LDAP
, MACOSX
, PDC
).
List user information (authorization; number of references; user ID; user name; full name; time in cache).
List group information (authorization; number of references; group ID; group name; time in cache).
Sum up the users
and groups
information.
Leave the interface.
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) |
Changes to the authentication settings require an “authsrv” service restart to take effect.
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.
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”.
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.
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.
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 are supported. Every group in group membership is resolved and the complete list of groups is provided for AD/PDC users.
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.
Set up a user and password on the Windows AD/PDC server.
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):
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 Login Name
and Password
which
the authentication server should use to connect to the AD/PDC server.
Specify an existing local UNIX user as template user in the
Local Template User
field.
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. 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.
UB2 offers a new PDC (Primary Domain Controller) authentication that has several advantages over the previous UB+ PDC authentication:
Consistent UNIX user and group ids if several HELIOS installations authenticate against the same PDC (see “Mapping of Windows SIDs to UNIX user and group IDs”)
Faster and more reliable authentication especially in PDC domains with many groups
Backup Domain Controller support
The new PDC authentication is active by default. The following steps are necessary for a successful migration:
Upgrade UB+ to UB2.
On the Windows host, install the “HELIOS PDC Logon” service.
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.
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.
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”.
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”.
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
The TCP port 2030 needs to be open to allow the HELIOS PDC Logon service.
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.
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.
The “HELIOS PDC Logon” service needs to be restarted if the group filter files have been changed.
The “heliospdclogon.exe” utility can also be used from command line. The available commands are:
Registers “heliospdclogon” as a Windows service.
Removes “heliospdclogon” as a Windows service.
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.
# 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.
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 “Administrators” group is mapped to group ID 0.
The “Print Operators” group is mapped to group ID 1.
All other user and group SIDs are mapped to a UNIX ID in the range
16777216-83886079
(hex: 0x01000000-04FFFFFF
), using a built-in algorithm.
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.
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.
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.
Duration three years
No automatic renewal
Available for: HELIOS UB+ or newer products
Covers NIS, LDAP, AD/PDC support
Single agreement covers multiple servers
Include customer signed “SE004.pdf” form with order.
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>.)
Show information about a user. Either the user name or the user ID must be specified.
authutil user [-n <name>] [-i <uid>] [-r] [-q] [-t <timeout>]
The following options are supported:
User name.
User ID.
Force refreshing user information rather than using cache data.
Print nothing if user does not exist, return exit status only.
Timeout in seconds to complete the request.
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
Show information about a group. Either the group name or the group ID must be specified.
authutil group [-n <name>] [-i <gid>] [-r] [-q] [-t <timeout>]
The following options are supported:
Group name.
Group ID.
Refresh group information.
Print nothing if group does not exist, return exit status only.
Timeout in seconds to complete the request.
Display guest user.
authutil guest [-q] [-t <timeout>]
The following options are supported:
Print nothing if user does not exist, return exit status only.
Timeout in seconds to complete the request.
Verify user password.
authutil login -n <name> -p <passwd> [-s] [-q] [-t <timeout>] [-m <method>] [-d <domain>] authutil login -N
The following options are supported:
User name.
User password.
Show user information if login was successful.
Print nothing if password was wrong, return exit status only.
Timeout in seconds to complete the request.
Encrypt the password before sending it to the
authentication server. Available encryption methods
are: RSA
, LM
, NTLM
.
AD/PDC domain name.
Print CIFS/SMB challenge.
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.
authutil passwd [name] authutil passwd [-n <name>] [-o <oldpasswd>] [-p <passwd>] [-qCHMX] [-t <timeout>] [-m <method>]
The following options are supported:
User name.
Old password.
New password.
Print nothing if password change failed, return exit status only.
Print UNIX encoded (crypt) password.
Print HELIOS encoded password.
Print MD5 digest of password.
Do not change password (to be used with -H
, -C
or -M
option).
Encrypt the passwords before sending them to the authentication server. Available encryption methods are: RSA.
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.
“root” can set passwords without knowing the old password:
authutil passwd -n username -p newpassword
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.
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.
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.
authutil batch [-e] <batchfile>
The following option is supported:
Exit immediately if a command failed.
$ authutil batch cmd.txt
The “authutil” return exit code is always zero
on success
and non-zero
on failures.
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”.
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.
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.
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”:
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 “/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”.
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”:
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”.
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.