Skip to main content

Authentication and Passwords

Authentication and Passwords

OS-based authentication (see Operating System–Based AuthenticationOpens in a new tab in the Authentication Guide) is enabled for the InterSystems IRIS instance in a container created from an InterSystems image, and password authentication is disabled for the owner (irisowner).

InterSystems IRIS is installed with several predefined user accounts, including the _SYSTEM account (see Predefined User AccountsOpens in a new tab in the Authorization Guide). The default password for the predefined accounts is SYS. For effective security, it is important that this default password be changed immediately upon deployment of your container, which can be done using one of the following approaches. Any of these methods can be incorporated into automated deployment.


If you do not use one of the methods listed here to modify the default password, it is critical that you either log into each predefined account and change the password or disableOpens in a new tab the accounts as soon as possible. Only the iris-main --password-file option, described below, changes the password (SYS) for the predefined CSPSystem account, which is used by the InterSystems Web GatewayOpens in a new tab to authenticate to the InterSystems IRIS instances in its server access configuration. If you do not use the --password-file option in particular to change the default password, you must log into the CSPSystem account and change the password as soon as possible. For information about configuring Web Gateway authentication, see Protecting Web Gateway Connections to InterSystems IRISOpens in a new tab in the Web Gateway Configuration Guide and Change the Authentication Mechanism for an ApplicationOpens in a new tab in Securing Your Instance.


Once the instance is deployed and running with the new default password, you should log into each of the predefined accounts, which are configured to require a password change on first login, so that they are all secured with new individual passwords of your choosing rather than sharing a password; as an alternative, you can also disableOpens in a new tab one or more of them.


To avoid the expiration of passwords 90 days after an InterSystems IRIS image is built, which would occur using the default settings, a containerized instance is configured so that the passwords of the instance owner and the predefined accounts do not expire.

  • The PasswordHash CPF setting

    During automated deployment of InterSystems IRIS on UNIX and Linux platforms, you can change the default password for one or more instances before they are first started using the configuration parameter file (CPF) PasswordHash setting in conjunction with the configuration merge featureOpens in a new tab.

    Rather than recording the plain-text password for each account (a security risk), InterSystems IRIS stores only an irreversible cryptographic hash of that password; when the user logs in, the password value entered is hashed using the same algorithms, and the two versions are compared to authenticate the user. For more information about the stored password hash, see Instance AuthenticationOpens in a new tab in the Authentication Guide).

    You can set or change the stored password hash (and thus the password) for all of a newly-deployed instance’s predefined accounts (enabled user accounts that have at least one assigned role) using the PasswordHashOpens in a new tab setting, which is in the [Startup] section of the CPF. When included in a configuration merge fileOpens in a new tab at deployment (on UNIX® and Linux systems only), this setting customizes the default password of the predefined accounts on the instance (except CSPSystem, which does not have an assigned role), replacing SYS with the password of which the provided value is a hash.

    Immediately after deployment, as noted above, you should individually change the passwords of the predefined accounts from the new default password set by PasswordHash. The PasswordHash parameter works just once for a given instance, and can therefore be left in an instance’s CPF without having any effect.

    The value of the PasswordHash parameter is a hashed password and the salt for the password, for example:


    A description of the algorithms used to convert a plain-text password to these values is contained in Instance AuthenticationOpens in a new tab, and tools for applying them are available in the %SYSTEM.EncryptionOpens in a new tab API. However, undertaking this conversion as a manual procedure is not recommended, as it is likely to be error-prone and time-consuming. For your convenience, the InterSystems Container Registry (described in Downloading the InterSystems IRIS Image) provides the image for a nanocontainer, passwordhash, that does this conversion for you. You can optionally specify the workfactor and algorithm you want to use; the defaults if not specified are 10000 and SHA512. The following is an example of using this container:

    $ docker run --rm -it -algorithm SHA512 -workfactor 10000
    Enter password:
    Enter password again:

    You would then copy and paste the output and place it in the [Startup] section of your configuration merge file as shown above. After deployment, the default password for the predefined accounts (other than CSPSystem) is what you entered at the prompts.


    You can display usage information using the iris-main --help option as shown:

    $ docker run --help
    Usage of /passwordhash:
      -algorithm string
            Pseudorandom function to use (default "SHA512")
      -workfactor int
            PBKDF2 Work Factor (default 10000)

    You can also provide the password as input to the command, for example:

    $ echo **** | docker run --rm -i

    The PasswordHash property can be used just once on any given InterSystems IRIS instance, and only if the default password has not yet been changed for any of the predefined accounts. Because allowing the default password to remain unchanged following deployment is a serious security risk, the PasswordHash setting should be used in a configuration merge operation to change the default password during deployment and not later. (For information on how to change an individual user’s password, see Edit an Existing User Account in the Authorization Guide.)


    Blank passwords cannot be used with the PasswordHash setting.

  • The iris-main --password-file option

    This option to the iris-main entrypoint application changes the default password of an InterSystems IRIS instance’s predefined accounts, including the CSPSystem account, to the contents of a user-provided file during its initial startup in the container, then deletes the passworf file and creates a sentinel file that prevents it from running again, so that the option will not be invoked every time the container is started. In details, the following steps are taken:

    • If a sentinel file exists in the directory containing the specified password file, the script exits without attempting to change the password.

    • If a sentinel file does not exist, the script

      1. Reads the new password from the specified file.

      2. Shuts down the instance if it is running.

      3. Makes an API call to change the password of all enabled user accounts with at least one role, effectively changing the default password of the instance.

      4. On successful completion of the password change, makes another API call to change the password of the Web Gateway management user, CSPSystem, on both the InterSystems IRIS instance and the local Web Gateway (as described earlier in this section).


        Only the Web Gateway management password for the local instance is affected by this call; any Web Gateway containers in use (see Using the InterSystems Web Gateway Container) are unaffected and must be updated.

      5. If the password file is writeable, the script:

        • Deletes the password file.

        • Creates a sentinel file.

        If the password file is read-only, no sentinel file is created; this provides compatibility with Docker Secrets, Kubernetes Secrets, and similar technologies.

        The iris-main --password-file option invokes a script,, which can be found in dev/Container/ under the InterSystems IRIS installation directory on Linux platforms (including within an InterSystems-provided iris container). You can call this script in other ways in order to integrate it into your own tools.

    For information about the --password-file option, see The iris-main Program.

  • The SYS.ContainerOpens in a new tab API

    InterSystems IRIS is distributed with an API call, SYS.Container.ChangePassword()Opens in a new tab, that is also useful in scripts and other automation. SYS.Container.ChangePassword()Opens in a new tab changes the password of all of an instance’s enabled user accounts that have at least one assigned role to the contents of a user-provided file. (The option of specifying a read-only password file is provided for compatibility with Docker Secrets, Kubernetes Secrets, and similar technologies.) The change is made during the instance’s first startup, before login is possible, and is called by the script and thus by the iris-main --password-file option. When using it, bear in mind the risks of committing the password to a file for any significant length of time.

    The API also includes the SYS.Container.ChangeGatewayMgrPassword()Opens in a new tab call (also called by the script) which changes the password of the Web Gateway management user, CSPSystem, on both the InterSystems IRIS instance and the local Web Gateway (as described earlier in this section).

    For information about the SYS.Container API, see SYS.Container API.

FeedbackOpens in a new tab