Developer's Guide for Single Signon This document explains what OpenVMS is doing in the Single Signon space in the OpenVMS V7.1 timeframe, and how these changes can affect or potentially break layered products and applications. Also included are details on what you have to do to support Single Signon if you are affected by these changes. This document is provided as a single web page in order that it be easily printable. Contents What Is Changing? Who is Affected How to Fix It What If You Don't Fix It? Contact Information What Is Changing? OpenVMS is adding support for External Authentication mechanisms in V7.1. This is part of the larger Single Signon project which is scheduled for inclusion in OpenVMS V7.2. External Authentication External Authentication will allow something other than OpenVMS to authenticate a user at login time. This means that a user who is externally authenticated will not be authenticated against the username and password that exists in the System Authorization File (SYSUAF). Note that this does not mean that a user no longer needs to have an entry in the SYSUAF; indeed, a SYSUAF record is still required so that LOGINOUT can obtain the user's UIC, privileges, quotas, etc. What it does mean is that the password stored in SYSUAF is not the password used to verify the user, and that a userid is not necessarily an OpenVMS username. Passwords If a user is being externally authenticated, then LOGINOUT does not check the user-supplied password against the password that is stored in the user's SYSUAF record. Instead, LOGINOUT calls out to the external authentication routine and it is this external authentication routine that is responsible for verifying the user's password. In the case of the LAN Manager authentication routine for example, it would verify the user against the information that was stored in the domain's UAS file. This external password is referred to as the user's Network Password. OpenVMS attempts to keep the user's SYSUAF and Network passwords synchronized in order to minimize application breakage. Normally there will be an up to date copy of the user's network password stored in the SYSUAF record, but this can not be guaranteed (for example, the user's network password may contain characters that are not valid in an OpenVMS password). Userid and Username A user who has an account and password in some other authentication domain is identified by a userid in the domain. This userid may or may not be the same as the user's OpenVMS username. In cases where the userid and username are not the same, the user enters their userid when accessing the OpenVMS system. How is External Authentication Controlled External Authentication is controlled at two levels; system level and user level. A new flag in the SYSUAF record determines whether individual users are authenticated by OpenVMS or by an External Authenticator, hence external authentication can be enabled on a per-user basis. External Authentication is also controlled system wide by the setting of a logical name. Until this logical is set, external authentications will not be attempted, regardless of the setting of the users' external authentication flags. External Authentication is disabled by default. When Does This Appear? This functionality was introduced in FT1 (BL5) of OpenVMS V7.1. On AXP this corresponds to builds X67V and later. On VAX this corresponds to builds X6FL and later. Who is Affected Applications that perform any of the following tasks are affected and should read the appropriate topics in the How To Fix It section that follows. Attempt to validate a username either directly by reading the SYSUAF file or indirectly by calling $GETUAI. Attempt to authenticate a user by hashing a password and comparing it with the user's hashed password in the SYSUAF file (either directly by reading the password from the SYSUAF or indirectly by reading the hashed password via a $GETUAI call). Attempt to set a password by calling $SETUAI with either a plaintext or hashed password. Attempt to set a password by directly writing a new hashed password into a SYSUAF record. How to Fix It This section examines each of the problem areas listed in the Who Is Affected section above and explains what is needed to remedy the situation. Validating a Username The issue here is that for an externally authenticated user, their network userid is not necessarily the same as their OpenVMS account name, and when accessing the OpenVMS system they will be supplying their network userid. For example, an OpenVMS system is set up to externally authenticate me via LAN Manager. My OpenVMS account name is BLAKE but my LAN Manager userid is COLIN. When I access the system I specify COLIN as my userid. Code such as LOGINOUT or applications such as FAL or UCX that handle userids must be aware of this. It is no longer valid to look up a userid in the SYSUAF (either directly or via $GETUAI). In this example, a lookup of COLIN in the SYSUAF would either fail or find the wrong user record. Any code that deals with userids can not assume that they are dealing with usernames. A map operation must be performed in order to determine the OpenVMS account name (or username) that is associated with the supplied userid. The new system service, $LOGON, is used to perform this task ($LOGON will be fully implemented and supported in OpenVMS V7.2, until then there is sufficient support in the V7.1 version of $LOGON to perform the userid to username mapping function). ! ! Perform userid-to-username mapping. We pass in the userid in the ! ACME$_USERID item in the itemlist, and get back the OpenVMS username ! in the ACME$_OUTPUT_VMS_USERNAME output item. ! ! A return of SS$_NORMAL means that the userid exists as an username in the SYSUAF ! file and user is NOT being externally authenticated. A return of SS$_REMOTE ! (also a success status) means that the user is being externally authenticated ! and that their OpenVMS username is returned via the ACME$_OUTPUT_VMS_USERNAME ! item. ! ! Any other status return is an error and should be treated as "no such user". ! ! Note that if either success status is returned (SS$_NORMAL or SS$_REMOTE) then ! a valid OpenVMS username is returned via the ACME$_OUTPUT_VMS_USERNAME item. ! $ITMLST_INIT (ITMLST = itmlst, (ITMCOD = ACME$_USERID, BUFADR = .userid[DSC$A_POINTER], BUFSIZ = .userid[DSC$W_LENGTH]), (ITMCOD = ACME$_OUTPUT_VMS_USERNAME, BUFADR = .username[DSC$A_POINTER], BUFSIZ = .username[DSC$W_LENGTH], RETLEN = username[DSC$W_LENGTH])); status = SYS$LOGONW (0, ACME$_MAP_TO_USERNAME, itmlst, 0, 0, iosb, 0, 0); IF .status THEN status = .iosb[0]; Upon successful completion of $LOGON, the caller knows the OpenVMS account name (username) associated with the user, and can then proceed as before to look it up in the SYSUAF file. Authenticating a User So you have a userid and password and you wish to authenticate the user. There are in fact two problems here. The first is that you have to map the userid to its OpenVMS username (you can not assume that what the user gives you is an OpenVMS username). This is the problem discussed above in Validating a Username. The second problem is that for externally authenticated users, we have to call out to the external authentication routine to validate the user. It is wrong to compare the user-supplied password with the password that is stored in the SYSUAF file. It is this problem that this section addresses. For externally authenticated users it is necessary to call out to the external authentication routine in order to authenticate the user. Although the SYSUAF should have an up-to-date copy of the user's network password, this can not be guaranteed. In addition, the external authentication routine may implement additional security policy that you are not aware of. An externally authenticated user is identified by having the ExtAuth flag set in their SYSUAF record. Regardless of if the user is being externally authenticated or not, you should always call $LOGON to perform the authentication. $LOGON will first perform the userid to username mapping function, then determine if the user is being externally authenticated, and if necessary, load and call the appropriate external authentication routine. For non-externally authenticated users $LOGON will compare the supplied password with the user's password from the SYSUAF record. $LOGON is a new system service and will be fully implemented and supported in OpenVMS V7.2. Until then there is sufficient support in the V7.1 version of $LOGON to perform the authentication operation. Sample code follows: ! ! Perform authentication: we just pass in userid and password. We get back the ! OpenVMS username (optionally). ! $ITMLST_INIT (ITMLST = itmlst, (ITMCOD = ACME$_USERID, BUFADR = .userid[DSC$A_POINTER], BUFSIZ = .userid[DSC$W_LENGTH]), (ITMCOD = ACME$_PASSWORD, BUFADR = .password[DSC$A_POINTER], BUFSIZ = .password[DSC$W_LENGTH]), (ITMCOD = ACME$_OUTPUT_VMS_USERNAME, BUFADR = .username[DSC$A_POINTER], BUFSIZ = .username[DSC$W_LENGTH], RETLEN = username[DSC$W_LENGTH])); status = SYS$LOGONW (0, ACME$_VERIFY_PASSWORD_ONLY, itmlst, 0, 0, iosb, 0, 0); IF .status THEN status = .iosb[0]; Setting a New Password via $SETUAI Any code that updates an externally authenticated user's password by calling $SETUAI should continue to work without change. Although for externally authenticated users the user's network password is not stored in the SYSUAF (only a cached copy exists there), a mechanism exists that allows a local password change to be migrated out to the network authenticator. It works as follows. When $SETUAI writes a new password to the SYSUAF record, it also sets the MigratePwd flag. At this point the user's new network password in correct in the SYSUAF and the password held by the network authenticator is stale. The situation remains like this until the next time the user logs in to the OpenVMS system. Then, LOGINOUT sees the MigratePwd flag is set, and calls $SET_PASSSWORD which causes the user's new password to be sent to the external authenticator. Finally LOGINOUT clears the MigratePwd flag. This technique is known as Reverse Password Synchronization. Note that this solution is not perfect as there is a window between the user's password getting set on the OpenVMS system and it being migrated out to the network authenticator. If the user tries to log in to another system within the domain during this period then their new password will not work (they will have to supply their old password). The correct solution is for applications to call $SET_PASSWORD instead of $SETUAI, but the $SET_PASSWORD service is not generally available in the V7.1 release (it will be documented and available in the V7.2 release). If Reverse Password Synchronization is not an acceptable solution for you, please contact OpenVMS engineering and we can discuss the possibility of your application calling $SET_PASSWORD in V7.1. Setting a New Password via writing to the SYSUAF Any code that updates an externally authenticated user's password by writing directly to the SYSUAF file is broken. This is because for externally authenticated users, the password is not stored in the SYSUAF (only a cached copy of the user's password is maintained in the SYSUAF but this is effectively a read-only copy). So although the write to the SYSUAF record will succeed, when the user logs in LOGINOUT will not use the SYSUAF password. Instead it will call the network authenticator to validate the user, and upon successful completion store the user's current network password in the SYSUAF record, overwriting the "new" password. A workaround may be for LOGINOUT to use Reverse Password Synchronization as described in the previous section, Setting a New Password via $SETUAI. For this to happen you must manually set the MigratePwd flag when you update the SYSUAF record of a user who is externally authenticated. For example: IF .uafrec[uaf$v_extauth] THEN uaf_record[uaf$v_migratepwd] = TRUE; This will cause the new password to be migrated out to the network authenticator the next time the user logs in. If Reverse Password Synchronization is not an acceptable solution for you, please contact OpenVMS engineering and we can discuss the possibility of your application calling $SET_PASSWORD in V7.1. What If You Don't Fix It? What's going to happen if you've determined that your code falls into one or more of the categories listed above, but for some reason you can not change the code in the V7.1 timeframe? Well, remember that nothing breaks if Single Signon is not enabled. And by default Single Signon is disabled. And even when Single Signon is enabled, its only users who are externally authenticated that will be affected. It may be that your code is used in an environment where Single Signon will not be used. If this is true, you are indeed lucky! But if Single Signon is going to be used in the environment where your application is used, the information above should allow you to determine exactly what won't work in your application and document it accordingly. However, we urge all application groups to fix any breakage in the OpenVMS V7.1 versions of their products if at all possible. OpenVMS will help you in any way we can to resolve any issues that arise and answer any further questions you may have. Contact Information If you have any questions regarding Single Signon please contact: Single Signon in OpenVMS 7.1 - Colin Blake at blake@star.zko.dec.com Single Signon in OpenVMS 7.2 - Rick Barry at barry@star.zko.dec.com Last Updated - 3/25/96