Skip to content

Commit 6e10eec

Browse files
zhouyifan279yaooqinn
authored andcommitted
[KYUUBI #1550] Provide a specific user guide about connecting to kerberized kyuubi
### _Why are the changes needed?_ Many kyuubi users are not familiar with kerberos authentication mechanism and encountered troubles connecting to kerberized Kyuubi. ### _How was this patch tested?_ - [ ] Add some test cases that check the changes thoroughly including negative and positive cases if possible - [x] Add screenshots for manual tests if appropriate Configurations are verified in #1432 - [ ] [Run test](https://kyuubi.readthedocs.io/en/latest/develop_tools/testing.html#running-tests) locally before make a pull request Closes #1552 from zhouyifan279/1550. Closes #1550 58e324a [zhouyifan279] [KYUUBI #1550] Add kerberos authentication flow 3b030a9 [zhouyifan279] [KYUUBI #1550] Add kerberos authentication flow 4449b68 [zhouyifan279] [KYUUBI #1550] Improve doc style 3aa8e20 [zhouyifan279] [KYUUBI #1550] Add Windows configuration steps 7e67cdc [zhouyifan279] [KYUUBI #1550] Capitalize title and emphasize the relation between KinitAuxiliaryService and Kerberos authentication 424e56b [zhouyifan279] [KYUUBI #1550] Rename client/kerberos.md to client/kerberized_kyuubi.md d8977ce [zhouyifan279] [KYUUBI #1550] Provide a specific user guide about connecting to kerberized kyuubi Authored-by: zhouyifan279 <zhouyifan279@gmail.com> Signed-off-by: Kent Yao <yao@apache.org>
1 parent 4b58b0a commit 6e10eec

File tree

5 files changed

+255
-26
lines changed

5 files changed

+255
-26
lines changed

docs/client/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,4 @@ Client Documentation
2424
:numbered: 2
2525

2626
hive_jdbc
27+
kerberized_kyuubi

docs/client/kerberized_kyuubi.md

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
<!--
2+
- Licensed to the Apache Software Foundation (ASF) under one or more
3+
- contributor license agreements. See the NOTICE file distributed with
4+
- this work for additional information regarding copyright ownership.
5+
- The ASF licenses this file to You under the Apache License, Version 2.0
6+
- (the "License"); you may not use this file except in compliance with
7+
- the License. You may obtain a copy of the License at
8+
-
9+
- http://www.apache.org/licenses/LICENSE-2.0
10+
-
11+
- Unless required by applicable law or agreed to in writing, software
12+
- distributed under the License is distributed on an "AS IS" BASIS,
13+
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
- See the License for the specific language governing permissions and
15+
- limitations under the License.
16+
-->
17+
18+
<div align=center>
19+
20+
![](../imgs/kyuubi_logo.png)
21+
22+
</div>
23+
24+
# Access Kerberized Kyuubi with Beeline & BI Tools
25+
26+
## Instructions
27+
When Kyuubi is secured by Kerberos, the authentication procedure becomes a little complicated.
28+
29+
![](../imgs/kyuubi_kerberos_authentication.png)
30+
31+
The graph above shows a simplified kerberos authentication procedure:
32+
1. Kerberos client sends user principal and secret key to KDC. Secret key can be a password or a keytab file.
33+
2. KDC returns a `ticket-granting ticket`(TGT).
34+
3. Kerberos client stores TGT into a ticket cache.
35+
4. JDBC client, such as beeline and BI tools, reads TGT from the ticket cache.
36+
5. JDBC client sends TGT and server principal to KDC.
37+
6. KDC returns a `client-to-server ticket`.
38+
7. JDBC client sends `client-to-server ticket` to Kyuubi server to prove its identity.
39+
40+
In the rest part of this page, we will describe steps needed to pass through this authentication.
41+
42+
## Install Kerberos Client
43+
Usually, Kerberos client is installed as default. You can validate it using klist tool.
44+
45+
Linux command and output:
46+
```bash
47+
$ klist -V
48+
Kerberos 5 version 1.15.1
49+
```
50+
51+
MacOS command and output:
52+
```bash
53+
$ klist --version
54+
klist (Heimdal 1.5.1apple1)
55+
Copyright 1995-2011 Kungliga Tekniska Högskolan
56+
Send bug-reports to heimdal-bugs@h5l.org
57+
```
58+
59+
Windows command and output:
60+
```cmd
61+
> klist -V
62+
Kerberos for Windows
63+
```
64+
65+
If the client is not installed, you should install it ahead based on the OS platform.
66+
We recommend you to install the MIT Kerberos Distribution as all commands in this guide is based on it.
67+
68+
## Configure Kerberos Client
69+
Kerberos client needs a configuration file for tuning up the creation of Kerberos ticket cache.
70+
Following is the configuration file's default location on different OS:
71+
72+
OS | Path
73+
---| ---
74+
Linux | /etc/krb5.conf
75+
MacOS | /etc/krb5.conf
76+
Windows | %ProgramData%\MIT\Kerberos5\krb5.ini
77+
78+
You can use `KRB5_CONFIG` environment variable to overwrite the default location.
79+
80+
The configuration file should be configured to point to the same KDC as Kyuubi points to.
81+
82+
## Get Kerberos TGT
83+
Execute `kinit` command to get TGT from KDC.
84+
85+
Suppose user principal is `kyuubi_user@KYUUBI.APACHE.ORG` and user keytab file name is `kyuubi_user.keytab`,
86+
the command should be:
87+
88+
```
89+
$ kinit -kt kyuubi_user.keytab kyuubi_user@KYUUBI.APACHE.ORG
90+
91+
(Command is identical on different OS platform)
92+
```
93+
94+
You may also execute `kinit` command with principal and password to get TGT:
95+
96+
```
97+
$ kinit kyuubi_user@KYUUBI.APACHE.ORG
98+
Password for kyuubi_user@KYUUBI.APACHE.ORG: password
99+
100+
(Command is identical on different OS platform)
101+
```
102+
103+
If the command executes successfully, TGT will be store in ticket cache.
104+
Use `klist` command to print TGT info in ticket cache:
105+
106+
```
107+
$ klist
108+
109+
Ticket cache: FILE:/tmp/krb5cc_1000
110+
Default principal: kyuubi_user@KYUUBI.APACHE.ORG
111+
112+
Valid starting Expires Service principal
113+
2021-12-13T18:44:58 2021-12-14T04:44:58 krbtgt/KYUUBI.APACHE.ORG@KYUUBI.APACHE.ORG
114+
renew until 2021-12-14T18:44:57
115+
116+
(Command is identical on different OS platform. Ticket cache location may be different.)
117+
```
118+
119+
Ticket cache may have different storage type on different OS platform.
120+
121+
For example,
122+
123+
OS | Default Ticket Cache Type and Location
124+
---| ---
125+
Linux | FILE:/tmp/krb5cc_%{uid}
126+
MacOS | KCM:%{uid}:%{gid}
127+
Windows | API:krb5cc
128+
129+
You can find your ticket cache type and location in the `Ticket cache` part of `klist` output.
130+
131+
**Note**:
132+
- Ensure your ticket cache type is `FILE` as JVM can only read ticket cache stored as file.
133+
- Do not store TGT into default ticket cache if you are running Kyuubi and execute `kinit` on the same
134+
host with the same OS user. The default ticket cache is already used by Kyuubi server.
135+
136+
Either because the default ticket cache is not a file, or because it is used by Kyuubi server, you
137+
should store ticket cache in another file location.
138+
This can be achieved by specifying a file location with `-c` argument in `kinit` command.
139+
140+
For example,
141+
```
142+
$ kinit -c /tmp/krb5cc_beeline -kt kyuubi_user.keytab kyuubi_user@KYUUBI.APACHE.ORG
143+
144+
(Command is identical on different OS platform)
145+
```
146+
147+
To check the ticket cache, specify the file location with `-c` argument in `klist` command.
148+
149+
For example,
150+
```
151+
$ klist -c /tmp/krb5cc_beeline
152+
153+
(Command is identical on different OS platform)
154+
```
155+
156+
## Add Kerberos Client Configuration File to JVM Search Path
157+
The JVM, which JDBC client is running on, also needs to read the Kerberos client configuration file.
158+
However, JVM uses different default locations from Kerberos client, and does not honour `KRB5_CONFIG`
159+
environment variable.
160+
161+
OS | JVM Search Paths
162+
---| ---
163+
Linux | System scope: `/etc/krb5.conf`
164+
MacOS | User scope: `$HOME/Library/Preferences/edu.mit.Kerberos`<br/>System scope: `/etc/krb5.conf`
165+
Windows | User scoep: `%USERPROFILE%\krb5.ini`<br/>System scope: `%windir%\krb5.ini`
166+
167+
You can use JVM system property, `java.security.krb5.conf`, to overwrite the default location.
168+
169+
## Add Kerberos Ticket Cache to JVM Search Path
170+
JVM determines the ticket cache location in the following order:
171+
1. Path specified by `KRB5CCNAME` environment variable. Path must start with `FILE:`.
172+
2. `/tmp/krb5cc_%{uid}` on Unix-like OS, e.g. Linux, MacOS
173+
3. `${user.home}/krb5cc_${user.name}` if `${user.name}` is not null
174+
4. `${user.home}/krb5cc` if `${user.name}` is null
175+
176+
**Note**:
177+
- `${user.home}` and `${user.name}` are JVM system properties.
178+
- `${user.home}` should be replaced with `${user.dir}` if `${user.home}` is null.
179+
180+
Ensure your ticket cache is stored as a file and put it in one of the above locations.
181+
182+
## Ensure core-site.xml Exists in Classpath
183+
Like hadoop clients, `hadoop.security.authentication` should be set to `KERBEROS` in `core-site.xml`
184+
to let Hive JDBC driver use Kerberos authentication. `core-site.xml` should be placed under beeline's
185+
classpath or BI tools' classpath.
186+
187+
### Beeline
188+
Here are the usual locations where `core-site.xml` should exist for different beeline distributions:
189+
190+
Client | Location | Note
191+
--- | --- | ---
192+
Hive beeline | `$HADOOP_HOME/etc/hadoop` | Hive resolves `$HADOOP_HOME` and use `$HADOOP_HOME/bin/hadoop` command to launch beeline. `$HADOOP_HOME/etc/hadoop` is in `hadoop` command's classpath.
193+
Spark beeline | `$HADOOP_CONF_DIR` | In `$SPARK_HOME/conf/spark-env.sh`, `$HADOOP_CONF_DIR` often be set to the directory containing hadoop client configuration files.
194+
Kyuubi beeline | `$HADOOP_CONF_DIR` | In `$KYUUBI_HOME/conf/kyuubi-env.sh`, `$HADOOP_CONF_DIR` often be set to the directory containing hadoop client configuration files.
195+
196+
If `core-site.xml` is not found in above locations, create one with the following content:
197+
```xml
198+
<configuration>
199+
<property>
200+
<name>hadoop.security.authentication</name>
201+
<value>kerberos</value>
202+
</property>
203+
</configuration>
204+
```
205+
206+
### BI Tools
207+
As to BI tools, ways to add `core-site.xml` varies.
208+
Take DBeaver as an example. We can add files to DBeaver's classpath through its `Global libraries` preference.
209+
As `Global libraries` only accepts jar files, you should package `core-site.xml` into a jar file.
210+
211+
```bash
212+
$ jar -c -f core-site.jar core-site.xml
213+
214+
(Command is identical on different OS platform)
215+
```
216+
217+
## Connect with JDBC URL
218+
The last step is to connect to Kyuubi with the right JDBC URL.
219+
The JDBC URL should be in format:
220+
221+
```
222+
jdbc:hive2://<kyuubi_server_a ddress>:<kyuubi_server_port>/<db>;principal=<kyuubi_server_principal>
223+
```
224+
225+
**Note**:
226+
- `kyuubi_server_principal` is the value of `kyuubi.kinit.principal` set in `kyuubi-defaults.conf`.
227+
- As a command line argument, JDBC URL should be quoted to avoid being split into 2 commands by ";".
228+
- As to DBeaver, `<db>;principal=<kyuubi_server_principal>` should be set as the `Database/Schema` argument.
229+
142 KB
Loading

docs/security/authentication.md

Lines changed: 4 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -60,32 +60,14 @@ The Kerberos architecture is centered around a trusted authentication service ca
6060
Users and services in a Kerberos environment are referred to as principals;
6161
each principal shares a secret, such as a password, with the KDC.
6262

63-
Set following for KERBEROS mode:
63+
Following configurations also need to be set to enable KERBEROS authentication:
6464

6565
Key | Default | Meaning | Since
6666
--- | --- | --- | ---
6767
kyuubi\.kinit<br>\.principal|<div style='width: 80pt;word-wrap: break-word;white-space: normal'>&lt;undefined&gt;</div>|<div style='width: 200pt;word-wrap: break-word;white-space: normal'>Name of the Kerberos principal.</div>|<div style='width: 20pt'>1.0.0</div>
6868
kyuubi\.kinit\.keytab|<div style='width: 80pt;word-wrap: break-word;white-space: normal'>&lt;undefined&gt;</div>|<div style='width: 200pt;word-wrap: break-word;white-space: normal'>Location of Kyuubi server's keytab.</div>|<div style='width: 20pt'>1.0.0</div>
69+
kyuubi\.kinit\.interval|<div style='width: 80pt;word-wrap: break-word;white-space: normal'>PT1H</div>|<div style='width: 200pt;word-wrap: break-word;white-space: normal'>How often will Kyuubi server run `kinit -kt [keytab] [principal]` to renew the local Kerberos credentials cache</div>|<div style='width: 20pt'>1.0.0</div>
70+
kyuubi\.kinit\.max<br>\.attempts|<div style='width: 80pt;word-wrap: break-word;white-space: normal'>10</div>|<div style='width: 200pt;word-wrap: break-word;white-space: normal'>How many times will `kinit` process retry</div>|<div style='width: 20pt'>1.0.0</div>
6971

7072

71-
For example,
72-
73-
- Configure with Kyuubi service principal
74-
```bash
75-
kyuubi.authentication=KERBEROS
76-
kyuubi.kinit.principal=spark/kyuubi.apache.org@KYUUBI.APACHE.ORG
77-
kyuubi.kinit.keytab=/path/to/kyuuib.keytab
78-
```
79-
80-
- Start Kyuubi
81-
```bash
82-
$ ./bin/kyuubi start
83-
```
84-
85-
- Kinit with user principal and connect using beeline
86-
87-
```bash
88-
$ kinit -kt user.keytab user.principal
89-
90-
$ beeline -u "jdbc:hive2://localhost:10009/;principal=spark/kyuubi.apache.org@KYUUBI.APACHE.ORG"
91-
```
73+
Please refer to [Kinit Auxiliary Service](kinit.html) to get configuration steps.

docs/security/kinit.md

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,13 @@
2323

2424
# Kinit Auxiliary Service
2525

26-
In order to work with a kerberos-enabled cluster, Kyuubi provides this kinit auxiliary service.
27-
It will periodically re-kinit with to keep the Ticket Cache fresh.
26+
Kinit auxiliary service is a critical service both for authentication between Kyuubi client/server
27+
and for authentication between Kyuubi server/Hadoop cluster in a Kerberos environment.
28+
It will get a Kerberos Ticket Cache from KDC and periodically re-kinit to keep the Ticket Cache fresh.
2829

30+
**Note**:
31+
- Kinit auxiliary service is critical to Kyuubi Kerberos authentication, but not vice versa.
32+
- Kinit auxiliary service can also work with other authentication mode.
2933

3034
## Installing and Configuring the Kerberos Clients
3135

@@ -78,8 +82,21 @@ kyuubi\.kinit\.keytab|<div style='width: 80pt;word-wrap: break-word;white-space:
7882
kyuubi\.kinit\.interval|<div style='width: 80pt;word-wrap: break-word;white-space: normal'>PT1H</div>|<div style='width: 200pt;word-wrap: break-word;white-space: normal'>How often will Kyuubi server run `kinit -kt [keytab] [principal]` to renew the local Kerberos credentials cache</div>|<div style='width: 20pt'>1.0.0</div>
7983
kyuubi\.kinit\.max<br>\.attempts|<div style='width: 80pt;word-wrap: break-word;white-space: normal'>10</div>|<div style='width: 200pt;word-wrap: break-word;white-space: normal'>How many times will `kinit` process retry</div>|<div style='width: 20pt'>1.0.0</div>
8084
81-
When `hadoop.security.authentication` is set to `KERBEROS`, in `$HADOOP_CONF_DIR/core-site` or `$KYUUBI_HOME/conf/kyuubi-defaults.conf`,
82-
it indicates that we are targeting a secured cluster, then we need to specify `kyuubi.kinit.principal` and `kyuubi.kinit.keytab` for authentication.
85+
When working with a Kerberos-enabled Hadoop cluster, we should ensure that `hadoop.security.authentication`
86+
is set to `KERBEROS` in `$HADOOP_CONF_DIR/core-site.xml` or `$KYUUBI_HOME/conf/kyuubi-defaults.conf`.
87+
Then we need to specify `kyuubi.kinit.principal` and `kyuubi.kinit.keytab` for authentication.
88+
89+
90+
For example,
91+
92+
```bash
93+
kyuubi.kinit.principal=spark/kyuubi.apache.org@KYUUBI.APACHE.ORG
94+
kyuubi.kinit.keytab=/path/to/kyuuib.keytab
95+
```
96+
97+
**Note**:
98+
`kyuubi.kinit.principal` must be in the format: `<user>/<host>@<realm>`, and `<host>` must
99+
be a FQDN of the host Kyuubi is running.
83100
84101
Kyuubi will use this `principal` to impersonate client users,
85102
so the cluster should enable it to do impersonation for some particular user from some particular hosts.

0 commit comments

Comments
 (0)