Caché Security Administration Guide
Authentication
|
|
Authentication verifies the identity of any user attempting to connect to Caché. Once authenticated, a user has established communications with Caché, 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. Caché is typically configured to use only one of them. The supported authentication mechanisms are:
Caché 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, Caché 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 Caché. Each connection tool (such as the Terminal, Java, or CSP) uses a Caché service that allows the administrator to specify the supported authentication mechanism(s). (A Caché service is a gatekeeper for connecting to Caché; 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:
-
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.
An end-user uses a connection tool to interact with Caché 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 Caché use only one authentication mechanism and that you choose the instance’s authentication mechanism prior to installing Caché. Once installation has occurred, you can then begin configuring Caché to use the selected mechanism. This involves several steps:
-
With Kerberos, ensure that all Caché users are listed in the Kerberos KDC (Key Distribution Center) or Windows Domain Controller.
-
With operating-systembased 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.
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:
-
-
-
-
Caché has several ways in which it can authenticate a user, that is, verify the identity of a user. These are:
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 uses the TGT and session key to obtain both a service ticket for Caché as well as another encrypted session key.
-
The client uses the service ticket and second session key to authenticate to Caché 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 Caché 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 Caché 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.
With operating-systembased authentication, Caché uses the operating system’s user identity to identify the user for Caché purposes. Specifically, the process is:
-
Caché obtains the process’ operating-system user identity.
-
Caché checks if the operating system identity matches a Caché username. If so, then the user is automatically authenticated for Caché as well.
Caché 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 Caché mechanism as
Caché login.
For password authentication, Caché 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, Caché 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.
Caché 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.
Caché supports authentication based on LDAP (the Lightweight Directory Access Protocol). With LDAP authentication, Caché 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 Caché 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.
Caché supports three access modes:
With local access, the end-user is on the same machine as the Caché server. To gain access to the data, the user runs a private image of Caché that is reading from and writing to shared memory. If there are multiple local users, each has an individual copy of the Caché 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 Caché go on within a single process, this is also known as
in-process authentication.
Local access is available for:
-
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.
With client/server access, the Caché executable is the server and there is a client executable that can reside on a separate machine. Caché accepts a connection, possibly over a wire, from the client. This connection can use any language or protocol that Caché supports. These include:
-
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
All connection tools support authentication through Kerberos or Caché login except
%Service_ComPort, which only supports authentication through Caché login.
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.
The web access mode supports connections of the following form:
Architecture of a Web Connection
-
A user requests content or an action in a Web browser.
-
The Web browser passes along the request to the Web server.
-
The Web server is co-located with the CSP Gateway and passes the request to the Gateway.
-
The Gateway passes the request to the Caché server.
When the Caché 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 Caché, 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 Caché 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.
To configure a Caché instance for Kerberos authentication, the process is:
-
Ensure that Caché is set up to run as a Kerberos service.
-
-
-
-
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.
-
-
To maximally secure web connections, set up
secure channels for the following connections:
-
Web browser to Web server
-
CSP Gateway to Caché server
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.
Each connection tool uses a service to establish communications with Caché. 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 |
ActiveX |
Client/Server |
%Service_Bindings |
C++ |
Client/Server |
%Service_Bindings |
Caché Telnet |
Client/Server |
%Service_Telnet |
CallIn |
Local |
%Service_CallIn |
Console |
Local |
%Service_Console |
CSP |
Web |
%Service_CSP |
Java |
Client/Server |
%Service_Bindings |
JDBC |
Client/Server |
%Service_Bindings |
ODBC |
Client/Server |
%Service_Bindings |
Terminal |
Local |
%Service_Terminal |
Zen |
Web |
%Service_CSP |
Kerberos authentication for a local service establishes that the user and Caché 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 Caché, 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 applications include connections from ActiveX, C++, Java, JDBC, ODBC, Perl, Python, and through Caché Direct and Telnet. For a client/server application using Kerberos authentication, the user needs credentials to interact with Caché 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 Caché server machine:
-
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é.
When running a web application (using either CSP or Zen), the user does not interact directly with the Caché server. To protect all information from monitoring, you need to encrypt the connections between the user and Caché as follows:
-
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.
This applies to both CSP and Zen, since Zen uses CSP for its underlying connection.
Architecture of a Kerberos-Protected Web Connection
Any communications between the end-user and Caché occurs through SSL-encrypted or Kerberos-encrypted pipes. For Kerberos-secured connections, this includes the end-user’s Kerberos authentication.
Because the Caché 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 CSP Gateway, which then hands it to the CSP server (which is part of Caché itself). The CSP 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.
Client/server connections to Caché use one of the following services:
-
%Service_Bindings ActiveX, C++, Java, JDBC, ODBC, Perl, Python
-
%Service_CacheDirect Caché Direct
-
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
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.
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 and Caché Direct: Setting Up the Preferred Server for Use with Kerberos
With a Windows client, when establishing a connection using Caché Direct or Caché telnet for Windows, the client uses configuration information that has been stored as part of a remote server.
Important:
Caché has its own telnet server for Windows. When connecting to a non-Windows machine, there is no Caché 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 Caché using the
%Service_Terminal service.
To configure a client connection coming in through telnet or Caché Direct, go to the client machine. On that machine, the procedure is:
-
Click on the Caché cube and select
from the menu (the
choice also displays the name of the current preferred server).
-
From the submenu that appears, choose
.
-
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.
-
-
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.
-
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
-
-
If you are configuring a telnet connection to a Windows machine, check the box specifying that the connection use the Windows Caché Telnet server.
-
Click
OK to save the specified values and dismiss the dialog.
Setting Up an ODBC DSN for Use with Kerberos
Caché 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 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.
-
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.
Setting Up a Java or JDBC Client for Use with Kerberos
Caché 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, 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:
-
-
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.
-
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.
Setting Up a Client on C++, Perl, Python, and ActiveX for Use with Kerberos
To be able to establish a Kerberized connections through these bindings, you need only configure the Caché 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
Caché Language Bindings books.
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 Caché. In this situation, the application is using a service to connect to Caché. This includes the following services:
To specify how to get credentials, the procedure is:
-
-
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 Caché.
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 Caché 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, Caché 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:
-
ActiveX, Caché Direct, C++, ODBC, Perl, Python, and Telnet
-
ActiveX, Caché Direct, C++, ODBC, Perl, Python, and Telnet
The underlying Caché 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.
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:
-
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);
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:
-
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.
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.
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 CSP Gateway and Caché 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 Caché does not provide implementations of these technologies to accomplish this, various third-party products provide this capability.
Setting Up a Kerberized Connection from the CSP Gateway to Caché
To set up a secure, encrypted channel between the CSP Gateway and the Caché server, you need a Kerberos principal that represents the Gateway. This principal establishes an encrypted connection to Caché, and all information is transmitted through the connection. This allows an end-user to authenticate to Caché and prevents any snooping during that process.
-
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.
-
-
-
-
Configure the Gateway so that it can contact the server. The procedure is:
-
-
-
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.
-
-
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.
The CSP 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-Web server connection uses SSL.
Operating-systembased authentication (sometimes called
OS-based authentication) is only available for local processes, namely:
-
-
Console (
%Service_Console)
-
Terminal (
%Service_Terminal)
To set up the use of this type of authentication, the procedure is:
-
-
-
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.
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.
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.
The services available for authentication with Caché login are:
For a service to use Caché login, you must configure it as follows:
-
-
-
On this page, choose Caché login, listed simply as
Password from the list of authentication types.
-
Click
Save to save this setting.
-
In addition to this basic procedure, certain services require further configuration. This is described in the following sections:
For web access, you can optionally require that the CSP Gateway authenticate itself to the Caché server through Caché login. To perform this configuration, the procedure is:
-
-
-
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:
-
-
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.)
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 Caché login 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 Caché login, 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 CSP Gateway. Since the Gateway has its own connection to the Caché server, it then passes the username and password to the Caché server. To establish its connection to the Caché server, the Gateway uses the CSPSystem account, which is one of the
Caché 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 Caché server as described in the section
Setting Up a Secure Channel for a CSP 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 Caché server machines in a locked area with a direct physical connection between them.
Caché supports Caché login for ODBC connections among all its supported platforms. This requires client-side configuration. The ways of configuring client behavior vary by platform:
-
On non-Windows platforms, use the 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.
When establishing a connection using Caché Direct and the Caché Telnet server for Windows, the client uses configuration information that has been stored as part of a Caché remote server. To configure a remote server, go to the client machine. On that machine, the procedure is:
-
Click on the Caché cube and select
from the menu (the
choice also displays the name of the current preferred server).
-
From the submenu that appears, choose
.
-
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.
-
-
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.
-
Click
OK to save the specified values and dismiss the dialog.
Important:
When connecting to a non-Windows machine using telnet, there is no Caché 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 Caché using the
%Service_Terminal service.
In addition to the authentication mechanism in use, Caché supports the use of
two-factor authentication. This means that Caché 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. Caché performs two-factor authentication on its end-users using either of two mechanisms:
-
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.
This section covers the following topics:
The major steps to setting up two-factor authentication are:
-
-
-
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).
-
Configure the service, as appropriate:
-
-
-
%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.
-
Configure client/server applications and web applications, as appropriate:
-
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.
-
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.
-
-
Two-factor authentication using a time-based one-time password (TOTP) authentication works as follows:
-
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:
-
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).
-
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.
The end-user can get the secret key from Caché in several ways:
-
When you configure the end-user’s account to support two-factor TOTP authentication, the
Edit User page for the end-user displays the end-user’s secret key, as well as the name of the issuer and the end-user’s account name. It also displays a QR code that includes all this information (a QR code is a machine-readable code such as the one pictured below). The end-user can then enter the information into an authentication device or an application by scanning the code or entering the information manually.
-
If you choose to show the end-user their secret key during the login to a web application or Terminal session (using
%Service_Console or
%Service_Terminal), you can enable this behavior by selecting the
Display Time-Based One-time Password QR Code on next login field on the
Edit User page. The Terminal session will then display the end-user’s issuer, account, and secret key. A web application will display the end-user’s issuer, account, and secret key, along with a QR code; here, the end-user can then scan the code or enter the information manually.
Important:
InterSystems does not recommend this option. See the following caution for more details.
Caution:
The following are critical security concerns when using two-factor TOTP authentication:
-
Do
not transmit the secret key or QR code in an unsecured environment. Out-of-band transmission is preferable to transmission even on a secure network. (The secret key gives an end-user the means to log into Caché or a Caché application. If you and your end-users do not ensure the secret key’s safety, then an attacker may gain access to it, which renders it useless for security.)
-
When configuring two-factor TOTP authentication for your organization, InterSystems strongly recommends that you provide the secret key to each end-user in person or by phone, or that you have the end-user scan the QR code in the physical presence of an administrator. This provides the opportunity to authenticate the individual who obtains the secret key.
Delivering the secret key over the network increases the possibility of exposing it. This includes displaying the secret key to the end-user when they first log into a web application, console, or Terminal; this also includes displaying the QR code to the end-user when they first log into a web application.
A TOTP Issuer, Account, Key, and QR Code
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 Caché server. Without Java, Caché 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.
The steps in configuring two-factor authentication for the Caché server are:
-
-
-
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).
Enabling and Configuring Two-Factor Authentication Settings for an Instance
When setting up two-factor authentication for a Caché instance (server), you can enable one or both of:
To enable either form of two-factor authentication, the procedure is:
-
-
-
-
-
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).
-
-
SMTP username Optional username for SMTP authentication (if the SMTP server requires it).
-
-
-
If the instance is supporting SMS text authentication, configure mobile phone service providers as required. These procedures are described in the next section.
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:
-
-
-
To edit an existing provider, click
Edit on the provider’s row in the table of providers.
-
-
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.
Deleting a Mobile Phone Service Provider
To delete a mobile phone service provider, the procedure is:
-
-
-
When prompted to confirm the deletion, click
OK.
Predefined Mobile Phone Service Providers
Caché ships with a predefined list of mobile phone service providers, each with its SMS (short message service) gateway preset. These are:
To enable or disable two-factor authentication for
%Service_Bindings,
%Service_Console, and
%Service _Terminal, procedure is:
-
-
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.
-
-
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:
-
-
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.
-
Note:
A web application cannot simultaneously support both two-factor authentication and web services.
To configure an end-user to receive a one-time security token for two-factor authentication, the procedure is:
-
-
-
-
If you select
SMS Text, you must complete the following fields:
-
-
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.
-
-
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.
-
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.
-
-
QR Code A scannable code that contains the values of the issuer, account, and secret key.
-
Click
Save to save these values for the user.
If a service uses two-factor authentication and an end-user has two-factor authentication enabled, then authentication requires:
-
For SMS text authentication, a mobile phone that is able to receive text messages on that phone.
-
For TOTP authentication, an application or authentication device that can generate verification codes.
Otherwise, the end-user cannot authenticate:
-
For SMS text authentication, the end-user must have a mobile phone and be able to receive text messages on that phone. This is the phone number at which the user receives a text message containing the one-time security token as an SMS text.
-
For TOTP authentication, the user must have an authentication device or application that can either scan a QR code or that can accept the secret key and other information required to generate each TOTP (which serves as a verification code).
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:
-
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.
-
It gets the one-time security token from the user. This generally involves user-interface code that is not specifically related to Caché.
-
It provides the one-time security token to the Caché server. This also typically uses a connection object method.
Note:
When a user logs in through
%Service_Bindings, Caché 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 Caché server using
%Service_Bindings, does not support two-factor authentication.
With C++, support for two-factor authentication uses two methods of the
tcp_conn class:
-
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.
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:
-
It uses that instance’s methods to check if two-factor authentication is enabled.
-
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.
With Java, support for two-factor authentication uses two methods of the
CacheConnection class:
-
public boolean isTwoFactorEnabled() throws Exception
This method checks if two-factor authentication is enabled on the server. It returns a boolean;
true means that two-factor authentication is enabled.
-
public void sendTwoFactorToken(String token) throws Exception
This method provides the one-time security token to the server. It takes one argument,
token, the one-time security token that the user has received.
The following example uses an instance of a connection called
conn:
-
It uses that instance’s methods to check if two-factor authentication is enabled.
-
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.
}
}
For .NET, Caché supports connections with two-factor authentication with the managed provider and with ADO.NET. Support for two-factor authentication uses two methods of the
tcp_conn class:
-
bool 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.
Important:
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:
-
It uses that instance’s methods to check if two-factor authentication is enabled.
-
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
}
With ODBC, support for two-factor authentication uses two standard ODBC function calls (which are documented in the
Microsoft ODBC API Reference):
-
SQLRETURN rc = SQLGetConnectAttr(conn, 1002, &attr, sizeof(attr), &stringLengthPtr);
The
SQLGetConnectAttr function, part of the Microsoft ODBC API, returns the current value of a specified connection attribute. The 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.
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:
-
-
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.
}
}
-
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.
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:
-
It uses that instance’s methods to check if two-factor authentication is enabled.
-
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.
}
-
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.
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:
-
It uses that instance’s methods to check if two-factor authentication is enabled.
-
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.
Areas covered in this section are:
After authentication, two variables have values:
-
-
$ROLES contains a comma-delimited list of the roles held by the user
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:
-
For the transition period, configure all supported services to allow both unauthenticated and Kerberos-authenticated access. Users can then connect using either mechanism.
-
If appropriate, install new client software (which uses Kerberos for authentication).
-
Once the list of Caché 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.
While Caché 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, Caché uses what is called
cascading authentication to manage user access. With cascading authentication, Caché attempts to authenticate users via the specified mechanisms in the following order:
-
Kerberos cache (includes Kerberos with or without integrity-checking or encryption)
-
-
LDAP (with checking the LDAP credentials cache second)
-
-
-
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 Caché uses Kerberos cache only.
For example, if a service supports authentication through:
-
-
-
If a user attempts to connect to Caché, 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 Caché. If this succeeds, the user gets in. If either there is no initial TGT or a Caché service cannot be obtained, authentication fails and, so, cascades downward.
If the user has an OS-based identity that is in the Caché list of users, then the user gets in. If the user’s OS-based identity is not in the Caché 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 Caché.
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.
If Caché login 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 Caché login is enabled, then pressing
Enter at the
Username and
Password prompts denies access to the service; Caché treats this as a user attempting to log in as the UnknownUser account and providing the wrong password.
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 Caché log in functionality through the
Login method of the
$SYSTEM.Security class with the following syntax:
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
-
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.
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 Caché 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.
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
}