You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@knox.apache.org by lm...@apache.org on 2015/03/22 18:44:17 UTC
svn commit: r1668419 - in /knox: site/books/knox-0-6-0/user-guide.html
trunk/books/0.6.0/book_gateway-details.md
trunk/books/0.6.0/config_mutual_authentication_ssl.md
Author: lmccay
Date: Sun Mar 22 17:44:17 2015
New Revision: 1668419
URL: http://svn.apache.org/r1668419
Log:
KNOX-504 - document mutual authentication using SSL
Added:
knox/trunk/books/0.6.0/config_mutual_authentication_ssl.md
Modified:
knox/site/books/knox-0-6-0/user-guide.html
knox/trunk/books/0.6.0/book_gateway-details.md
Modified: knox/site/books/knox-0-6-0/user-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-6-0/user-guide.html?rev=1668419&r1=1668418&r2=1668419&view=diff
==============================================================================
--- knox/site/books/knox-0-6-0/user-guide.html (original)
+++ knox/site/books/knox-0-6-0/user-guide.html Sun Mar 22 17:44:17 2015
@@ -1456,7 +1456,33 @@ APACHE_HOME/bin/apachectl -k stop
</provider>
</code></pre><h5><a id="REST+Invocation+for+Tivoli+AM"></a>REST Invocation for Tivoli AM</h5><p>The following curl command can be used to request a directory listing from HDFS while passing in the expected headers of iv_user and iv_group. Note that the iv_group value in this command matches the expected ACL for webhdfs in the above topology file. Changing this from “admin” to “admin2” should result in a 401 unauthorized response.</p>
<pre><code>curl -k -i --header "iv_user: guest" --header "iv_group: admin" -v https://localhost:8443/gateway/sandbox/webhdfs/v1/tmp?op=LISTSTATUS
-</code></pre><p>Omitting the –header “iv_user: guest” above will result in a rejected request.</p><h3><a id="Audit"></a>Audit</h3><p>The Audit facility within the Knox Gateway introduces functionality for tracking actions that are executed by Knox per user’s request or that are produced by Knox internal events like topology deploy, etc. The Knox Audit module is based on the <a href="http://logging.apache.org/log4j/1.2/">Apache log4j</a>.</p><h4><a id="Configuration+needed"></a>Configuration needed</h4><p>Out of the box, the Knox Gateway includes preconfigured auditing capabilities. To change its configuration please read following sections.</p><h4><a id="Where+audit+logs+go"></a>Where audit logs go</h4><p>Audit module is preconfigured to write audit records to the log file <code>/var/log/knox/gateway-audit.log</code>.</p><p>This behavior can be changed in the <code>conf/gateway-log4j.properties</code> file. <code>log4j.appender.auditfile.*</code> properties d
etermine this behavior. For detailed information read <a href="http://logging.apache.org/log4j/1.2/">Apache log4j</a>.</p><h4><a id="Audit+format"></a>Audit format</h4><p>Out of the box, the audit record format is defined by org.apache.hadoop.gateway.audit.log4j.layout.AuditLayout. Its structure is following:</p>
+</code></pre><p>Omitting the –header “iv_user: guest” above will result in a rejected request.</p><h3><a id="Mutual+Authentication+with+SSL"></a>Mutual Authentication with SSL</h3><p>To establish a stronger trust relationship between client and server, we provide mutual authentication with SSL via client certs. This is particularly useful in providing additional validation for Preauthenticated SSO with HTTP Headers. Rather than just ip address validation, connections will only be accepted by Knox from clients presenting trusted certificates.</p><p>This behavior is configured for the entire gateway instance within the gateway-site.xml file. All topologies deployed within the gateway instance with mutual authentication enabled will require incoming connections to present trusted client certificates during the SSL handshake. Otherwise, connections will be refused.</p><p>The following table describes the configuration elements related to mutual authentication and their
defaults:</p>
+<table>
+ <thead>
+ <tr>
+ <th>Configuration Element </th>
+ <th>Description </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>gateway.client.auth.needed </td>
+ <td>True|False - indicating the need for client authentication. Default is False.</td>
+ </tr>
+ <tr>
+ <td>gateway.truststore.path </td>
+ <td>Fully qualified path to the trust store to use. Default is the gateway.jks.</td>
+ </tr>
+ <tr>
+ <td>gateway.truststore.type </td>
+ <td>Keystore type of the trust store. Default is JKS. </td>
+ </tr>
+ <tr>
+ <td>gateway.trust.all.certs </td>
+ <td>Allows for all certificates to be trusted. Default is false.</td>
+ </tr>
+ </tbody>
+</table><p>By only indicating that it is needed with gateway.client.auth.needed, the {GATEWAY_HOME}/data/security/keystores/gateway.jks keystore is used. This is the identity keystore for the server and can also be used as the truststore. In addition, we can specify the path to a dedicated truststore via gateway.truststore.path. If the truststore password is different from the gateway master secret then it can be set using the </p><p>knoxcli.sh create-alias gateway-truststore-password –value {pwd} </p><p>Otherwise, the master secret will be used. If the truststore is not a JKS type then it can be set via gateway.truststore.type.</p><h3><a id="Audit"></a>Audit</h3><p>The Audit facility within the Knox Gateway introduces functionality for tracking actions that are executed by Knox per user’s request or that are produced by Knox internal events like topology deploy, etc. The Knox Audit module is based on the <a href="http://logging.apache.org/log4j/1.2/">Apache log4j</a>.</
p><h4><a id="Configuration+needed"></a>Configuration needed</h4><p>Out of the box, the Knox Gateway includes preconfigured auditing capabilities. To change its configuration please read following sections.</p><h4><a id="Where+audit+logs+go"></a>Where audit logs go</h4><p>Audit module is preconfigured to write audit records to the log file <code>/var/log/knox/gateway-audit.log</code>.</p><p>This behavior can be changed in the <code>conf/gateway-log4j.properties</code> file. <code>log4j.appender.auditfile.*</code> properties determine this behavior. For detailed information read <a href="http://logging.apache.org/log4j/1.2/">Apache log4j</a>.</p><h4><a id="Audit+format"></a>Audit format</h4><p>Out of the box, the audit record format is defined by org.apache.hadoop.gateway.audit.log4j.layout.AuditLayout. Its structure is following:</p>
<pre><code>EVENT_PUBLISHING_TIME ROOT_REQUEST_ID|PARENT_REQUEST_ID|REQUEST_ID|LOGGER_NAME|TARGET_SERVICE_NAME|USER_NAME|PROXY_USER_NAME|SYSTEM_USER_NAME|ACTION|RESOURCE_TYPE|RESOURCE_NAME|OUTCOME|LOGGING_MESSAGE
</code></pre><p>The audit record format can be changed by setting <code>log4j.appender.auditfile.layout</code> property in <code>conf/gateway-log4j.properties</code> to another class that extends org.apache.log4j.Layout or its subclasses.</p><p>For detailed information read <a href="http://logging.apache.org/log4j/1.2/">Apache log4j</a>.</p><h5><a id="How+to+interpret+audit+log"></a>How to interpret audit log</h5>
<table>
Modified: knox/trunk/books/0.6.0/book_gateway-details.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.6.0/book_gateway-details.md?rev=1668419&r1=1668418&r2=1668419&view=diff
==============================================================================
--- knox/trunk/books/0.6.0/book_gateway-details.md (original)
+++ knox/trunk/books/0.6.0/book_gateway-details.md Sun Mar 22 17:44:17 2015
@@ -87,4 +87,5 @@ Their values can also be provided via th
<<config_ha.md>>
<<config_webappsec_provider.md>>
<<config_preauth_sso_provider.md>>
+<<config_mutual_authentication_ssl.md>>
<<config_audit.md>>
Added: knox/trunk/books/0.6.0/config_mutual_authentication_ssl.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.6.0/config_mutual_authentication_ssl.md?rev=1668419&view=auto
==============================================================================
--- knox/trunk/books/0.6.0/config_mutual_authentication_ssl.md (added)
+++ knox/trunk/books/0.6.0/config_mutual_authentication_ssl.md Sun Mar 22 17:44:17 2015
@@ -0,0 +1,39 @@
+<!---
+ 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.
+--->
+
+### Mutual Authentication with SSL ###
+
+To establish a stronger trust relationship between client and server, we provide mutual authentication with SSL via client certs. This is particularly useful in providing additional validation for Preauthenticated SSO with HTTP Headers. Rather than just ip address validation, connections will only be accepted by Knox from clients presenting trusted certificates.
+
+This behavior is configured for the entire gateway instance within the gateway-site.xml file. All topologies deployed within the gateway instance with mutual authentication enabled will require incoming connections to present trusted client certificates during the SSL handshake. Otherwise, connections will be refused.
+
+The following table describes the configuration elements related to mutual authentication and their defaults:
+
+| Configuration Element | Description |
+| -----------------------------------------------|-----------------------------------------------------------|
+| gateway.client.auth.needed | True\|False - indicating the need for client authentication. Default is False.|
+| gateway.truststore.path | Fully qualified path to the trust store to use. Default is the gateway.jks.|
+| gateway.truststore.type | Keystore type of the trust store. Default is JKS. |
+| gateway.trust.all.certs | Allows for all certificates to be trusted. Default is false.|
+
+By only indicating that it is needed with gateway.client.auth.needed, the {GATEWAY_HOME}/data/security/keystores/gateway.jks keystore is used. This is the identity keystore for the server and can also be used as the truststore.
+In addition, we can specify the path to a dedicated truststore via gateway.truststore.path. If the truststore password is different from the gateway master secret then it can be set using the
+
+ knoxcli.sh create-alias gateway-truststore-password --value {pwd}
+
+Otherwise, the master secret will be used.
+If the truststore is not a JKS type then it can be set via gateway.truststore.type.