cb23a7d9aa
### _Why are the changes needed?_ Add `_configurations` in kerberos.rst ### _How was this patch tested?_ - [ ] Add some test cases that check the changes thoroughly including negative and positive cases if possible - [ ] Add screenshots for manual tests if appropriate - [x] [Run test](https://kyuubi.readthedocs.io/en/master/develop_tools/testing.html#running-tests) locally before make a pull request Closes #4362 from Yikf/kerberos-doc-config. Closes #4362 d8f197642 [Yikf] Add _configurations in kerberos.rst Authored-by: Yikf <yikaifei@apache.org> Signed-off-by: liangbowen <liangbowen@gf.com.cn>
120 lines
4.6 KiB
ReStructuredText
120 lines
4.6 KiB
ReStructuredText
.. 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.
|
|
|
|
Configure Kyuubi to use Kerberos Authentication
|
|
===============================================
|
|
|
|
If you are deploying Kyuubi with a kerberized Hadoop cluster, it is strongly
|
|
recommended that ``kyuubi.authentication`` should be set to `KERBEROS` too.
|
|
|
|
Kerberos Overview
|
|
-----------------
|
|
|
|
Kerberos is a network authentication protocol that provides the tools of
|
|
authentication and strong cryptography over the network.
|
|
The Kerberos protocol uses strong cryptography so that a client or a server
|
|
can prove its identity to its server or client across an insecure network connection.
|
|
After a client and server have used Kerberos to prove their identity, they can
|
|
also encrypt all of their communications to assure privacy and data integrity as
|
|
they go about their business.
|
|
|
|
The Kerberos architecture is centered around a trusted authentication service
|
|
called the key distribution center, or KDC.
|
|
Users and services in a Kerberos environment are referred to as principals;
|
|
each principal shares a secret, such as a password, with the KDC.
|
|
|
|
Enable Kerberos Authentication
|
|
------------------------------
|
|
|
|
To enable the Kerberos authentication method, we need to
|
|
|
|
Create a Kerberos principal and keytab
|
|
**************************************
|
|
|
|
You can use the following commands in a Linux-based Kerberos environment to set up
|
|
the identity and update the keytab file:
|
|
|
|
The ``kyuubi.keytab`` file must be owned and readable by the Linux login user.
|
|
|
|
.. code-block::
|
|
|
|
# kadmin
|
|
: addprinc -randkey superuser/FQDN@REALM
|
|
: ktadd -k ./kyuubi.keytab superuser/FQDN@REALM
|
|
|
|
.. note:: A widespread use case of kyuubi is to replace HiveServer2/Hive QL with
|
|
Kyuubi/Spark SQL. If an existing HiveServer2 environment is already there,
|
|
copying the environment and reusing the keytab and principal of HiveServer2 is
|
|
a convenient way.
|
|
|
|
Enable `Hadoop Impersonation`_
|
|
*******************************
|
|
|
|
If background cluster is also an kerberized Hadoop cluster, we need to enable the
|
|
impersonation capability of the superuser we use to start kyuubi server.
|
|
|
|
You can configure proxy user using properties ``hadoop.proxyuser.$superuser.hosts``
|
|
along with either or both of ``hadoop.proxyuser.$superuser.groups`` and ``hadoop.proxyuser.$superuser.users``.
|
|
|
|
For instance, by specifying as below in ``core-site.xml``, the ``superuser`` named ``admin`` can connect
|
|
only from ``host1`` and ``host2`` to impersonate a user belonging to ``group1`` and ``group2``.
|
|
|
|
.. code-block:: xml
|
|
|
|
<property>
|
|
<name>hadoop.proxyuser.admin.hosts</name>
|
|
<value>host1,host2</value>
|
|
</property>
|
|
<property>
|
|
<name>hadoop.proxyuser.admin.groups</name>
|
|
<value>group1,group2</value>
|
|
</property>
|
|
|
|
|
|
Here,
|
|
|
|
- ``admin`` is the principal(short name) used to start kyuubi servers
|
|
- ``host1`` and ``host2`` are node addresses of kyuubi servers
|
|
- ``group1`` and ``group2`` are groups of client users
|
|
|
|
.. note:: These configurations need to be configured in the Hadoop cluster
|
|
and refreshed to take effect.
|
|
|
|
.. note:: If you are using the keytab of existing HiveServer2, this step can
|
|
also be omitted
|
|
|
|
Configure the authentication properties
|
|
***************************************
|
|
|
|
Configure the following properties to ``$KYUUBI_HOME/conf/kyuubi-defaults.conf``
|
|
on each node where kyuubi server is installed.
|
|
|
|
.. code-block:: property
|
|
|
|
kyuubi.authentication=KERBEROS
|
|
kyuubi.kinit.principal=superuser/FQDN@REALM
|
|
kyuubi.kinit.keytab=/path/to/kyuubi.keytab
|
|
|
|
These `configurations`_ also need to be set to enable KERBEROS authentication.
|
|
|
|
Refresh all the kyuubi server instances
|
|
***************************************
|
|
|
|
Restart all the kyuubi server instances or `Refresh Configurations`_ to activate the settings.
|
|
|
|
.. _Hadoop Impersonation: https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/Superusers.html
|
|
.. _configurations: ../client/advanced/kerberos.html
|
|
.. _Refresh Configurations: ../tools/kyuubi-admin.html#refresh-config
|