Configuring Kerberos For Windows Clients
Configuring Kerberos For Windows Clients
You can configure Microsoft Windows client applications to connect to a Greenplum Database system that is configured to authenticate with Kerberos.
When a Greenplum Database system is configured to authenticate with Kerberos, you can configure Kerberos authentication for the Greenplum Database client utilities gpload and psql on a Microsoft Windows system. The Greenplum Database clients authenticate with Kerberos directly.
This section contains the following information.
These topics assume that the Greenplum Database system is configured to authenticate with Kerberos. For information about configuring Greenplum Database with Kerberos authentication, refer to Using Kerberos Authentication.
Installing and Configuring Kerberos on a Windows System
The kinit, kdestroy, and klist MIT Kerberos Windows client programs and supporting libraries are installed on your system when you install the Greenplum Database Client and Load Tools package:
- kinit - generate a Kerberos ticket
- kdestroy - destroy active Kerberos tickets
- klist - list Kerberos tickets
You must configure Kerberos on the Windows client to authenticate with Greenplum Database:
- Copy the Kerberos configuration file /etc/krb5.conf from the Greenplum Database master to the Windows system, rename it to krb5.ini, and place it in the default Kerberos location on the Windows system, C:\ProgramData\MIT\Kerberos5\krb5.ini. This directory may be hidden. This step requires administrative privileges on the Windows client system. You may also choose to place the /etc/krb5.ini file in a custom location. If you choose to do this, you must configure and set a system environment variable named KRB5_CONFIG to the custom location.
- Locate the [libdefaults] section of the krb5.ini
file, and remove the entry identifying the location of the Kerberos credentials
cache file, default_ccache_name. This step requires administrative
privileges on the Windows client system.
This is an example configuration file with default_ccache_name removed. The [logging] section is also removed.
[libdefaults] debug = true default_etypes = aes256-cts-hmac-sha1-96 default_realm = EXAMPLE.LOCAL dns_lookup_realm = false dns_lookup_kdc = false ticket_lifetime = 24h renew_lifetime = 7d forwardable = true [realms] EXAMPLE.LOCAL = { kdc =bocdc.example.local admin_server = bocdc.example.local } [domain_realm] .example.local = EXAMPLE.LOCAL example.local = EXAMPLE.LOCAL
- Set up the Kerberos credential cache file. On the Windows system, set the environment
variable KRB5CCNAME to specify the file system location of the cache
file. The file must be named krb5cache. This location identifies a
file, not a directory, and should be unique to each login on the server.
When you set KRB5CCNAME, you can specify the value in either
a local user environment or within a session. For example, the following command
sets KRB5CCNAME in the session:
set KRB5CCNAME=%USERPROFILE%\krb5cache
- Obtain your Kerberos principal and password or keytab file from your system administrator.
- Generate a Kerberos ticket using a password or a keytab. For example, to generate a
ticket using a password:
kinit [<principal>]
To generate a ticket using a keytab (as described in Creating a Kerberos Keytab File):kinit -k -t <keytab_filepath> [<principal>]
- Set up the Greenplum clients environment:
set PGGSSLIB=gssapi "c:\Program Files\Greenplum\greenplum-clients\greenplum_clients_path.bat"
Running the psql Utility
After you configure Kerberos and generate the Kerberos ticket on a Windows system, you can run the Greenplum Database command line client psql.
If you get warnings indicating that the Console code page differs from Windows code page, you can run the Windows utility chcp to change the code page. This is an example of the warning and fix:
psql -h prod1.example.local warehouse psql (9.4.20) WARNING: Console code page (850) differs from Windows code page (1252) 8-bit characters might not work correctly. See psql reference page "Notes for Windows users" for details. Type "help" for help. warehouse=# \q chcp 1252 Active code page: 1252 psql -h prod1.example.local warehouse psql (9.4.20) Type "help" for help.
Creating a Kerberos Keytab File
You can create and use a Kerberos keytab file to avoid entering a password at the command line or listing a password in a script file when you connect to a Greenplum Database system, perhaps when automating a scheduled Greenplum task such as gpload. You can create a keytab file with the Java JRE keytab utility ktab. If you use AES256-CTS-HMAC-SHA1-96 encryption, you need to download and install the Java extension Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for JDK/JRE from Oracle.
This example runs the Java ktab.exe program to create a keytab file (-a option) and list the keytab name and entries (-l -e -t options).
C:\Users\dev1>"\Program Files\Java\jre1.8.0_77\bin"\ktab -a dev1 Password for dev1@EXAMPLE.LOCAL:your_password Done! Service key for dev1 is saved in C:\Users\dev1\krb5.keytab C:\Users\dev1>"\Program Files\Java\jre1.8.0_77\bin"\ktab -l -e -t Keytab name: C:\Users\dev1\krb5.keytab KVNO Timestamp Principal ---- -------------- ------------------------------------------------------ 4 13/04/16 19:14 dev1@EXAMPLE.LOCAL (18:AES256 CTS mode with HMAC SHA1-96) 4 13/04/16 19:14 dev1@EXAMPLE.LOCAL (17:AES128 CTS mode with HMAC SHA1-96) 4 13/04/16 19:14 dev1@EXAMPLE.LOCAL (16:DES3 CBC mode with SHA1-KD) 4 13/04/16 19:14 dev1@EXAMPLE.LOCAL (23:RC4 with HMAC)
You can then generate a Kerberos ticket using a keytab with the following command:
kinit -kt dev1.keytab dev1
or
kinit -kt %USERPROFILE%\krb5.keytab dev1
Example gpload YAML File
When you initiate a gpload job to a Greenplum Database system using Kerberos authentication, you omit the USER: property and value from the YAML control file.
This example gpload YAML control file named test.yaml does not include a USER: entry:
--- VERSION: 1.0.0.1 DATABASE: warehouse HOST: prod1.example.local PORT: 5432 GPLOAD: INPUT: - SOURCE: PORT_RANGE: [18080,18080] FILE: - /Users/dev1/Downloads/test.csv - FORMAT: text - DELIMITER: ',' - QUOTE: '"' - ERROR_LIMIT: 25 - LOG_ERRORS: true OUTPUT: - TABLE: public.test - MODE: INSERT PRELOAD: - REUSE_TABLES: true
These commands run kinit using a keytab file, run gpload.bat with the test.yaml file, and then display successful gpload output.
kinit -kt %USERPROFILE%\krb5.keytab dev1 gpload.bat -f test.yaml 2016-04-10 16:54:12|INFO|gpload session started 2016-04-10 16:54:12 2016-04-10 16:54:12|INFO|started gpfdist -p 18080 -P 18080 -f "/Users/dev1/Downloads/test.csv" -t 30 2016-04-10 16:54:13|INFO|running time: 0.23 seconds 2016-04-10 16:54:13|INFO|rows Inserted = 3 2016-04-10 16:54:13|INFO|rows Updated = 0 2016-04-10 16:54:13|INFO|data formatting errors = 0 2016-04-10 16:54:13|INFO|gpload succeeded
Issues and Possible Solutions
- This message indicates that Kerberos cannot find your Kerberos credentials cache
file:
Credentials cache I/O operation failed XXX (Kerberos error 193) krb5_cc_default() failed
To ensure that Kerberos can find the file, set the environment variable KRB5CCNAME and run kinit.
set KRB5CCNAME=%USERPROFILE%\krb5cache kinit
- This kinit message indicates that the kinit -k -t
command could not find the
keytab.
kinit: Generic preauthentication failure while getting initial credentials
Confirm that the full path and filename for the Kerberos keytab file is correct.