Skip to main content

Advanced Topics in Authentication

System Variables and Authentication

After authentication, two variables have values:

  • $USERNAME contains the username

  • $ROLES contains a comma-delimited list of the roles that the user holds

You can use the $ROLES variable to manage roles programmatically.

Use Multiple Authentication Mechanisms

The one situation in which InterSystems recommends the use of multiple authentication mechanisms is when moving from a less rigorous mechanism to a more rigorous one. For example, if an instance has been using no authentication and plans to make a transition to Kerberos, the following scenario might occur:

  1. For the transition period, configure all supported services to allow both unauthenticated and Kerberos-authenticated access. Users can then connect using either mechanism.

  2. If appropriate, install new client software (which uses Kerberos for authentication).

  3. Once the list of InterSystems IRIS users has been synchronized with that in the Kerberos database, shut off unauthenticated access for all services.

The use of multiple authentication mechanisms is often in conjunction with cascading authentication, described in the next section.

Cascading Authentication

While InterSystems IRIS supports for a number of different authentication mechanisms, InterSystems recommends that you do not use any other password-based authentication mechanism along with Kerberos. Also, there are limited sets of circumstances when it is advisable for an instance to have multiple authentication mechanisms in use.

If a service supports multiple authentication mechanisms, InterSystems IRIS uses what is called cascading authentication to manage user access. With cascading authentication, InterSystems IRIS attempts to authenticate users via the specified mechanisms in the following order:

  • Kerberos cache (includes Kerberos with or without integrity-checking or encryption)

  • OS-based

  • LDAP (with checking the LDAP credentials cache second)

  • Delegated

  • Instance authentication

  • Unauthenticated


If a service specifies Kerberos prompting and this fails, there is no cascading authentication. If a service specifies both Kerberos prompting and Kerberos cache, then InterSystems IRIS uses Kerberos cache only.

For example, if a service supports authentication through:

  1. Kerberos cache

  2. OS-based

  3. Unauthenticated

If a user attempts to connect to InterSystems IRIS, then there is a check if the user has a Kerberos ticket-granting ticket; if there is such a ticket, there is an attempt to obtain a service ticket for InterSystems IRIS. If this succeeds, the user gets in. If either there is no initial TGT or an InterSystems service cannot be obtained, authentication fails and, so, cascades downward.

If the user has an OS-based identity that is in the InterSystems IRIS list of users, then the user gets in. If the user’s OS-based identity is not in the InterSystems IRIS list of users, then authentication fails and cascades downward again.

When the final option in cascading authentication is unauthenticated access, then all users who reach this level gain access to InterSystems IRIS.


If an instance supports cascading authentication and a user is authenticated with the second or subsequent authentication mechanism, then there have been login failures with any mechanisms attempted prior to the successful one. If the %System/%Login/LoginFailure audit event is enabled, these login failures will appear in the instance’s audit log.

Establish Connections with the UnknownUser Account

If instance authentication and unauthenticated mode are both enabled, then a user can simply press Enter at the Username and Password prompts to connect to the service in unauthenticated mode, using the UnknownUser account. If only instance authentication is enabled, then pressing Enter at the Username and Password prompts denies access to the service; InterSystems IRIS treats this as a user attempting to log in as the UnknownUser account and providing the wrong password.

Programmatic Logins

In some situations, it may be necessary for a user to log in after execution of an application has begun. For example, an application may offer some functionality for unauthenticated users and later request the user to log in before some protected functionality is provided.

An application can call the InterSystems IRIS log in functionality through the Login method of the $SYSTEM.Security class with the following syntax:

 set success = $SYSTEM.Security.Login(username,password)


  • success is a boolean where 1 indicates success and 0 indicates failure

  • username is a string holding the name of the account logging in

  • password is a string holding the password for the username account

If the username and password are valid and the user account is enabled and its expiration date has not been reached, then the user is logged in, $USERNAME and $ROLES are updated accordingly, and the function returns 1. Otherwise, $USERNAME and $ROLES are unchanged and the function returns 0.

No checking of privileges occurs as a result of executing $SYSTEM.Security.Login. As a result, it is possible that the process has lost privileges that were previously held.

There is also a one-argument form of $SYSTEM.Security.Login:

 set success = $SYSTEM.Security.Login(username)

It behaves exactly the same as the two-argument form except that no password checking is performed. The single-argument form of $SYSTEM.Security.Login is useful when applications have performed their own authentication and want to set the InterSystems IRIS user identity accordingly. It can also be used in situations where a process is executing on behalf of a specific user but is not started by that user.


The single-argument form of the Login method is a restricted system capability.

The JOB Command and Establishing a New User Identity

When a process is created using the JOB command, it inherits the security characteristics (that is, the values of $USERNAME and $ROLES) of the process that created it. Note that all roles held by the parent process, User as well as Added, are inherited.

In some cases, it is desirable for the newly created process to have $USERNAME and $ROLES values that are different from its parent’s values. For example, a task manager might be created to start certain tasks at certain times on behalf of certain users. While the task manager itself would likely have significant privileges, the tasks should run with the privileges of the users on whose behalf they are executing, not with the task manager’s privileges.

The following pseudocode illustrates how this can be done:

WHILE ConditionToTest {
    IF SomeThingToStart {
        DO Start(Routine, User)

Start(Routine, User) {
    NEW $ROLES    // Preserve $USERNAME and $ROLES

    // Try to change username and roles
    IF $SYSTEM.Security.Login(User) {
        JOB ...
        QUIT $TEST
    QUIT 0       // Login call failed

Authentication and the Management Portal

The Management Portal consists of several separate web applications. The main page of the Portal is associated with the /csp/sys application and other pages are associated with various /csp/sys/* applications (such as the security-related content, which is associated with the /csp/sys/sec application). If the applications do not all have a common set of authentication mechanism(s) in use, users going from one Portal page to another may encounter login prompts or sudden shifts in their level of privilege.

For example, if the /csp/sys application is using instance authentication exclusively, while other related Portal applications are using unauthenticated access exclusively, then, as users move from one Portal page to another, they go from unauthenticated access to requiring authentication. Another possible case is this: the /csp/sys application supports only instance authentication, the other applications support only unauthenticated access, and UnknownUser has no special privileges; in this case, when users go from the Portal’s main page to its other pages, they may not have sufficient privileges to perform any action.

To check and configure the authentication mechanism for a web application, select the application from the Web Applications page in the Portal (System Administration > Security > Applications > Web Applications) and, for the displayed application, make selections under Allowed Authentication Methods as appropriate (typically, so that /csp/sys and /csp/sys/* share a common set of authentication mechanisms).

FeedbackOpens in a new tab