Instance Authentication

About Instance Authentication

InterSystems IRIS itself can provide a login mechanism, called instance authentication. (In the Management Portal, it is referred to as Password Authorization.) Specifically, InterSystems IRIS maintains a password value for each user account and compares that value to the one provided by the user at each login. As with traditional OS-based authentication, InterSystems IRIS stores a hashed version of the password. When the user logs in, the password value entered is hashed and the two hashed versions are compared. The system manager can configure certain password criteria, such as minimum length, to ensure a desired degree of robustness in the passwords selected by users. The criteria are described in Password Strength and Password Policies.

InterSystems IRIS stores only irreversible cryptographic hashes of passwords. The hashes are calculated using the PBKDF2 algorithm with the HMAC-SHA-512 pseudorandom function, as defined in Public Key Cryptography Standard #5 v2.1: “Password-Based Cryptography Standard.” The current implementation uses 10,000 iterations, 64 bits of salt, and generates 64-byte hash values; to specify a different algorithm or increase the number of iterations, use the Security.System.PasswordHashAlgorithmOpens in a new tab and Security.System.PasswordHashWorkFactorOpens in a new tab methods, respectively. There are no known techniques for recovering original passwords from these hash values.

The services available for authentication with instance authentication are:

• %Service_Binding

• %Service_CallIn

• %Service_ComPort

• %Service_Console

• %Service_Telnet

• %Service_Terminal

• %Service_WebGateway

Overview of Configuring Instance Authentication

For a service to use instance authentication, you must configure it as follows:

1. On the Authentication/Web Sessions Options page (System Administration > Security > System Security > Authentication/Web Session Options), enable authentication with instance authentication by selecting Allow Password authentication).

2. For the particular service, go to the Services page (System Administration > Security > Services) and select that service, such as %Service_Bindings, in the Name column; this displays the Edit Service page for the service.

3. On this page, choose instance authentication, listed simply as Password from the list of authentication types.

4. Click Save to save this setting.

5. In addition to this basic procedure, certain services require further configuration. This is described in the following sections:

   • Web

   • ODBC

   • Telnet

Web

For web access, you can optionally require that the web gateway authenticate itself to the InterSystems IRIS server through instance authentication. To perform this configuration, the procedure is:

1. From the Management Portal home page, go to the Web Gateway Management page (System Administration > Configuration > Web Gateway Management).

2. On the web gateway management page, there are a set of choices on the left. Under Configuration, click Server Access. This displays the Server Access page.

3. On the Server Access page, you can add a new configuration or edit an existing one. To add a new configuration, click the Add Server button; to edit an existing one, select it from the list on the left, select the Edit Server radio button, and click Submit. This displays the page for editing or configuring server access parameters. In addition to the general parameters on this page (described on its help screen), this page allows you to specify security-related parameters for the gateway. For instance authentication connections, these are:

   • Connection Security Level — Choose Password from the drop-down list to use instance authentication.

   • User Name — The user name under which the gateway service runs (the installation process creates the CSPSystem user for this purpose). This user (CSPSystem or any other) should have no expiration date; that is, its Expiration Date property should have a value of 0.

   • Password — The password associated with the user account just entered.

   • Product — InterSystems IRIS.

   • Service Principal Name — Do not specify a value for this. (This field is used when configuring the gateway for use with Kerberos.)

   • Key Table — Do not specify a value for this. (This field is used when configuring the gateway for use with Kerberos.)

   After entering all these values, click the Save Configuration button to save them.

It is important to remember that the authentication requirements for the gateway are not directly related to those for an application that uses the gateway. For example, you can require instance authentication as the authentication mechanism for a web application, while configuring the gateway to use Kerberos authentication — or no authentication at all. In fact, choosing a particular authentication mechanism for the gateway itself makes no technical requirement for the web application, and vice versa. At the same time, some pairings are more likely to occur than others. If a web application uses Kerberos authentication, then using any other form of authentication for the gateway means that Kerberos authentication information will be flowing through an unencrypted channel, thereby potentially reducing its effectiveness.

With a web application that uses instance authentication, the username and password of the end-user are passed from the browser to the web server, which then hands them to the web gateway. Since the gateway has its own connection to the InterSystems IRIS server, it then passes the username and password to the InterSystems IRIS server. To establish its connection to the InterSystems IRIS server, the gateway uses the CSPSystem account, which is one of the InterSystems IRIS predefined accounts.

By default, all these transactions are unencrypted. You can use TLS to encrypt messages from the browser to the web server. You can use Kerberos to encrypt messages from the gateway to the InterSystems IRIS server as described in Set Up a Secure Channel for a Web Connection; if you are not using Kerberos, you may prefer to physically secure the connection between the host machines, such as by co-locating the gateway and InterSystems IRIS server machines in a locked area with a direct physical connection between them.

Regardless of your architecture, ensure that the data on each connection is secure.

ODBC

InterSystems IRIS supports instance authentication for ODBC connections among all its supported platforms. This requires client-side configuration. The ways of configuring client behavior vary by platform:

• On non-Windows platforms, use the InterSystems ODBC initialization file to specify name-value pairs that provide connection information . This file is described generally in Using the InterSystems ODBC Driver. The file has the following variables relevant to instance authentication:

  • Authentication Method — Specifies how the ODBC client authenticates to the DSN. 0 specifies instance authentication; 1 specifies Kerberos.

  • UID — Specifies the name for the default user account for connecting to the DSN. At runtime, depending on application behavior, the end-user may be permitted to override this value with a different user account.

  • Password — Specifies the password associated with the default user account. If the end-user has been permitted to override the UID value, the application will accept a value for the newly specified user’s password.

• On a Windows client, you can specify connection information either through a GUI or programmatically:

  • Through a GUI, there is an ODBC DSN configuration dialog. InterSystems IRIS provides options on the System DSN tab. This screen has associated help that describes its fields. The path from the Windows Start menu to display this screen varies by version of Windows; it may be listed in the Windows Control Panel, under Administrative Tools, on the screen for Data Sources (ODBC).

  • Programmatically, the SQLDriverConnect function is available, which accepts a set of name-value pairs. SQLDriverConnect is a C call that is part of the ODBC API. Its name-value pairs are the same as those for the initialization file available on non-Windows platforms, except that the password is identified with the PWD keyword.

Telnet

When establishing a connection using the InterSystems IRIS Telnet server for Windows, the client uses configuration information that has been stored as part of an InterSystems IRIS remote server. To configure a remote server, go to the client machine. On that machine, the procedure is:

1. Click on the InterSystems IRIS launcher and select Preferred Server from the menu (the Preferred Server choice also displays the name of the current preferred server).

2. From the submenu that appears, choose Add/Edit.

3. To create a new remote server, click the Add button; to configure an already-existing server, choose the InterSystems IRIS server to which you are connecting and click the Edit button.

4. This displays the Add Connection dialog. In the Authentication Method area on that dialog, click Password for instance authentication.

5. If you are editing the values for an already-existing server, there should be no need to change or add values for the more general fields in this dialog, as they are determined by the server that you chose to edit.

   If you are adding a new server, the fields to complete are described in Define a Remote Server Connection.

6. Click OK to save the specified values and dismiss the dialog.