[GitHub] [pulsar] eolivelli commented on a change in pull request #4134: Issue #3654: add documentation for kerberos authentication

[GitBox <gi...@apache.org>]

eolivelli commented on a change in pull request #4134: Issue #3654: add documentation for kerberos authentication
URL: https://github.com/apache/pulsar/pull/4134#discussion_r278818657
 
 

 ##########
 File path: site2/docs/security-kerberos.md
 ##########
 @@ -0,0 +1,274 @@
+---
+id: security-kerberos
+title: Authentication using Kerberos
+sidebar_label: Authentication using Kerberos
+---
+
+[Kerberos](https://web.mit.edu/kerberos/) is a network authentication protocol. It is designed to provide strong authentication for client/server applications by using secret-key cryptography. 
+
+In Pulsar, we use Kerberos with [SASL](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer) as a choice for authentication. While in SASL, Pulsar uses the [Java Authentication and Authorization Service (JAAS)](https://en.wikipedia.org/wiki/Java_Authentication_and_Authorization_Service) for SASL configuration. You must provide JAAS configurations for Kerberos authentication. 
+
+In this documentation, We will start with a general description of how to configure `Kerberos` with `SASL` between Pulsar clients and brokers, followed by some operational details. Then comparing with it, we will show how to configure for Pulsar Proxy.
+
+## Configuration for Kerberos between Client and Broker
+
+### Prerequisites
+
+To begin, you need to set up(or already have) a [Key Distribution Center](KDC) configured and running. 
+
+If your organization is already using a Kerberos server (for example, by using `Active Directory`), there is no need to install a new server just for Pulsar. Otherwise you will need to install one, your Linux vendor likely has packages for `Kerberos` and a short guide on how to install and configure it ([Ubuntu](https://help.ubuntu.com/community/Kerberos),
+[Redhat](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/installing-kerberos.html)).
+
+Note that if you are using Oracle Java, you will need to download JCE policy files for your Java version and copy them to `$JAVA_HOME/jre/lib/security`.
+
+#### Kerberos Principals
+
+If you are using the organization’s Kerberos or Active Directory server, ask your Kerberos administrator for a principal for each Brokers in your cluster and for every operating system user that will access Pulsar with Kerberos authentication(via clients and tools).
+
+If you have installed your own Kerberos, you will need to create these principals yourself using the following commands:
+
+```shell
+### add Principals for broker
+sudo /usr/sbin/kadmin.local -q 'addprinc -randkey broker/{hostname}@{REALM}'
+sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{broker-keytabname}.keytab broker/{hostname}@{REALM}"
+### add Principals for client
+sudo /usr/sbin/kadmin.local -q 'addprinc -randkey client/{hostname}@{REALM}'
+sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{client-keytabname}.keytab client/{hostname}@{REALM}"
+```
+Note that it is a *Kerberos* requirement that all your hosts can be resolved with their FQDNs.
+
+#### Configure how to connect to KDC
+
+User need to specify the path to the `krb5.conf` file for both client and broker side. `krb5.conf` indicate the default Realm and KDC information. see [JDK’s Kerberos Requirements](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/KerberosReq.html) for more details):
+
+```shell
+-Djava.security.krb5.conf=/etc/pulsar/krb5.conf
+```
+Here is an example of krb5.conf file:
+ 
+In this configuration file, it provides `EXAMPLE.COM` as default realm; set `udp_preference_limit = 1` to force use TCP; set kdc server url `kdc = localhost:62037` for realm `EXAMPLE.COM `:
+
+```
+[libdefaults]
+ default_realm = EXAMPLE.COM
+ udp_preference_limit = 1
 
 Review comment:
   This is not needed.
   It is only for our tests, to force tcp

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services