You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@calcite.apache.org by el...@apache.org on 2016/04/04 19:16:42 UTC

svn commit: r1737706 - in /calcite/site/avatica/docs: client_reference.html security.html

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">&quot;/path/to/jetty-users.properties&quot;</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">&quot;*&quot;</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">&quot;users&quot;</span><span class="o">,</span> <span class="s">&quot;admins&quot;</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">&quot;/path/to/jetty-users.properties&quot;</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">&quot;*&quot;</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">&quot;users&quot;</span><span class="o">,</span> <span class="s">&quot;admins&quot;</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">&quot;/etc/security/keytabs/avatica.spnego.keytab&quot;</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>
+