docs.intersystems.com
Home  /  Security Features of InterSystems IRIS  /  Security Administration Guide  /  Authentication


Security Administration Guide
Authentication
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


Authentication Basics
Authentication verifies the identity of any user attempting to connect to InterSystems IRIS™. Once authenticated, a user has established communications with InterSystems IRIS, so that its data and tools are available. There are a number of different ways that a user can be authenticated; each is known as an authentication mechanism. InterSystems IRIS is typically configured to use only one of them. The supported authentication mechanisms are:
InterSystems IRIS supports authentication using user-defined code, which is known as delegated authentication. It also supports authentication using LDAP, the Lightweight Directory Access Protocol. Finally, for those sites that prefer no authentication at all, InterSystems IRIS supports unauthenticated access.
The authentication mechanism is used by what are called connection tools. These specify the means by which users establish their connection with InterSystems IRIS. Each connection tool (such as the Terminal, Java, or web) uses an InterSystems service that allows the administrator to specify the supported authentication mechanism(s). (A InterSystems service is a gatekeeper for connecting to InterSystems IRIS; for more information on services, see the chapter Services.”)
There are three categories of connection tools, each of which is known as an access mode. Each access mode has its own characteristics and has its own supported services. The access modes are:
An end-user uses a connection tool to interact with InterSystems IRIS in a particular access mode using a particular authentication mechanism. Remember that the processes described in this chapter do not themselves establish authenticated access. Rather, they establish the infrastructure that an application uses when authenticating users via a particular mechanism in a particular access mode.
It is recommended that each instance of InterSystems IRIS use only one authentication mechanism and that you choose the instance’s authentication mechanism prior to installing InterSystems IRIS. Once installation has occurred, you can then begin configuring InterSystems IRIS to use the selected mechanism. This involves several steps:
Note:
Regardless of the selected authentication mechanism, during start-up and shut-down, operating system authentication is always used.
Here’s how to use this chapter:
  1. If you have already chosen an authentication mechanism, read about it; if you have not chosen an authentication mechanism, read about them all and choose one. The relevant section for this is About the Different Authentication Mechanisms.”
  2. Read about those access modes that are relevant for your situation in the section About the Different Access Modes.”
  3. Configure your environment according to the instructions in Configuring for Kerberos Authentication,” Configuring for Operating-System–Based Authentication,” or Configuring for Authentication with Instance Authentication.” To use an external mechanism for authentication, InterSystems IRIS includes support for LDAP authentication and delegated (user-defined) authentication.
  4. For all authentication mechanisms, InterSystems IRIS supports two-factor authentication. If you want to implement two-factor authentication, configure the instance according to the instructions in the section Configuring Two-factor Authentication.”
About the Different Authentication Mechanisms
InterSystems IRIS has several ways in which it can authenticate a user, that is, verify the identity of a user. These are:
A site may also be configured for unauthenticated access.
Kerberos Authentication
Where strong authentication is required, InterSystems IRIS can use the Kerberos protocol to enable users and InterSystems IRIS itself to identify each other and to ensure the validity of communications within a session. For a brief overview of Kerberos, see the About Kerberos section in the “Introduction” chapter of this book; for more detailed information, see the MIT Kerberos Web site and its list of available documentation.
In the Kerberos model, there are several different actors. All the different programs and people being authenticated by Kerberos are known as principals. The Kerberos system is administered by a Kerberos Key Distribution Center (KDC); on Windows, the Windows Domain Controller performs the tasks of a KDC. The KDC issues tickets to users so that they can interact with programs, which are themselves represented by service principals. Once a user has authenticated and has a service ticket, it can then use a program.
Specifically, Kerberos authentication involves three separate transactions:
  1. The client receives what is called a “ticket-granting ticket” (“TGT”) and an encrypted session key.
  2. The client uses the TGT and session key to obtain both a service ticket for InterSystems IRIS as well as another encrypted session key.
  3. The client uses the service ticket and second session key to authenticate to InterSystems IRIS and optionally establish a protected connection.
Aside from a possible initial password prompt, this is designed to be invisible to the user.
In order for strong authentication to be meaningful, all InterSystems services that support it must have Kerberos enabled and those that don’t support it must be disabled. The exception to this is that services intended to operate within the InterSystems security perimeter, such as ECP, do not support Kerberos; you can simply enable or disable these services, since they are designed for use in an externally secured environment.
Operating-System–Based Authentication
With operating-system–based authentication, InterSystems IRIS uses the operating system’s user identity to identify the user for InterSystems IRIS purposes. Specifically, the process is:
  1. InterSystems IRIS acquires the process’ operating-system user identity.
  2. InterSystems IRIS checks if the operating system identity matches an InterSystems IRIS username. If so, then the user is automatically authenticated for InterSystems IRIS as well.
InterSystems Authentication
InterSystems IRIS has its own algorithms for providing password-based authentication. This mechanism is listed in the Management Portal as “Password” authentication. Since Kerberos and OS-based authentication both typically use passwords, this documentation refers to the native InterSystems IRIS mechanism as Instance Authentication.
For password authentication, InterSystems IRIS maintains a password value for each user account and compares that value to the one provided by the user at each log in. (In actuality, InterSystems IRIS does not store the password value itself but a hashed version of it. When the user logs in, that entered password value is hashed and the two hashed versions are compared.) The system manager can establish certain password criteria, such as minimum length, to ensure a certain degree of robustness in the passwords selected by users; the criteria are described in the section Password Strength and Password Policies in the chapter “System Management and Security.”
InterSystems IRIS stores only irreversible cryptographic hashes of passwords. The hashes are calculated using the PBKDF2 algorithm with the HMAC-SHA-1 pseudorandom function, as defined in Public Key Cryptography Standard #5 v2.1: “Password-Based Cryptography Standard.” The current implementation uses 1024 iterations, 64 bits of salt, and generates 20 byte hash values. There are no known techniques for recovering original passwords from these hash values.
LDAP Authentication
InterSystems IRIS supports authentication based on LDAP (the Lightweight Directory Access Protocol). With LDAP authentication, InterSystems IRIS retrieves user information from a central LDAP repository. Because an environment may already support LDAP authentication, such as with Windows Active Directory, an instance of InterSystems IRIS may be able to use LDAP for its authentication and simply fit into this larger infrastructure. For more details about LDAP authentication, see the chapter Using LDAP Authentication.”
Delegated Authentication
InterSystems IRIS supports the use of custom authentication mechanisms through what is known as “delegated authentication.” Delegated authentication occurs if an instance of InterSystems IRIS has a ZAUTHENTICATE routine in its %SYS namespace. If such a routine exists, InterSystems IRIS uses it to authenticate users, either with calls to new or existing code. For more details about delegated authentication, see the chapter Using Delegated Authentication.”
Unauthenticated Access
You can configure any InterSystems service to operate without any authentication mechanism. This is known as unauthenticated access. Generally, if you configure InterSystems services to allow unauthenticated access, it is recommended there be unauthenticated access exclusively. If there is support for an authentication mechanism and then unauthenticated access if authentication fails, this is what is called cascading authentication, which is described in the section Cascading Authentication; the circumstances for using more than one authentication mechanism are described in the section Using Multiple Authentication Mechanisms.”
About the Different Access Modes
InterSystems IRIS supports three access modes:
About Local Access
With local access, the end-user is on the same machine as the InterSystems IRIS server. To gain access to the data, the user runs a private image of InterSystems IRIS that is reading from and writing to shared memory. If there are multiple local users, each has an individual copy of the InterSystems IRIS executable and all the executables point to the same shared memory. Because the user and the executable are on the same machine, there is no need to protect or encrypt communications between the two, since nothing is being passed from one executable to another. Because communications between the user and InterSystems IRIS go on within a single process, this is also known as in-process authentication.
Local access is available for:
About Client/Server Access
With client/server access, the InterSystems IRIS executable is the server and there is a client executable that can reside on a separate machine. InterSystems IRIS accepts a connection, possibly over a wire, from the client. This connection can use any language or protocol that InterSystems IRIS supports. These include:
All connection tools support authentication through Kerberos or Instance Authentication except %Service_ComPort, which only supports authentication through Instance Authentication.
In each case, the server specifies the supported authentication type(s). When the client initiates contact with the server, it must attempt to use one of these supported types; otherwise, the connection attempt is rejected. Not all authentication types are available for all connection tools.
About Web Access
The web access mode supports connections of the following form:
Architecture of a Web Connection
  1. A user requests content or an action in a Web browser.
  2. The Web browser passes along the request to the Web server.
  3. The Web server is co-located with the Web Gateway and passes the request to the Gateway.
  4. The Gateway passes the request to the InterSystems IRIS server.
When the InterSystems IRIS server provides content for or performs an action relating to the user, the entire process happens in the other direction.
For the user to authenticate to InterSystems IRIS, a username and password must be passed down the line. Hence, this access mode is also known as a proxy mode or proxy connection. Once the information reaches the InterSystems IRIS machine, the arrangement between user and server is similar to that in the local access mode. In fact, the web access mode also uses in-process authentication.
Configuring for Kerberos Authentication
To configure an InterSystems IRIS instance for Kerberos authentication, the process is:
  1. Ensure that InterSystems IRIS is set up to run as a Kerberos service.
    The procedure varies, depending on the operating system of the InterSystems IRIS server and the type of environment; see the Preparing the Security Environment for Kerberos section of the “Preparing for InterSystems Security” appendix of the Installation Guide for more information.
  2. Determine which services will be used to connect to InterSystems IRIS and disable all other services. For a list of which services are used by what connection tools, see the table Connection Tools, Their Access Modes, and Their Services.”
  3. For client/server connections, specify what Kerberos connection security level the server requires. This is how you determine which Kerberos features are to be part of connections that use the service. See the section Specifying Connection Security Levels for more information.
  4. For client/server connections, perform client-side setup. This ensures that the application has access to the information it needs at runtime. This information includes:
    Setting up this information may involve configuring a Windows preferred server or some other configuration mechanism. See the section Setting Up a Client for more information.
  5. Specify how the authentication process obtains user credentials. This is either by checking the user’s Kerberos credentials cache or by providing a Kerberos password prompt for the user. See the section Obtaining User Credentials for more information.
  6. To maximally secure web connections, set up secure channels for the following connections:
Important:
On Windows, when logged in using a domain account, OS-based and Kerberos authentication are the same. When logged on locally, Kerberos is subject to a KDC spoofing attack and is therefore neither secure nor recommended.
About Kerberos and the Access Modes
Each connection tool uses a service to establish communications with InterSystems IRIS. It also uses a particular access mode. To ensure maximum protection, determine which services you need, based on which connection tools you are using. If you are not using a service, disable it.
The following is a list of connection tools, their access modes, and their services:
Connection Tools, Their Access Modes, and Their Services
Connection Tool Access Mode Service
C++ Client/Server %Service_Bindings
InterSystems IRIS Telnet Client/Server %Service_Telnet
CallIn Local %Service_CallIn
Console Local %Service_Console
Web technologies Web %Service_CSP
Java Client/Server %Service_Bindings
JDBC Client/Server %Service_Bindings
ODBC Client/Server %Service_Bindings
Terminal Local %Service_Terminal
Local
Kerberos authentication for a local service establishes that the user and InterSystems IRIS are both valid Kerberos principals. There is only one machine in use and only one process on that machine; hence, the configuration pages for these services in the Portal allow you to specify whether to use Kerberos prompting (labeled simply as Kerberos in the Management Portal) or Kerberos credentials cache.
In this scenario, there is no connection between the user and InterSystems IRIS, since both are using the same process on the same machine. Because the two are sharing a process, there is no information being passed through an insecure medium and therefore no need to offer special protections for this data. (This situation is known as in-process authentication.)
Client/Server
Client/server applications include connections from C++, Java, JDBC, ODBC, and through Telnet. For a client/server application using Kerberos authentication, the user needs credentials to interact with InterSystems IRIS via the application.
The server and client each require configuration. Server configuration specifies which type of connections are accepted; client configuration specifies what type of connection is attempted and may also specify how to obtain the user’s credentials.
With client/server connections, Kerberos supports various connection security levels, which are configured on the InterSystems IRIS server machine:
Web
When running a web application, the user does not interact directly with the InterSystems IRIS server. To protect all information from monitoring, you need to encrypt the connections between the user and InterSystems IRIS as follows:
The architecture is:
Architecture of a Kerberos-Protected Web Connection
Any communications between the end-user and InterSystems IRIS occurs through SSL-encrypted or Kerberos-encrypted pipes. For Kerberos-secured connections, this includes the end-user’s Kerberos authentication.
Because the InterSystems IRIS server cannot prompt the end-user for a password, it invokes an API that sends HTML content to the browser to prompt. The user completes this form that has been sent; it travels back to the Web server, which hands it to the Web Gateway, which then hands it to the web server (which is part of InterSystems IRIS itself). The web server acts as a proxy on behalf of the user at the browser; this is why this kind of a connection is known as a proxy connection. At the same time, all information related to the user resides on the server machine (as with the local access mode); hence a web connection is also a form of in-process authentication.
Specifying Connection Security Levels
Client/server connections to InterSystems IRIS use one of the following services:
For any Kerberos connection using one of these services, you must specify the connection security levels which the server accepts. To configure the service’s supported connection security levels, the procedure is:
  1. On the Authentication/Web Session Options page (System Administration > Security > System Security > Authentication/Web Session Options), specify which connection security levels to enable for the entire InterSystems IRIS instance, where these can be:
    For more information on the Authentication Options page, see the section Authentication Options in the chapter “System Management and Security.”
  2. On the Services page (System Administration > Security > Services), click the service name (in the Name column); this displays the Edit Service page for the service.
  3. On the Edit Service page, specify which connection security levels to require as part of a Kerberos connection. After making this selection, click Save.
If a client attempts to connect to the server using a lower level of security than that which is specified for the server, then the connection is not accepted. If a client attempts to connect to the server using a higher level of security than that which is specified for the server, then the server connection attempts to perform authentication using the level of security that it specified.
Setting Up a Client
When using the client/server access mode, you need to configure the client. The particulars of this process depend on the connection technology being used.
Telnet: Setting Up the Preferred Server for Use with Kerberos
With a Windows client, when establishing a connection using InterSystems IRIS telnet for Windows, the client uses configuration information that has been stored as part of a remote server.
Important:
InterSystems IRIS has its own telnet server for Windows. When connecting to a non-Windows machine, there is no InterSystems IRIS telnet server available — you simply use the telnet server that comes with the operating system. Once you have established the connection to the server machine, you can then start InterSystems IRIS using the %Service_Terminal service.
To configure a client connection coming in through telnet go to the client machine. On that machine, the procedure is:
  1. Click on the InterSystems IRIS cube 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 Kerberos. This expands the dialog to display a number of additional fields.
  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 the section Define a Remote Server Connection of the “Connecting to Remote Servers” chapter of the System Administration Guide.
  6. In the dialog’s Kerberos-related fields, specify values for the following fields:
  7. Click OK to save the specified values and dismiss the dialog.
Setting Up an ODBC DSN for Use with Kerberos
InterSystems IRIS supports Kerberized ODBC connections from clients on Windows, UNIX®, and Mac to DSNs (Data Source Nodes) on all platforms. The ways of configuring client behavior vary by platform:
Setting Up a Java or JDBC Client for Use with Kerberos
InterSystems IRIS provides a Java class that serves as a utility to assist with Java client configuration. Run it when you are ready to configure the client. The procedure is:
  1. Make sure that the path to cachejdbc.jar and cachedb.jar is available to the CLASSPATH variable on the client. By default, this file is in the <iris-install-dir>/dev/java/lib/JDK16 directory. (For general information on setting up Java clients, see the Installation and Configuration section of “The InterSystems IRIS Java Binding” chapter of Using Java with InterSystems IRIS; for a description of the jar files, see The InterSystems IRIS Java Class Packages in the same chapter.)
  2. To configure the client, issue the Java Configure command:
    > java com.intersys.jgss.Configure
    Note:
    This command is case-sensitive.
    This program uses Java Generic Security Services (JGSS) to perform the following actions:
  3. The program then prompts you to create and configure the krb5.conf file. If the file exists, the command prompts if you wish to use the existing krb5.conf or replace it; if you choose to replace it, it prompts for the following information:
    1. Kerberos realm — It offers the local domain in lowercase as a default value for the domain.
    2. Primary KDC — You only need include the local machine name, as the program appends the Kerberos realm name to the machine name for you.
    3. Secondary KDC(s) — You can specify the names of zero or more KDCs to replicate the content of the primary KDC.
  4. After receiving this information, run the command a second time. (It instructs you to do this.)
  5. When prompted to replace krb5.conf, choose to leave the existing file. The command then tests the connection by prompting for the username and password of a principal in the specified Kerberos realm.
If this succeeds, then client configuration is complete.
Setting Up a Client on C++ for Use with Kerberos
To be able to establish a Kerberized connections through these bindings, you need only configure the InterSystems IRIS server to accept Kerberos connections. Once the server is properly configured, the application then can establish the connection by using the appropriate calls. For information on the appropriate language-specific calls, see the Language Bindings books.
Obtaining User Credentials
For all access modes, you need to specify whether the application obtains the user’s credentials from an existing credentials cache or by prompting for a username and password.
Obtaining Credentials for Local Access Mode
For the local access mode, the user’s credentials reside on the same machine as InterSystems IRIS. In this situation, the application is using a service to connect to InterSystems IRIS. This includes the following services:
To specify how to get credentials, the procedure is:
  1. On the Services page (System Administration > Security > Services) and select the service from the Name column. This displays the Edit Service page for the service.
  2. On the Edit Service page, specify how to get credentials. Either select prompting (the Kerberos check box) or by using a credentials cache (the Kerberos Credentials Cache check box). Do not mark both.
    Click Save to use the settings.
Note:
If you enable both Kerberos (prompting) and Kerberos credentials cache authentication for the service, then the credentials cache authentication takes precedence. This is behavior specified by Kerberos, not InterSystems IRIS.
On Windows with a Domain Controller (the likely configuration for Windows), logging in establishes a Kerberos credentials cache. On UNIX®, Linux, and MacOS, the typical default condition is to have no Kerberos credentials, so that InterSystems IRIS is then configured to use Kerberos prompting; on these systems, the user can obtain credentials in either of the following ways:
In these situations, InterSystems IRIS can be configured to use the credentials cache.
Obtaining Credentials for Client/Server Access Mode
For client/server access mode, the user’s credentials reside on the machine that hosts the client application. In this case, the manner in which you specify how to obtain credentials varies according to how the client is connecting:
C++, ODBC, and Telnet
The underlying InterSystems IRIS code used by these connection tools assumes that end-users already have their credentials; no prompting is necessary.
On Windows, every user logged on in the domain has a credentials cache.
On other operating systems, a user has a credentials cache if the operating system has performed Kerberos authentication for the user, or if the user has explicitly run kinit. Otherwise, the user has no credentials in the cache and the connection tool fails authentication.
Note:
Not all connection tools are available on all operating systems.
Java and JDBC
When using Java and JDBC, there are two different implementations of Java available — either Sun or IBM. These have several common behaviors and several differing behaviors.
Both implementations store information about a connection in properties of an instance of the java.util.Properties class. These properties are:
In the following discussions, the instance of the java.util.Properties class is referred to as the connection_properties object, where the value of each of its properties is set with a call to the connection_properties.put method, such as
 String principalName = "MyServer";
 connection_properties.put("service principal name",principalName);
For both implementations, credentials-related behavior is determined by the value of a parameter in the isclogin.conf file (see Setting Up a Java or JDBC Client for Use with Kerberos for more information on this file).
There are two differences between the behavior of the two Java implementations:
Specifying Behavior on a Client Using the IBM Implementation
The options are:
Specifying Behavior on a Client Using the Sun Implementation
The options are:
Obtaining Credentials for Web Access Mode
With a Web-based connection that uses Kerberos, there is always a username and password prompt. If these result in authentication, the user’s credentials are placed in memory and then discarded when no longer needed.
Setting Up a Secure Channel for a Web Connection
To maximally secure a web connection, it is recommended that the two legs of communication — both between the browser and the Web server and then between the Web Gateway and InterSystems IRIS — use secure channels. This ensures that any information, such as Kerberos usernames and passwords, be protected in transmission from one point to another. To secure each communications channel, the procedure is:
Securing the Connection between a Web Browser and Web Server
The typical means of securing a connection between a Web browser and a Web server is to use SSL (Secure Sockets Layer) or TLS (Transport Layer Security), its successor. While InterSystems IRIS does not provide implementations of these technologies to accomplish this, various third-party products provide this capability.
Setting Up a Kerberized Connection from the Web Gateway to InterSystems IRIS
To set up a secure, encrypted channel between the Web Gateway and the InterSystems IRIS server, you need a Kerberos principal that represents the Gateway. This principal establishes an encrypted connection to InterSystems IRIS, and all information is transmitted through the connection. This allows an end-user to authenticate to InterSystems IRIS and prevents any snooping during that process.
Note:
For information on setting up a connection between the Web Gateway and the InterSystems IRIS server that is protected by SSL/TLS, see the Configuring the Web Gateway to Connect to InterSystems IRIS Using SSL/TLS section of the “Using SSL/TLS with InterSystems IRIS” chapter.
The procedure is:
  1. Determine or choose the name of the Kerberos principal that represents the Gateway.
    For Windows, this is the principal name representing the Gateway host’s network service session (that is, the name of the machine hosting the Gateway with the “$” appended to it — machine_name$, , such as Athens$). For other platforms, this is any valid principal name entered as the username in the Gateway configuration screen; this identifies the appropriate key in the key table file.
  2. Create a user in InterSystems IRIS with the same name as the Gateway’s Kerberos principal. To do this, follow the instructions in the section Creating a New User in the “Users” chapter.
  3. Give that user permissions to use, read, or write any required resources (these are also known as privileges). This is done by associating those privileges with a role and then associating the user with the role.
  4. Configure the %Service_CSP service. To do this, complete the fields described in the section Service Properties in the “Services” chapter.
  5. Configure the Gateway so that it can contact the server. 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 Kerberos connections, these are:
      • Connection Security Level — Choose the kind of protection that you would like Kerberos to attempt to provide this connection. (Note that this must match or exceed the type of security specified for the web service in the previous step.)
      • User Name — The name of the Kerberos principal that represents the Gateway. (This must be the same principal as was used in the first step of this process.)
      • Password — Do not specify a value for this. (This field is used when configuring the Gateway for use with Instance Authentication.)
      • Product — InterSystems IRIS.
      • Service Principal Name — The name of the principal that represents the InterSystems IRIS server. This is typically a standard Kerberos principal name, of the form “iris/machine.domain”, where iris is a fixed string indicating that the service is for InterSystems IRIS, machine is the machine name, and domain is the domain name, such as “intersystems.com”.
      • Key Table — When connecting to an instance of InterSystems IRIS on Windows, leave this field blank; for other operating systems, provide the name of the keytab file containing the permanent key belonging to the Web Gateway, including the full path.
      After entering all these values, click the Save Configuration button to save them.
The web service is now ready to configured. This means that it can now provide the necessary underlying infrastructure to support a web application.
When creating a secured web application, the application developer needs to:
  1. Choose an authentication method.
  2. Configure the roles for the application.
  3. If required, make sure the browser-to-Web server connection uses SSL.
Configuring for Operating-System–Based Authentication
Operating-system–based authentication (sometimes called “OS-based authentication”) is only available for local processes, namely:
To set up the use of this type of authentication, the procedure is:
  1. On to the Services page (System Administration > Security > Services) and select the service from the Name column. This displays the Edit Service page for the service.
  2. On the Edit Service page, choose operating-system–based (the Operating System check box).
    Click Save to use the settings.
This type of authentication requires no other configuration actions.
Note:
On Windows, when logged in using a domain account, OS-based and Kerberos authentication are the same.
A Note on %Service_Console
Since the console (%Service_Console) is a Windows-based service and Windows domain logins typically use Kerberos, console’s OS-based authentication provides authentication for local logins.
A Note on %Service_Callin
With callin (%Service_Callin), OS-based authentication is only available from an OS-level prompt. When using callin programmatically, OS-based authentication is not supported — only unauthenticated access is available.
Configuring for Authentication with Instance Authentication
The services available for authentication with Instance Authentication are:
For a service to use Instance Authentication, you must configure it as follows:
  1. 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.
  2. On this page, choose Instance Authentication, listed simply as Password from the list of authentication types.
  3. Click Save to save this setting.
  4. In addition to this basic procedure, certain services require further configuration. This is described in the following sections:
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:
    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 co-located 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 SSL to encrypt messages from the browser to the Web server. You can use Kerberos to encrypt messages from the Gateway to the the InterSystems IRIS server as described in the section Setting 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.
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:
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 cube 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 the section Define a Remote Server Connection of the “Connecting to Remote Servers” chapter of the System Administration Guide.
  6. Click OK to save the specified values and dismiss the dialog.
Important:
When connecting to a non-Windows machine using telnet, there is no InterSystems IRIS telnet server available — you simply use the telnet server that comes with the operating system. Once you have established the connection to the server machine, you can then connect to InterSystems IRIS using the %Service_Terminal service.
Configuring 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:
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 the Two-Factor TOTP Overview section.
  2. For SMS text authentication, configure the mobile phone service provider(s), if necessary. This includes:
  3. Configure the service, as appropriate:
    You can enable either or both types of authentication for each service. For more information about services, see the Services chapter.
  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_CSP), 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 Using 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. As a requirement, each end-user must have either an authentication device or an application that generates such passwords. For example, end-users can use one of the following apps for mobile phones:
  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:
Caution:
The following are critical security concerns when using two-factor TOTP authentication:
A TOTP Issuer, Account, Key, and QR Code
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.
Configuring 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:
Enabling and Configuring 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:
To enable either form of two-factor authentication, the procedure is:
  1. 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.
  2. 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:
  3. Click Save.
  4. 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.
Configuring Mobile Phone Service Providers
The topics related to configuring mobile phone service providers are:
Creating or Editing 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):
    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:
Deleting 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:
Enabling or Disabling Two-Factor Authentication for a Service
Important:
For %Service_CSP, there is no central location for enabling or disabling two-factor authentication. Enable or disable it for each application as described in Configuring 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.
Configuring 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.
Configuring 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 the Creating a New User section of the “Users” chapter). 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:
  5. If you select Time-based One-time Password enabled, the page displays the following fields and information:
  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:
Otherwise, the end-user cannot authenticate:
Configuring 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, 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.
C++
With C++, support for two-factor authentication uses two methods of the tcp_conn class:
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 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. Note that the sample code here assumes that the application code has stored the one-time security token in a variable of type std::string; it then uses the c_str method of the string class to extract the one-time security token as a null-terminated string to pass to the server.
// Given a connection called "conn"
if (conn->is_two_factor_enabled()) {
  // Prompt the user for the one-time security token.
  // Store the token in the "token" variable of type std::string.
  Conn_err err;
  if (!conn->send_two_factor_token(token.c_str(), &err;))
      // Process the error from a invalid authentication token here.
} 
Note:
The light C++ binding does not support two-factor authentication.
Java and JDBC
With Java, support for two-factor authentication uses two methods of the CacheConnection class:
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:
Important:
A client application makes a call to isTwoFactorEnabledOpen instead of a call to CacheConnection.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):
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.
    }
} 
Other Topics
Areas covered in this section are:
System Variables and Authentication
After authentication, two variables have values:
The $ROLES variable allows you to manage roles programmatically. For more information on this, see the section Programmatically Managing Roles in the “Roles” chapter.
Using 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:
Note:
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.
Note:
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.
Establishing 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)
where
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.
Note:
The single-argument Login method is a restricted system capability as described in the section Special Capabilities in the “Resources” chapter.
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
}