Skip to main content

Two-Factor Authentication

In addition to the authentication mechanism in use, InterSystems IRIS supports the use of two-factor authentication. This means that InterSystems authentication can require the end-user to possess two separate elements or “factors.” From the end-user’s perspective, the first factor is something that you know — for example, a password; the second factor is something that you have — for example, a smart phone. InterSystems IRIS performs two-factor authentication on its end-users using either of two mechanisms:

  • SMS text authentication — InterSystems IRIS sends a security code to the end-user’s phone via SMS. The end-user enters that code when prompted.

  • Time-based one-time password (TOTP) — The end-user initially receives a secret key from InterSystems IRIS. That key is a shared secret between InterSystems IRIS and the end-user’s application (such as an app on a mobile phone) or physical authentication device; both use the key and other information to generate a TOTP that serves as a verification code and that the end-user enters at an InterSystems IRIS prompt. The TOTP expires after 60 seconds and the end-user can only use it a single time, which is why it is called time-based and one-time.

This section covers the following topics:

Overview of Setting Up Two-Factor Authentication

The major steps to setting up two-factor authentication are:

  1. Enable and configure two-factor authentication for the instance as a whole. You can configure the instance to use SMS text authentication, TOTP authentication, or both. For details about TOTP authentication, see Two-factor TOTP overview.

  2. For SMS text authentication, configure the mobile phone service provider(s), if necessary. This includes:

    • Adding any mobile phone service providers if any are required and are not included in the list of default providers.

    • Changing configuration information as necessary for any existing providers (default or added).

  3. Configure the service, as appropriate:

    You can enable either or both types of authentication for each service. For more information about services, see Services.

  4. Configure client-server applications and web applications, as appropriate:

    1. For client-server applications (those that use %Service_Bindings), add the appropriate calls into the client application to support it; this is a programming task that varies according to the client-side component in use (for example, Java, JDBC, or .NET, among others).

      Important:

      Two-factor authentication is designed to receive a response from a human end-user in real time. If what the end-user considers a single session actually consists of multiple, sequential sessions, then the repeated prompting for the second factor may result in an unexpectedly difficult user experience. With client-server applications, the underlying protocol often causes clients to establish, disconnect, and reestablish connections repeatedly; such activity makes the use of two-factor authentication less desirable for this type of application.

    2. For web applications (those that use %Service_WebGateway), configure each application to support it.

    Note:

    For the InterSystems IRIS Terminal, which uses the %Service_Console service on Windows and the %Service_Terminal service on other operating systems, there is no configuration required other than server-side setup; since InterSystems IRIS controls the prompting in these, it simply follows the standard prompt (regardless of the authentication mechanism) with the two-factor authentication prompt and processes end-user input accordingly.

  5. If you are using delegated authentication, modify the ZAUTHENTICATE.mac routine as required. See Delegated Authentication for more information.

  6. Configure each end-user to enable SMS text authentication or TOTP authentication. An end-user can be configured to use both mechanisms, but cannot have both mechanisms enabled simultaneously.

Two-Factor TOTP Overview

Two-factor authentication using a time-based one-time password (TOTP) authentication works as follows:

  1. Select either an authentication device or an application that generates a TOTP, and then provide it or ensure that your users have it.

  2. When you configure an end-user for two-factor TOTP authentication, the system generates a secret key, which is displayed as a base-32 encoded randomized bit string. InterSystems IRIS and the end-user share this secret key (which is why it is known as a shared secret). Both InterSystems IRIS and the end-user’s authentication device or application use it to generate the TOTP itself, which serves as a verification code. The TOTP, which the end-user enters into a Verification code field or prompt, is a string of six digits, and a new one is generated at a regular interval (thirty seconds, by default).

  3. At login time, after the end-user provides InterSystems IRIS with a password, InterSystems IRIS then additionally prompts for the TOTP. The end-user provides the TOTP, and then completes the login process.

The end-user can get the secret key from InterSystems IRIS in several ways:

  • When you configure the end-user’s account to support two-factor TOTP authentication, the Edit User page for the end-user displays the end-user’s secret key, as well as the name of the issuer and the end-user’s account name. It also displays a QR code that includes all this information (a QR code is a machine-readable code such as the one pictured below). The end-user can then enter the information into an authentication device or an application by scanning the code or entering the information manually.

  • If you choose to show the end-user their secret key during the login to a web application or Terminal session (using %Service_Console or %Service_Terminal), you can enable this behavior by selecting the Display Time-Based One-time Password QR Code on next login field on the Edit User page. The Terminal session will then display the end-user’s issuer, account, and secret key. A web application will display the end-user’s issuer, account, and secret key, along with a QR code; here, the end-user can then scan the code or enter the information manually.

    Important:

    InterSystems does not recommend this option. See the following caution for more details.

Caution:

The following are critical security concerns when using two-factor TOTP authentication:

  • Do not transmit the secret key or QR code in an unsecured environment. Out-of-band transmission is preferable to transmission even on a secure network. (The secret key gives an end-user the means to log into InterSystems IRIS or an InterSystems IRIS application. If you and your end-users do not ensure the secret key’s safety, then an attacker may gain access to it, which renders it useless for security.)

  • When configuring two-factor TOTP authentication for your organization, InterSystems strongly recommends that you provide the secret key to each end-user in person or by phone, or that you have the end-user scan the QR code in the physical presence of an administrator. This provides the opportunity to authenticate the individual who obtains the secret key.

    Delivering the secret key over the network increases the possibility of exposing it. This includes displaying the secret key to the end-user when they first log into a web application, console, or the Terminal; this also includes displaying the QR code to the end-user when they first log into a web application.

A TOTP Issuer, Account, Key, and QR Code
A sample QR code that the Management Portal might display.
Note:

If you are using two-factor TOTP authentication and wish to generate QR codes, Java 1.7 or higher must be running on the InterSystems IRIS server. Without Java, InterSystems IRIS can use two-factor TOTP authentication, but the end-user enters the values for the issuer, account, and key manually on the authentication device or in the application.

Configure Two-Factor Authentication for the Server

The steps in configuring two-factor authentication for the InterSystems IRIS server are:

  1. Enable and configure two-factor authentication for the instance as a whole. You can configure the instance to use SMS text authentication, TOTP authentication, or both.

  2. For SMS text authentication, configure the mobile phone service provider(s), if necessary. This includes:

    • Adding any mobile phone service providers if any are required and are not included in the list of default providers.

    • Changing configuration information as necessary for any existing providers (default or added).

Enable and Configure Two-Factor Authentication Settings for an Instance

When setting up two-factor authentication for an InterSystems IRIS instance (server), you can enable one or both of:

  • Two-factor time-based one-time password authentication (TOTP authentication)

  • Two-factor SMS text authentication

To enable either form of two-factor authentication, the procedure is:

  1. From the Management Portal home page, go to the Authentication/Web Session Options page (System Administration > Security > System Security > Authentication/Web Session Options).

  2. To enable two-factor TOTP authentication, on the Authentication/Web Session Options page, select the Allow Two-Factor Time-Based One-Time Password Authentication check box. This displays the Two-Factor Time-Based One-Time Password Issuer field; here, enter a string to identify this instance of InterSystems IRIS.

  3. To enable two-factor SMS text authentication, on the Authentication/Web Session Options page, select the Allow Two-Factor SMS Text Authentication check box. This displays the following fields:

    • Two-Factor Timeout (secs) — Optional timeout in seconds for entering the one-time security token.

    • DNS name of SMTP server — The DNS (Domain Name Service) name of the SMTP (Simple Mail Transfer Protocol) server that this instance of InterSystems IRIS is using to send SMS text messages, such as smtp.example.com (required).

    • From (address) — Address to appear in the “From” field of message (required).

    • SMTP username — Optional username for SMTP authentication (if the SMTP server requires it).

    • SMTP Password and SMTP Password (confirm) — Optional password (entered and confirmed) for SMTP authentication (if the SMTP server requires it).

  4. Click Save.

  5. If the instance is supporting SMS text authentication, configure mobile phone service providers as required. These procedures are described in the next section.

After completing this process for the instance itself, you may need to perform other configuration, such as for the instance’s services, web applications, and client-server applications; you will need to configure the instance’s users. The Overview of Setting Up Two-Factor Authentication provides general direction about this.

Configure Mobile Phone Service Providers

The topics related to configuring mobile phone service providers are:

Create or Edit a Mobile Phone Service Provider

To create or edit a mobile phone service provider, the procedure is:

  1. From the Management Portal home page, go to the Mobile Phone Service Providers page (System Administration > Security > Mobile Phone):

    • To create a new provider, click Create New Provider.

    • To edit an existing provider, click Edit on the provider’s row in the table of providers.

    This displays the Edit Phone Provider page for the selected mobile phone service provider.

  2. On the Edit Phone Provider page, enter or change the value for each of the following fields:

    • Service Provider — The name of the mobile phone service provider (typically, its company name).

    • SMS Gateway — The address of the server that the mobile phone service provider uses to dispatch SMS (short message service) messages.

Delete a Mobile Phone Service Provider

To delete a mobile phone service provider, the procedure is:

  1. From the Management Portal home page, go to the Mobile Phone Service Providers page (System Administration > Security > Mobile Phone).

  2. On the Mobile Phone Service Providers page, in the row of the provider, click Delete.

  3. When prompted to confirm the deletion, click OK.

Predefined Mobile Phone Service Providers

InterSystems IRIS ships with a predefined list of mobile phone service providers, each with its SMS (short message service) gateway preset. These are:

  • AT&T Wireless — txt.att.net

  • Alltel — message.alltel.com

  • Cellular One — mobile.celloneusa.com

  • Nextel — messaging.nextel.com

  • Sprint PCS — messaging.sprintpcs.com

  • T-Mobile — tmomail.net

  • Verizon — vtext.com

Enable or Disable Two-Factor Authentication for a Service

Important:

For %Service_WebGateway, there is no central location for enabling or disabling two-factor authentication. Enable or disable it for each application as described in Configure Web Applications for Two-Factor Authentication.

To enable or disable two-factor authentication for %Service_Bindings, %Service_Console, and %Service _Terminal, procedure is:

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

  2. On the Services page, click the name of the service for which you wish to enable either form of two-factor authentication. This displays the Edit Service page for the service.

  3. On the service’s Edit Service page, select or clear the Two-factor SMS check box, Two-factor Time-based One-time Password check box, or both. Note that each of these check boxes only appear if two-factor authentication is enabled for the instance.

  4. Click Save.

Configure Web Applications for Two-Factor Authentication

Once you have enabled two-factor authentication for an instance, you must enable it for all web applications that will use it. The procedure to enable it for an application is:

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

  2. On the Web Applications page, for the application you wish to enable two-factor authentication, click the name of the application, which displays its Edit page.

  3. On the Edit page, in the Security Settings section of the page, select or clear the Two-factor SMS check box, Two-factor Time-based One-time Password check box, or both. Note that each of these check boxes only appear if two-factor authentication is enabled for the instance.

Note:

A web application cannot simultaneously support both two-factor authentication and web services.

Configure an End-User for Two-Factor Authentication

To configure an end-user to receive a one-time security token for two-factor authentication, the procedure is:

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

  2. For an existing user, click the name of the user to edit; for a new user, begin creating the user by clicking Create New User (for details about creating a new user, see Create a New User). Either of these actions displays the Edit page for the end-user.

  3. On the Edit User page, select SMS text enabled or Time-based One-time Password enabled, as appropriate.

  4. If you select SMS Text, you must complete the following fields:

    • Mobile phone service provider — The company that provides mobile phone service for the user. Either select a provider from those listed or, if the provider does not appear in the list, click Create new provider to add a new provider for the InterSystems IRIS instance. (Clicking Create a new provider displays the Create a New Mobile Phone Provider window, which has fields for the Service Provider and the SMS Gateway, the purpose of which are identical to those described in Create or Edit a Mobile Phone Service Provider.)

    • Mobile phone number — The user’s mobile phone number. This is the second factor, and is where the user receives the text message containing the one-time security token.

  5. If you select Time-based One-time Password enabled, the page displays the following fields and information:

    • Display Time-Based One-time Password QR Code on next login — Whether or not to display a QR code when the user next logs in. If selected, InterSystems IRIS displays the code at the next login and prompts the user to scan it into the authentication device or application, and then to provide the displayed token to complete the authentication process. By default, this option is not selected. InterSystems recommends that you do not use this option.

    • Generate a new Time-based One-time Password Key — Creates and displays both a new shared secret for the end-user and a new QR code.

      Important:

      If you generate a new time-based one-time password key for a user, the current key in the user’s authenticator application will no longer work. Before logging in, the user must enter the new key into the authenticator, either by scanning the QR code or by manually entering it. (This does not affect existing sessions.)

    • Issuer — The identifier for the InterSystems IRIS instance, which you established when configuring two-factor TOTP authentication for the instance.

    • Account — The identifier for the InterSystems IRIS account, which is the account’s username.

    • Base-32 Time-Based One-Time Password (OTP) Key — The secret key that the end-user enters into the authentication device or application.

    • QR Code — A scannable code that contains the values of the issuer, account, and secret key.

  6. Click Save to save these values for the user.

If a service uses two-factor authentication and an end-user has two-factor authentication enabled, then authentication requires:

  • For SMS text authentication, a mobile phone that is able to receive text messages on that phone.

  • For TOTP authentication, an application or authentication device that can generate verification codes.

Otherwise, the end-user cannot authenticate:

  • For SMS text authentication, the end-user must have a mobile phone and be able to receive text messages on that phone. This is the phone number at which the user receives a text message containing the one-time security token as an SMS text.

  • For TOTP authentication, the user must have an authentication device or application that can either scan a QR code or that can accept the secret key and other information required to generate each TOTP (which serves as a verification code).

Configure Bindings Clients for Two-Factor Authentication

Client-server connections use %Service_Bindings. For these connections, the code required to use two-factor authentication varies by programming language. (Note that Console, the Terminal, and web applications do not require any client-side configuration.) Supported languages include:

Client-side code performs three operations:

  1. After establishing a connection to the InterSystems IRIS server, it checks if two-factor authentication is enabled on the server. Typically, this uses a method of the client’s connection object.

  2. It gets the one-time security token from the user. This generally involves user-interface code that is not specifically related to InterSystems IRIS.

  3. It provides the one-time security token to the InterSystems IRIS server. This also typically uses a connection object method.

Note:

When a user logs in through %Service_Bindings, InterSystems IRIS does not present a QR code to scan. The user must have previously set up the authentication device or application.

Important:

Studio, which connects to the InterSystems IRIS server using %Service_Bindings, does not support two-factor authentication.

Java and JDBC

With Java, support for two-factor authentication uses two methods of the IRISConnection class:

  • public boolean isTwoFactorEnabled() throws Exception

    This method checks if two-factor authentication is enabled on the server. It returns a boolean; true means that two-factor authentication is enabled.

  • public void sendTwoFactorToken(String token) throws Exception

    This method provides the one-time security token to the server. It takes one argument, token, the one-time security token that the user has received.

The following example uses an instance of a connection called conn:

  1. It uses that instance’s methods to check if two-factor authentication is enabled.

  2. It attempts to provide the token to the server and performs error processing if this fails.

Important:

If two-factor authentication is enabled on the server and the client code does not implement two-factor authentication calls, then the server will drop the connection with the client.

// Given a connection called "conn"
if (conn.isTwoFactorEnabled()) {
  // Prompt the user for the two-factor authentication token.
  // Store the token in the "token" variable.
  try {
    conn.sendTwoFactorToken(token); 
  } 
  catch (Exception ex) {
    // Process the error from a invalid authentication token here.
  }
}

.NET

For .NET, InterSystems IRIS supports connections with two-factor authentication with the managed provider and with ADO.NET. Support for two-factor authentication uses two methods of the tcp_conn class:

  • bool IRISConnection.isTwoFactorEnabledOpen()

    This method opens a connection to the InterSystems IRIS server and checks if two-factor authentication is enabled there. It returns a boolean; true means that two-factor authentication is enabled.

  • void IRISConnection.sendTwoFactorToken(token)

    This method provides the one-time security token to the server. It has no return value. It takes one argument, token, the one-time security token that the user has received. If there is a problem with either the token (such as if it is not valid) or the connection, then the method throws an exception.

Important:

A client application makes a call to isTwoFactorEnabledOpen instead of a call to IRISConnection.Open. The isTwoFactorEnabledOpen method requires a subsequent call to sendTwoFactorToken.

Also, if two-factor authentication is enabled on the server and the client code does not implement two-factor authentication calls, then the server will drop the connection with the client.

The following example uses an instance of a connection called conn:

  1. It uses that instance’s methods to check if two-factor authentication is enabled.

  2. It attempts to provide the token to the server and performs error processing if this fails.

// Given a connection called "conn"
try {
  if (conn.isTwoFactorEnabledOpen()) {
    // Prompt the user for the two-factor authentication token.
    // Store the token in the "token" variable.
    conn.sendTwoFactorToken(token);
  }
}
catch (Exception ex) {
  // Process exception
}

ODBC

With ODBC, support for two-factor authentication uses two standard ODBC function calls (which are documented in the Microsoft ODBC API Reference):

  • SQLRETURN rc = SQLGetConnectAttr(conn, 1002, &attr, sizeof(attr), &stringLengthPtr);

    The SQLGetConnectAttr function, part of the Microsoft ODBC API, returns the current value of a specified connection attribute. The InterSystems ODBC client uses this function to determine if the server supports two-factor authentication. The value of the first argument is a handle to the connection from the client to the server; the value of the second argument is 1002, the ODBC attribute that specifies whether or not two-factor authentication is supported; the values of the subsequent arguments are for the string containing the value of attribute 1002, as well as relevant variable sizes.

  • SQLRETURN rc = SQLSetConnectAttr(conn, 1002, securityToken, SQL_NTS);

    The SQLSetConnectAttr function, also part of the Microsoft ODBC API, sets the value of a specified connection attribute. The InterSystems ODBC client uses this function to send the value of the two-factor authentication token to the server. The values of the four arguments are, respectively:

    • The connection from the client to the server.

    • 1002, the ODBC attribute that specifies whether or not two-factor authentication is supported.

    • The value of the one-time security token.

    • SQLNTS, which indicates that the one-time security token is stored in a string.

Important:

If two-factor authentication is enabled on the server and the client code does not implement two-factor authentication calls, then the server will drop the connection with the client.

The following example uses an instance of a connection called conn:

  1. It uses SQLGetConnectAttr to check if two-factor authentication is enabled.

  2. It attempts to provide the token to the server with the SQLSetConnectAttr call and performs error processing if this fails. If SQLSetConnectAttr fails, the server drops the connection, so you need to reestablish the connection before you can attempt authentication again.

// Given a connection called "conn"
SQLINTEGER stringLengthPtr;
SQLINTEGER attr;  
SQLRETURN rc = SQLGetConnectAttr(conn, 1002, &attr, sizeof(attr), &stringLengthPtr);
if attr {
  // Prompt the user for the two-factor authentication token.
  wstring token;
  SQLRETURN rc = SQLSetConnectAttr(conn, 1002, token, SQL_NTS);
    if !rc {
      // Process the error from a invalid authentication token.
    }
} 
Feedback