User Properties
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
-
Properties("Password") — The user’s password
-
Properties("Username") — The user’s username
-
Properties("PhoneNumber") — The user’s mobile phone number, for use with two-factor authentication
-
Properties("PhoneProvider") — The user’s mobile phone’s service provider, for use with two-factor authentication
Each of these elements is described in more detail in one of the following sections.
Note:
The value of each element in the properties array determines the value of its associated property for the user being authenticated. It is not possible to use only a subset of the properties or to manipulate their values after authentication.
FullName
If ZAUTHENTICATE sets the value of 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 then holds no content.
NameSpace
If ZAUTHENTICATE 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 then holds no content.
Once connected to InterSystems IRIS, the value of Startup Namespace (hence, that 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 (since Properties("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 ZAUTHENTICATE 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.
Roles
If ZAUTHENTICATE 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 the value of Roles for the user account is a null string and the relevant field in the Management Portal then holds no content. Information about a user’s roles is available on the Roles tab of a user’s Edit User page.
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 ZAUTHENTICATE 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 for Console, Terminal, or Telnet). If Properties("Routine") has no value, then login starts the Terminal session in programmer mode.
Username
If ZAUTHENTICATE returns the Username property, then the value of Username is written to the security database after any processing in the function; this provides chance to modify the value that the user entered at the prompt. If ZAUTHENTICATE does not return the Username property, then the value of the property is written to the security database as entered.
If ZAUTHENTICATE 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.
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.
PhoneNumber and PhoneProvider
These are properties associated with two-factor authentication.
If ZAUTHENTICATE sets the value of Properties("PhoneNumber") and Properties("PhoneProvider"), then these then these are written to the InterSystems IRIS database for the user as the user’s mobile phone number and mobile phone service provider. If these are not passed back to the calling routine, then the phone number and service provider written to the InterSystems IRIS database are a null string. Hence, to use two-factor authentication with delegated authentication, you must supply both of these.
The User Information Repository
ZAUTHENTICATE 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, ZAUTHENTICATE 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 ZAUTHENTICATE 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 re-set by ZAUTHENTICATE.