About Kerberos Authentication
For maximally secure connections, InterSystems IRIS supports the Kerberos authentication system, which provides a highly secure and effective means of verifying user identities. Kerberos was developed at the Massachusetts Institute of Technology (MIT) to provide authentication over an unsecured network, and protects communications using it against sophisticated attacks. The most evident aspect of this protection is that a user’s password is never transmitted over the network — even encrypted.
Kerberos is what is called a trusted-third-party system: the Kerberos server holds all sensitive authentication information (such as passwords) and is itself kept in a physically secure location.
Kerberos is also:
Time-tested — Kerberos was originally developed in the late nineteen-eighties. Its principal architecture and design have been used for many years at many sites; subsequent revisions have addressed issues that have been discovered over the years.
Available on all supported InterSystems IRIS platforms — Originally developed for UNIX®, Kerberos is available on all InterSystems IRIS-supported variants of UNIX®; Microsoft has integrated Kerberos into Windows 2000 and subsequent versions of Windows. (Note that because the Microsoft .NET framework does not include direct Kerberos support, InterSystems IRIS does not support Kerberos for the InterSystems IRIS Managed Provider for .NET.)
Flexibly configurable — It accommodates heterogeneous networks.
Scalable — The Kerberos protocol minimizes the number of interactions with its Key Distribution Center (KDC); this prevents such interactions from becoming a bottleneck on larger systems.
Fast — As an open-source product, the Kerberos code has been scrutinized and optimized extensively over the years.
Underlying Kerberos authentication is the AES encryption algorithm. AES — the Advanced Encryption Standard — is a royalty-free, publicly defined symmetric block cipher that supports key sizes of 128, 192, and 256 bits. It is part of the US Federal Information Processing Standard (FIPS), as chosen by United States National Institute of Standards and Technology (NIST).
How Kerberos Works
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:
The client receives what is called a “ticket-granting ticket” (“TGT”) and an encrypted session key.
The client uses the TGT and session key to obtain both a service ticket for InterSystems IRIS as well as another encrypted session key.
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.
How InterSystems IRIS Uses Kerberos
To ensure that Kerberos properly secures an environment, 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.
Overview of Configuring Kerberos
To configure an InterSystems IRIS instance for Kerberos authentication:
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 Preparing the Security Environment for Kerberos for more information.
Enable the relevant Kerberos mechanisms on the Authentication/Web Session Options page (System Administration > Security > System Security > Authentication/Web Session Options).
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.
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 Specify Connection Security Levels for more information.
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:
The name of the service principal representing InterSystems IRIS.
The allowed connection security levels.
Setting up this information may involve configuring a Windows preferred server or some other configuration mechanism. See Set Up a Client for more information.
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 Obtain User Credentials for more information.
To maximally secure web connections, set up secure channels for the following connections:
Web browser to webserver
Web Gateway to InterSystems IRIS server
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 Tool||Access Mode||Service|
|InterSystems IRIS Telnet||Client-Server||%Service_Telnet|
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 unsecured medium and therefore no need to offer special protections for this data. (This situation is known as in-process authentication.)
Client-server applications include connections from 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:
Kerberos — Kerberos manages the initial authentication between the user and InterSystems IRIS. Subsequent communications are not protected.
Kerberos with Packet Integrity — Kerberos manages the initial authentication between the user and InterSystems IRIS; each subsequent message has a hash that provides source and content validation. This provides verification that each message in each direction is actually from its purported sender; it also provides verification that the message has not been altered in transit from sender to receiver.
Kerberos with Encryption — Kerberos manages initial authentication, ensures the integrity of all communications, and also encrypts all communications. This involves end-to-end encryption for all messages in each direction between the user and InterSystems IRIS.
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:
Configure the webserver so that it uses TLS to secure browser connections to it.
Co-locate the webserver and the Web Gateway, so there is no need to secure the connection between them.
Configure the Web Gateway to use Kerberos authentication and encryption. Use the Gateway’s Kerberos principal to establish such a connection.
The architecture is:
Any communications between the end-user and InterSystems IRIS occurs through TLS-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 webserver, which hands it to the Web Gateway, which then hands it to the webserver (which is part of InterSystems IRIS itself). The webserver 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.
Specify Connection Security Levels
Client-server connections to InterSystems IRIS use one of the following services:
%Service_Bindings — Java, JDBC, ODBC
%Service_Telnet — Telnet
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:
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:
Kerberos — Initial authentication only
Kerberos with Packet Integrity — Initial authentication and packet integrity
Kerberos with Encryption — Initial authentication, packet integrity, and encrypting all messages
For more information on the Authentication Options page, see Authentication Options.
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.
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.
Set 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: Set 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.
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:
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).
From the submenu that appears, choose Add/Edit.
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.
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.
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.
In the dialog’s Kerberos-related fields, specify values for the following fields:
The connection security level, where the choices are Kerberos authentication only; Kerberos authentication with packet integrity; or Kerberos authentication, packet integrity, and encryption
The service principal name. For information on setting up service principal names, see Names and Naming Conventions.
If you are configuring a telnet connection to a Windows machine, check the box specifying that the connection use the Windows InterSystems IRIS Telnet server.
Click OK to save the specified values and dismiss the dialog.
Set Up an ODBC DSN 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:
On all platforms, 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 and is documented at the Microsoft website. Its name-value pairs are the same as those for the initialization file available on non-Windows platforms.
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 Kerberos-related variables:
Authentication Method — Specifies how the ODBC client authenticates to the DSN. 0 specifies instance authentication; 1 specifies Kerberos.
Security Level — For Kerberos connections, specifies which functionality is used to protect the connection. 1 specifies that Kerberos is used for authentication only; 2 specifies that Kerberos is used for authentication and to ensure the integrity of all packets passed between client and server; and 3 specifies that Kerberos is used for authentication, packet integrity, and to encrypt all messages.
Service Principal Name — Specifies the name of InterSystems service that is serving as the DSN. For example, the service principal might have “iris/localhost.domain.com” as its name.
The names of these variables must have spaces between the words. They are not case-sensitive.
On a Windows client, you can specify connection information through a GUI: the ODBC DSN configuration dialog. InterSystems IRIS provides options on the System DSN tab. This screen has associated help that describes its fields. The path on the Windows Start menu to display this screen varies by version of Windows; it may be listed under Administrative Tools.Important:
On 64-bit Windows, there are two versions of odbcad32.exe: one is located in the C:\Windows\System32\ directory and the other is located in the C:\Windows\SysWOW64\ directory. If you are running 64-bit Windows, configure DSNs through the one in C:\Windows\SysWOW64\.
Set Up a Java or JDBC Client 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:
To configure the client for use with Kerberos, issue the Java Configure command such as:
java –classpath '$IRIS_INSTALL_DIRECTORY/dev/java/lib/JDK18/*' com.intersystems.jgss.ConfigureCopy code to clipboard
This allows Configure to run from any location on the machine, not just from within the JDK directory. Note that the specifics of this command may vary, depending on your site, such as to accommodate Windows path styles or using JDK11.
This program uses Java Generic Security Services (JGSS) to perform the following actions:
If necessary, modifies the java.security file.
Creates or modifies the isclogin.conf file.
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:
Kerberos realm — It offers the local domain in lowercase as a default value for the domain.
Primary KDC — You only need include the local machine name, as the program appends the Kerberos realm name to the machine name for you.
Secondary KDC(s) — You can specify the names of zero or more KDCs to replicate the content of the primary KDC.
After receiving this information, run the command a second time. (It instructs you to do this.)
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.
Obtain 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.
Obtain 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:
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.
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.
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:
Running kinit before invoking the Terminal
Logging in to a system where the login process performs Kerberos authentication for the user
In these situations, InterSystems IRIS can be configured to use the credentials cache.
Obtain 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:
ODBC and Telnet
Java and JDBC
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.
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 Oracle or IBM. These have several common behaviors and several differing behaviors.
IBM implementations of Java are available through version 8 only; for later versions, IBM supports open source versions.
Both implementations store information about a connection in properties of an instance of the java.util.Properties class. These properties are:
user — The name of the user who is connecting to the InterSystems IRIS server. This value is only set for certain connection behaviors.
password — That user’s password. This value is only set for certain connection behaviors.
service principal name — The Kerberos principal name for the InterSystems IRIS server. This value is set for all connection behaviors.
connection security level — The type of protection that Kerberos provides for this connection. 1 specifies that Kerberos is used for authentication only; 2 specifies that Kerberos is used for authentication and to ensure the integrity of all packets passed between client and server; and 3 specifies that Kerberos is used for authentication, packet integrity, and to encrypt all messages. This value is set for all connection behaviors.
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 Set 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:
To specify credentials-related behavior, the parameter name to set in the isclogin.conf file differs for each implementation:
For IBM, it is useDefaultCcache.
For Oracle, it is useTicketCache.
There are different behaviors available on each implementation. These are described in the following sections.
Specifying Behavior on a Client Using the IBM Implementation
The options are:
To use a credentials cache, set the value of the useDefaultCcache parameter to TRUE and do not set the values of the user or password properties. Note that if no credentials cache is available, then an exception is thrown.
To use a username and password that are passed in programmatically, set the value of the useDefaultCcache parameter to FALSE and set the values of the user and password properties.
To prompt for a username and password, set the value of the useDefaultCcache parameter to FALSE and do not set the values of the user or password properties. Because these properties do not have values set, classes from libraries supplied with InterSystems IRIS can be used to generate prompts for them.
Specifying Behavior on a Client Using the Oracle Implementation
The options are:
To exclusively use a username and password that are passed in programmatically, set the value of the useTicketCache parameter to FALSE and set the values of the user and password properties.
To exclusively prompt for a username and password, set the value of the useTicketCache parameter to FALSE and do not set the values of the user or password properties. Because these properties do not have values set, classes from libraries supplied with InterSystems IRIS can be used to generate prompts for them.
To exclusively use a credentials cache, set the value of the useTicketCache parameter to TRUE. To prevent any further action, set the values of the user and password properties to bogus values; this prevents prompting from occurring and ensures the failure of any authentication attempt based on the properties’ values.
To attempt to use a credentials cache and then fall through to using a username and password that are passed in programmatically, set the value of the useTicketCache parameter to TRUE and set the values of the user and password properties. If there is no credentials cache, then the properties’ values are used.
To attempt to use a credentials cache and then fall through to prompting for a username and password, set the value of the useTicketCache parameter to TRUE and do not set the values of the user or password properties. If there is no credentials cache, then classes from libraries supplied with InterSystems IRIS can be used to generate prompts for them.
Obtain 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.
Set 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 webserver 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:
Secure the Connection Between a Web Browser and Webserver
The typical means of securing a connection between a web browser and a webserver is to use TLS (Transport Layer Security). While InterSystems IRIS does not provide implementations of this technology to accomplish this, various third-party products provide this capability.
Set 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.
For information on setting up a connection between the Web Gateway and the InterSystems IRIS server that is protected by TLS, see Configuring the Web Gateway to Connect to InterSystems IRIS Using TLS.
The procedure is:
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.
Create a user in InterSystems IRIS with the same name as the Gateway’s Kerberos principal. To do this, follow the instructions in Create a New User.
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.
Configure the %Service_WebGateway service. To do this, complete the fields described in Service Properties.
Configure the Gateway so that it can contact the server. The procedure is:
From the Management Portal home page, go to the Web Gateway Management page (System Administration > Configuration > Web Gateway Management).
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.
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:
Choose an authentication method.
Configure the roles for the application.
If required, make sure the browser-to-webserver connection uses TLS.