Security for InterSystems IRIS Containers
Security for InterSystems IRIS Containers
When working with InterSystems IRIS images from InterSystems it is important to understand the security-related mechanisms and options, including:
While InterSystems IRIS security is comprehensive and container images from InterSystems are engineered to support the strictest security requirements, there are some important security practices designed for noncontainerized instances to which containerized instances present a challenge. In particular, operations requiring human intervention are not suitable for automated containerized deployment and operation. For example, startup with interactive key activationOpens in a new tab (which is the default behavior for an instance with a database encryption key activated) interrupts startup with a prompt for the location of the key, to which an operator must respond. Other tasks, such as configuring an instance to use delegated authorizationOpens in a new tab, are typically done using the interactive ^SECURITY routine.
The configuration merge featureOpens in a new tab can help in some cases by allowing you to automatically deploy containerized instances with any desired configuration, but some security tasks are best addressed by using the features of container orchestrators such as Kubernetes, which rely on security mechanisms designed for containerized software. For example, secretsOpens in a new tab are a widely used mechanism in which a small amount of sensitive information is placed in an object that can then be provided by the platform when needed, letting you avoid the inclusion of confidential data in application code; this would be a suitable and safe means of providing an encryption key to a containerized InterSystems IRIS instance configured for startup with unattended key activationOpens in a new tab, which does not require human intervention. In addition, third-party tools, such as Hashicorp’s Vault, work with Kubernetes and other platforms to provide additional support for managing and safeguarding sensitive data with policies and multiple options to fit a range of needs.
Ownership and Directories
The InterSystems IRIS instance in a container created from an InterSystems image is always named IRIS and is nonrootOpens in a new tab, meaning it was installed and is owned by a user account, irisowner (UID 51773), which does not have root privileges. All file system entities comprising the instance are owned by irisowner, and nothing is therefore owned by root. Operating system-based authenticationOpens in a new tab is enabled on the instance, which means that an irisowner process or client authenticated on another system can connect to the instance without authentication. Because commands issued from outside the container using docker execOpens in a new tab are executed inside the container as irisowner, you can use this command to conveniently connect to the instance without authentication. For example, to open the InterSystems TerminalOpens in a new tab for an instance in a container named iris273 without being prompted for credentials, you could use the following command:
docker exec -it iris273 iris terminal IRIS
The installation directory (containing the mgr/ subdirectory) within the container is /usr/irissys/. The working directory (containing files such as iris-main.log) is /home/irisowner/, while the registry directory is /home/irisowner/irissys/.
For information about the installation parameters used to specify these configuration details, see Required Environment Variables. For more information on these general installation-related topics, see InterSystems IRIS InstallationOpens in a new tab in the “Installing on UNIX®, Linux, and macOS” chapter of the Installation Guide.
InterSystems provides tools that allow you to determine these configuration details for InterSystems IRIS-based images that you create, as described in InterSystems IRIS Containerization Tools.
When using the durable %SYS feature to provide a containerized InterSystems IRIS instance with persistent storage, the host file system location mounted and specified for this purpose must be writable by user 51773. (You will most likely need root privileges to effect this.)
When using durable %SYS with an InterSystems IRIS container deployed with the Pod Manager tool (podman), you must do the following:
Issue the following command before starting the container:
podman unshare chown 51773:51773 $INSTANCEDIR
where $INSTANCEDIR is the host file system location that will contain the durable %SYS directory.
If Red Hat Security-Enhanced Linux (SELinux) is active, include the --privileged=true flag when creating the container.
When using durable %SYS on Kubernetes without the InterSystems Kubernetes OperatorOpens in a new tab, you must include the following security contextOpens in a new tab setting in the pod specification:
securityContext: fsGroup: 51773
Before upgrading an InterSystems IRIS container that uses durable %SYS to version 2021.2 or later, you must make the existing durable directory writable by user 51773.
If the irisowner user account is not defined in the /etc/passwd file on the system hosting the container, it is represented by its UID (51773) on that system.
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 containers.intersystems.com/intersystems/passwordhash:1.1 -algorithm SHA512 -workfactor 10000 Enter password: Enter password again: PasswordHash=0fad6b1a565e04efb5fe9259da8457456883e0a3a42c1a34acec49cbbc1fb8c4c40f1846559ce180c103898db836,10000,SHA512
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.Note:
You can display usage information using the iris-main --help option as shown:
$ docker run containers.intersystems.com/intersystems/passwordhash:1.1 --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 containers.intersystems.com/intersystems/passwordhash:1.1Important:
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.)Note:
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
Reads the new password from the specified file.
Shuts down the instance if it is running.
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.
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).Note:
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.
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, changePassword.sh, 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 changePassword.sh 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.
Locked Down InterSystems IRIS Container
To support the strictest security requirements, InterSystems provides an image named iris-lockeddown, from which you can deploy a highly secure InterSystems IRIS container. The differences between containers from this image and those from the standard iris image are detailed in the following list.
The characteristics of the iris-lockeddown image are subject to change as best practices evolve. We may add, remove, or change features in response to our best understanding of current security practices and the requirements of the production container orchestrators in use by our customers.
The instance in a locked down InterSystems IRIS container was installed with Locked Down securityOpens in a new tab, as opposed to the Normal security installation of an instance in the standard InterSystems IRIS container. For details on the differences between Locked Down and Normal security, see Prepare for InterSystems SecurityOpens in a new tab in Securing Your Instance.
The instance’s private web server is disabled. As a consequence, the Management Portal becomes inaccessible, and if InterSystems System Alerting and Monitoring (SAM)Opens in a new tab is part of the deployment it will not be able to access the instance. To restore access to the Management Portal, you can use configuration merge (see Automated Deployment of InterSystems IRIS Containers) when deploying the container to set the WebServerOpens in a new tab parameter by including the following in the merge file:
The Management Portal itself is not disabled, which means that if you configure a web server for the instance, the portal may become accessible again.
Be sure to use configuration merge to enable the Management Portal, as above, when deploying with InterSystems Cloud Manager (ICM) or the InterSystems Kubernetes Operator (IKO) if you want access to the deployment or its individual instances through the Management Portal for management and maintenance purposes.
You can also enable the private web server by adding the WebServer parameter to the [Startup] section of an existing locked down instance’s CPF (using docker exec to modify it inside the container, or modifying it in the durable %SYS directory on the host file system) and then restarting the instance.
If SAM is deployed with the instance, to give it access to the instance you must not only set WebServer to 1 as described in the previous point, but change the Allowed Authentication Method setting of the /api/monitor web application from Password to Unauthenticated. To do this, on the Web Applications page of the Management Portal (System Administration > Security > Applications > Web Applications), click /api/monitor in the left-hand column to display the Edit Web Application page, make the needed change in the Security Settings section, and click Save.
In addition to the environment variables defined in the standard container, as listed in the following section, the SYS_CONTAINER_LOCKEDDOWN variable is defined as 1 in a locked down container.