Setting up Kerberos Authentication

A newer version of this documentation is available. Click here to view the most up-to-date release of the Greenplum 4.x documentation.

Setting up Kerberos Authentication

On the versions of Red Hat Enterprise Linux that are supported by Greenplum Database, you can use a Kerberos authentication system to control access to Greenplum Database. Greenplum Database supports GSSAPI with Kerberos authentication. GSSAPI provides automatic authentication (single sign-on) for systems that support it. If Kerberos authentication is not available when a role attempts to log into Greenplum Database the login fails.

You specify which Greenplum Database users require Kerberos authentication in the Greenplum Database configuration file pg_hba.conf. Whether you specify Kerberos authentication or another type of authentication for a Greenplum Database user, authorization to access Greenplum databases and database objects such as schemas and tables is controlled by the settings specified in the pg_hba.conf file and the privileges given to Greenplum Database users and roles within the database. For information about managing authorization privileges, see Managing Roles and Privileges.

This chapter describes how to configure a Kerberos authentication system and Greenplum Database to authenticate a Greenplum Database administrator.

For more information about Kerberos, see http://web.mit.edu/kerberos/.

Enabling Kerberos authentication for Greenplum Database

The following tasks are required to use Kerberos with Greenplum Database:

  1. Set up a Kerberos Key Distribution Center (KDC) server.

    In a Kerberos database on the KDC server, set up a Kerberos realm and principals on the server. For Greenplum Database, a principal is a Greenplum Database role that utilizes Kerberos authentication. In the Kerberos database, a realm groups together the Kerberos principals that are the Greenplum Database roles.

  2. Create a Kerberos keytab file for Greenplum Database.

    To access Greenplum Database, you create a service key known only by Kerberos and Greenplum Database. On the Kerberos server, the service key is stored in the Kerberos database.

    On the Greenplum Database master, the service key is stored in key tables, which are files known as keytabs. The service keys are usually stored in the keytab file /etc/krb5.keytab. This service key is the equivalent of the service’s password, and must be kept secure. Data which is meant to be read only by the service is encrypted using this key.

  3. Install the Kerberos client packages and the keytab file on Greenplum Database master.
  4. Create a Kerberos ticket for gpadmin on Greenplum Database master node using the keytab file. The ticket contains the Kerberos authentication credentials that grant access to the Greenplum Database.

With Kerberos authentication configured on the Greenplum Database, you can use to use Kerberos for PSQL and JDBC.

Setting up Greenplum Database with Kerberos for PSQL

Setting up Greenplum Database with Kerberos for JDBC

Requirements for using Kerberos with Greenplum Database

The following items are required for using Kerberos with Greenplum Database:

  • Kerberos Key Distribution Center (KDC) server that uses the krb5-server library.
  • Kerberos packages for version 5
  • krb5-libs
  • krb5-workstation
  • Greenplum Database capable of supporting Kerberos
  • A configuration that allows the Kerberos server and the Greenplum Database master to communicate with each other.
  • Red Hat Enterprise Linux 6.x requires Java 1.7.0_17 or later.
  • Red Hat Enterprise Linux 5.x requires Java 1.6.0_21 or later.
  • Red Hat Enterprise Linux 4.x requires Java 1.6.0_21 or later.

Notes

The dates and times on the Kerberos server and clients must be synchronized. Authentication fails if the time difference between the Kerberos server and a client too large. The maximum time difference is configurable, 5 minutes is the default.

The Kerberos server and client must be configured so that they can ping each other using their host names.

The Kerberos authentication itself is secure, but the data sent over the database connection is transmitted in clear text unless SSL is used.

Installing and Configuring a Kerberos KDC Server

The following steps install and configure a Kerberos Key Distribution Center (KDC) server:

  1. Install the Kerberos packages for the Kerberos server: krb5-libs krb5-server krb5-workstation
  2. Edit the /etc/krb5.conf configuration file. See krb5.conf Configuration File for sample configuration file parameters.

    When you create a KDC database, the parameters in the /etc/krb5.conf file specify that the realm KRB.GREENPLUM.COM is created. You use this realm when you create the Kerberos principals that are Greenplum Database roles.

    If you have an existing Kerberos server you might need to edit the kdc.conf file. See the Kerberos documentation for information about the kdc.conf file.

  3. To create a Kerberos KDC database, run the kdb5_util. For example:
    kdb5_util create -s

    The create option creates the database to store keys for the Kerberos realms that are managed by this KDC server. The -s option creates a stash file. Without the stash file, every time the KDC server starts it requests a password.

  4. The Kerberos utility kadmin uses Kerberos to authenticate to the server. Before using kadmin, add an administrative user to KDC database with kadmin.local. kadmin.local is local to the server and does not use Kerberos authentication. To add the user gpadmin as an administrative user to the KDC database, run the following command:
    kadmin.local -q "addprinc gpadmin/admin"

    Most users do not need administrative access to the Kerberos server. They can use kadmin to manage their own principals (for example, to change their own password). For information about kadmin, see the Kerberos documentation.

  5. If needed, edit the /var/kerberos/krb5kdc/kadm5.acl file to grant the appropriate permissions to gpadmin.
  6. Start the Kerberos daemons with the following commands:
    /sbin/service krb5kdc start
    /sbin/service kadmin start

    If you want to start Kerberos automatically upon restart, run the following commands:

    /sbin/chkconfig krb5kdc on
    /sbin/chkconfig kadmin on

Creating Greenplum Database Roles in the KDC Database

After you have set up a Kerberos KDC and have created a realm for Greenplum Database, you add principals to the realm.

  1. Create principals in the Kerberos database with kadmin.local.

    Using kadmin.local in interactive mode, the following commands add users:

    addprinc gpadmin/kerberos-gpdb@KRB.EXAMPLE.COM
    addprinc postgres/master.test.com@KRB.EXAMPLE.COM
    

    The first addprinc command creates a Greenplum Database user as a principal. In this example, the principal is gpadmin/kerberos-gpdb. See Setting up Greenplum Database with Kerberos for PSQL for information on modifying the file pg_hba.conf so The Greenplum Database user gpadmin/kerberos-gpdb uses Kerberos authentication to access Greenplum Database from the master host.

    The second addprinc command creates the postgres process as principal in the Kerberos KDC. This principal is required when using Kerberos authentication with Greenplum Database. The syntax for the principal is postgres/GPDB_master_host. The GPDB_master_host is the host name of the Greenplum Database master.

  2. Create a Kerberos keytab file with kadmin.local. The following example creates a keytab file gpdb-kerberos.keytab with authentication information for the two principals.
    xst -k gpdb-kerberos.keytab
       gpadmin/kerberos-gpdb@KRB.EXAMPLE.COM
       postgres/master.test.com@KRB.EXAMPLE.COM
    

You use the keytab file gpdb-kerberos.keytab on the Greenplum Database master.

Installing and Configuring the Kerberos Client

Install the Kerberos client libraries on the Greenplum Database master and configure the Kerberos client:

  1. Install the Kerberos packages on the Greenplum Database master. krb5-libs krb5-workstation
  2. Ensure that the /etc/krb5.conf file is the same as the one that is on the Kerberos server.
  3. Copy the gpdb-kerberos.keytab that was generated on the Kerberos server to Greenplum Database master.
  4. Remove any existing tickets with the Kerberos utility kdestroy. As root, run the utility.
    # kdestroy
    
  5. Use the Kerberos utility kinit to request a ticket using the keytab file on the Greenplum Database master for gpadmin/kerberos-gpdb@KRB.EXAMPLE.COM. The -t option specifies the keytab file on the Greenplum Database master.
    # kinit -k -t gpdb-kerberos.keytab 
    gpadmin/kerberos-gpdb@KRB.EXAMPLE.COM
    

Use the Kerberos utility klist to display the contents of the Kerberos ticket cache on the Greenplum Database master. The following is example klist output:

# klist
Ticket cache: FILE:/tmp/krb5cc_108061
Default principal: gpadmin/kerberos-gpdb@KRB.EXAMPLE.COM
Valid starting     Expires            Service principal
03/28/13 14:50:26  03/29/13 14:50:26   krbtgt/KRB.GREENPLUM.COM     @KRB.EXAMPLE.COM
    renew until 03/28/13 14:50:26

Setting up Greenplum Database with Kerberos for PSQL

After you have set up Kerberos on the Greenplum Database master, you can configure a Greenplum database to use Kerberos. For information on setting up the Greenplum Database master, see Installing and Configuring the Kerberos Client.

  1. Create a Greenplum Database administrator role in the database template1 for the Kerberos principal that is used as the database administrator. The following example uses gpamin/kerberos-gpdb.
    psql template1 -c 'create role "gpadmin/kerberos-gpdb" login 
    superuser;'
    

    The role you create in the database template1 will be available in any new Greenplum database that you create.

  2. Modify postgresql.conf to specify the location of the keytab file. For example, adding this line to the postgresql.conf specifies the folder /home/gpadmin as the location of the keytab file gpdb-kerberos.keytab.
    krb_server_keyfile = '/home/gpadmin/gpdb-kerberos.keytab'
    
  3. Modify the Greenplum Database file pg_hba.conf to enable Kerberos support. Then restart Greenplum Database (gpstop -ar). For example, adding the following line to pg_hba.conf adds GSSAPI and Kerberos support. The value for krb_realm is the Kerberos realm that is used for authentication to Greenplum Database.

    host all all 0.0.0.0/0 gss include_realm=0 krb_realm=KRB.GREENPLUM.COM

    For information about the pg_hba.conf file, see the Postgres documentation: http://www.postgresql.org/docs/8.4/static/auth-pg-hba-conf.html

  4. Create a ticket using kinit and show the tickets in the Kerberos ticket cache with klist.
  5. As a test, log in to the database as the gpadmin role with the Kerberos credentials gpadmin/kerberos-gpdb:
    psql -U "gpadmin/kerberos-gpdb" -h master.test template1
    

Notes

  • A username map can be defined in the pg_ident.conf file and specified in the pg_hba.conf file to simplify logging into Greenplum Database. For example, this psql command logs into the default Greenplum Database on mdw.proddb as the Kerberos principal adminuser/mdw.proddb:
    $ psql -U "adminuser/mdw.proddb" -h mdw.proddb
    

    If the default user is adminuser, the pg_ident.conf file and the pg_hba.conf file can be configured so that the adminuser can log into the database as the Kerberos principal adminuser/mdw.proddb without specifying the -U option:

    $ psql -h mdw.proddb

    The following username map is defined in the Greenplum Database file $MASTER_DATA_DIRECTORY/pg_ident.conf:

    # MAPNAME   SYSTEM-USERNAME        GP-USERNAME
    mymap       /^(.*)mdw\.proddb$     adminuser

    The map can be specified in the pg_hba.conf file as part of the line that enables Kerberos support:

    host all all 0.0.0.0/0 krb5 include_realm=0 krb_realm=proddb 
       map=mymap
    

    For more information on specifying username maps see the Postgres documentation: http://www.postgresql.org/docs/8.4/static/auth-username-maps.html

  • If a Kerberos principal is not a Greenplum Database user, a message is similar to the following is displayed from the psql command line when the user attempts to log into the database:
    psql: krb5_sendauth: Bad response

    The principal must be added as a Greenplum Database user.

Setting up Greenplum Database with Kerberos for JDBC

You can configure Greenplum Database to use Kerberos to run user-defined Java functions.

  1. Ensure that a Kerberos is installed and configured on the Greenplum Database master. See Installing and Configuring the Kerberos Client.
  2. Create the file .java.login.config in the folder /home/gpadmin and add the following text to the file:
    pgjdbc {
      com.sun.security.auth.module.Krb5LoginModule required
      doNotPrompt=true
      useTicketCache=true
      debug=true
      client=true;
    };
    
  3. Create a Java application that connects to Greenplum Database using Kerberos authentication.

    The this example database connection URL uses a PostgreSQL JDBC driver and specifies parameters for Kerberos authentication.

    jdbc:postgresql://mdw:5432/mytest?kerberosServerName=
    postgres&jaasApplicationName=pgjdbc&user=
    gpadmin/kerberos-gpdb
    

    The parameter names and values specified depend on how the Java application performs Kerberos authentication.

  4. Test the Kerberos login by running a sample Java application from Greenplum Database.

Sample Kerberos Configuration File

This sample krb5.conf Kerberos configuration file is used in the example that configures Greenplum Database to use Kerberos authentication.

krb5.conf Configuration File

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

[libdefaults]
 default_realm = KRB.GREENPLUM.COM
 dns_lookup_realm = false
 dns_lookup_kdc = false
 ticket_lifetime = 24h
 renew_lifetime = 7d
 forwardable = yes
 default_tgs_enctypes = aes128-cts des3-hmac-sha1 des-cbc-crc des-cbc-md5
 default_tkt_enctypes = aes128-cts des3-hmac-sha1 des-cbc-crc des-cbc-md5
 permitted_enctypes = aes128-cts des3-hmac-sha1 des-cbc-crc des-cbc-md5

[realms]
 KRB.GREENPLUM.COM = {
  kdc = kerberos-gpdb:88
  admin_server = kerberos-gpdb:749
  default_domain = kerberos-gpdb
 }

[domain_realm]
 .kerberos-gpdb = KRB.GREENPLUM.COM
 kerberos-gpdb = KRB.GREENPLUM.COM

[appdefaults]
 pam = {
    debug = false
    ticket_lifetime = 36000
    renew_lifetime = 36000
    forwardable = true
    krb4_convert = false
 }