Caution:
Because InterSystems IRIS does not and cannot place any constraints on the authorization code in ZAUTHORIZE, the application programmer is responsible for ensuring that this code is sufficiently secure.
ZAUTHORIZE and User Properties
Elements of the Properties array specify values of attributes associated with the user specified by the Username parameter. Typically, code within ZAUTHORIZE sets values for these elements. The elements in the Properties array are:
-
Properties("Comment") — Any text.
-
Properties("FullName") — The first and last name of the user.
-
Properties("NameSpace") — The default namespace for a Terminal login.
-
Properties("Roles") — The comma-separated list of roles that the user holds in InterSystems IRIS.
-
Properties("Routine") — The routine that is executed for a Terminal login. A value of "" specifies that the Terminal run in programmer mode.
-
Properties("Password") — The user’s password.
-
Properties("Username") — The user’s username.
Each of these elements is described in more detail in one of the following sections.
Note:
It is not possible to manipulate the value of any member of the Properties array after authorization.
FullName
If ZAUTHORIZE returns a value for Properties("FullName"), then that string becomes the value of the user account’s Full name property in InterSystems IRIS. (This property is described in User Account Properties.) If no value is passed back to the calling routine, then the value of Full name for the user account is a null string and the relevant field in the Management Portal holds no content.
NameSpace
If ZAUTHORIZE sets the value of Properties("Namespace"), then that string becomes the value of the user account’s Startup Namespace property in InterSystems IRIS. (This property is described in User Account Properties.) If no value is passed back to the calling routine, then the value of Startup Namespace for the user account is a null string and the relevant field in the Management Portal holds no content.
Once connected to InterSystems IRIS, the value of Startup Namespace — as specified by the value of Properties("Namespace") — determines the initial namespace for any user authenticated for local access (such as for Console, Terminal, or Telnet). If Startup Namespace has no value, then the initial namespace for any user authenticated for local access is determined as follows:
-
If the USER namespace exists, that is the initial namespace.
-
If the USER namespace does not exist, the initial namespace is the %SYS namespace.
Note:
If the user does not have the appropriate privileges for the initial namespace, access is denied.
Password
If ZAUTHORIZE sets the value of Properties("Password"), then that string becomes the value of the user account’s Password property in InterSystems IRIS. (This property is described in User Account Properties.) If no value is passed back to the calling routine, then the value of Password for the user account is a null string and the relevant field in the Management Portal then holds no content.
If ZAUTHORIZE returns a password, this allows the user to log in to the system via Password authentication if it is enabled. This is a possible mechanism to help migrate from delegated authentication to Password authentication, though with the usual cautions associated with the use of multiple authentication mechanisms; see Cascading Authentication for more details.
Roles
If ZAUTHORIZE sets the value of Properties("Roles"), then that string specifies the Roles to which a user is assigned; this value is a string containing a comma-delimited list of roles. If no value is passed back to the calling routine, then there are no roles associated with the user account and the Management Portal indicates this. Information about a user’s roles is available on the Roles tab of a user’s Edit User page and a user’s profile.
If any roles returned in Properties("Roles") are not defined, then the user is not assigned to the role.
Hence, the logged-in user is assigned to roles as follows:
-
If a role is listed in Properties("Roles") and is defined by the InterSystems IRIS instance, then the user is assigned to the role.
-
If a role is listed in Properties("Roles") and is not defined by the InterSystems IRIS instance, then the user is not assigned to the role.
-
A user is always assigned to those roles associated with the _PUBLIC user. A user also has access to all public resources. For information on the _PUBLIC user, see The _PUBLIC account; for information on public resources, see Services and their resources.
Routine
If ZAUTHORIZE sets the value of Properties("Routine"), then that string becomes the value of the user account’s Startup Tag^Routine property in InterSystems IRIS. (This property is described in User Account Properties.) If no value is passed back to the calling routine, then the value of Startup Tag^Routine for the user account is a null string and the relevant field in the Management Portal then holds no content.
If Properties("Routine") has a value, then this value specifies the routine to execute automatically following login on a terminal-type service (such as Console, Terminal, or Telnet). If Properties("Routine") has no value or a value of "", then login starts the Terminal session in programmer mode, subject to whether they have the privilege to access programmer mode or not.
Username
If ZAUTHORIZE sets the value of Properties("Username"), then that string becomes the value of the user account’s Name property in InterSystems IRIS. (This property is described in User Account Properties.) This provides the application programmer with an opportunity to normalize content provided by the end-user at the login prompt (while ensuring that the normalized username only differ by case).
If there is no explicit call that passes the value of Properties("Username") back to the calling routine, then there is no normalization and the value entered by the end-user at the prompt serves as the value of the user account’s Name property without any modification.
The User Information Repository
ZAUTHORIZE can refer to any kind of repository of user information, such as a global or an external file. It is up to the code in the routine to set any external properties in the Properties array so that the authenticated user can be created or updated with this information. For example, while a repository can include information such as roles and namespaces, ZAUTHORIZE code must make that information available to InterSystems IRIS.
If information in the repository changes, this information is only propagated back into the InterSystems IRIS user information if there is code in ZAUTHORIZE to perform this action. Also, if there is such code, changes to users’ roles must occur in the repository; if you change a user’s roles during a session, the change does not become effective until the next login, at which point the user’s roles are reset by ZAUTHORIZE.