LATEST VERSION: 4.5.1 - RELEASE NOTES

Pivotal Greenplum Command Center

Download Ask for Help Knowledge Base Supported Platforms

Enabling Authentication with Kerberos

Before You Begin
Add Command Center Principals to the KDC Database
Set Up Keytab Files
- Command Center Instance on the Greenplum Master Host
- Command Center Instance on a Separate Host
Update the Greenplum Database pg_hba.conf File
Enable Kerberos for the Command Center Instance
Authenticating With Kerberos on the Client Workstation

If you have enabled Kerberos authentication for Greenplum Database, you can set up Greenplum Command Center to accept connections from Kerberos-authenticated users.

Greenplum Database and Command Center include support for the Generic Security Service Applications Program Interface (GSS-API) standard. A related standard, Simple and Protected GSS-API Negotiation Mechanism (SPNEGO), describes the protocol GSS-API clients and servers use to agree on the method of authentication.

With a SPNEGO-compliant web application such as Command Center, the client and server agree on the authentication method on the client’s initial HTTP request. If Kerberos authentication is not supported on both ends of the connection the server falls back to basic authentication, and displays a login form requesting a user name and password. If a user has authenticated on the workstation with Kerberos and has a valid ticket granting ticket, the web browser offers the user’s credential to the Command Center web server. A Kerberos-enabled Command Center web server is configured to handle the authenticated user’s connection request in one of three modes, called strict, normal, or gpmon-only.

Strict

Command Center has a Kerberos keytab file containing the Command Center service principal and a principal for every Command Center user. If the principal in the client’s connection request is in the keytab file, the web server grants the client access and the web server connects to Greenplum Database using the client’s principal name. If the principal is not in the keytab file, the connection request fails.

Normal

The Command Center Kerberos keytab file contains the Command Center principal and may contain principals for Command Center users. If the principal in the client’s connection request is in Command Center’s keytab file, it uses the client’s principal for database connections. Otherwise, Command Center uses the gpmon user for database connections.

gpmon-only

The Command Center uses the gpmon database role for all Greenplum Database connections. No client principals are needed in the Command Center’s keytab file.

If you have set up Kerberos authentication for Greenplum Database, most of the configuration required to enable Command Center Kerberos authentication has been done. The Command Center Kerberos configuration builds upon the Greenplum Database Kerberos setup.

Kerberos authentication can be enabled by responding to prompts when you set up a new Command Center instance with the gpcmdr --setup command, or you can use the gpcmdr --krbenable <instance-name> command to enable Kerberos for an existing Command Center instance.

Before You Begin

Kerberos authentication must be enabled for Greenplum Database. See Using Kerberos Authentication for instructions. Make sure the following prerequisites are met before you continue:

The krb5-workstation package and associated libraries (libkrb5*) must be installed on the Greenplum master host and each client workstation.
The date and time on the Greenplum master host and all client workstations must be synchronized with the KDC.
The krb5.conf configuration file must be the same on the KDC host, the Greenplum master host, and client workstations.
The KDC database must have a service principal for Greenplum Database. The default service name for Greenplum Database is postgres/<master-host>@<realm>. You can choose a service name other than postgres, but it must match the value of the krb_srvname parameter in the $MASTER_DATA_DIRECTORY/postgresql.conf file.
A keyfile file with the Greenplum Database principal must be installed on the Greenplum master host and identified by the krb_server_keyfile parameter in the $MASTER_DATA_DIRECTORY/postgresql.conf file.
Each client workstation must have a keytab file containing their Kerberos principal, <username>@<realm>.

Add Command Center Principals to the KDC Database

Before you configure a Command Center instance for Kerberos authentication, you must create the required Kerberos principals. All of the principals used with Command Center are created in the Greenplum Database Kerberos realm. Command Center users use the same Kerberos principal to log in to Command Center and Greenplum Database.

Command Center Service Principal

A service principal is needed for the Command Center web server. This principal has the format HTTP/<host>@<realm>. For example, if users access Command Center at the URL http://mdw.example.com:28080, the <host> part of the service key is mdw.example.com and the <realm> part is the Greenplum Database Kerberos realm, for example GPDB-KRB.EXAMPLE.COM.

Note that Kerberos authentication only works if Command Center users enter the host in the same format specified in the Kerberos service principal. If the principal specifies the FQDN, for example, using the host’s IP address in the browser URL will not work; the web server will fall back to basic authentication, presenting a login screen.

Greenplum Database gpmon User

Command Center uses the gpmon Greenplum role to access the gpperfmon database, which contains data presented in the Command Center UI.

You can choose to authenticate the gpmon user with Kerberos or with basic authentication. To use Kerberos, you must create a principal for the gpmon user.

If you choose to use basic authentication you do not need a Kerberos principal for the gpmon user. The gpmon user will authenticate with Greenplum Database using the password saved in the ~gpadmin/.pgpass file on the host running the Command Center instance. See Changing the gpmon Password for instructions to manage the gpmon password.

Command Center Users

Add Kerberos principals for any Command Center users who do not already have principals in the KDC for Greenplum Database.

Adding Kerberos Principals

To add the required principals, perform the following steps as root on the KDC server.

Start kadmin.local.
```
kadmin.local
```
Add a principal for the Command Center web service. Be sure to specify the <gpcc-host> in the same format that users should enter the host in their browsers.
```
kadmin.local: addprinc HTTP/<gpcc-host>@<realm>
```
If you want the gpmon database user to use Kerberos authentication, add a gpmon principal.
```
kadmin.local: addprinc gpmon@<realm>
```
Add principals for any new Command Center users.
```
kadmin.local: addprinc cc_user1@<realm>
```
Repeat for each new Command Center user.
Enter quit to exit kadmin.local.

Set Up Keytab Files

After you have created all of the Kerberos principals needed, you create and distribute keytab files. Keytab files contain Kerberos principals and encrypted keys based on the principals’ Kerberos passwords. Keytab files are needed for Greenplum Database, the Command Center instance, and each Command Center and Database user.

The Command Center instance is usually installed on the Greenplum master and, when this is true, a single keyfile file can be shared by Greenplum Database and the Command Center instance. Running Command Center on the Greenplum master is recommended, since it confines authentication with the database to a single host.

If you install the Command Center instance on a host other than the Greenplum master, you will need to create a separate keyfile file.

You must also create a keyfile file for each Greenplum Database or Command Center user containing just the user’s principal. This keyfile file is installed on the user’s workstation to enable the user to authenticate to Kerberos.

Command Center Instance on the Greenplum Master Host

If the Greenplum Command Center web server is running on the Greenplum Database master host, Command Center can share the Greenplum Database keyfile file. You need to create a keyfile file that contains the following principals:

Service key for the postgres process on the Greenplum Database master host, for example postgres/mdw.example.com@GPDB.EXAMPLE.COM.
Service key created for Command Center in the previous section, for example HTTP/mdw.example.com@GPDB.EXAMPLE.COM.
A principal for every Kerberos-authenticated Greenplum Database or Command Center user.

All service keys and principals should be in the Greenplum Database realm.

To create a keytab file for Greenplum Database and Command Center, perform perform the following steps as root on the KDC server.

Start kadmin.local.
```
kadmin.local
```
Create a keytab file and add the Greeplum Database service key, the command center service key, and all database and Command Center users.
```
kadmin.local: ktadd -k gpdb-kerberos.keytab postgres/mdw.example.com@GPDB.EXAMPLE.COM HTTP/mdw.example.com@GPDB.EXAMPLE.COM
```
You can enter one or more principals with each ktadd command. You can specify a wildcard using the -glob option. For example this command adds all principals in the GPDB.EXAMPLE.COM realm, including service principals and admin users.
```
 kadmin.local: ktadd -k gpdb-kerberos.keytab -glob *@GPDB.EXAMPLE.COM  
```
Enter quit to exit kadmin.local.
Copy the keyfile you created to the Greenplum Database master host, replacing the old keytab file. The location of the file is given by the krb_server_keyfile parameter in the $MASTER_DATA_FILE/postgresql.conf file. Set the permissions on the file so that it can be read only by the gpadmin user.
Update any entries required for new Greenplum Database principals in the pg_hba.conf file and pg_ident.conf files. See Update the Greenplum Database pg_hba.conf File for details.

Command Center Instance on a Separate Host

If the Command Center web server is on a different host than the Greenplum Database master, you need separate keytab files for Greenplum Database and Command Center. The keytab file for Greenplum Database may not require any updates, but you will need to create a keytab file for Command Center.

The Greenplum Database keytab file must contain the Greenplum Database service key and all principals for users with database access.
The Command Center keytab file contains the Command Center service key and principals for users that have Command Center access. Users with Command Center access must also have Greenplum Database access, so user principals in the Command Center keytab file must also be in the Greenplum Database keytab file.

Update the Greenplum Database keyfile if you created new database roles and principals for Command Center. For example, if you want to use Kerberos authentication for the gpmon user, you must create a principal and add it to both the Greenplum Database and Command Center keytab files.

To create the keytab file for Command Center, perform the following steps as root on the KDC host.

Start kadmin.local.
```
kadmin.local
```

Create a keytab file and add the Command Center service key.

kadmin.local: ktadd -k gpcc-kerberos.keytab HTTP/mdw.example.com@GPDB.EXAMPLE.COM

If you want to authenticate the gpmon user with Kerberos, add the gpmon principal.
```
kadmin.local: ktadd -k gpcc-kerberos.keytab gpmon@GPDB.EXAMPLE.COM
```
Add principals for all Command Center users:
```
kadmin.local: ktadd -k gpcc-kerberos.keytab cc_user1@GPDB.EXAMPLE.COM cc_user2@GPDB.EXAMPLE.COM
```
You can enter one or more principals with each ktadd command.
Enter quit to exit kadmin.local.
Copy the keyfile you created to the the host running Command Center, for example:
```
$ scp gpcc-kerberos.keytab gpadmin@<host-name>:/home/gpadmin
```
Update any entries required for new principals in the pg_hba.conf file and pg_ident.conf files on the Greenplum master. See Update the Greenplum Database pg_hba.conf File.

Update the Greenplum Database pg_hba.conf File

The Greenplum Database $MASTER_DATA_DIRECTORY/pg_hba.conf configuration file determines which authentication methods to use to allow database access.

If you created new Command Center users, you may need to add an entry to allow access via Command Center. The entry for an individual user has this format:

host database <user-name> <gpcc CIDR> gss [options]

Authentication for the gpmon user needs to be set up in the pg_hba.conf file in one of the following ways.

Basic authentication

The /home/gpadmin/.gpass file contains the password for gpmon to use. See Changing the gpmon Password for details. An entry in the pg_hba.conf file specifies the md5 authentication method for gpmon:

local all gpmon md5

Trust authentication

On the Greenplum Database host only, the gpmon user can access databases without authentication:

local all gpmon trust

The /home/gpadmin/.pgpass file is not needed.

Kerberos authentication

A Kerberos principal has been created for the gpmon user and added to the Greenplum Database and Command Center keytab files.

host all gpmon <gpcc CIDR>] gss [options]

Remove any existing reject rules for gpmon:

host all gpmon <auth-method> reject

See Using Kerberos Authentication for more information about the pg_hba.conf file.

Enable Kerberos for the Command Center Instance

Set up the Command Center instance to use the Command Center keytab file you created.

If you are creating a new Command Center instance with the gpcmdr --setup command, answer Y to the prompt Enable kerberos login for this intance?, and enter the Command Center host name and path to the keytab file at the prompts. See Create the Greenplum Command Center Instance for complete instructions.

If you are adding Kerberos authentication to an existing Command Center instance, use the gpcmdr --krbenable <instance-name> command. For example, if your Command Center instance is named my-gpcc enter this command:

$ gpcmdr --krbenable my-gpcc

Enter the Command Center host name and path to the keytab file at the prompts. See the gpcmdr Reference for more information.

Authenticating With Kerberos on the Client Workstation

To use Kerberos Command Center authentication, the user must have authenticated with Kerberos using the kinit command-line tool.

The user then accesses the Command Center web server with a URL containing the host name in the format specified in the Command Center service principal and the port number, for example http://gpcc.example.com:28080.

The web browser must be configured to use the SPNEGO protocol so that it offers the user’s Kerberos principal to the web browser. The method for configuring web browsers varies with different browsers and operating systems. Search online to find instructions to set up your browser and OS.