Github user lisakowen commented on a diff in the pull request:
https://github.com/apache/incubator-hawq-docs/pull/132#discussion_r147250402
--- Diff: markdown/clientaccess/kerberos-userauth.html.md.erb ---
@@ -0,0 +1,459 @@
+---
+title: Configuring Kerberos User Authentication for HAWQ
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+When Kerberos authentication is enabled at the user level, HAWQ uses the
Generic Security Service Application Program Interface \(GSSAPI\) to provide
automatic authentication \(single sign-on\). When HAWQ uses Kerberos user
authentication, HAWQ itself and the HAWQ users \(roles\) that require Kerberos
authentication require a principal and keytab. When a user attempts to log in
to HAWQ, HAWQ uses its Kerberos principal to connect to the Kerberos server,
and presents the user's principal for Kerberos validation. If the user
principal is valid, login succeeds and the user can access HAWQ. Conversely,
the login fails and HAWQ denies access to the user if the principal is not
valid.
+
+When HAWQ utilizes Kerberos for user authentication, it uses a standard
principal to connect to the Kerberos KDC. The format of this principal is
`postgres/<FQDN_of_master>@<realm>`, where \<FQDN\_of\_master\> refers to the
fully qualified distinguish name of the HAWQ master node.
+
+(You may choose to configure HAWQ user principals before you enable
Kerberos user authentication for HAWQ. See [Configuring Kerberos-Authenticated
HAWQ Users](#hawq_kerb_user_cfg).)
+
+The procedure to configure Kerberos user authentication for HAWQ includes:
+
+If you use an MIT Kerberos KDC Server:
+**Step 1a**: [Configuring the HAWQ Principals using an MIT KDC
Server](#hawq_kerb_cfg_mitkdc)
+
+If you use an Active Directory Kerberos KDC Server:
+**Step 1b**: [Configuring the HAWQ Principal using an AD KDC
Server](#hawq_kerb_cfg_adkdc)
+
+**Step 2**: [Configuring HAWQ to use Kerberos
Authentication](#hawq_kerb_cfg)
+**Step 3**: [Configuring Kerberos-Authenticated HAWQ
Users](#hawq_kerb_user_cfg)
+**Step 4**: [Authenticating User Access to HAWQ](#hawq_kerb_dbaccess)
+
+## <a id="hawq_kerb_cfg_mitkdc"></a>Step 1a: Configuring the HAWQ
Principals using an MIT KDC Server
+
+Perform the following procedure to configure HAWQ Kerberos and `gpadmin`
principals when you are using an MIT KDC server.
+
+**Note**: Some operations may differ based on whether or not you have
configured secure HDFS. These operations are called out below.
+
+1. Log in to the Kerberos KDC server system:
+
+ ``` shell
+ $ ssh root@<kdc-server>
+ root@kdc-server$
+ ```
+
+2. Create a keytab entry for the HAWQ `postgres/<master>` principal using
the `kadmin.local` command. Substitute the HAWQ master node fully qualified
distinguished hostname and your Kerberos realm. For example:
+
+ ``` shell
+ root@kdc-server$ kadmin.local -q "addprinc -randkey
postgres/<master>@REALM.DOMAIN"
+ ```
+
+ The `addprinc` command adds the principal `postgres/<master>` to the
KDC managing your \<realm\>.
+
+3. Generate a keytab file for the HAWQ `postgres/<master>` principal.
Provide the same name you used to create the principal.
+
+ **If you have configured Kerberos for your HDFS filesystem**, add the
keytab to the HAWQ client HDFS keytab file:
+
+ ``` shell
+ root@kdc-server$ kadmin.local -q "xst -norandkey -k
/etc/security/keytabs/hawq.service.keytab postgres/<master>@REALM.DOMAIN"
+ ```
+
+ **Otherwise**, generate a new file for the keytab:
+
+ ``` shell
+ root@kdc-server$ kadmin.local -q "xst -norandkey -k hawq-krb5.keytab
postgres/<master>@REALM.DOMAIN"
+ ```
+
+4. Use the `klist` command to view the key you just generated:
+
+ ``` shell
+ root@kdc-server$ klist -ket ./hawq-krb5.keytab
+ ```
+
+ Or:
+
+ ``` shell
+ root@kdc-server$ klist -ket /etc/security/keytabs/hawq.service.keytab
+ ```
+
+ The `-ket` option lists the keytabs and encryption types in the
identified key file.
+
+5. When you enable Kerberos user authentication for HAWQ, you must create
a Kerberos principal for `gpadmin` or another HAWQ administrative user. Create
a Kerberos principal for the HAWQ `gpadmin` administrative role, substituting
your Kerberos realm. For example:
+
+ ``` shell
+ root@kdc-server$ kadmin.local -q "addprinc -pw changeme
gpadmin@REALM.DOMAIN"
+ ```
+
+ This `addprinc` command adds the principal `gpadmin` to the Kerberos
KDC managing your \<realm\>. When you invoke `kadmin.local` as specified in the
example above, `gpadmin` will be required to provide the password identified by
the `-pw` option when authenticating. Alternatively, you can create a keytab
file for the `gpadmin` principal and distribute the file to HAWQ client nodes.
+
+6. Copy the file in which you added the `postgres/<master>@<realm>` keytab
to the HAWQ master node:
+
+ ``` shell
+ root@kdc-server$ scp ./hawq-krb5.keytab gpadmin@<master>:/home/gpadmin/
+ ```
+
+ Or:
+
+ ``` shell
+ root@kdc-server$ scp /etc/security/keytabs/hawq.service.keytab
gpadmin@<master>:/etc/security/keytabs/hawq.service.keytab
+ ```
+
+## <a id="hawq_kerb_cfg_adkdc"></a>Step 1b: Configuring the HAWQ Principal
using an AD KDC Server
+
+Perform the following procedure to configure a HAWQ Kerberos principal
when you are using an AD KDC server.
+
+1. Log on to the Windows Active Directory Kerberos KDC server system as a
user with administrator privileges.
+
+2. From the **Start** menu, select **Control Panel > Administrative Tools
> Active Directory Users and Computers**. (If the **Active Directory Users and
Computers** menu item is not available, the Active Directory service may not
have been (correctly) installed.)
+
+ The **Active Directory Users and Computers** window displays.
+
+3. When you enable Kerberos user authentication for HAWQ, you must create
a Kerberos principal for the `gpadmin` HAWQ administrative user. Use the left
pane tree view to navigate to your Kerberos \<realm\> **Managed Service
Accounts** folder, right-click, and select **New > User** to create a user with
this name.
+
+ The **New Object - User** wizard displays.
+
+4. Fill in the **New Object - User** fields:
+
+ **First name:** gpadmin
+ **User logon name:** gpadmin
+
+5. Click **Next** to advance to the next screen.
+
+6. Add and confirm the password. Be sure to enable the **Password never
expires** checkbox.
+
+7. Click **Next**, and then **Finish** to complete creation of the
`gpadmin` user.
+
+8. Open an administrative terminal window or command prompt session on the
Windows AD KDC server system. Be sure to select **Run as administrator -> Yes**.
+
+9. Add a Service Name Principal (SNP) for the `gpadmin` account you just
created. Substitute the fully qualified distinguished name of your HAWQ master
node. This hostname must be resolvable from the Windows AD KDC server. For
example:
+
+ ``` shell
+ PS C:\Users\Administrator> setspn -A postgres/<master> gpadmin
+ ```
+
+ The `setspn` command adds the principal `postgres/<master>` to the KDC
managing your \<realm\>.
+
+10. Create a keytab file for the `postgres/<master>` SPN using the
`ktpass` command. Substitute the HAWQ master node fully qualified distinguished
hostname and your Kerberos realm. For example:
+
+ ```shell
+ PS C:\Users\Administrator> ktpass -princ postgres/<master>@<realm>
-pass changeme -mapuser gpadmin -crypto ALL -ptype KRB5_NT_PRINCIPAL -out
hawq-krb5.keytab -kvno 0
+ ```
+
+ The `ktpass` command generates a keytab file named `hawq-krb5.keytab`.
+
+11. Copy the keytab file to the HAWQ master node.
+
+
+## <a id="hawq_kerb_cfg"></a>Step 2: Configuring HAWQ to use Kerberos
Authentication
+
+Perform the following procedure to configure Kerberos user authentication
for HAWQ. You will perform operations on the HAWQ \<master\> node.
+
+1. Log in to the HAWQ master node as the `gpadmin` user and set up the
HAWQ environment:
+
+ ``` shell
+ $ ssh gpadmin@<master>
+ gpadmin@master$ . /usr/local/hawq/greenplum_path.sh
+ ```
+
+2. If you copied the `hawq-krb5.keytab` file, verify the ownership and
mode of this file:
+
+ ``` shell
+ gpadmin@master$ chown gpadmin:gpadmin /home/gpadmin/hawq-krb5.keytab
+ gpadmin@master$ chmod 400 /home/gpadmin/hawq-krb5.keytab
+ ```
+
+ The HAWQ server keytab file must be readable (and preferably only
readable) by the HAWQ `gpadmin` administrative account.
+
+3. Add a `pg_hba.conf` entry that mandates Kerberos authentication for
HAWQ. The `pg_hba.conf` file resides in the directory specified by the
`hawq_master_directory` server configuration parameter value. For example, add:
+
+ ``` pre
+ host all all 0.0.0.0/0 gss include_realm=0 krb_realm=REALM.DOMAIN
+ ```
+
+ This `pg_hba.conf` entry specifies that any remote access (i.e. from
any user on any remote host) to HAWQ must be authenticated through the Kerberos
realm named `REALM.DOMAIN`.
+
+ **Note**: Place the Kerberos entry in the appropriate location in the
`pg_hba.conf` file. For example, you may choose to retain `pg_hba.conf` entries
for the `gpadmin` user that grant `trust` or `ident` authentication for local
connections. Locate the Kerberos entry after these line(s). Refer to
[Configuring Client Authentication](client_auth.html) for additional
information about the `pg_hba.conf` file.
+
+4. Update HAWQ configuration and restart your cluster. You will perform
different procedures if you manage your cluster from the command line or use
Ambari to manage your cluster.
+
+ **Note**: After you restart your hawq cluster, Kerberos user
authentication is enabled for HAWQ, and all users, including `gpadmin`, must
authenticate before performing any HAWQ operations.
+
+ 1. If you manage your cluster using Ambari or are employing a Windows
Active Directory KDC server:
+
+ 1. Login in to the Ambari UI from a supported web browser.
+
+ 2. Navigate to the **HAWQ** service, **Configs > Advanced** tab
and expand the **Custom hawq-site** drop down.
+
+ 3. Set the `krb_server_keyfile` path value to the new keytab file
location, `/home/gpadmin/hawq-krb5.keytab`.
+
+ 4. **Save** this configuration change and then select the now
orange **Restart > Restart All Affected** menu button to restart your HAWQ
cluster.
+
+ 5. Exit the Ambari UI.
+
+ 2. If you manage your cluster from the command line:
+
+ 1. Update the `krb_server_keyfile` configuration parameter:
+
+ ``` shell
+ gpadmin@master$ hawq config -c krb_server_keyfile -v
'/home/gpadmin/hawq-krb5.keytab'
+ GUC krb_server_keyfile already exist in hawq-site.xml
+ Update it with value: /home/gpadmin/hawq-krb5.keytab
+ GUC : krb_server_keyfile
+ Value : /home/gpadmin/hawq-krb5.keytab
+ ```
+
+ 2. Restart your HAWQ cluster:
+
+ ``` shell
+ gpadmin@master$ hawq restart cluster
+ ```
+
+5. When Kerberos user authentication is enabled for HAWQ, all users,
including the `gpadmin` administrative user, must request a ticket to
authenticate before performing HAWQ operations. Generate a ticket for `gpadmin`
on the HAWQ master node. You may be required to enter a password if you
specified one when you created the principal. For example:
+
+ ``` shell
+ gpadmin@master$ kinit gpadmin@<realm>
+ ```
+
+ **Note**: If you are using an Active Directory KDC server and the
`kinit` command fails with the error "Preauthentication failed while getting
initial credentials", navigate to the `gpadmin` **Account options** view on the
Windows AD server system and enable the **Do not require Kerberos
preauthentication** checkbox.
--- End diff --
i don't know if there would be an issue doing the kinit before updating
pg_hba.conf, configing the keytab file, and restarting the cluster. this order
does work for MIT KDC.
what if i move the note to the end of the "cfg hawq principal with AD KDC"
section and reword a bit?
---
