Using Kerberos Authentication
A newer version of this documentation is available. Use the version menu above 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.
For more information about Kerberos, see http://web.mit.edu/kerberos/.
Requirements for Using Kerberos with Greenplum Database
The following items are required for using Kerberos with Greenplum Database:
- Kerberos Key Distribution Center (KDC) server using the
krb5-server library
- Kerberos version 5 krb5-libs and
krb5-workstation packages installed on the Greenplum Database master
host
- Greenplum Database version with support for Kerberos
- System time on the Kerberos server and Greenplum Database master host must be
synchronized. (Install Linux ntp package on both servers.)
- Network connectivity between the Kerberos server and the Greenplum
Database master
- Java 1.7.0_17 or later is required to use Kerberos-authenticated JDBC on
Red Hat Enterprise Linux 6.x
- Java 1.6.0_21 or later is required to use Kerberos-authenticated JDBC on
Red Hat Enterprise Linux 4.x or 5.x
Enabling Kerberos Authentication for Greenplum Database
Complete the following tasks to set up Kerberos authentication with Greenplum Database:
- Verify your system satisfies the prequisites for using Kerberos with Greenplum Database.
See Requirements for Using Kerberos with Greenplum Database.
- Set up, or identify, a Kerberos Key Distribution Center (KDC) server to
use for authentication. See Install and Configure a Kerberos 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 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.
You can also configure external authentication for clients running on a Microsoft Windows
system.
Install and Configure a Kerberos KDC Server
Steps to set up a Kerberos Key Distribution Center (KDC) server on a Red Hat
Enterprise Linux host for use with Greenplum Database.
Follow these steps to install and configure a Kerberos Key Distribution Center (KDC)
server on a Red Hat Enterprise Linux host.
-
Install the Kerberos server packages:
sudo yum install krb5-libs krb5-server krb5-workstation
-
Edit the /etc/krb5.conf configuration file. The following
example shows a Kerberos server with a default KRB.GREENPLUM.COM realm.
[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 = true
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
}
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.
The kdb5_util
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.
-
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.
-
Start kadmin.local in interactive mode:
-
Add principals:
kadmin.local: addprinc gpadmin/kerberos-gpdb@KRB.EXAMPLE.COM
kadmin.local: addprinc postgres/master.test.com@KRB.EXAMPLE.COM
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.
kadmin.local: xst -k gpdb-kerberos.keytab
gpadmin/kerberos-gpdb@KRB.EXAMPLE.COM
postgres/master.test.com@KRB.EXAMPLE.COM
You will copy this file to the Greenplum Database master host.
-
Exit kadmin.local interactive mode with the quit
command:
kadmin.local: quit
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.
-
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 an
example:
# 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
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.
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.
-
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.
host all all 0.0.0.0/0 gss include_realm=0 krb_realm=KRB.GREENPLUM.COM
-
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:
# 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 about specifying username maps see Username maps in the Postgres
documentation.
-
If a Kerberos principal is not a Greenplum Database user, a message similar to the
following is displayed from the psql command line when the user
attempts to log in to the database:
psql: krb5_sendauth: Bad response
The principal must be added as a Greenplum Database user.
Set up Greenplum Database with Kerberos for JDBC
Enable Kerberos-authenticated JDBC access to Greenplum Database.
You can configure Greenplum Database to use Kerberos to run user-defined Java
functions.
-
Ensure that Kerberos is installed and configured on the Greenplum
Database master. See Install and Configure the Kerberos Client.
-
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;
};
-
Create a Java application that connects to Greenplum Database using Kerberos
authentication. The following 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.
-
Test the Kerberos login by running a sample Java application from Greenplum
Database.