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