blob: 8987f25f18bcd0c9f5516ac4acff2124353b10cf [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Apache Druid">
<meta name="keywords" content="druid,kafka,database,analytics,streaming,real-time,real time,apache,open source">
<meta name="author" content="Apache Software Foundation">
<title>Druid | Kerberos</title>
<link rel="alternate" type="application/atom+xml" href="/feed">
<link rel="shortcut icon" href="/img/favicon.png">
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.7.2/css/all.css" integrity="sha384-fnmOCqbTlWIlj8LyTjo7mOUStjsKC4pOpQbqyi7RrhN7udi9RwhKkMHpvLbHG9Sr" crossorigin="anonymous">
<link href='//fonts.googleapis.com/css?family=Open+Sans+Condensed:300,700,300italic|Open+Sans:300italic,400italic,600italic,400,300,600,700' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="/css/bootstrap-pure.css?v=1.1">
<link rel="stylesheet" href="/css/base.css?v=1.1">
<link rel="stylesheet" href="/css/header.css?v=1.1">
<link rel="stylesheet" href="/css/footer.css?v=1.1">
<link rel="stylesheet" href="/css/syntax.css?v=1.1">
<link rel="stylesheet" href="/css/docs.css?v=1.1">
<script>
(function() {
var cx = '000162378814775985090:molvbm0vggm';
var gcse = document.createElement('script');
gcse.type = 'text/javascript';
gcse.async = true;
gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
'//cse.google.com/cse.js?cx=' + cx;
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(gcse, s);
})();
</script>
</head>
<body>
<!-- Start page_header include -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/2.2.4/jquery.min.js"></script>
<div class="top-navigator">
<div class="container">
<div class="left-cont">
<a class="logo" href="/"><span class="druid-logo"></span></a>
</div>
<div class="right-cont">
<ul class="links">
<li class=""><a href="/technology">Technology</a></li>
<li class=""><a href="/use-cases">Use Cases</a></li>
<li class=""><a href="/druid-powered">Powered By</a></li>
<li class=""><a href="/docs/latest/design/">Docs</a></li>
<li class=""><a href="/community/">Community</a></li>
<li class="header-dropdown">
<a>Apache</a>
<div class="header-dropdown-menu">
<a href="https://www.apache.org/" target="_blank">Foundation</a>
<a href="https://www.apache.org/events/current-event" target="_blank">Events</a>
<a href="https://www.apache.org/licenses/" target="_blank">License</a>
<a href="https://www.apache.org/foundation/thanks.html" target="_blank">Thanks</a>
<a href="https://www.apache.org/security/" target="_blank">Security</a>
<a href="https://www.apache.org/foundation/sponsorship.html" target="_blank">Sponsorship</a>
</div>
</li>
<li class=" button-link"><a href="/downloads.html">Download</a></li>
</ul>
</div>
</div>
<div class="action-button menu-icon">
<span class="fa fa-bars"></span> MENU
</div>
<div class="action-button menu-icon-close">
<span class="fa fa-times"></span> MENU
</div>
</div>
<script type="text/javascript">
var $menu = $('.right-cont');
var $menuIcon = $('.menu-icon');
var $menuIconClose = $('.menu-icon-close');
function showMenu() {
$menu.fadeIn(100);
$menuIcon.fadeOut(100);
$menuIconClose.fadeIn(100);
}
$menuIcon.click(showMenu);
function hideMenu() {
$menu.fadeOut(100);
$menuIconClose.fadeOut(100);
$menuIcon.fadeIn(100);
}
$menuIconClose.click(hideMenu);
$(window).resize(function() {
if ($(window).width() >= 840) {
$menu.fadeIn(100);
$menuIcon.fadeOut(100);
$menuIconClose.fadeOut(100);
}
else {
$menu.fadeOut(100);
$menuIcon.fadeIn(100);
$menuIconClose.fadeOut(100);
}
});
</script>
<!-- Stop page_header include -->
<div class="container doc-container">
<p> Looking for the <a href="/docs/0.16.1-incubating/">latest stable documentation</a>?</p>
<div class="row">
<div class="col-md-9 doc-content">
<p>
<a class="btn btn-default btn-xs visible-xs-inline-block visible-sm-inline-block" href="#toc">Table of Contents</a>
</p>
<!--
~ 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.
-->
<h1 id="kerberos">Kerberos</h1>
<p>Apache Druid (incubating) Extension to enable Authentication for Druid Processes using Kerberos.
This extension adds an Authenticator which is used to protect HTTP Endpoints using the simple and protected GSSAPI negotiation mechanism <a href="https://en.wikipedia.org/wiki/SPNEGO">SPNEGO</a>.
Make sure to <a href="../../operations/including-extensions.html">include</a> <code>druid-kerberos</code> as an extension.</p>
<h2 id="configuration">Configuration</h2>
<h3 id="creating-an-authenticator">Creating an Authenticator</h3>
<div class="highlight"><pre><code class="language-text" data-lang="text"><span></span>druid.auth.authenticatorChain=[&quot;MyKerberosAuthenticator&quot;]
druid.auth.authenticator.MyKerberosAuthenticator.type=kerberos
</code></pre></div>
<p>To use the Kerberos authenticator, add an authenticator with type <code>kerberos</code> to the authenticatorChain. The example above uses the name &quot;MyKerberosAuthenticator&quot; for the Authenticator.</p>
<p>Configuration of the named authenticator is assigned through properties with the form:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text"><span></span>druid.auth.authenticator.&lt;authenticatorName&gt;.&lt;authenticatorProperty&gt;
</code></pre></div>
<p>The configuration examples in the rest of this document will use &quot;kerberos&quot; as the name of the authenticator being configured.</p>
<h3 id="properties">Properties</h3>
<table><thead>
<tr>
<th>Property</th>
<th>Possible Values</th>
<th>Description</th>
<th>Default</th>
<th>required</th>
</tr>
</thead><tbody>
<tr>
<td><code>druid.auth.authenticator.kerberos.serverPrincipal</code></td>
<td><code>HTTP/_HOST@EXAMPLE.COM</code></td>
<td>SPNego service principal used by druid processes</td>
<td>empty</td>
<td>Yes</td>
</tr>
<tr>
<td><code>druid.auth.authenticator.kerberos.serverKeytab</code></td>
<td><code>/etc/security/keytabs/spnego.service.keytab</code></td>
<td>SPNego service keytab used by druid processes</td>
<td>empty</td>
<td>Yes</td>
</tr>
<tr>
<td><code>druid.auth.authenticator.kerberos.authToLocal</code></td>
<td><code>RULE:[1:$1@$0](druid@EXAMPLE.COM)s/.*/druid DEFAULT</code></td>
<td>It allows you to set a general rule for mapping principal names to local user names. It will be used if there is not an explicit mapping for the principal name that is being translated.</td>
<td>DEFAULT</td>
<td>No</td>
</tr>
<tr>
<td><code>druid.auth.authenticator.kerberos.excludedPaths</code></td>
<td><code>[&#39;/status&#39;,&#39;/health&#39;]</code></td>
<td>Array of HTTP paths which which does NOT need to be authenticated.</td>
<td>None</td>
<td>No</td>
</tr>
<tr>
<td><code>druid.auth.authenticator.kerberos.cookieSignatureSecret</code></td>
<td><code>secretString</code></td>
<td>Secret used to sign authentication cookies. It is advisable to explicitly set it, if you have multiple druid ndoes running on same machine with different ports as the Cookie Specification does not guarantee isolation by port.</td>
<td><Random value></td>
<td>No</td>
</tr>
<tr>
<td><code>druid.auth.authenticator.kerberos.authorizerName</code></td>
<td>Depends on available authorizers</td>
<td>Authorizer that requests should be directed to</td>
<td>Empty</td>
<td>Yes</td>
</tr>
</tbody></table>
<p>As a note, it is required that the SPNego principal in use by the druid processes must start with HTTP (This specified by <a href="https://tools.ietf.org/html/rfc4559">RFC-4559</a>) and must be of the form &quot;HTTP/_HOST@REALM&quot;.
The special string _HOST will be replaced automatically with the value of config <code>druid.host</code></p>
<h3 id="auth-to-local-syntax">Auth to Local Syntax</h3>
<p><code>druid.auth.authenticator.kerberos.authToLocal</code> allows you to set a general rules for mapping principal names to local user names.
The syntax for mapping rules is <code>RULE:\[n:string](regexp)s/pattern/replacement/g</code>. The integer n indicates how many components the target principal should have. If this matches, then a string will be formed from string, substituting the realm of the principal for $0 and the n‘th component of the principal for $n. e.g. if the principal was druid/admin then <code>\[2:$2$1suffix]</code> would result in the string <code>admindruidsuffix</code>.
If this string matches regexp, then the s//[g] substitution command will be run over the string. The optional g will cause the substitution to be global over the string, instead of replacing only the first match in the string.
If required, multiple rules can be be joined by newline character and specified as a String.</p>
<h3 id="increasing-http-header-size-for-large-spnego-negotiate-header">Increasing HTTP Header size for large SPNEGO negotiate header</h3>
<p>In Active Directory environment, SPNEGO token in the Authorization header includes PAC (Privilege Access Certificate) information,
which includes all security groups for the user. In some cases when the user belongs to many security groups the header to grow beyond what druid can handle by default.
In such cases, max request header size that druid can handle can be increased by setting <code>druid.server.http.maxRequestHeaderSize</code> (default 8Kb) and <code>druid.router.http.maxRequestBufferSize</code> (default 8Kb).</p>
<h2 id="configuring-kerberos-escalated-client">Configuring Kerberos Escalated Client</h2>
<p>Druid internal processes communicate with each other using an escalated http Client. A Kerberos enabled escalated HTTP Client can be configured by following properties -</p>
<table><thead>
<tr>
<th>Property</th>
<th>Example Values</th>
<th>Description</th>
<th>Default</th>
<th>required</th>
</tr>
</thead><tbody>
<tr>
<td><code>druid.escalator.type</code></td>
<td><code>kerberos</code></td>
<td>Type of Escalator client used for internal process communication.</td>
<td>n/a</td>
<td>Yes</td>
</tr>
<tr>
<td><code>druid.escalator.internalClientPrincipal</code></td>
<td><code>druid@EXAMPLE.COM</code></td>
<td>Principal user name, used for internal process communication</td>
<td>n/a</td>
<td>Yes</td>
</tr>
<tr>
<td><code>druid.escalator.internalClientKeytab</code></td>
<td><code>/etc/security/keytabs/druid.keytab</code></td>
<td>Path to keytab file used for internal process communication</td>
<td>n/a</td>
<td>Yes</td>
</tr>
<tr>
<td><code>druid.escalator.authorizerName</code></td>
<td><code>MyBasicAuthorizer</code></td>
<td>Authorizer that requests should be directed to.</td>
<td>n/a</td>
<td>Yes</td>
</tr>
</tbody></table>
<h2 id="accessing-druid-http-end-points-when-kerberos-security-is-enabled">Accessing Druid HTTP end points when kerberos security is enabled</h2>
<ol>
<li><p>To access druid HTTP endpoints via curl user will need to first login using <code>kinit</code> command as follows -</p>
<div class="highlight"><pre><code class="language-text" data-lang="text"><span></span>kinit -k -t &lt;path_to_keytab_file&gt; user@REALM.COM
</code></pre></div></li>
<li><p>Once the login is successful verify that login is successful using <code>klist</code> command</p></li>
<li><p>Now you can access druid HTTP endpoints using curl command as follows -</p>
<div class="highlight"><pre><code class="language-text" data-lang="text"><span></span>curl --negotiate -u:anyUser -b ~/cookies.txt -c ~/cookies.txt -X POST -H&#39;Content-Type: application/json&#39; &lt;HTTP_END_POINT&gt;
</code></pre></div>
<p>e.g to send a query from file <code>query.json</code> to the Druid Broker use this command -</p>
<div class="highlight"><pre><code class="language-text" data-lang="text"><span></span>curl --negotiate -u:anyUser -b ~/cookies.txt -c ~/cookies.txt -X POST -H&#39;Content-Type: application/json&#39; http://broker-host:port/druid/v2/?pretty -d @query.json
</code></pre></div>
<p>Note: Above command will authenticate the user first time using SPNego negotiate mechanism and store the authentication cookie in file. For subsequent requests the cookie will be used for authentication.</p></li>
</ol>
<h2 id="accessing-coordinator-or-overlord-console-from-web-browser">Accessing Coordinator or Overlord console from web browser</h2>
<p>To access Coordinator/Overlord console from browser you will need to configure your browser for SPNego authentication as follows -</p>
<ol>
<li>Safari - No configurations required.</li>
<li>Firefox - Open firefox and follow these steps -
<ol>
<li>Go to <code>about:config</code> and search for <code>network.negotiate-auth.trusted-uris</code>.</li>
<li>Double-click and add the following values: <code>&quot;http://druid-coordinator-hostname:ui-port&quot;</code> and <code>&quot;http://druid-overlord-hostname:port&quot;</code></li>
</ol></li>
<li>Google Chrome - From the command line run following commands -
<ol>
<li><code>google-chrome --auth-server-whitelist=&quot;druid-coordinator-hostname&quot; --auth-negotiate-delegate-whitelist=&quot;druid-coordinator-hostname&quot;</code></li>
<li><code>google-chrome --auth-server-whitelist=&quot;druid-overlord-hostname&quot; --auth-negotiate-delegate-whitelist=&quot;druid-overlord-hostname&quot;</code></li>
</ol></li>
<li>Internet Explorer -
<ol>
<li>Configure trusted websites to include <code>&quot;druid-coordinator-hostname&quot;</code> and <code>&quot;druid-overlord-hostname&quot;</code></li>
<li>Allow negotiation for the UI website.</li>
</ol></li>
</ol>
<h2 id="sending-queries-programmatically">Sending Queries programmatically</h2>
<p>Many HTTP client libraries, such as Apache Commons <a href="https://hc.apache.org/">HttpComponents</a>, already have support for performing SPNEGO authentication. You can use any of the available HTTP client library to communicate with druid cluster.</p>
</div>
<div class="col-md-3">
<div class="searchbox">
<gcse:searchbox-only></gcse:searchbox-only>
</div>
<div id="toc" class="nav toc hidden-print">
</div>
</div>
</div>
</div>
<!-- Start page_footer include -->
<footer class="druid-footer">
<div class="container">
<div class="text-center">
<p>
<a href="/technology">Technology</a>&ensp;·&ensp;
<a href="/use-cases">Use Cases</a>&ensp;·&ensp;
<a href="/druid-powered">Powered by Druid</a>&ensp;·&ensp;
<a href="/docs/latest">Docs</a>&ensp;·&ensp;
<a href="/community/">Community</a>&ensp;·&ensp;
<a href="/downloads.html">Download</a>&ensp;·&ensp;
<a href="/faq">FAQ</a>
</p>
</div>
<div class="text-center">
<a title="Join the user group" href="https://groups.google.com/forum/#!forum/druid-user" target="_blank"><span class="fa fa-comments"></span></a>&ensp;·&ensp;
<a title="Follow Druid" href="https://twitter.com/druidio" target="_blank"><span class="fab fa-twitter"></span></a>&ensp;·&ensp;
<a title="Download via Apache" href="https://www.apache.org/dyn/closer.cgi?path=/incubator/druid/0.16.1-incubating/apache-druid-0.16.1-incubating-bin.tar.gz" target="_blank"><span class="fas fa-feather"></span></a>&ensp;·&ensp;
<a title="GitHub" href="https://github.com/apache/incubator-druid" target="_blank"><span class="fab fa-github"></span></a>
</div>
<div class="text-center license">
Copyright © 2019 <a href="https://www.apache.org/" target="_blank">Apache Software Foundation</a>.<br>
Except where otherwise noted, licensed under <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a>.<br>
Apache Druid, Druid, and the Druid logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries.
</div>
</div>
</footer>
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-131010415-1"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-131010415-1');
</script>
<script>
function trackDownload(type, url) {
ga('send', 'event', 'download', type, url);
}
</script>
<script src="//code.jquery.com/jquery.min.js"></script>
<script src="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script>
<script src="/assets/js/druid.js"></script>
<!-- stop page_footer include -->
<script>
$(function() {
$(".toc").load("/docs/0.14.1-incubating/toc.html");
// There is no way to tell when .gsc-input will be async loaded into the page so just try to set a placeholder until it works
var tries = 0;
var timer = setInterval(function() {
tries++;
if (tries > 300) clearInterval(timer);
var searchInput = $('input.gsc-input');
if (searchInput.length) {
searchInput.attr('placeholder', 'Search');
clearInterval(timer);
}
}, 100);
});
</script>
</body>
</html>