Skip to main content

This is documentation for Caché and Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

Please read this important announcement about the future of Caché and Ensemble maintenanceOpens in a new tab. Contact your account team to migrate to InterSystems IRIS.

Users

This chapter includes the following sections:

Properties of Users

Each Caché user account has a number of properties. The following are listed on the General tab for the user:

User Account Properties
Property Name Property Description
Name Unique user identifier that is up to 128 characters long. This can include any character except “@” or “*”. A name is not case-sensitive. All usernames can include Unicode characters.
Full Name The user’s displayable name.
Comment Any text.
Password New password value. This value is never visible, regardless of the privileges of user viewing this page; a user either with the %Admin_Secure:Use privilege or assigned to the %All role can change another user’s password, such as if that user’s password has been forgotten or lost. A password can be up to 128 characters long and is case-sensitive. All paswords can include Unicode characters.
Confirm Password Confirmation of new password value.
Change Password on Next Login A check box specifying whether or not the user is required to change the password at the next login.
Password Never Expires A check box specifying whether or not the system-wide password expiration limit applies to this user. If selected, the user’s password does not expire, even if it has been unchanged for longer than the system limit. To set the password expiration limit, see the System-wide Security Parameters page.
User Enabled A check box specifying whether or not the account is currently enabled.
Expiration Date The last date on which the account can be used.
Account Never Expires A check box specifying whether or not the system-wide account inactivity limit applies to this user. If selected, the user’s account does not expire, even if it has been inactive for longer than the system limit. To set the inactivity limit, see the System-wide Security Parameters page.
Startup Namespace The namespace in which to begin execution following login from a terminal-type service or the Portal. This property overrides any namespace value provided via the command invoking Caché.
Startup Tag^Routine The routine to execute automatically following login from a terminal-type service. This property overrides any routine value provided via the command invoking Caché.
Mobile Phone Service Provider For two-factor authentication, the user’s mobile phone service provider.
Mobile Phone Number For two-factor authentication, the mobile phone number at which the user receives a text message containing the second authentication token (factor).
Type (only displayed on the Users page) The kind of user, which is determined by the authentication and role-assignment mechanisms in use. Values can be Password user, Delegated user, Kerberos user, LDAP user, or OS user. For more information on user types, see the following section, “About User Types.”

About User Types

Among a user’s properties is the user’s Type. There are multiple possible types:

  • Password user — This type is authenticated through Caché login, Kerberos (without delegated authorization), or the operating system (without delegated authorization). The Caché tools for editing or otherwise altering users are for use with Password users.

  • Delegated user — This type is authenticated through a user-defined authentication mechanism. The Caché tools are available only for viewing this type of user’s properties; the user’s properties must be edited through external means.

  • Kerberos user — This type is authenticated using Kerberos when delegated authorization is in use; with delegated authorization, Caché tools are available only for viewing this type of user’s properties; the user’s properties must be edited through external means and specified by the ZAUTHORIZE routine, as described in the chapter “Delegated Authorization.” If a user is authenticated through Kerberos without using delegated authorization, then the user is of type Password User.

  • LDAP user — This type is authenticated through LDAP. The Caché tools are available only for viewing this type of user’s properties; the user’s properties must be edited through external means.

  • OS user — This type is authenticated through the operating system (OS) when delegated authorization is in use; with delegated authorization, Caché tools are available only for viewing this type of user’s properties; the user’s properties must be edited through external means and specified by the ZAUTHORIZE routine, as described in the chapter “Delegated Authorization.” If a user is authenticated through the operating system without using delegated authorization, then the user is of type Password User.

Important:

A user can only have one type. A user of one type cannot log in using authentication mechanisms associated with another type.

Creating and Editing Users

To either create or edit a user, the Management Portal provides the Edit User page, which is off the Users page (System Administration > Security > Users) for each user being created or edited. This page differs for creating and editing users as follows:

Creating a New User

To create a new user:

  1. From the Management Portal home page, go to the Users page (System Administration > Security > Users).

  2. On the Users page, select Create New User. This displays the General tab of the Edit User page for creating and configuring users.

  3. On the Edit User page, set values for the following user properties, which are described in the Properties of Users section:

    • Name (required) — Unique user identifier.

    • Copy from (optional) — The name of another user, the settings of which are to serve as the basis for the new user. See the next step for details.

    • Full Name (optional) — The account’s displayable name.

    • Comment (optional) — Any text.

    • Password (required) — New password value.

    • Confirm Password (required) — Confirmation of new password value.

    • Change Password on Next Login (optional) — Whether or not a password change is required at the next login.

    • Password Never Expires (optional) — Whether or not the user’s password is valid past the system-wide password expiration limit. For information about the password expiration limit, see the System-wide Security Parameters page.

    • User Enabled (required) — Whether or not the account is available for use.

    • Expiration Date (optional) — The last date on which the account is available for use.

    • Account Never Expires (optional) — Whether or not the user’s account remains active past the system-wide inactivity limit. For information about the inactivity limit, see the System-wide Security Parameters page.

    • Startup Namespace (optional) — The namespace in which to begin execution following login from a terminal-type service.

    • Startup Tag^Routine (optional) — The routine to execute automatically following login from a terminal-type service.

    • Mobile phone service provider — For two-factor authentication, the user’s mobile phone service provider. (If the user’s mobile phone service provide does not appear in the list, you can add a new provide by clicking Create new provider; this displays fields for adding a new mobile phone service provider, which will then be visible.

    • Mobile phone number — For two-factor authentication, the mobile phone number at which the user receives the text message containing the second authentication token (factor).

  4. As a shortcut, if you wish to create multiple users with similar characteristics, you can use the Copy from field on the Edit User screen to begin the process of creating a new user. When you select an existing user from this field’s drop-down menu, the following properties of the selected user receive values for the user being created:

    • Full Name

    • Expiration Date

    • Default Namespace

    • Default Tag^Routine

  5. Click the Save button to create the new user.

Once you have created a user account, you can then edit its characteristics.

Editing an Existing User

Once you have created a user account, you can alter any of its basic properties (on the General tab of the Edit User page):

  1. From the Management Portal home page, go to the Users page (System Administration > Security > Users).

  2. On the Users page, there is a table of users. To edit an existing user, select the name of the user from the table. This displays the General tab of the Edit User page for creating and configuring users.

  3. On the Edit User page, you can alter values for the following properties, which are described in the Properties of Users section:

    • Full Name

    • Comment

    • Password — If you use this page to set a new password, the password must conform to the pattern (types of characters and length) specified in the Password Pattern field on the System Security Settings page (System Administration > Security > System Security > System-wide Security Parameters).

    • Change password on next login

    • Password Never Expires

    • User Enabled

    • Expiration Date

    • Account Never Expires

    • Startup Namespace — This refers to the Terminal Namespace property.

    • Startup Tag^Routine — This refers to the Terminal Routine property.

    • Mobile phone service provider

    • Mobile phone number

  4. Click the Save button to save the new values for the user.

You can also modify other aspects of the user account on this page’s other tabs:

  • Roles — Lists the roles that the user currently holds. You can also give a user new roles (or take them away) on this page.

  • SQL Properties — This includes:

    • SQL Privileges — Lists all the SQL privileges that a user currently holds, on a per-namespace basis. You can also assign or revoke SQL privileges on this page.

    • SQL Tables — Lists, by namespace, the tables for which a user has been granted privileges (%ALTER, DELETE, INSERT, REFERENCES, SELECT, and UPDATE). You can also assign or revoke SQL table privileges on this page.

    • SQL Views — Lists, by namespace, the views for which a user has been granted privileges (%ALTER, DELETE, INSERT, REFERENCES, SELECT, and UPDATE). You can also assign or revoke SQL view privileges on this page.

    • SQL Procedures — Lists, by namespace, the stored procedures which a user can run. You can also assign or revoke the right to run procedures on this page.

Note:

A change to a user account only takes effect after the user logs out and then logs back in.

Modifying a User’s Roles

On the Roles tab of the Edit User page, you can assign a user to a role or remove it from a role:

  • To assign a user to a role, first move the role from the Available list to the Selected list (either double-click it or select it and then click the single right-arrow); click the Assign button to assign the user to the role.

  • To assign a user to all roles, click the double-arrow pointing from the Available list to the Selected list; click the Assign button to assign the user to all the roles.

    Note:

    If you assign a user to all roles, this includes the predefined %SecureBreak role, which limits (and does not expand) the user’s abilities. If a user is assigned to the %SecureBreak role, this enables the Caché secure debug shell, which restricts the commands that the user may issue. This may also have unexpected consequences in other areas.

  • To remove a user from a role, click the generated description: roles removebtn button to the right of role name.

  • To remove a user from all roles, click Remove All below the table listing the currently assigned roles. (This button is only present if a user is assigned to two or more roles.)

Modifying a User’s SQL-Related Options

For every user, you can grant or remove the following SQL-related characteristics:

General SQL Privileges

On the SQL Privileges tab of the Edit User page, you can add or remove SQL privilege for a user:

  • To add a privilege to a user, first move the privilege from the Available list to the Selected list (either double-click it or select it and then click the single right-arrow); click the Assign button to give the privilege to the user. To also add the privilege of being able to grant the added privilege to other users, click the relevant button below the Available list.

  • To add all privileges to a user, click the double-arrow pointing from the Available list to the Selected list; click the Assign button to give the privileges to the user. To also add the privileges of being able to grant the added privileges to other users, click the relevant button below the Available list.

  • To remove a privilege from a user, click the Remove link to the right of privilege name.

  • To remove all privileges from a user, click the Remove All button below the table listing the currently assigned privileges.

The following privileges are available:

  • %ALTER _TABLE — For a given namespace, allow the user to run the ALTER TABLE command.

  • %ALTER_VIEW — For a given namespace, allow the user to run the ALTER VIEW command.

  • %CREATE_FUNCTION — For a given namespace, allow the user to run the CREATE FUNCTION command.

  • %CREATE_METHOD — For a given namespace, allow the user to run the CREATE METHOD command.

  • %CREATE_PROCEDURE — For a given namespace, allow the user to run the CREATE PROCEDURE command.

  • %CREATE_QUERY — For a given namespace, allow the user to run the CREATE QUERY command.

  • %CREATE_TABLE — For a given namespace, allow the user to run the CREATE TABLE command.

  • %CREATE_TRIGGER — For a given namespace, allow the user to run the CREATE TRIGGER command.

  • %CREATE_VIEW — For a given namespace, allow the user to run the CREATE VIEW command.

  • %DROP_FUNCTION — For a given namespace, allow the user to run the DROP FUNCTION command.

  • %DROP_METHOD — For a given namespace, allow the user to run the DROP METHOD command.

  • %DROP_PROCEDURE — For a given namespace, allow the user to run the DROP PROCEDURE command.

  • %DROP_QUERY — For a given namespace, allow the user to run the DROP QUERY command.

  • %DROP_TABLE — For a given namespace, allow the user to run the DROP TABLE command.

  • %DROP_TRIGGER — For a given namespace, allow the user to run the DROP TRIGGER command.

  • %DROP_VIEW — For a given namespace, allow the user to run the DROP VIEW command.

Privileges for Tables

On the SQL Tables tab of the Edit User page, you can add or remove table-related SQL privileges for a user:

  1. Choose the relevant namespace from the drop-down near the top of the page. A list of the namespace’s tables will appear.

  2. To change privileges for a table, select the Edit button in that table’s row. This displays a window for altering privileges.

  3. In this window, you can check or uncheck any of the following items:

  4. After making your selection(s), click the Apply button to establish the new privileges for the table.

Privileges on Views

On the SQL Views tab of the Edit User page, you can add or remove view-related SQL privileges for a user.

To add privileges for the view:

  1. Choose the relevant namespace from the drop-down near the top of the page. A list of the namespace’s views will appear.

  2. To change privileges for a view, select the Edit button in that view’s row. This displays a window for altering privileges.

  3. In this window, you can check or uncheck any of the following items:

  4. After making your selection(s), click the Apply button to establish the new privileges for the table.

Privileges for Stored Procedures

On the SQL Procedures tab of the Edit User page, you can add or remove a user’s SQL privileges related to stored procedures.

To add privileges for a stored procedure:

  1. Choose the relevant namespace from the drop-down near the top of the page. A list of the namespace’s stored procedures will appear.

  2. Below this window, click the Add button, which displays the Grant procedure privilege... dialog.

  3. In this dialog, near the top, select the Schema from the drop-down that contains the procedure that you wish to add. This displays a list of the schema’s procedures in the Available window on the left part of the page.

  4. Move one or more procedures into the Selected window. Make sure the EXECUTE box is checked, so that the user has the privilege to execute the stored procedure.

  5. Optionally, you can grant the users the ability to grant this privilege on other users; to do this, click the Grant privilege box near the bottom of the page.

  6. Click the Apply button to grant the privilege(s) to the user.

To remove a user’s stored procedure privileges:

  1. Choose the relevant namespace from the drop-down near the top of the page. A list of the namespace’s stored procedures will appear.

  2. To change privileges for a stored procedure, select the Edit button in that table’s row. This displays a page for altering privileges.

  3. On the page that appears, uncheck the EXECUTE check box and the GRANT privilege check box as appropriate.

  4. Click the Apply button to change the privilege(s) for the user.

Viewing and Managing Existing Users

To view a list of the currently existing users, see the Users page in the Portal (System Administration > Security > Users). This page displays information on the following fields (as described in more detail in the Properties of Users section):

  • User — A unique identifier for the user

  • Full Name — The user’s displayable name

  • Enabled — Whether or not the user is currently enabled

  • Namespace (default namespace) — The initial namespace for a terminal-type connection

  • Routine (default routine) — The initial routine executed for a terminal-type connection

  • Type — The kind of user, which is determined by the authentication and role-assignment mechanisms in use

For each user, you can

Deleting a User

To delete a user:

  1. From the Management Portal home page, go to the Users page (System Administration > Security > Users).

  2. On the Users page, for the user you wish to delete, select the Delete button in that user’s row.

  3. Caché displays a confirmation dialog. Select OK to delete the user and Cancel otherwise.

Viewing a User Profile

A user profile provides security information about a user account, such as the roles to which the user is assigned and the time of the user’s last login. To view a user’s profile, the procedure is:

  1. From the Management Portal home page, go to the Users page (System Administration > Security > Users).

  2. On the Users page, in the row for the user, click Profile. This displays the user’s profile.

Alternately, if the Edit User page is visible for a user, click Profile in the upper-left corner of the page.

The following properties are listed as part of the user profile.

User Profile Properties
Property Name Property Description
Name Unique user identifier. This can include any characters except the @, which is used to identify a domain. This is editable on the Edit User page.
Full Name The user’s displayable name. This is editable on the Edit User page.
Roles A comma-separated list of roles assigned to user. These are editable on the Roles tab of the Edit User page.
Last Password Change The date and time of user’s most recent password change.
Last Login The date and time of most recent successful login or 0 if there has not yet been a successful login. Read-only.
Last Login Device The IP address of the host from which the user last logged in.
Invalid Login Attempts The number of invalid login attempts since the most recent successful login. Read-only.
Last Invalid Login The date and time of most recent invalid login attempt. Read-only.
Last Invalid Login Device The IP address of the host from which the user last unsuccessfully attempted to log in.
Last Reason for Failing to Login The error thrown for the most recent invalid login attempt. Read-only.
Time account was created The date and time at which the user account was created. Read-only.
Username who created account The account name associated with the user who created the account. Read-only.
Time account was last modified The date and time at which the account was last modified. Read-only.
Username who last modified account The account name associated with the user who last modified the account. Read-only.
Information last modified in account A list of properties that were last modified for the account. Read-only.

Predefined User Accounts

Every instance of Caché automatically includes the following accounts:

Predefined Users
Username Assigned Roles Purpose
Admin %Manager Default administrator account. This account exists for all instances of all InterSystems products to support instance administration. InterSystems recommends that you change the password for this account from its initial value prior to going into production.
CSPSystem (None) Default account representing the CSP Gateway when it connects to Caché via Caché login for Normal and Locked-down instances. InterSystems recommends that you change the password for this account from its initial value prior to going into production.
SuperUser %All Default account with all privileges available. This account exists for all instances of all InterSystems products to provide complete access to all aspects of the product. InterSystems recommends that you change the password for this account from its initial value prior to going into production.
UnknownUser %All (Minimal security) or None (Normal or Locked-Down security) Default account for a non-logged in user
_PUBLIC (None) Set of privileges given to all users (not a login account).
_SYSTEM %All Default SQL account. This account exists for all instances of all InterSystems products to provide SQL access. InterSystems recommends that you disable this account for production systems.
_Ensemble %All Internal Ensemble user (not a login account). Only on Ensemble instances.

There is also an account called a “privileged user account,” which is created during Normal and Locked Down installations and for which you supply a username and password.

It is not possible to delete the following accounts:

  • _Ensemble

  • _PUBLIC

  • _SYSTEM

  • UnknownUser

You can delete other predefined user accounts, subject to the requirement that there be at least one user with the %All role.

Caution:

If the _SYSTEM account is available with its default password of “SYS” on deployed systems, this is a security vulnerability. To address this issue, you can disable the account or change its password. InterSystems recommends disabling the account.

Default Predefined Account Behavior

The predefined accounts have different defaults and behavior depending on whether an installation uses Minimal security, Normal security, or Locked Down security.

Minimal Security Defaults

For an installation with Minimal security, all the created accounts except _PUBLIC have an initial default password of “SYS”. With the exception of UnknownUser, you should change the account passwords after installation in order to prevent unauthorized access to your Caché instance.

The _PUBLIC account has no password by default and should never be given a password, since it is never enabled.

Normal Security Defaults

For an installation with Normal security, all the created accounts except _PUBLIC receive the same password as is chosen for the privileged user account. It is recommended that you change these passwords after installation, so that each account has its own password.

The _PUBLIC account has no password by default and should never be given a password, since it is never enabled.

Locked Down Security Defaults

For an installation with Locked Down security, all the created accounts except _PUBLIC receive the same password as is chosen for the privileged user account. It is recommended that you change these passwords after installation, so that each account has its own password.

The _PUBLIC account has no password by default and should never be given a password, since it is never enabled. In Locked-Down installations, the _SYSTEM account is also disabled.

Notes on Various Accounts

The UnknownUser Account

For certain applications, or certain parts of an application, unauthenticated users may have a legitimate reason to use Caché, such as for a retail system to display availability of products, prior to the user initiating a purchase. For this type of situation, Caché supports the UnknownUser account. When an unauthenticated user connects, a special name, UnknownUser, is assigned to $USERNAME and the roles defined for that user are assigned to $ROLES.

Unauthenticated access is not used when authentication fails. For example, suppose that a user attempts to connect to Caché via terminal and supplies a username and password that fails authentication. Here, the user is not connected to Caché, even if unauthenticated access is permitted; on the other hand, if unauthenticated access is permitted and that same user connects to Caché without supplying a username (such as by pressing the Enter key at the username prompt), then that user is connected as UnknownUser, the unauthenticated user. Similarly, if an ODBC client attempts to connect with null strings for username and password, that connection will be accepted if unauthenticated access is permitted for the service; if the same ODBC client provides a non-empty username and password values that fail authentication, that client is not connected even if unauthenticated access is permitted.

The _PUBLIC Account

The predefined user, _PUBLIC, is a special account that does not exist for logins. Rather, it holds a set of roles. These roles are specified as the default roles for any user who connects to the system. This ensures a minimum set of roles for any user. For example, if you associate the %Operator role with the _PUBLIC user, then the value of $Roles for any user will always include %Operator.

Validating User Accounts

If you need to validate user accounts in application code, you can do this by creating a simple routine that attempts to log the user in with the one-argument form of the $SYSTEM.Security.Login method. If the login succeeds, the user is valid; if the login fails, the user is not valid. When the routine exits (regardless of the login’s success or failure), the current user will be the user who invoked the routine.

Here is a sample routine to perform this task, called ValidateUser:

ValidateUser(TestUser) {
    Write "Validating ",TestUser,"...",!
    New $Roles
    Set sc = $SYSTEM.Security.Login(TestUser)
    If sc = 1 {
        Write $Username," is a valid user.",!
        Write $Username," belongs to the following login roles: ",$Roles,!
    } Else {
        Write TestUser," is not a valid user.",!
    }
    Quit sc
}

This routine takes as its single argument, a string that is the name of the user to be validated. It then performs the following actions:

  1. The call of New $Roles stacks both the $Roles variable and the $Username variable. For more information on $Roles, see the $Roles reference page.

  2. It then invokes the one-argument form of the $SYSTEM.Security.Login method, which attempts to log the user in and does not require the user’s password. If the login succeeds, the method returns 1; this determines the information that the routine displays and the routine’s return value.

  3. When the routine exits, this implicitly logs out the user, if there has been a successful login.

Important:

This routine uses the one-argument form of the $SYSTEM.Security.Login method. To successfully invoke the one-argument form of $SYSTEM.Security.Login, a user must have the CACHESYS:Write and %Service_Login:Use privileges. For more information on $SYSTEM.Security.Login, see the reference page for the %SYSTEM.SecurityOpens in a new tab class.

Here is a sample routine that demonstrates invoking ValidateUser, called VUTest. It is hard-coded to test two users, one called ValidUser and one called NonexistentUser:

VUTest() {
    Write $Username," is the current user.",!,!
    
    Set sc = $$^ValidateUser("ValidUser")
    Write !
    
    Write "Exited validation code. ",$Username," is the current user.",!,!
    
    Set sc = $$^ValidateUser("NonexistentUser")
    Write !
    
    Write "Testing complete.",!
    Write $Username," is the current user."
    Quit 1
}

Suppose the VUTest routine were created in the User namespace of a Caché instance, the PrivilegedUser account were a member of the %All role, and only the ValidUser were to exist. Here are the results of invoking VUTest at a Terminal prompt:

Username: PrivilegedUser
Password: ***********
USER>d ^VUTest
PrivilegedUser is the current user.
 
Validating ValidUser...
ValidUser is a valid user.
ValidUser belongs to the following login roles: %Manager
 
Exited validation code. PrivilegedUser is the current user.
 
Validating NonexistentUser...
NonexistentUser is not a valid user.
 
Testing complete.
PrivilegedUser is the current user.
USER>
Next sectionServices
Previous sectionRoles
FeedbackOpens in a new tab