Caché Security Administration Guide Authentication [Home] [Back] [Next]

• Authentication Basics
• About the Different Authentication Mechanisms
• About the Different Access Modes
• Configuring for Kerberos Authentication
• Configuring for Operating-System–Based Authentication
• Configuring for Authentication with Caché Login
• Configuring Two-Factor Authentication
• Other Topics

• Kerberos
• Operating-System–Based
• Caché Login
• LDAP Authentication
• Delegated Authentication

• Local — The user interacts directly with the Caché executable on the machine where that executable is running.
• Client/Server — The user is operating a separate executable that connects to Caché.
• Web — The user has a Web browser and is interacting with Caché through a Web-based application.

• With Kerberos, ensure that all Caché users are listed in the Kerberos KDC (Key Distribution Center) or Windows Domain Controller.
• With operating-system–based authentication, ensure that all Caché users appear in the operating system list.
• For all authentication mechanisms, configure all supported services to use only the selected authentication mechanism.
• For all authentication mechanisms, disable all unsupported services.
• For all authentication mechanisms, configure all applications to use only the selected authentication mechanism.

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 Caché Login.” To use an external mechanism for authentication, Caché includes support for LDAP authentication and delegated (user-defined) authentication.
4. For all authentication mechanisms, Caché 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.”

• Kerberos Authentication
• Operating-System–Based Authentication
• Caché Authentication
• LDAP Authentication
• Delegated Authentication

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 Caché as well as another encrypted session key.
3. The client uses the service ticket and second session key to authenticate to Caché and optionally establish a protected connection.

1. Caché obtains the process’ operating-system user identity.
2. Caché checks if the operating system identity matches a Caché username. If so, then the user is automatically authenticated for Caché as well.

• Local
• Client/Server
• Web

• The terminal — The Terminal uses the %Service_Console service on Windows and the %Service_Terminal service on other operating systems.
• Callin — Callin uses the %Service_CallIn service.

• ActiveX — Uses %Service_Bindings
• C++ — Uses %Service_Bindings
• Caché Direct — Uses %Service_CacheDirect
• ComPort — Uses %Service_ComPort
• Java — Uses %Service_Bindings
• JDBC — Uses %Service_Bindings
• ODBC — Uses %Service_Bindings
• Perl — Uses %Service_Bindings
• Python — Uses %Service_Bindings
• Telnet — Uses %Service_Telnet

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 CSP Gateway and passes the request to the Gateway.
4. The Gateway passes the request to the Caché server.

1. Ensure that Caché is set up to run as a Kerberos service.
   The procedure varies, depending on the operating system of the Caché server and the type of environment; see the “Preparing the Security Environment for Kerberos” section of the “Preparing for Caché Security” appendix of the Caché Installation Guide for more information.
2. Enable the relevant Kerberos mechanisms on the Authentication/CSP Session Options page (System Administration > Security > System Security > Authentication/CSP Session Options).
3. Determine which services will be used to connect to Caché 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.”
4. 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.
5. 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 Caché.
   • The allowed connection security levels.
   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.
6. 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.
7. To maximally secure web connections, set up secure channels for the following connections:
   • Web browser to Web server
   • CSP Gateway to Caché server

• Kerberos — Kerberos manages the initial authentication between the user and Caché. Subsequent communications are not protected.
• Kerberos with Packet Integrity — Kerberos manages the initial authentication between the user and Caché; 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 Caché.

• Configure the Web server so that it uses SSL to secure browser connections to it.
• Co-locate the Web server and the CSP Gateway, so there is no need to secure the connection between them.
• Configure the CSP Gateway to use Kerberos authentication and encryption. Use the Gateway’s Kerberos principal to establish such a connection.

• %Service_Bindings — ActiveX, C++, Java, JDBC, ODBC, Perl, Python
• %Service_CacheDirect — Caché Direct
• %Service_Telnet — Telnet

1. On the Authentication/CSP Session Options page (System Administration > Security > System Security > Authentication/CSP Session Options), specify which connection security levels to enable for the entire Caché 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 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.

1. Click on the Caché 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 Caché 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 Caché System Administration Guide.
6. 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 the section “Names and Naming Conventions” in the appendix “Preparing for Caché Security” of the Caché Installation Guide.
   • If you are configuring a telnet connection to a Windows machine, check the box specifying that the connection use the Windows Caché Telnet server.
7. Click OK to save the specified values and dismiss the dialog.

• 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 Web site. Its name-value pairs are the same as those for the initialization file available on non-Windows platforms.
• On non-Windows platforms, use the Caché ODBC initialization file to specify name-value pairs that provide connection information. This file is described generally in Using Caché ODBC. The file has the following Kerberos-related variables:
  • Authentication Method — Specifies how the ODBC client authenticates to the DSN. 0 specifies Caché login; 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 Caché service that is serving as the DSN. For example, the service principal might have “cache/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. Caché 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\.

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 <cache-install-dir>/dev/java/lib/JDK16 directory. (For general information on setting up Java clients, see the “Installation and Configuration” section of “The Caché Java Binding” chapter of Using Java with Caché; for a description of the jar files, see “The Caché 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:
   • If necessary, modifies the java.security file.
   • Creates or modifies the isclogin.conf file.
     Note:

     The parameters to the login module that appear in the isclogin.conf file depend on whether the server is using the Sun Java implementation or the IBM Java implementation. IBM AIX® and SUSE Linux use the IBM implementation; all other supported Caché platforms use the Sun implementation.
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.

• %Service_CallIn
• %Service_Console
• %Service_Terminal

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.

• Running kinit before invoking the Terminal
• Logging in to a system where the login process performs Kerberos authentication for the user

• ActiveX, Caché Direct, C++, ODBC, Perl, Python, and Telnet
• Java and JDBC

• user — The name of the user who is connecting to the Caché 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 Caché 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.

 String principalName = "MyCacheServer";
 connection_properties.put("service principal name",principalName);

• 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 Sun, it is useTicketCache.
• There are different behaviors available on each implementation. These are described in the following sections.

• 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 Caché can be used to generate prompts for them.

• 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 Caché 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 Caché can be used to generate prompts for them.

• Between the Web browser and Web server
• Between the CSP Gateway and Caché

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 Caché 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 > CSP 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 CSP 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 Caché login.)
      • Product — Caché or Ensemble, depending on which product you are using.
      • Service Principal Name — The name of the principal that represents the Caché server. This is typically a standard Kerberos principal name, of the form “cache/machine.domain”, where cache is a fixed string indicating that the service is for Caché, machine is the machine name, and domain is the domain name, such as “intersystems.com”.
      • Key Table — When connecting to an instance of Caché on Windows, leave this field blank; for other operating systems, provide the name of the keytab file containing the permanent key belonging to the CSP Gateway, including the full path.
      After entering all these values, click the Save Configuration button to save them.

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.

• Callin (%Service_Callin)
• Console (%Service_Console)
• Terminal (%Service_Terminal)

1. On the Authentication/CSP Session Options page (System Administration > Security > System Security > Authentication/CSP Session Options), select Allow Operating System authentication.
2. 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.
3. On the Edit Service page, choose operating-system–based (the Operating System check box).
   Click Save to use the settings.

• %Service_Binding
• %Service_CSP
• %Service_CacheDirect
• %Service_CallIn
• %Service_ComPort
• %Service_Console
• %Service_Telnet
• %Service_Terminal

1. On the Authentication/CSP Sessions Options page (System Administration > Security > System Security > Authentication/CSP Session Options), enable authentication with Caché login by selecting Allow Password authentication).
2. For the particular service, go to the Services page (System Administration > Security > Services) and select that service, such as %Service_Bindings, in the Name column; this displays the Edit Service page for the service.
3. On this page, choose Caché login, listed simply as Password from the list of authentication types.
4. Click Save to save this setting.
5. In addition to this basic procedure, certain services require further configuration. This is described in the following sections:
   • Web
   • ODBC
   • Telnet and Caché Direct

1. From the Management Portal home page, go to the Web Gateway Management page (System Administration > Configuration > CSP 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 Caché login connections, these are:
   • Connection Security Level — Choose Password from the drop-down list to use Caché login.
   • User Name — The user name under which the Gateway service runs (the installation process creates the CSPSystem user for this purpose). This user (CSPSystem or any other) should have no expiration date; that is, its Expiration Date property should have a value of 0.
   • Password — The password associated with the user account just entered.
   • Product — Caché or Ensemble, depending on which product you are using.
   • Service Principal Name — Do not specify a value for this. (This field is used when configuring the Gateway for use with Kerberos.)
   • Key Table — Do not specify a value for this. (This field is used when configuring the Gateway for use with Kerberos.)
   After entering all these values, click the Save Configuration button to save them.

• On non-Windows platforms, use the Caché ODBC initialization file to specify name-value pairs that provide connection information . This file is described generally in Using Caché ODBC. The file has the following variables relevant to Caché login:
  • Authentication Method — Specifies how the ODBC client authenticates to the DSN. 0 specifies Caché login; 1 specifies Kerberos.
  • UID — Specifies the name for the default user account for connecting to the DSN. At runtime, depending on application behavior, the end-user may be permitted to override this value with a different user account.
  • Password — Specifies the password associated with the default user account. If the end-user has been permitted to override the UID value, the application will accept a value for the newly specified user’s password.
• On a Windows client, you can specify connection information either through a GUI or programmatically:
  • Through a GUI, there is an ODBC DSN configuration dialog. Caché provides options on the System DSN tab. This screen has associated help that describes its fields. The path from the Windows Start menu to display this screen varies by version of Windows; it may be listed in the Windows Control Panel, under Administrative Tools, on the screen for Data Sources (ODBC).
  • Programmatically, the SQLDriverConnect function is available, which accepts a set of name-value pairs. SQLDriverConnect is a C call that is part of the ODBC API and is documented at the Microsoft Web site. Its name-value pairs are the same as those for the initialization file available on non-Windows platforms, except that the password is identified with the PWD keyword.

1. Click on the Caché 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 Caché 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 Caché login.
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 Caché System Administration Guide.
6. Click OK to save the specified values and dismiss the dialog.

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

• Overview of Setting Up Two-Factor Authentication
• Configuring Two-Factor Authentication for the Server
• Enabling or Disabling Two-Factor Authentication for a Service
• Configuring Web Applications for Two-Factor Authentication
• Configuring an End-User for Two-Factor Authentication
• Configuring Bindings Clients for Two-Factor Authentication

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:
   • Adding any mobile phone service providers if any are required and are not included in the list of default providers.
   • Changing configuration information as necessary for any existing providers (default or added).
3. Configure the service, as appropriate:
   • %Service_Bindings — Enable two-factor authentication for the service and continue to the next step.
   • %Service_Console and %Service_Terminal — Simply enable two-factor authentication for the service. This is all that is required.
   • %Service_CSP — There is no central means of enabling two-factor authentication for %Service_CSP. Continue to the next step.
   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, ODBC, JDBC, C++, Java, .NET, Python, or Perl).
      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 Caché 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 Caché 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.

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:
   • Google Authenticator, for Android, BlackBerry, or iPhone
   • Duo Mobile, for Android or iPhone
   • Amazon AWS MFA, for Android
   • Authenticator, for Windows Phone 7
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. Caché and the end-user share this secret key (which is why it is known as a shared secret). Both Caché 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 Caché with a password, Caché then additionally prompts for the TOTP. The end-user provides the TOTP, and then completes the login process.

• When you configure the end-user’s account to support two-factor TOTP authentication, the Edit User page for the end-user displays the end-user’s secret key, as well as the name of the issuer and the end-user’s account name. It also displays a QR code that includes all this information (a QR code is a machine-readable code such as the one pictured below). The end-user can then enter the information into an authentication device or an application by scanning the code or entering the information manually.
• If you choose to show the end-user their secret key during the login to a web application or Terminal session (using %Service_Console or %Service_Terminal), you can enable this behavior by selecting the Display Time-Based One-time Password QR Code on next login field on the Edit User page. The Terminal session will then display the end-user’s issuer, account, and secret key. A web application will display the end-user’s issuer, account, and secret key, along with a QR code; here, the end-user can then scan the code or enter the information manually.
  Important:

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

1. Enable and configure two-factor authentication for the instance as a whole. You can configure the instance to use SMS text authentication, TOTP authentication, or both.
2. For SMS text authentication, configure the mobile phone service provider(s), if necessary. This includes:
   • Adding any mobile phone service providers if any are required and are not included in the list of default providers.
   • Changing configuration information as necessary for any existing providers (default or added).

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

1. From the Management Portal home page, go to the Authentication/CSP Session Options page (System Administration > Security > System Security > Authentication/CSP Session Options).
2. To enable two-factor TOTP authentication, on the Authentication/CSP 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 Caché.
3. To enable two-factor SMS text authentication, on the Authentication/CSP Session Options page, select the Allow Two-Factor SMS Text Authentication check box. This displays the following fields:
   • Two-Factor Timeout (secs) — Optional timeout in seconds for entering the one-time security token.
   • DNS name of SMTP server — The DNS (Domain Name Service) name of the SMTP (Simple Mail Transfer Protocol) server that this instance of Caché is using to send SMS text messages, such as smtp.example.com (required).
   • From (address) — Address to appear in the “From” field of message (required).
   • SMTP username — Optional username for SMTP authentication (if the SMTP server requires it).
   • SMTP Password and SMTP Password (confirm) — Optional password (entered and confirmed) for SMTP authentication (if the SMTP server requires it).
4. Click Save.
5. If the instance is supporting SMS text authentication, configure mobile phone service providers as required. These procedures are described in the next section.

• Creating or Editing a Mobile Phone Service Provider
• Deleting a Mobile Phone Service Provider
• Predefined Mobile Phone Service Providers

1. From the Management Portal home page, go to the Mobile Phone Service Providers page (System Administration > Security > Mobile Phone):
   • To create a new provider, click Create New Provider.
   • To edit an existing provider, click Edit on the provider’s row in the table of providers.
   This displays the Edit Phone Provider page for the selected mobile phone service provider.
2. On the Edit Phone Provider page, enter or change the value for each of the following fields:
   • Service Provider — The name of the mobile phone service provider (typically, its company name).
   • SMS Gateway — The address of the server that the mobile phone service provider uses to dispatch SMS (short message service) messages.

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.

• AT&T Wireless — txt.att.net
• Alltel — message.alltel.com
• Cellular One — mobile.celloneusa.com
• Nextel — messaging.nextel.com
• Sprint PCS — messaging.sprintpcs.com
• T-Mobile — tmomail.net
• Verizon — vtext.com

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.

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.

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:
   • Mobile phone service provider — The company that provides mobile phone service for the user. Either select a provider from those listed or, if the provider does not appear in the list, click Create new provider to add a new provider for the Caché instance. (Clicking Create a new provider displays the Create a New Mobile Phone Provider window, which has fields for the Service Provider and the SMS Gateway, the purpose of which are identical to those described in the section Creating or Editing a Mobile Phone Service Provider.)
   • Mobile phone number — The user’s mobile phone number. This is the second factor, and is where the user receives the text message containing the one-time security token.
5. If you select Time-based One-time Password enabled, the page displays the following fields and information:
   • Display Time-Based One-time Password QR Code on next login — Whether or not to display a QR code when the user next logs in. If selected, Caché displays the code at the next login and prompts the user to scan it into the authentication device or application, and then to provide the displayed token to complete the authentication process. By default, this option is not selected. InterSystems recommends that you do not use this option.
   • Generate a new Time-based One-time Password Key — Creates and displays both a new shared secret for the end-user and a new QR code.
     Important:

     If you generate a new time-based one-time password key for a user, the current key in the user’s authenticator application will no longer work. Before logging in, the user must enter the new key into the authenticator, either by scanning the QR code or by manually entering it. (This does not affect existing sessions.)
   • Issuer — The identifier for the Caché instance, which you established when configuring two-factor TOTP authentication for the instance.
   • Account — The identifier for the Caché account, which is the account’s username.
   • Base-32 Time-Based One-Time Password (OTP) Key — The secret key that the end-user enters into the authentication device or application.
   • QR Code — A scannable code that contains the values of the issuer, account, and secret key.
6. Click Save to save these values for the user.

• For SMS text authentication, a mobile phone that is able to receive text messages on that phone.
• For TOTP authentication, an application or authentication device that can generate verification codes.

• For SMS text authentication, the end-user must have a mobile phone and be able to receive text messages on that phone. This is the phone number at which the user receives a text message containing the one-time security token as an SMS text.
• For TOTP authentication, the user must have an authentication device or application that can either scan a QR code or that can accept the secret key and other information required to generate each TOTP (which serves as a verification code).

• C++
• Java and JDBC
• .NET
• ODBC
• Perl
• Python

1. After establishing a connection to the Caché 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 Caché.
3. It provides the one-time security token to the Caché server. This also typically uses a connection object method.

• bool tcp_conn::is_two_factor_enabled()

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

• bool tcp_conn::send_two_factor_token(const wchar_t* token, Conn_err* err)

  This method provides the two-factor authentication token to the server. It returns a boolean; true means that the user has been authenticated. It takes two arguments:
  • token, the two-factor authentication token that the user has received. Note that the client application is responsible for obtaining the value of the token from the user.
  • err, an error that the method throws if the user does not successfully authenticate.

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.
} 

• public boolean isTwoFactorEnabled() throws Exception

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

• public void sendTwoFactorToken(String token) throws Exception

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

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"
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.
  }
}

• bool CacheConnection.isTwoFactorEnabledOpen()

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

• void CacheConnection.sendTwoFactorToken(token)

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

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
}

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

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

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

  The SQLSetConnectAttr function, also part of the Microsoft ODBC API, sets the value of a specified connection attribute. The Caché ODBC client uses this function to send the value of the two-factor authentication token to the server. The values of the four arguments are, respectively:
  • The connection from the client to the server.
  • 1002, the ODBC attribute that specifies whether or not two-factor authentication is supported.
  • The value of the one-time security token.
  • SQLNTS, which indicates that the one-time security token is stored in a string.

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.
    }
} 

• is_two_factor_enabled()

  This method checks if two-factor authentication is enabled on the server. It returns a integer; 1 means that two-factor authentication is enabled and 0 means that it is disabled.

• send_two_factor_token($token)

  This method provides the two-factor authentication token to the server. It returns a integer; 1 indicates success and 0 indicates failure. Its argument, $token, is the two-factor authentication token that the user has received and then entered at the client prompt. Note that the client application is responsible for obtaining the value of the token from the user.

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"
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.
  if (!$conn->send_two_factor_token($token)) {
    # Process the error from a invalid authentication token here.
  } else {
    # two-factor authentication succeeded
} 
else {
  # Handle if two-factor authentication is not enabled on the server.
}

• is_two_factor_enabled()

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

• send_two_factor_token(token)

  This method provides the two-factor authentication token to the server. It returns a boolean; true means that the user has been authenticated. It takes one argument, token, the two-factor authentication token that the user has received. Note that the client application is responsible for obtaining the value of the token from the user.
  Note:

  Python leaves carriage returns in input. This means that, when processing the one-time security token, it is necessary to strip any carriage returns out of it.

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"
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.
  # Make sure that the carriage returns are stripped from the string.
  if !conn.send_two_factor_token(token):
    # Process the error from a invalid authentication token here.
  else:
    # two-factor authentication succeeded
else:
  # Handle if two-factor authentication is not enabled on the server.

• System Variables and Authentication
• Using Multiple Authentication Mechanisms
• Cascading Authentication
• Establishing Connections with the UnknownUser Account
• Programmatic Logins
• The JOB Command and Establishing a New User Identity

• $USERNAME contains the username
• $ROLES contains a comma-delimited list of the roles held by the user

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 Caché users has been synchronized with that in the Kerberos database, shut off unauthenticated access for all services.

• Kerberos cache (includes Kerberos with or without integrity-checking or encryption)
• OS-based
• LDAP (with checking the LDAP credentials cache second)
• Delegated
• Caché login
• Unauthenticated

1. Kerberos cache
2. OS-based
3. Unauthenticated

 set success = $SYSTEM.Security.Login(username,password)

• success is a boolean where 1 indicates success and 0 indicates failure
• username is a string holding the name of the account logging in
• password is a string holding the password for the username account

 set success = $SYSTEM.Security.Login(username)

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
}