Introduction

Single Sign-On (SSO) is a new authentication mechanism to IBM Informix Dynamic Server (IDS) 11.50. With SSO support, users enter their password once when they login to the operating system, and thereafter, they have access to multiple software systems without needing to reenter their username and password. Other IDS server authentication mechanisms include traditional OS user name and password authentication and Pluggable Authentication Module (PAM), both of which generally require the user to supply a user name and password each time they connect to the database.

The IDS server provides SSO support using Kerberos 5 and the Generic Security Services Application Programming Interface (GSS API) open standards. IDS support for SSO is provided as a communication support module called GSSCSM.

Back to top

Kerberos overview

Kerberos is an authentication protocol that uses 'tickets' to verify the identity of a user in an unprotected network. Kerberos uses a trusted third party called the key distribution center (KDC). The KDC is trusted by all clients and servers in the network and is used to verify user identities. The KDC logically consists of an Authentication Server (AS) and a Ticket Granting Server (TGS). KDC also has a database of secret keys; each entity (user, host, or an application server) shares a secret key with the KDC.

The figure below provides an overview of the communication between the client, application server and the KDC during authentication. The first step is for the user to obtain a Ticket Granting Ticket (TGT) from the KDC. This can be done as part of the login process if that is kerberized. Alternatively, the TGT can be obtained after the login process. Once the user has a TGT, the authentication to different kerberized services is invisible to the user. The user does not need to do anything after entering the password for the initial TGT. Refer to the Kerberos standard for the details of the Kerberos protocol [RFC4120] (see Resources).

• AS_REQ

• AS_REQ is the initial user authentication request. This message is directed to the KDC component known as Authentication Server (AS).

• AS_REP

• AS_REP is the reply of the AS to the previous request. Basically, it contains the TGT (encrypted using the TGS secret key) and the session key (encrypted using the secret key of the requesting user).

• TGS_REQ
  • TGS_REQ is the request from the client to the Ticket Granting Server (TGS) for a service ticket. This packet includes the TGT obtained from the previous message and an authenticator generated by the client and encrypted with the session key.
• TGS_REP
  • TGS_REP is the reply of the TGS to the previous request. Located inside is the requested service ticket (encrypted with the secret key of the service) and a service session key generated by the TGS and encrypted using the session key previously generated by the AS.
• AP_REQ
  • AP_REQ is the request that the client sends to an application server to access a service. The components are the service ticket obtained from the TGS with the previous reply and another authenticator generated by the client, but this time encrypted using the service session key (generated by TGS).
• AP_REP
  • AP_REP is the reply that the application server gives to the client to prove that it really is the server the client is expecting. This packet is not always requested. The client requests the server for it only when mutual authentication is necessary.

The KDC holds the passwords of all the principals in a realm. This makes it very important that the KDC database is not compromised because otherwise it becomes a single point of failure. The host running the KDC should run essentially no other services to minimize the risk of compromise. Kerberos does not address password-guessing and denial-of-service attacks. Kerberos uses a principal's password (encryption key) as the fundamental proof of identity. If a user's Kerberos password is stolen by an attacker, then the attacker can impersonate that user. It is important to understand how to configure a KDC and the steps to take to prevent it from being compromised.

Back to top

Configure IDS to use SSO

The SSO solution provided with IDS relies on Kerberos being properly installed and configured on IDS server and client machines. The KDC should be on a machine separate from both the IDS server and client machines. Follow these steps to configure SSO:

1. Configure the KDC server
2. Configure the IDS server (service) principal in the KDC
3. Configure the client (user) principal in the KDC
4. Configure IDS to use SSO authentication
5. Configure the client to use SSO authentication

Each of these steps is explained in detail below.

1. Configure the KDC Server

The example KDC setup below shows the steps needed to set up an MIT Kerberos authentication system. The Kerberos setup for other Kerberos implementations is very similar.

Note: This step is required only if the machine is not already configured for Kerberos authentication. The location of the Kerberos configuration files and Kerberos utility is dependent on the Kerberos installation location.

• Install Kerberos and necessary packages if Kerberos is not already available. Edit the krb5.conf and kdc.conf configuration files to reflect your realm name and domain-to-realm mappings.

[logging]
 default = FILE:/var/log/krb5libs.log
 kdc = FILE:/var/log/krb5kdc.log
 admin_server = FILE:/var/log/kadmind.log

[libdefaults]
 default_realm = EXAMPLE.LENEXA.IBM.COM
 dns_lookup_realm = true
 dns_lookup_kdc = true

[realms]
  EXAMPLE.LENEXA.IBM.COM = {
  kdc = toru.lenexa.ibm.com:88
  admin_server = toru.lenexa.ibm.com:749
  default_domain = lenexa.ibm.com
 }

[domain_realm]
 .lenexa.ibm..com = EXAMPLE.LENEXA.IBM.COM
 lenexa.ibm.com = EXAMPLE.LENEXA.IBM.COM

[kdc]
 profile = /var/kerberos/krb5kdc/kdc.conf

[kdcdefaults]
 acl_file = /var/kerberos/krb5kdc/kadm5.acl
 dict_file = /usr/share/dict/words
 admin_keytab = /var/kerberos/krb5kdc/kadm5.keytab
 v4_mode = nopreauth

[realms]
 EXAMPLE.LENEXA.IBM.COM = {
  master_key_type = des-cbc-crc
  supported_enctypes = des3-hmac-sha1:normal des-hmac-sha1:normal 
    des-cbc- md5:normal des-cbc-crc:normal des-cbc-crc:v4 des-cbc-crc:afs3
 }

The kadm5.acl (access control list) file resides on the KDC host and controls access to the Kerberos database. The location of the kadm5.acl is specified in the kdc.conf. It contains the names of principals and the access permissions followed by an optional principal that the ACL applies.

• Create the KDC database using the kdb5_util utility.

$kdb5_util create –s
Loading random data
Initializing database '/var/kerberos/krb5kdc/principal' for realm
'EXAMPLE.LENEXA.IBM.COM'
master key name 'K/M@EXAMPLE.LENEXA.IBM.COM'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key: 
Re-enter KDC database master key to verify:

• Define the policy for handling passwords and its lifetime using kadmin.

/usr/kerberos/sbin/kadmin.local
------------------------------------
kadmin.local:  add_policy -maxlife 180days -minlife  2days 
	       -minlength 8 –minclasses 3 -history 10 default

• Add admin principal using kadmin.

Kadmin is the administrative interface to the Kerberos database. Using the kadmin utility, a Kerberos administrator can add principals, modify principals, delete principals, change passwords, and do other administrative tasks.The kadmin is run over a network from another machine, and requires you to authenticate to a principal that has administrative privileges.

The kadmin.local is a copy of kadmin. It must be run locally on the KDC as root and modifies the KDC databases directly. The admin principals are KDC service principals that handle the administrative tasks.

The kadmin utility has to be started from the command line.

kadmin.local
Authenticating as principal informix/admin@EXAMPLE.LENEXA.IBM.COM with
password.
kadmin.local:
    

Once in kadmin.local, you can execute Kerberos administrator tasks. The code listings in this article assume that you have logged into either kadmin.local or kadmin before executing the administrator commands.

kadmin.local: addprinc informix/admin
Note: This will prompt for password for informix/admin@EXAMPLE.LENEXA.IBM.COM

Ex: kadmin.local:  add_principal informix/admin
Enter password for principal "informix/admin@EXAMPLE.LENEXA.IBM.COM": 
Re-enter password for principal "informix/admin@EXAMPLE.LENEXA.IBM.COM": 
Principal "informix/admin@EXAMPLE.LENEXA.IBM.COM" created.

kadmin.local:  list_principals
K/M@EXAMPLE.LENEXA.IBM.COM
informix/admin@EXAMPLE.LENEXA.IBM.COM
kadmin/admin@EXAMPLE.LENEXA.IBM.COM
kadmin/changepw@EXAMPLE.LENEXA.IBM.COM
kadmin/history@EXAMPLE.LENEXA.IBM.COM
krbtgt/EXAMPLE.LENEXA.IBM.COM@EXAMPLE.LENEXA.IBM.COM
Kadmin.local:quit

• Start the KDC daemon.

$/usr/local/sbin/krb5kdc

2. Configure the IDS server (service) principal in the KDC

In a Kerberos installation, each entity (individual users, computers, and services running on servers) has a principal associated with it. The KDC administrator must add a server principal to the KDC database for each SSO-enabled IDS database server.

The service principal name starts with the service name. Kerberos 5 service principals include the fully qualified domain name (FQDN) of the host that the service is installed on. The generic service principal format is

service/fully-qualified-domain-name@REALM

In the example below, a service principal for Informix server called ol_ids_1150 is added to the KDC.

kadmin.local:  add_principal ol_ids_1150/toru.lenexa.ibm.com 
---------------------------------------------
Enter password for principal
"ol_ids_1150/toru.lenexa.ibm.com@EXAMPLE.LENEXA.IBM.COM": 
Re-enter password for principal
"ol_ids_1150/toru.lenexa.ibm.com@EXAMPLE.LENEXA.IBM.COM": 
Principal "ol_ids_1150/toru.lenexa.ibm.com@EXAMPLE.LENEXA.IBM.COM" created.

List the principals:
--------------------
kadmin.local:  list_principals
K/M@EXAMPLE.LENEXA.IBM.COM
informix/admin@EXAMPLE.LENEXA.IBM.COM
kadmin/admin@EXAMPLE.LENEXA.IBM.COM
kadmin/changepw@EXAMPLE.LENEXA.IBM.COM
kadmin/history@EXAMPLE.LENEXA.IBM.COM
krbtgt/EXAMPLE.LENEXA.IBM.COM@EXAMPLE.LENEXA.IBM.COM
ol_ids_1150/toru.lenexa.ibm.com@EXAMPLE.LENEXA.IBM.COM
kadmin.local:  quit

Each IDS server principal shares its own private key with KDC, and this key is stored in the server's keytab file. It is imperative that the keytab file is protected by process access permissions. On UNIX, the owner should be user informix, the group should be group informix , and the permission should be 400.

kadmin.local:  ktadd -k /etc/krb5.keytab -e "des-cbc-crc:normal"
 ol_ids_1150/toru.lenexa.ibm.com
Entry for principal ol_ids_1150 with kvno 2, 
encryption type DES cbc mode with CRC-32 added to keytab
WRFILE:/etc/krb5.keytab.

The keytab file should reside in the machine where the IDS server resides. The location of the keytab file is specified in the krb5.conf file. The keytab file can be generated in the KDC, securely transported to the IDS server machine, and merged with existing keytab file as shown below.

Example:/usr/kerberos/sbin/ktutil 
ktutil: rkt /etc/keytab.ol_ids_1150_fromkdc
ktutil: wkt /etc/krb5.keytab 
ktutil: quit

3. Configure client (user) principal in the KDC

Each client login name must be added to Kerberos database. The generic user principal format is username[/instance]@REALM.

kadmin.local:  add_principal informix
Enter password for principal "informix@EXAMPLE.LENEXA.IBM.COM": 
Re-enter password for principal "informix@EXAMPLE.LENEXA.IBM.COM": 
Principal "informix@EXAMPLE.LENEXA.IBM.COM" created.
kadmin.local:  quit

4. Configure IDS to use SSO authentication

SSO authentication is enabled using the sqlhosts and concsm.cfg entries in IDS server and client.

Define a SSO GSSCSM

The concsm.cfg file defines the CSM configuration information. By default, the concsm.cfg file resides in $INFORMIXDIR/etc/. The IDS administrator (DBSA) can configure the location of CSM configuration by specifying the INFORMIXCONCSMCFG environment variable for IDS when it is started.

The syntax of entry in concsm.cfg is

csmname("client=clientlib, server=serverlib, "global_opts", "conn_opts")

• csmname is name to the communication support module
• clientlib and server lib value specifies the full path and name of the GSSCSM shared library
• there are no global options in the current release of the GSSCSM module
• connection option specifies whether confidentiality and integrity is used
• confidentiality is specified by connection option 'c = [01],' the vaule 1 indicating that confidentiality (encryption) is used, and 0 indicating that it is not.
• integrity is specified using connection option 'i = [01],' the value 1 indicating that integrity (using message authentication codes to ensure that the message received is the one that was sent) is used, and 0 indicating that it is not used.

Example concsm.cfg configuration

GSSCSM("/work/informixdir/lib/csm/igsss11a.so", "", "c=1,i=1")

Configure SQLHOSTS file for SSO

Associate SSO CSM with a particular server alias of an IDS server.

Example sqlhosts entry configured for SSO authentication

ol_ids_1150 onsoctcp toru ol_ids_1150 s=7,csm=(GSSCSM)

Please refer to the IBM Informix Dynamic Server Administrators guide and the IBM Informix Security guide for more details on SQLHOSTS and concsm.cfg syntax and usage (see Resources).

Do not forget to restart IDS after configuring SSO because the changes will not take effect until the next time it is started.

5. Configure the client to use SSO authentication

The steps for preparing the SQLHOSTS information and the Generic Security Services (GSS) CSM configuration file for the Client SDK program and client computer are similar to the corresponding server-side setup procedures.

ESQL/C client

Include a SQLHOSTS entry specifying onsoctcp (or ontlitcp) in the NETTYPE field and s=7,csm=(GSSCSM) in the OPTIONS field matching the same information for the Kerberos service in the server's SQLHOSTS information. If the client is not running out of the same INFORMIXDIR (or on the same machine) as the server, then you must create an appropriate concsm.cfg file, possibly setting the INFORMIXCONCSMCFG environment variable.

ODBC client on UNIX and Linux

Add Options=s=7,csm=(GSSCSM) to the connection settings for the SSO-enabled database server entry in the odbc.ini file.

Driver=/ATM/STR100/sqldist/lib/cli/iclit01b.${SHLIBSUFFIX} 
Description=IBM INFORMIX ODBC DRIVER LogonID=informix Password=$INFORMIXPASSWORD
Pwd=$INFORMIXPASSWORD Database=common_db ServerName=ol_ids_1150 
Options=s=7,csm=(GSSCSM).

JDBC client

1. When the JDBC driver is the client for SSO, use the DriverManager.getConnection() method with an SSO connection property set to the IDS server service principal.

Modify the connection URL so that it includes the service principal. The ENC=true setting means that Generic Security Services (GSS) encryption and integrity is enabled.

String url = 
"jdbc:informix-sqli://toru.lenexa.ibm.com:9019:informixserver=ol_ids_1150; 
 CSM=(SSO=ol_ids_1150/toru.lenexa.ibm.com@LENEXA.IBM.COM,ENC=true)";

2. Create a login configuration file with the following code:

bcsLogin.conf file
com.sun.security.jgss.initiate {
        com.sun.security.auth.module.Krb5LoginModule required 
useTicketCache=true 
doNotPrompt=true;
}

3. Run the application with the java.security.auth.login.config property set to the login configuration file's full path name.

java -Djava.security.auth.login.config=bcsLogin.conf TestSso

Back to top

Additional Kerberos configuration in IDS server and client machines

Each IDS client and server machine should have enabled Kerberos authentication to use SSO. It is not necessary to configure Kerberos as users' default login authentication. The user can always obtain Kerberos credentials by using kinit on the client machine after login. The server credentials are automatically obtained by the IDS server when it starts up, using the keytab file.

Obtain client authentication credential (TGT) using kinit

Ideally, the client machine is configured so that the login process acquires Kerberos credentials for the user as he or she logs in. However, if the client machine is not set up to do this, the user can obtain the credential using the kinit command as shown below.

/usr/local/bin/kinit  informix/admin@EXAMPLE.LENEXA.IBM.COM
Password for informix/admin@EXAMPLE.LENEXA.IBM.COM:

klist
-------
Ticket cache: FILE:/tmp/krb5cc_200
Default principal: informix/admin@EXAMPLE.LENEXA.IBM.COM

Valid starting     Expires            Service principal
07/16/08 06:53:46  07/17/08 06:53:40  krbtgt/EXAMPLE.LENEXA.IBM.COM@EXAMPLE.LENEXA.IBM.COM

Kerberos 4 ticket cache: /tmp/tkt200
klist: You have no tickets cached

Add host principals of IDS client and server machines

In a Kerberos realm, the hosts and servers offering Kerberos services also have principals. Therefore, the host machines of IDS client and server have to be added to the KDC for successful Kerberos authentication.

An example Kerberos 5 host principal: host/toru.lenexa.ibm.com@EXAMPLE.LENEXA.IBM.COM

kadmin.local:  add_principal host/toru.lenexa.ibm.com 
---------------------------------------------
Enter password for principal "host/toru.lenexa.ibm.com@EXAMPLE.LENEXA.IBM.COM": 
Re-enter password for principal "host/toru.lenexa.ibm.com@EXAMPLE.LENEXA.IBM.COM": 
Principal "host/toru.lenexa.ibm.com@EXAMPLE.LENEXA.IBM.COM" created.

Back to top

Troubleshooting

Kerberos authentication failures can happen at many stages when using the Kerberos protocol. These are some of the most common causes of failure – and all of them are readily avoided with a little experience using the system.

• The client cannot get the initial Ticket Granting Ticket (TGT)
  • A client cannot get a TGT when the password is incorrect or there are Kerberos configuration errors in the client machine. The client principal name and client host principal name should be in the KDC database.
• The client has the valid TGT but cannot obtain the service ticket(TGS)
  • To troubleshoot the problem, look for the error messages in krb5kdc.log files. Check the Kerberos configuration on the client machine. The server service principal should exist in KDC database.
• The client has a valid TGT and TGS for the IDS server but is not able to connect to the kerberized server
  • Look for error messages in the Kerberos log and online.log file. The problem is most likely on the server side. Verify the keytab file and key version numbers. The Kerberos log would provide more information if there is any mismatch in encryption, clock synchronization or any configuration errors. IDS does not support cross-realm authentication.

To test Kerberos setup, we recommend running the sample client and server program which is generally part of Kerberos installation package. For example, MIT Kerberos 5 distribution has sample programs called sclient and sserver. The Heimdal version includes gssapi_client and gssapi_server programs. These tests programs would easily catch any configuration issues which would cause the authentication to fail.

Some specific SSO error messages and solutions are explained below.

1. 5000: CSM error gss_init_sec_context() fails : clock not synchronized

Server error :

5000: CSM error: gss_init_sec_context: Unspecified GSS failure.  
Minor code may provide more information. Clock skew too great

Message in krb5kdc.log file:

 Jul 10 13:02:52 lxvm-l141 krb5kdc[12925](info): TGS_REQ (5 etypes {17 16 23 3 1}) 
9.25.151.39: PROCESS_TGS: authtime 0,  <unknown client> 
for ol_ids_1150/toru.lenexa.ibm.com@LENEXA.IBM.COM, Clock skew too great

Fix: The Kerberos authentication protocol requires that the clock skew between a server and a client is no greater than 5 minutes. If this error occurs, synchronize the clocks in the IDS client, server, and KDC machines.

2. 5000: CSM error: No server service principal in keytab file

Server error :

14:05:30  listener-thread: err = -5000: oserr = 0: errstr = gss_acquire_cred:
 Unspecified GSS failure. Minor code may provide more information.
 No principal in keytab matches desired name

Fix: The IDS server key is stored in the keytab file pointed to by the Kerberos configuration file. If the key is not generated for the Informix server principal or when the server key is stored in an incorrect location in the IDS server machine, the gss_acquire_cred() fails.

If the kerberized IDS server is able to read the ticket contents sent by clients for authentication, both the encryption key and the key version number that is stored in the service's keytab must match the encryption key and key version number that is stored in the Kerberos database. A mismatch in either the encryption key or key version number causes the decryption process to fail.

3. 25590: Authentication error

Message in Kerberos log file:

Jul 24 05:07:27 sun280-6 krb5kdc[26612](info): TGS_REQ 9.25.148.203(0): 
UNKNOWN_SERVER: authtime 1216893965, informix@SUN_KDC for ol_vardhan/sun280-
6.lenexa.ibm.com@SUN_KDC, Server not found in Kerberos database

Fix: Verify whether the server service principal name and client principal name are in the KDC database. Also, check for valid Kerberos credentials on the client using the output from klist. Only a user with a valid, unexpired TGT can connect to the kerberized server.

4. 5000: CSM error: gss_acquire_cred: No credentials error

Server error:

5000: CSM error: gss_acquire_cred: No credentials were supplied, 
  or the credentials not found

Messages in online.log:

14:14:46  listener-thread: err = -14565: oserr = 0: errstr = : CSS: error reading data.
14:14:49  listener-thread: err = -25580: oserr = 32: errstr =
 : System error occurred in network function.
 System error = 32.

An authentication error will occur if the user trying to connect is not same as the user whose credential is in the Kerberos cache.

5. Encryption type mismatch

Message in krb5kdc.log file:

Jul 24 05:12:53 sun280-6 krb5kdc[26612](info): TGS_REQ 9.25.148.203(0): 
BAD_ENCRYPTION_TYPE: authtime 1216893965,  informix@SUN_KDC for\
ol_ids_1150/toru.lenexa.ibm.com@SUN_KDC, KDC has no support for encryption type

Check the list of supported Kerberos encryption types on client and server (and KDC). Encryption type mismatches occur particularly when the client and server machine are configured with different Kerberos installations.

Back to top

Conclusion

Single-sign-on (SSO) support in IDS will simplify the user authentication and password administration. This article gives an overview of the Kerberos protocol used by IDS to provide SSO support. You learned to set up Kerberos environment and the steps needed to enable SSO in IDS.

Back to top

Acknowledgments

The authors would like to thank their architect Jonathan Leffler for reviewing this article.

Resources

Learn

• RFC 4120: See "The Kerberos network authentication service (V5)."
  
  
• RFC 4121: Read "The Kerberos 5 Gss-API mechanism: Version 2."
  
  
• Visit MIT Kerberos V to get information about the latest Kerberos release.
  
  
• Get help in the IBM Informix Dynamic Server v11.50 Information Center.
  
  
• Check out these Kerberos FAQ's.
  
  
• Learn about the Kerberos Protocol and its implementations.
  
  
• developerWorks Information Management zone: Learn more about Information Management. Find technical documentation, how-to articles, education, downloads, product information, and more.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  

Get products and technologies

• Build your next development project with IBM trial software, available for download directly from developerWorks.
  
  

Discuss

• Participate in developerWorks blogs and get involved in the developerWorks community.
  
  

About the authors

Manoj Mohan has worked in the IBM-IDS Team as a software developer for five years. His experiences include designing and implementing Pluggable Authentication Module (PAM) and IP V6 support in IDS Server. Manoj was also involved in designing and implementing trusted context support in DB2 for Linux, UNIX, and Windows.

Priya Govindarajan is a software engineer working in IDS security team. She is involved in implementing IDS security features. Priya holds a master's degree in Computer Science from University of California, Irvine.

Harshavardhan Changappa works for the IDS Integration Team at India Software Labs, IBM. He has worked on IDS certification of various Linux OS levels such as Ubuntu, Asianux, Debian etc. He is also involved in developing automated test cases for various features of IDS. He got certified as a System Administrator for IBM IDS V11.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Kerberos overview
• Configure IDS to use SSO
• Additional Kerberos configuration in IDS server and client machines
• Troubleshooting
• Conclusion
• Acknowledgments
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Informix Dynamic Server Enterprise Edition
• Demo: Use DB2 First Steps and the DB2 Control Center
• Webcast: A smarter way to successful SOA - Information as a trusted strategic asset
• Briefing: Information on Demand
• Buy: Informix Dynamic Server Enterprise Edition

My developerWorks community

Dig deeper into Information Management on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers