Gryphon Documentation Requirements for Single
Sign-On
Summary
This document describes the documentation requirements for the OpenVMS
release of Gryphon which relate to the Single Sign-On project.
Background
Single Sign-On provides LAN Manager-authenticated logins to OpenVMS.
New management, configuration, and user features added to support single
sign-on are to be documented.
Documentation Requirements
This section contains brief descriptions of each feature that must be
documented:
General description
OpenVMS configuration control parameters
LAN Manager configuration control issues
Changes to the AUTHORIZE utility
Changes to SET PASSWORD
Changes to the SYS$GETUAI and SYS$SETUAI system services
Changes to LOGINOUT.EXE
DECwindows version dependency
Effect on DECnet proxy and Auto-Login databases
Effect on layered products and third-party products
New messages
Release Notes
General Description
Username Mapping and Password Verification
If single sign-on is enabled on the system, and certain user accounts in the
SYSUAF file are marked for external authentication, then these users will be
authenticated using their LAN Manager usernames and passwords. That is, an
externally-authenticated user provides his or her LAN Manager username
and password at the OpenVMS login prompt and these are used for
authentication by a LAN Manager domain controller. Upon successful
authentication, the LAN Manager username is mapped to the appropriate
OpenVMS username to obtain the correct user profile and the login sequence
is completed.
When performing name-mapping, OpenVMS first tries to locate a match in
the SYSUAF file and uses that name if it finds a match; otherwise, it searches
the LAN Manager database for a matching username.
External authentication is supported for interactive logins (including
DECwindows) and network logins where a proxy is used or
username/password is supplied.
Normal OpenVMS users are not affected by external authentication.
What does it mean to be "externally-authenticated"?
Externally-authenticated users are considered to have a single password
(which may be NULL, if so defined) and are not subject to normal OpenVMS
password policy (password expiration, password history, minimum and
maximum password length restrictions), but are instead subject to any defined
LAN Manager policy. All other OpenVMS account restrictions remain in
effect, such as disabled accounts, modal time restrictions, quotas, etc.
Externally-authenticated users are identified by having the EXTAUTH flag
set in their SYSUAF record.
Password Migration and Synchronization
Although password verification is done using the LAN Manager database,
OpenVMS attempts to keep the LAN Manager and SYSUAF password fields
synchronized. This synchronization can occur in either direction from LAN
Manager to the SYSUAF (password synchronization) or from the SYSUAF
to LAN Manager (password migration).
Migration occurs when the password used to login is the same as that stored in
the SYSUAF and the user's MIGRATEPWD bit is found to be set indicating
that the SYSUAF password field has been recently updated. LOGINOUT will
use this password to update the LAN Manager database during the next login
attempt.
Synchronization takes place at the completion of a successful
externally-authenticated login. If the LAN Manager password is different
than the one stored in the SYSUAF file, LOGINOUT will update the
SYSUAF password field with the LAN Manager password. (Synchronization
may not be possible due to the different sets of valid characters allowed by
OpenVMS and LAN Manager.)
If required, password migration and synchronization features may be
selectively turned on or off.
Requirements
External authentication must be explicitly enabled and requires
PATHWORKS for OpenVMS version 5.0E or later (still TBD)
OpenVMS Configuration Issues
Configuration and management is controlled through protected logical names
and two new SYSUAF flags.
SYS$SINGLE_SIGNON logical name
The SYS$SINGLE_SIGNON system-wide executive-mode logical name is
used to control overall operation. The logical name is translated as a
hexadecimal string and treated as a bit vector, with each bit controlling a
separate component
(We need to document where this logical name should be defined during
system startup.)
Numbered from right to left (least significant bit first), bits are defined as
follows:
Bit # Status Description
0ON Enable external authentication. Users tagged in the SYSUAF as
externally-authenticated will use LAN Manager authentication to login.
OFF Disable external authentication. If local authentication is enabled (bit 1
is ON), then local authentication will be attempted using the user's normal
SYSUAF username and password; otherwise, the login will not be allowed.
1ON Enable local authentication. If external authentication is disabled (bit 0
is OFF), then a user can login using local authentication; otherwise, the login
will not be allowed.
OFF Disable local authentication. A user can force local authentication using
the /LOCAL_PASSWORD qualifier. SYSPRV privilege is required to use this
qualifier when bit 1 is OFF.
2ON Disable external password migration. Password migration from the
SYSUAF file to the LAN Manager database will not be performed.
OFF Enable password migration. When a new password is set for a user in the
SYSUAF using AUTHORIZE or $SETUAI, the MIGRATEPWD flag will be
set in the SYSUAF, causing the SYSUAF password to "migrate" over to the
LAN Manager database during the next login.
3ON Enable forced uppercase terminal input during login. This feature is
equivalent to the RMS ROP$V_CVT option. Setting this bit restores previous
OpenVMS behavior, but does not allow for case-sensitive input of username
and password which might be required in future versions of LAN Manager or
by some other authentication service.
OFF Disable forced uppercase terminal input during login.
4ON Disable local password synchronization. Password synchronization from
LAN Manager to the SYSUAF will not be performed.
OFF Enable local password synchronization. During a successful login, an
attempt will be made to synchronize the SYSUAF password with the LAN
Manager password (if they are found to be different) by calculating the
OpenVMS hash value of the LAN Manager password used for login and
storing the hash value in the SYSUAF file.
31 ONEnable OPCOM debug messages. During each login and SET
PASSWORD use, various debugging messages can be displayed on
OPERATOR terminals to help diagnose potential problems with single
sign-on operation.
OFF Disable OPCOM debug messages.
Some examples:
$ DEFINE/SYSTEM/EXECUTIVE SYS$SINGLE_SIGNON 1
This definition enables external authentication (bit 0). All other components
take their default values.
The next definition enables external authentication (bit 0), forces uppercase
terminal input at the "Username:" prompt (bit 3), and disables password
synchronization (bit 4):
$ DEFINE/SYSTEM/EXECUTIVE SYS$SINGLE_SIGNON 19
If SYS$SINGLE_SIGNON is undefined or equates to an invalid
hexadecimal string, all bits are considered OFF.
SYS$ACME_MODULE logical name
The SYS$ACME_MODULE system-wide executive-mode logical name
equates to the file specification of the shareable image that provides the
interface to LAN Manager authentication for EXTAUTH users. This image is
activated during login by LOGINOUT and must be installed as a known
shareable image:
$ INSTALL ADD SYS$LIBRARY:acme-module-name.EXE
/SHARE /OPEN /HEAD
$ DEFINE/SYSTEM/EXECUTIVE SYS$ACME_MODULE
SYS$LIBRARY:acme-module-name.EXE
(Need to document the PATHWORKS ACME module to use in these
commands. Where will this be documented, OpenVMS or PATHWORKS?
New UAF flags: ExtAuth, MigratePwd
Two new OpenVMS authorization flags are defined:
EXTAUTH
If this flag is set, the user is considered to be
"externally-authenticated" by his or her LAN Manager username and
password, not the SYSUAF username and password. (The SYSUAF
record is still used for checking login restrictions and quotas and for
creating the user's OpenVMS process profile.
MIGRATEPWD
When set, this flag indicates that the SYSUAF password for the user
has been set using AUTHORIZE or SYS$SETUAI and is likely to be
inconsistent with the user's LAN Manager password. If password
migration is enabled, the system will attempt to update the LAN
Manager password the next time the user attempts a login.
LAN Manager Configuration Issues
(This information may belong in the Pathworks documentation.)
Pathworks for OpenVMS version 5.0E (or later) required.
The OpenVMS system may be a primary LAN domain controller, backup
(secondary) LAN domain controller, or a simple LAN member.
Microsoft Windows NT (TM) primary domain controllers must be configured
to broadcast LAN Manager 2.x updates. (Need to give more details on where
this is set.)
Changes to the AUTHORIZE utility
Two new SYSUAF record flags are defined:
UAF$V_EXTAUTH
Signifies that external authentication (LAN Manager) is in effect for
this user.
UAF$V_MIGRATEPWD
Signifies that the password in the SYSUAF record has been updated
and that the password change is still to be propagated to the external
authenticator.
Support has been added to the AUTHORIZE utility for the corresponding
user account flags:
EXTAUTH
MIGRATEPWD
Use the following command syntax:
ADD username /FLAG=([NO]EXTAUTH, [NO]MIGRATEPWD)
MODIFY username /FLAG=([NO]EXTAUTH, [NO]MIGRATEPWD)
SHOW username
Flags: EXTAUTH, MIGRATEPWD
Whenever a password is changed on an account that has the EXTAUTH flag
set, the MIGRATEPWD flag is automatically set by AUTHORIZE.
The following informational message is displayed if the EXTAUTH flag is set
%UAF-I-EXTAUTH, ExtAuth set for username; field
modification may have no effect
when any of these fields have been modified:
/ALGORITHM - encryption algorithm for primary/secondary passwords
/FLAGS
DISFORCE_PWD_CHANGE - disable forced password
change
DISPWDDIC - disable password dictionary search
DISPWDHIS - disable password history search
LOCKPWD - disable SET PASSWORD command
PWD_EXPIRED - primary password has expired
PWD2_EXPIRED - secondary password has expired
/GENERATE_PASSWORD - passwords must be generated
/PASSWORD - primary/secondary password
/PWDEXPIRED - password is pre-expired
/PWDLIFETIME - password lifetime
/PWDMINIMUM - minimum password length
/PWDMAXIMUM - maximum password length
Note that when a password is set for an account which is set up for external
authentication, the password is only set in the SYSUAF file. The password is
not propagated to the network.
Changes to the SET PASSWORD command
When a user has logged in using external authentication, the SET
PASSWORD command will attempt to notify the external authentication
service of any password change. The following messages are displayed when
this takes place:
%SET-I-SNDEXTAUTH, Sending password request to
external authenticator
%SET-I-TRYPWDSYNCH, Attempting password
synchronization
If the external authentication service cannot be contacted or the password
change is rejected, an error message is displayed to the user:
%SET-E-EXTPWDERR, Password could not be set by
external authenticator
If the user was not externally authenticated but the EXTAUTH flag is set (eg.
the user logged in with /LOCAL_PASSWORD), the new password is only set
locally in the SYSUAF file (normal OpenVMS password policy checks do not
apply in this case).
Changes to the SYS$GETUAI and SYS$SETUAI system services
Added support for the two new user flags in the SYSUAF record via the
existing UAI$_FLAGS item code. UAI$V_EXTAUTH and
UAI$V_MIGRATEPWD are the two new bits that can be set/returned in the
flags longword bit vector.
Whenever SYS$SETUAI is used to change the password on an account that
has the EXTAUTH flag set, the MIGRATEPWD flag is automatically set.
This pertains to the following item codes:
UAI$_PASSWORD
UAI$_PWD
Changes to LOGINOUT.EXE
External Authentication
Users with EXTAUTH set must provide their LAN Manager username and
password at the login prompt. All authentication decisions for these users are
made by LAN Manager rather than OpenVMS. OpenVMS account
restrictions and quota checks remain in effect.
If local password synchronization was required, a message will be displayed
indicating the outcome the synchronization attempt:
OpenVMS password has been synchronized with network
password
or...
Not able to synchronize OpenVMS password with
network password
The above messages can be suppressed on a per-user basis by setting the
DISREPORT user account flag.
/LOCAL_PASSWORD qualifier
The login command line supports the /LOCAL_PASSWORD qualifier. The
presence of this qualifier indicates to LOGINOUT that the user intends to
override external authentication by using his or her OpenVMS username and
password. SYSPRV privilege is required to use /LOCAL_PASSWORD. Since
the SYSUAF password is normally kept synchronized with the LAN Manager
password, it is possible to use the same password even when logging in using
local authentication. Illegal use of /LOCAL_PASSWORD results in login
failure. Upon a successful login, the following message is displayed:
Local logon successful; network logon service not used
Locally authenticated users are not subject to OpenVMS password policy.
This is because the system manager has specified these users to be subject to
an external authentication policy. Using /LOCAL_PASSWORD (or when
local authentication is enabled) is considered a temporary means for logging
into the system when the external authentication service is unavailable.
DECwindows Version Dependency
DECwindows version 1.2-4 is required for /LOCAL_PASSWORD support.
Effect on DECnet proxy and Auto-Login (ALF) databases
OpenVMS will treat any "username" entry found in the DECnet proxy or
Auto-Login (ALF) databases as a potential LAN Manager username.
When using DECnet proxies, it is important to maintain unique usernames
across OpenVMS and LAN Manager domains. If the same username appears
in the SYSUAF file and LAN Manager database identifying two different
users, then the use of this username as a proxy is ambiguous. LOGINOUT
will treat the name as an OpenVMS username for login purposes, even though
the same name in LAN Manager may map to a different OpenVMS
username. This is due to the name-mapping rules which attempt to find a
match in the SYSUAF before LAN Manager.
Effect on Layered and Third-party Products
A site wishing to employ external authentication may experience problems if
the site is running software that performs any of the following activities:
Using SYS$GETUAI to verifying usernames in the SYSUAF file.
Externally-authenticated users may identify themselves using a LAN
Manager name that is different than their OpenVMS username and
may confuse users.
Validating passwords using SYS$HASH_PASSWORD against values
in the SYSUAF file.
If password synchronization is disabled, SYSUAF passwords may not
be consistent with LAN Manager passwords.
Modifying password-related fields using SYS$SETUAI.
If password migration is disabled, these passwords will not be
automatically updatd in LAN Manager.
LGI callout services.
Use of LGI callouts disables external authentication in this release.
New Messages
LOGIN messages
%LOGIN-F-NOEXTAUTH, external authentication service
disabled or unavailable
%LOGIN-F-NOLOCAUTH, not authorized to override
external authentication
Authorize messages
%UAF-I-EXTAUTH, ExtAuth set for !AD; field
modification may have no effect
SET PASSWORD messages
%SET-I-SNDEXTAUTH, Sending password request to
external authenticator
%SET-I-TRYPWDSYNCH, Attempting password
synchronization
%SET-E-EXTPWDERR, Password could not be set by
external authenticator
System messages
%SYS-F-NOEXTAUTH, external authentication is not
available
%SYS-F-ERRMAPAUTH, error mapping or authenticating
user
%SYS-F-AUTHFAIL, authorization failure
%SYS-F-INVUSER, no such user
ACME messages (These may not be documented in 7.1)
%ACME-S-NORMAL, normal successful completion
%ACME-I-PWDSYNCH, OpenVMS password has been
synchronized with external password
%ACME-I-PWDNOSYNCH, OpenVMS password was not
synchronized with external password
%ACME-I-LOCLOGIN, local logon successful; external
logon service not used
%ACME-E-NOSUCHUSERID, user-id does not exist or is
invalid
%ACME-E-PWDWRONG, password is incorrect
%ACME-E-ACCEXPIRED, account has expired
%ACME-E-PWDEXPIRED, password has expired
%ACME-E-INVALIDTIME, access is denied at this time
%ACME-E-UNSPECIFIED, general error, see secondary
status for details
%ACME-E-PWDINHISTORY, password exists in history
database
%ACME-E-PWDINDICT, password exists in dictionary
database
%ACME-E-PWDTOOSHORT, password less than minimum
length
%ACME-E-PWDTOOLONG, password greater than maximum
length
%ACME-E-PWDINVCHAR, password contains invalid
characters
%ACME-E-PWDTOOEASY, password can be easily guessed
%ACME-E-PWDINVALID, unspecified password policy
restriction
%ACME-E-PWDCANTCHANGE, password can not be changed
%ACME-E-NOLOCAUTH, not authorized to override
external authentication
%ACME-F-AUTHDOWN, external authenticator is
unavailable
Release Notes
OpenVMS "Username:" prompt accepts case-sensitive terminal input
Terminal input at the OpenVMS "Username:" login prompt now accepts
case-sensitive input. To enter a case-sensitive username, you must enclose
the username in quotes ("); otherwise, the normal DCL parsing performed by
LOGINOUT will uppercase the username. (This last sentence is a bit
confusing. The point is, the username will get uppercased by LOGINOUT in
the same fashion as DCL uppercases command input while being echoed
case-sensitive.)
OpenVMS and LAN Manager 2.x usernames are not case-sensitive hence
quotes should not be needed. In the future, other authentication services or
future LAN Manager versions may allow case-sensitive usernames in which
case quotes may become necessary.
A site may restore previous behavior by setting the "forced uppercase"
configuration parameter.
Refer to Configuration section for details.
Case Sensitivity and Character Sets
LAN Manager 2.x usernames and passwords are case insensitive. Valid
characters for usernames and passwords belong to the standard IBM extended
(8-bit) ASCII character set. LOGINOUT and SET PASSWORD pass these
strings to LAN Manager case preserved although the external authentication
service uppercases both strings according to this character set.
Namespace Considerations
OpenVMS usernames and LAN Manager usernames must be unique among
users. This restriction applies across both OpenVMS and LAN Manager
domains. For example, it is unsupported to have an OpenVMS username
"FRED" for one user and a LAN Manager username "FRED" for a different
user. Digital recommends you keep OpenVMS usernames and LAN Manager
usernames the same for each user.
LGI Callout services disable external authentication
In this release, the presence of LGI callouts disables external authentication.
This restriction will be removed in a future release.
DECwindows Pause Screen uses SYSUAF password
The current version of the DECwindows pause screen unlock mechanism does
not use LAN Manager for password validation; it continues to use the
password in the SYSUAF file. Therefore, if password synchronization is
disabled, it is important to keep the LAN Manager and SYSUAF passwords
synchronized manually.
DECnet Proxy usernames must exist in the SYSUAF file
Target usernames specified in DECnet proxies must exist in the SYSUAF file.
Externally-authenticated users wishing to use DECnet proxies must have the
same username in the SYSUAF file and LAN Manager database.
LAN Manager Passwords
LAN Manager passwords can contain characters that are not valid in
OpenVMS passwords. In such cases, local password synchronization will not
be performed and a message issued to that effect. (OpenVMS passwords are
limited to the 7-bit ASCII characters 'A' - 'Z', '0' - '9', '_', and '$'.)
Layered and Third-Party software
General
Software utilizing SYS$HASH_PASSWORD and/or
SYS$GETUAI/SYS$SETUAI to alter, fetch, or verify OpenVMS passwords
will only be affecting the SYSUAF database for externally authenticated users.
Password migration and synchronization features have been added to
minimize breakage to such software. Local site policy requirements may
dictate that these features be disabled or that external authentication itself not
be activated.
Software modifying passwords by writing the SYSUAF directly will not
benefit from password migration since the MIGRATEPWD bit will not be set.
Argus
No support for viewing or setting new SYSUAF flags in this release. This
support will be in a future release. When a password is set, it is set in the
SYSUAF along with the MIGRATEPWD flag (EXTAUTH users only). If
password migration is enabled, the new password will be updated in LAN
Manager during the next login attempt for that user.
Mixed-Version VMSclusters
External authentication is supported in a mixed-version VMScluster.
When operating with systems running versions of OpenVMS earlier than 7.1,
only the 7.1 systems directly interact with LAN Manager; the other systems
will continue to use the SYSUAF file for authentication and management of
passwords. If password synchronization is enabled on the 7.1 systems, the
SYSUAF passwords will be kept synchronized with LAN Manager and users
will be able to log into the 7.0 systems using their OpenVMS usernames and
passwords. LAN Manager usernames cannot be used on these systems. (If a
site maintains identical OpenVMS usernames and LAN Manager usernames,
this will not be an issue.)
Password maintenance performed on 7.0 systems will not be automatically
migrated to LAN Manager because these systems will not have the
MIGRATEPWD user account flag set. In addition, LOGINOUT on 7.0
systems will continue to enforce normal OpenVMS password policy on users
(password expiration, password history, etc.) even if tagged as
externally-authenticated.
For these reasons, running external authentication on mixed-version
VMSclusters with 7.0 systems is not recommended.
Richard J. Barry
STAR::BARRY
barry@star.zko.dec.com
Last Updated: 21 March 1996