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

Using Kerberos Authentication

You can control access to Greenplum Database with a Kerberos
authentication server.

Greenplum Database supports the Generic Security Service Application Program
Interface (GSSAPI) with Kerberos authentication. GSSAPI provides automatic authentication
(single sign-on) for systems that support it. You specify the Greenplum Database
users (roles) that require Kerberos authentication in the Greenplum Database
configuration file pg_hba.conf. The login fails if Kerberos
authentication is not available when a role attempts to log in to Greenplum Database.

Kerberos provides a secure, encrypted authentication service. It does not encrypt data
exchanged between the client and database and provides no authorization services. To encrypt
data exchanged over the network, you must use an SSL connection. To manage authorization for
access to Greenplum databases and objects such as schemas and
tables, you use settings in the pg_hba.conf file and privileges given to
Greenplum Database users and roles within the database. For information about
managing authorization privileges, see Managing Roles and Privileges.

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 uses Kerberos authentication. In the Kerberos
database, a realm groups together Kerberos principals that are Greenplum Database roles.

Create Kerberos keytab files 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 that is meant to be read-only by the service is
encrypted using this key.

Install the Kerberos client packages and the keytab file on Greenplum Database master.

Create a Kerberos ticket for gpadmin on the 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 Kerberos for PSQL and JDBC.

The kdc and admin_server keys in the
[realms] section specify the host (kerberos-gpdb)
and port where the Kerberos server is running. IP numbers can be used in place of host
names.

If your Kerberos server manages authentication for other realms, you would instead
add the KRB.GREENPLUM.COM realm in the [realms] and
[domain_realm] section of the kdc.conf file. See
the Kerberos documentation for information about the
kdc.conf file.

To create a Kerberos KDC database, run the kdb5_util.

kdb5_util create -s

The kdb5_utilcreate 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.

Add an administrative user to the KDC database with the kadmin.local
utility. Because it does not itself depend on Kerberos authentication, the
kadmin.local utility allows you to add an initial administrative user
to the local Kerberos server. 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.

If needed, edit the /var/kerberos/krb5kdc/kadm5.acl file to
grant the appropriate permissions to gpadmin.

Start the Kerberos daemons:

/sbin/service krb5kdc start
/sbin/service kadmin start

To start Kerberos automatically upon restart:

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

Create Greenplum Database Roles in the KDC Database

Add principals to the Kerberos realm for Greenplum Database.

Start kadmin.local in interactive mode, then add two principals to
the Greenplum Database Realm.

The adprinc commands prompt for passwords for each principal. The
first addprinc creates a Greenplum Database user as a
principal, gpadmin/kerberos-gpdb. The second addprinc
command creates the postgres process on the Greenplum Database master host as a principal in the Kerberos KDC. This principal
is required when using Kerberos authentication with Greenplum Database.

Create a Kerberos keytab file with kadmin.local. The following
example creates a keytab file gpdb-kerberos.keytab in the current
directory with authentication information for the two principals.

Install and Configure the Kerberos Client

Steps to install the Kerberos client on the Greenplum Database master
host.

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

Install the Kerberos packages on the Greenplum Database master.

sudo yum install krb5-libs krb5-workstation

Ensure that the /etc/krb5.conf file is the same as the one that is
on the Kerberos server.

Copy the gpdb-kerberos.keytab file that was generated on the
Kerberos server to the Greenplum Database master host.

Remove any existing tickets with the Kerberos utility kdestroy. Run
the utility as root.

sudo kdestroy

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.

Set up Greenplum Database with Kerberos for PSQL

Configure a Greenplum Database to use Kerberos.

After you have set up Kerberos on the Greenplum Database master, you
can configure Greenplum Database to use Kerberos. For information on setting
up the Greenplum Database master, see Install and Configure the Kerberos Client.

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.

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

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'

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.

Create a ticket using kinit and show the tickets in the Kerberos
ticket cache with klist.

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

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 in to 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: