Author: elserj
Date: Mon Apr 4 17:16:42 2016
New Revision: 1737706
URL: http://svn.apache.org/viewvc?rev=1737706&view=rev
Log:
[CALCITE-1173] Update website for basic/digest auth
Modified:
calcite/site/avatica/docs/client_reference.html
calcite/site/avatica/docs/security.html
Modified: calcite/site/avatica/docs/client_reference.html
URL:
http://svn.apache.org/viewvc/calcite/site/avatica/docs/client_reference.html?rev=1737706&r1=1737705&r2=1737706&view=diff
==============================================================================
--- calcite/site/avatica/docs/client_reference.html (original)
+++ calcite/site/avatica/docs/client_reference.html Mon Apr 4 17:16:42 2016
@@ -367,7 +367,7 @@ that are available for clients to specif
<p>The following are a list of supported options:</p>
<dl>
- <dt><strong>url</strong></dt>
+ <dt><strong><a name="url" href="#url">url</a></strong></dt>
<dd>
<p><em>Description</em>: This property is a URL which refers to the
location of the
Avatica Server which the driver will communicate with.</p>
@@ -379,7 +379,7 @@ user provides a value for this property.
<dd>
<p><em>Required</em>: Yes.</p>
</dd>
- <dt><strong>serialization</strong></dt>
+ <dt><strong><a name="serialization"
href="#serialization">serialization</a></strong></dt>
<dd>
<p><em>Description</em>: Avatica supports multiple types of serialization
mechanisms
to format data between the client and server. This property is used to ensure
@@ -392,20 +392,20 @@ values presently include <code>json</cod
<dd>
<p><em>Required</em>: No.</p>
</dd>
- <dt><strong>authentication</strong></dt>
+ <dt><strong><a name="authentication"
href="#authentication">authentication</a></strong></dt>
<dd>
<p><em>Description</em>: Avatica clients can specify the means in which it
authenticates
-with the Avatica server. Presently, the only form of authentication is SPNEGO
-which enables Kerberos authentication. Clients who want to use a specific form
-of authentication should specify the appropriate value in this property.</p>
+with the Avatica server. Clients who want to use a specific form
+of authentication should specify the appropriate value in this property. Valid
+values for this property are presently: <code>NONE</code>, <code>BASIC</code>,
<code>DIGEST</code>, and <code>SPNEGO</code>.</p>
</dd>
<dd>
- <p><em>Default</em>: <code>null</code> (implying âno
authenticationâ).</p>
+ <p><em>Default</em>: <code>null</code> (implying âno authenticationâ,
equivalent to <code>NONE</code>).</p>
</dd>
<dd>
<p><em>Required</em>: No.</p>
</dd>
- <dt><strong>timeZone</strong></dt>
+ <dt><strong><a name="timeZone" href="#timeZone">timeZone</a></strong></dt>
<dd>
<p><em>Description</em>: The timezone that will be used for dates and
times. Valid values for this
property are defined by <a href="https://www.ietf.org/rfc/rfc0822.txt";>RFC
822</a>, for
@@ -419,7 +419,7 @@ use the default timezone as specified by
<dd>
<p><em>Required</em>: No.</p>
</dd>
- <dt><strong>httpclient_factory</strong></dt>
+ <dt><strong><a name="httpclient-factory"
href="#httpclient-factory">httpclient_factory</a></strong></dt>
<dd>
<p><em>Description</em>: The Avatica client is a âfancyâ HTTP client.
As such, there are
many libraries and APIs available for making HTTP calls. To determine which
implementation
@@ -432,7 +432,7 @@ to control how the <code>AvaticaHttpClie
<dd>
<p><em>Required</em>: No.</p>
</dd>
- <dt><strong>httpclient_impl</strong></dt>
+ <dt><strong><a name="httpclient-impl"
href="#httpclient-impl">httpclient_impl</a></strong></dt>
<dd>
<p><em>Description</em>: When using the default
<code>AvaticaHttpClientFactoryImpl</code> HTTP client factory
implementation, this factory should choose the correct client implementation
for the
@@ -442,6 +442,30 @@ automatically choose the HTTP client imp
</dd>
<dd>
<p><em>Default</em>: <code>null</code>.</p>
+ </dd>
+ <dd>
+ <p><em>Required</em>: No.</p>
+ </dd>
+ <dt><strong><a name="avatica-user"
href="#avatica-user">avatica_user</a></strong></dt>
+ <dd>
+ <p><em>Description</em>: This is the username used by an Avatica client to
identify itself
+to the Avatica server. It is unique to the traditional âuserâ JDBC
property. It
+is only necessary if Avatica is configured for HTTP Basic or Digest
authentication.</p>
+ </dd>
+ <dd>
+ <p><em>Default</em>: <code>null</code>.</p>
+ </dd>
+ <dd>
+ <p><em>Required</em>: No.</p>
+ </dd>
+ <dt><strong><a name="avatica-password"
href="#avatica-password">avatica_password</a></strong></dt>
+ <dd>
+ <p><em>Description</em>: This is the password used by an Avatica client to
identify itself
+to the Avatica server. It is unique to the traditional âpasswordâ JDBC
property. It
+is only necessary if Avatica is configured for HTTP Basic or Digest
authentication.</p>
+ </dd>
+ <dd>
+ <p><em>Default</em>: <code>null</code>.</p>
</dd>
<dd>
<p><em>Required</em>: No.</p>
Modified: calcite/site/avatica/docs/security.html
URL:
http://svn.apache.org/viewvc/calcite/site/avatica/docs/security.html?rev=1737706&r1=1737705&r2=1737706&view=diff
==============================================================================
--- calcite/site/avatica/docs/security.html (original)
+++ calcite/site/avatica/docs/security.html Mon Apr 4 17:16:42 2016
@@ -362,16 +362,98 @@ for limit what actions clients are allow
<p>Similarly, Avatica must limit what users are allowed to connect and interact
with the server. Avatica must primarily deal with authentication while
authorization
is deferred to the underlying database. By default, Avatica provides no
authentication.
-Avatica does have the ability to perform client authentication using
Kerberos.</p>
+Avatica does have the ability to perform client authentication using Kerberos,
+HTTP Basic, and HTTP Digest.</p>
-<h2 id="kerberos-based-authentication">Kerberos-based authentication</h2>
+<p>The authentication and authorization provided by Avatica are designed for
use
+<em>instead</em> of the authentication and authorization provided by the
underlying database.
+The typical <code>user</code> and <code>password</code> JDBC properties are
<strong>always</strong> passed through to
+the Avatica server which will cause the server to enforce those credentials.
As such,
+Avaticaâs authentication types mentioned here only have relevance when the
underlying databaseâs authentication
+and authorization features are not used. (The Kerberos/SPNEGO integration is
one difference as the impersonation feature
+is specifically designed to allow the Kerberos identity to be passed to the
database -
+new advanced implementations could also follow this same approach if
desired).</p>
+
+<h2 id="table-of-contents">Table of Contents</h2>
+<ul>
+ <li><a href="#http-basic-authentication">HTTP Basic</a></li><li><a
href="#http-digest-authentication">HTTP Digest</a></li><li><a
href="#kerberos-with-spnego-authentication">Kerberos with SPNEGO</a></li><li><a
href="#client-implementation">Client implementation</a></li>
+</ul>
+
+<h2 id="http-basic-authentication">HTTP Basic Authentication</h2>
+
+<p>Avatica supports authentication over <a
href="https://en.wikipedia.org/wiki/Basic_access_authentication";>HTTP Basic</a>.
+This is simple username-password based authentication which is ultimately
insecure when
+operating over an untrusted network. Basic authentication is only secure when
the transport
+is encrypted (e.g. TLS) as the credentials are passed in the clear. This
authentication is
+supplementary to the provided JDBC authentication. If credentials are passed
to the database
+already, this authentication is unnecessary.</p>
+
+<h3 id="enabling-basic-authentication">Enabling Basic Authentication</h3>
+
+<div class="highlight"><pre><code class="language-java" data-lang="java"><span
class="n">String</span> <span class="n">propertiesFile</span> <span
class="o">=</span> <span
class="s">"/path/to/jetty-users.properties"</span><span
class="o">;</span>
+<span class="c1">// All roles allowed</span>
+<span class="n">String</span><span class="o">[]</span> <span
class="n">allowedRoles</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">String</span><span class="o">[]</span>
<span class="o">{</span><span class="s">"*"</span><span
class="o">};</span>
+<span class="c1">// Only specific roles are allowed</span>
+<span class="n">allowedRoles</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">String</span><span class="o">[]</span>
<span class="o">{</span> <span class="s">"users"</span><span
class="o">,</span> <span class="s">"admins"</span> <span
class="o">};</span>
+<span class="n">HttpServer</span> <span class="n">server</span> <span
class="o">=</span> <span class="k">new</span> <span
class="n">HttpServer</span><span class="o">.</span><span
class="na">Builder</span><span class="o">()</span>
+ <span class="o">.</span><span class="na">withPort</span><span
class="o">(</span><span class="mi">8765</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">withHandler</span><span
class="o">(</span><span class="k">new</span> <span
class="nf">LocalService</span><span class="o">(),</span> <span
class="n">Driver</span><span class="o">.</span><span
class="na">Serialization</span><span class="o">.</span><span
class="na">PROTOBUF</span><span class="o">)</span>
+ <span class="o">.</span><span
class="na">withBasicAuthentication</span><span class="o">(</span><span
class="n">propertiesFile</span><span class="o">,</span> <span
class="n">allowedRoles</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">build</span><span
class="o">();</span></code></pre></div>
+
+<p>The properties file must be in a form consumable by Jetty. Each line in this
+file is of the form: <code>username: password[,rolename ...]</code></p>
+
+<p>For example:</p>
+
+<div class="highlight"><pre><code class="language-properties"
data-lang="properties"><span class="na">bob</span><span class="o">:</span>
<span class="s">b0b5pA55w0rd,users</span>
+<span class="na">steve</span><span class="o">:</span> <span
class="s">5teve5pA55w0rd,users</span>
+<span class="na">alice</span><span class="o">:</span> <span
class="s">Al1cepA55w0rd,admins</span></code></pre></div>
+
+<p>Passwords can also be obfuscated as MD5 hashes or oneway cryptography
(âCRYPTâ).
+For more information, see the <a
href="http://www.eclipse.org/jetty/documentation/current/configuring-security-secure-passwords.html";>official
Jetty documentation</a>.</p>
+
+<h2 id="http-digest-authentication">HTTP Digest Authentication</h2>
+
+<p>Avatica also supports <a
href="https://en.wikipedia.org/wiki/Digest_access_authentication";>HTTP
Digest</a>.
+This is desirable for Avatica as it does not require the use of TLS to secure
communication
+between the Avatica client and server. It is configured very similarly to HTTP
Basic
+authentication. This authentication is supplementary to the provided JDBC
authentication.
+If credentials are passed to the database already, this authentication is
unnecessary.</p>
+
+<h3 id="enabling-digest-authentication">Enabling Digest Authentication</h3>
+
+<div class="highlight"><pre><code class="language-java" data-lang="java"><span
class="n">String</span> <span class="n">propertiesFile</span> <span
class="o">=</span> <span
class="s">"/path/to/jetty-users.properties"</span><span
class="o">;</span>
+<span class="c1">// All roles allowed</span>
+<span class="n">String</span><span class="o">[]</span> <span
class="n">allowedRoles</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">String</span><span class="o">[]</span>
<span class="o">{</span><span class="s">"*"</span><span
class="o">};</span>
+<span class="c1">// Only specific roles are allowed</span>
+<span class="n">allowedRoles</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">String</span><span class="o">[]</span>
<span class="o">{</span> <span class="s">"users"</span><span
class="o">,</span> <span class="s">"admins"</span> <span
class="o">};</span>
+<span class="n">HttpServer</span> <span class="n">server</span> <span
class="o">=</span> <span class="k">new</span> <span
class="n">HttpServer</span><span class="o">.</span><span
class="na">Builder</span><span class="o">()</span>
+ <span class="o">.</span><span class="na">withPort</span><span
class="o">(</span><span class="mi">8765</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">withHandler</span><span
class="o">(</span><span class="k">new</span> <span
class="nf">LocalService</span><span class="o">(),</span> <span
class="n">Driver</span><span class="o">.</span><span
class="na">Serialization</span><span class="o">.</span><span
class="na">PROTOBUF</span><span class="o">)</span>
+ <span class="o">.</span><span
class="na">withDigestAuthentication</span><span class="o">(</span><span
class="n">propertiesFile</span><span class="o">,</span> <span
class="n">allowedRoles</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">build</span><span
class="o">();</span></code></pre></div>
+
+<p>The properties file must be in a form consumable by Jetty. Each line in this
+file is of the form: <code>username: password[,rolename ...]</code></p>
+
+<p>For example:</p>
+
+<div class="highlight"><pre><code class="language-properties"
data-lang="properties"><span class="na">bob</span><span class="o">:</span>
<span class="s">b0b5pA55w0rd,users</span>
+<span class="na">steve</span><span class="o">:</span> <span
class="s">5teve5pA55w0rd,users</span>
+<span class="na">alice</span><span class="o">:</span> <span
class="s">Al1cepA55w0rd,admins</span></code></pre></div>
+
+<p>Passwords can also be obfuscated as MD5 hashes or oneway cryptography
(âCRYPTâ).
+For more information, see the <a
href="http://www.eclipse.org/jetty/documentation/current/configuring-security-secure-passwords.html";>official
Jetty documentation</a>.</p>
+
+<h2 id="kerberos-with-spnego-authentication">Kerberos with SPNEGO
Authentication</h2>
<p>Because Avatica operates over an HTTP interface, the simple and protected
GSSAPI
negotiation mechanism (<a
href="https://en.wikipedia.org/wiki/SPNEGO";>SPNEGO</a>) is a logical
choice. This mechanism makes use of the âHTTP Negotiateâ authentication
extension to
communicate with the Kerberos Key Distribution Center (KDC) to authenticate a
client.</p>
-<h2 id="enabling-spnegokerberos-authentication-in-servers">Enabling
SPNEGO/Kerberos Authentication in servers</h2>
+<h3 id="enabling-spnegokerberos-authentication-in-servers">Enabling
SPNEGO/Kerberos Authentication in servers</h3>
<p>The Avatica server can operate either by performing the login using
a JAAS configuration file or login programmatically. By default, authenticated
clients
@@ -382,7 +464,7 @@ is the feature which enables actions to
<strong>must</strong> have an primary of <code>HTTP</code> (where Kerberos
principals are of the form
<code>primary[/instance]@REALM</code>). This is specified by <a
href="https://tools.ietf.org/html/rfc4559";>RFC-4559</a>.</p>
-<h3 id="programmatic-login">Programmatic Login</h3>
+<h4 id="programmatic-login">Programmatic Login</h4>
<p>This approach requires no external file configurations and only requires a
keytab file for the principal.</p>
@@ -395,7 +477,7 @@ keytab file for the principal.</p>
<span class="k">new</span> <span class="nf">File</span><span
class="o">(</span><span
class="s">"/etc/security/keytabs/avatica.spnego.keytab"</span><span
class="o">))</span>
<span class="o">.</span><span class="na">build</span><span
class="o">();</span></code></pre></div>
-<h3 id="jaas-configuration-file-login">JAAS Configuration File Login</h3>
+<h4 id="jaas-configuration-file-login">JAAS Configuration File Login</h4>
<p>A JAAS configuration file can be set via the system property
<code>java.security.auth.login.config</code>.
The user must set this property when launching their Java application invoking
the Avatica server.
@@ -420,7 +502,7 @@ of the Avatica server. The invocation is
<p>Ensure the <code>keyTab</code> and <code>principal</code> attributes are
set correctly for your system.</p>
-<h2 id="impersonation">Impersonation</h2>
+<h3 id="impersonation">Impersonation</h3>
<p>Impersonation is a feature of the Avatica server which allows the Avatica
clients
to execute the server-side calls (e.g. the underlying JDBC calls). Because the
details
@@ -461,13 +543,25 @@ client but using the serverâs ident
<h2 id="client-implementation">Client implementation</h2>
<p>Many HTTP client libraries, such as <a href="https://hc.apache.org/";>Apache
Commons HttpComponents</a>, already have
-support for performing SPNEGO authentication. When in doubt, refer to one of
+support for performing Basic, Digest, and SPNEGO authentication. When in
doubt, refer to one of
these implementations as it is likely correct.</p>
-<p>For information on building this by hand, consult <a
href="https://tools.ietf.org/html/rfc4559";>RFC-4559</a>
-which describes how the authentication handshake, through use of the
âWWW-authenticateâ
+<h3 id="spnego">SPNEGO</h3>
+
+<p>For information on building SPNEGO support by hand, consult <a
href="https://tools.ietf.org/html/rfc4559";>RFC-4559</a>
+which describes how the authentication handshake, through use of the
âWWW-authenticate=Negotiateâ
HTTP header, is used to authenticate a client.</p>
+<h3 id="password-based">Password-based</h3>
+
+<p>For both HTTP Basic and Digest authentication, the <a
href="/avatica/docs/client_reference.html#avatica-user">avatica_user</a>
+and <a
href="/avatica/docs/client_reference.html#avatica-password">avatica_password</a>
+properties are used to identify the client with the server. If the underlying
database
+(the JDBC driver inside the Avatica server) require their own user and
password combination,
+these are set via the traditional âuserâ and âpasswordâ properties in
the Avatica
+JDBC driver. This also implies that adding HTTP-level authentication in
Avatica is likely
+superfluous.</p>
+
