knox-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lmc...@apache.org
Subject svn commit: r1768819 - in /knox: site/ site/books/knox-0-10-0/ trunk/books/0.10.0/
Date Wed, 09 Nov 2016 02:19:05 GMT
Author: lmccay
Date: Wed Nov  9 02:19:04 2016
New Revision: 1768819

URL: http://svn.apache.org/viewvc?rev=1768819&view=rev
Log:
added pam authentication docs

Added:
    knox/trunk/books/0.10.0/config_pam_authn.md
Modified:
    knox/site/books/knox-0-10-0/user-guide.html
    knox/site/index.html
    knox/site/issue-tracking.html
    knox/site/license.html
    knox/site/mail-lists.html
    knox/site/project-info.html
    knox/site/team-list.html
    knox/trunk/books/0.10.0/book.md
    knox/trunk/books/0.10.0/book_gateway-details.md

Modified: knox/site/books/knox-0-10-0/user-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-10-0/user-guide.html?rev=1768819&r1=1768818&r2=1768819&view=diff
==============================================================================
--- knox/site/books/knox-0-10-0/user-guide.html (original)
+++ knox/site/books/knox-0-10-0/user-guide.html Wed Nov  9 02:19:04 2016
@@ -34,7 +34,8 @@
     <li><a href="#Advanced+LDAP+Authentication">Advanced LDAP Authentication</a></li>
     <li><a href="#LDAP+Authentication+Caching">LDAP Authentication Caching</a></li>
     <li><a href="#LDAP+Group+Lookup">LDAP Group Lookup</a></li>
-    <li><a href="#Identity+Assertion">Identity Assertion</a></li>
+    <li><a href="#LDAP+Group+Lookup">LDAP Group Lookup</a></li>
+    <li><a href="#PAM+based+Authentication">PAM based Authentication</a></li>
     <li><a href="#Authorization">Authorization</a></li>
     <li><a href="#Secure+Clusters">Secure Clusters</a></li>
     <li><a href="#High+Availability">High Availability</a></li>
@@ -1625,7 +1626,52 @@ java -Dsandbox.ldcSystemPassword=guest-p
 <pre><code>curl  -i -v  -k -u guest:guest-password  -X GET https://localhost:8443/gateway/sandbox/webhdfs/v1?op=GETHOMEDIRECTORY
 </code></pre><p>Following call to WebHDFS should report: {&ldquo;Path&rdquo;:&ldquo;/user/bob&rdquo;}
As bob is a member of dynamic group &ldquo;directors&rdquo;, authorization provider
states user should be member of group &ldquo;directors&rdquo;</p>
 <pre><code>curl  -i -v  -k -u sam:sam-password  -X GET https://localhost:8443/gateway/sandbox/webhdfs/v1?op=GETHOMEDIRECTORY
-</code></pre><h3><a id="Identity+Assertion">Identity Assertion</a>
<a href="#Identity+Assertion"><img src="markbook-section-link.png"/></a></h3><p>The
identity assertion provider within Knox plays the critical role of communicating the identity
principal to be used within the Hadoop cluster to represent the identity that has been authenticated
at the gateway.</p><p>The general responsibilities of the identity assertion provider
is to interrogate the current Java Subject that has been established by the authentication
or federation provider and:</p>
+</code></pre><h3><a id="PAM+based+Authentication">PAM based Authentication</a>
<a href="#PAM+based+Authentication"><img src="markbook-section-link.png"/></a></h3><p>There
is a large number of pluggable authentication modules available on many linux installations
and from vendors of authentication solutions that are great to leverage for authenticating
access to Hadoop through the Knox Gateway. In addition to LDAP support described in this guide,
the ShiroProvider also includes support for PAM based authentication for unix based systems.</p><p>This
opens up the integration possibilities to many other readily available authentication mechanisms
as well as other implementations for LDAP based authentication. More flexibility may be available
through various PAM modules for group lookup, more complicated LDAP schemas or other areas
where the KnoxLdapRealm is not sufficient.</p><h4><a id="Configuration">Configuration</a>
<a href="#Configuration"><img src="markbook-section-link.png"/></a>
 </h4><h5><a id="Overview">Overview</a> <a href="#Overview"><img
src="markbook-section-link.png"/></a></h5><p>The primary motivation for
leveraging PAM based authentication is to provide the ability to use the configuration provided
by existing PAM modules that are available in a system&rsquo;s /etc/pam.d/ directory.
Therefore, the solution provided here is as simple as possible in order to allow the PAM module
config itself to be the source of truth. What we do need to configure is the fact that we
are using PAM through the main.pamRealm parameter and the KnoxPamRealm classname and the particular
PAM module to use with the main.pamRealm.service parameter in the below example we have &lsquo;login&rsquo;.</p>
+<pre><code>&lt;provider&gt; 
+   &lt;role&gt;authentication&lt;/role&gt; 
+   &lt;name&gt;ShiroProvider&lt;/name&gt; 
+   &lt;enabled&gt;true&lt;/enabled&gt; 
+   &lt;param&gt; 
+        &lt;name&gt;sessionTimeout&lt;/name&gt; 
+        &lt;value&gt;30&lt;/value&gt;
+    &lt;/param&gt;                                              
+    &lt;param&gt;
+        &lt;name&gt;main.pamRealm&lt;/name&gt; 
+        &lt;value&gt;org.apache.hadoop.gateway.shirorealm.KnoxPamRealm&lt;/value&gt;
+    &lt;/param&gt; 
+    &lt;param&gt;                                                    
+       &lt;name&gt;main.pamRealm.service&lt;/name&gt; 
+       &lt;value&gt;login&lt;/value&gt; &lt;/param&gt;
+    &lt;param&gt;                                                    
+       &lt;name&gt;urls./**&lt;/name&gt; 
+       &lt;value&gt;authcBasic&lt;/value&gt; 
+   &lt;/param&gt;
+&lt;/provider&gt;
+</code></pre><p>As a non-normative example of a PAM config file see the
below from my macbook /etc/pam.d/login:</p>
+<pre><code># login: auth account password session
+auth       optional       pam_krb5.so use_kcminit
+auth       optional       pam_ntlm.so try_first_pass
+auth       optional       pam_mount.so try_first_pass
+auth       required       pam_opendirectory.so try_first_pass
+account    required       pam_nologin.so
+account    required       pam_opendirectory.so
+password   required       pam_opendirectory.so
+session    required       pam_launchd.so
+session    required       pam_uwtmp.so
+session    optional       pam_mount.so
+</code></pre><p>The first four fields are: service-name, module-type, control-flag
and module-filename. The fifth and greater fields are for optional arguments that are specific
to the individual authentication modules.</p><p>The second field in the configuration
file is the module-type, it indicates which of the four PAM management services the corresponding
module will provide to the application. Our sample configuration file refers to all four groups:</p>
+<ul>
+  <li>auth: identifies the PAMs that are invoked when the application calls pam_authenticate()
and pam_setcred().</li>
+  <li>account: maps to the pam_acct_mgmt() function.</li>
+  <li>session: indicates the mapping for the pam_open_session() and pam_close_session()
calls.</li>
+  <li>password: group refers to the pam_chauthtok() function.</li>
+</ul><p>Generally, you only need to supply mappings for the functions that are
needed by a specific application. For example, the standard password changing application,
passwd, only requires a password group entry; any other entries are ignored.</p><p>The
third field indicates what action is to be taken based on the success or failure of the corresponding
module. Choices for tokens to fill this field are:</p>
+<ul>
+  <li>requisite: Failure instantly returns control to the application indicating the
nature of the first module failure.</li>
+  <li>required: All these modules are required to succeed for libpam to return success
to the application.</li>
+  <li>sufficient: Given that all preceding modules have succeeded, the success of this
module leads to an immediate and successful return to the application (failure of this module
is ignored).</li>
+  <li>optional: The success or failure of this module is generally not recorded.</li>
+</ul><p>The fourth field contains the name of the loadable module, pam_*.so.
For the sake of readability, the full pathname of each module is not given. Before Linux-PAM-0.56
was released, there was no support for a default authentication-module directory. If you have
an earlier version of Linux-PAM installed, you will have to specify the full path for each
of the modules. Your distribution most likely placed these modules exclusively in one of the
following directories: /lib/security/ or /usr/lib/security/.</p><h3><a id="Identity+Assertion">Identity
Assertion</a> <a href="#Identity+Assertion"><img src="markbook-section-link.png"/></a></h3><p>The
identity assertion provider within Knox plays the critical role of communicating the identity
principal to be used within the Hadoop cluster to represent the identity that has been authenticated
at the gateway.</p><p>The general responsibilities of the identity assertion provider
is to interrogate the current Java Subject that has been esta
 blished by the authentication or federation provider and:</p>
 <ol>
   <li>determine whether it matches any principal mapping rules and apply them appropriately</li>
   <li>determine whether it matches any group principal mapping rules and apply them</li>

Modified: knox/site/index.html
URL: http://svn.apache.org/viewvc/knox/site/index.html?rev=1768819&r1=1768818&r2=1768819&view=diff
==============================================================================
--- knox/site/index.html (original)
+++ knox/site/index.html Wed Nov  9 02:19:04 2016
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2016-11-07
+ | Generated by Apache Maven Doxia at 2016-11-08
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="Date-Revision-yyyymmdd" content="20161107" />
+    <meta name="Date-Revision-yyyymmdd" content="20161108" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Knox Gateway &#x2013; REST API Gateway for the Apache Hadoop Ecosystem</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
               
                 
                     
-                  <li id="publishDate" class="pull-right">Last Published: 2016-11-07</li>

+                  <li id="publishDate" class="pull-right">Last Published: 2016-11-08</li>

             
                             </ul>
       </div>

Modified: knox/site/issue-tracking.html
URL: http://svn.apache.org/viewvc/knox/site/issue-tracking.html?rev=1768819&r1=1768818&r2=1768819&view=diff
==============================================================================
--- knox/site/issue-tracking.html (original)
+++ knox/site/issue-tracking.html Wed Nov  9 02:19:04 2016
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2016-11-07
+ | Generated by Apache Maven Doxia at 2016-11-08
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="Date-Revision-yyyymmdd" content="20161107" />
+    <meta name="Date-Revision-yyyymmdd" content="20161108" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Knox Gateway &#x2013; Issue Tracking</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
               
                 
                     
-                  <li id="publishDate" class="pull-right">Last Published: 2016-11-07</li>

+                  <li id="publishDate" class="pull-right">Last Published: 2016-11-08</li>

             
                             </ul>
       </div>

Modified: knox/site/license.html
URL: http://svn.apache.org/viewvc/knox/site/license.html?rev=1768819&r1=1768818&r2=1768819&view=diff
==============================================================================
--- knox/site/license.html (original)
+++ knox/site/license.html Wed Nov  9 02:19:04 2016
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2016-11-07
+ | Generated by Apache Maven Doxia at 2016-11-08
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="Date-Revision-yyyymmdd" content="20161107" />
+    <meta name="Date-Revision-yyyymmdd" content="20161108" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Knox Gateway &#x2013; Project License</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
               
                 
                     
-                  <li id="publishDate" class="pull-right">Last Published: 2016-11-07</li>

+                  <li id="publishDate" class="pull-right">Last Published: 2016-11-08</li>

             
                             </ul>
       </div>

Modified: knox/site/mail-lists.html
URL: http://svn.apache.org/viewvc/knox/site/mail-lists.html?rev=1768819&r1=1768818&r2=1768819&view=diff
==============================================================================
--- knox/site/mail-lists.html (original)
+++ knox/site/mail-lists.html Wed Nov  9 02:19:04 2016
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2016-11-07
+ | Generated by Apache Maven Doxia at 2016-11-08
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="Date-Revision-yyyymmdd" content="20161107" />
+    <meta name="Date-Revision-yyyymmdd" content="20161108" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Knox Gateway &#x2013; Project Mailing Lists</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
               
                 
                     
-                  <li id="publishDate" class="pull-right">Last Published: 2016-11-07</li>

+                  <li id="publishDate" class="pull-right">Last Published: 2016-11-08</li>

             
                             </ul>
       </div>

Modified: knox/site/project-info.html
URL: http://svn.apache.org/viewvc/knox/site/project-info.html?rev=1768819&r1=1768818&r2=1768819&view=diff
==============================================================================
--- knox/site/project-info.html (original)
+++ knox/site/project-info.html Wed Nov  9 02:19:04 2016
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2016-11-07
+ | Generated by Apache Maven Doxia at 2016-11-08
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="Date-Revision-yyyymmdd" content="20161107" />
+    <meta name="Date-Revision-yyyymmdd" content="20161108" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Knox Gateway &#x2013; Project Information</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
               
                 
                     
-                  <li id="publishDate" class="pull-right">Last Published: 2016-11-07</li>

+                  <li id="publishDate" class="pull-right">Last Published: 2016-11-08</li>

             
                             </ul>
       </div>

Modified: knox/site/team-list.html
URL: http://svn.apache.org/viewvc/knox/site/team-list.html?rev=1768819&r1=1768818&r2=1768819&view=diff
==============================================================================
--- knox/site/team-list.html (original)
+++ knox/site/team-list.html Wed Nov  9 02:19:04 2016
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2016-11-07
+ | Generated by Apache Maven Doxia at 2016-11-08
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="Date-Revision-yyyymmdd" content="20161107" />
+    <meta name="Date-Revision-yyyymmdd" content="20161108" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Knox Gateway &#x2013; Team list</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
               
                 
                     
-                  <li id="publishDate" class="pull-right">Last Published: 2016-11-07</li>

+                  <li id="publishDate" class="pull-right">Last Published: 2016-11-08</li>

             
                             </ul>
       </div>

Modified: knox/trunk/books/0.10.0/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/book.md?rev=1768819&r1=1768818&r2=1768819&view=diff
==============================================================================
--- knox/trunk/books/0.10.0/book.md (original)
+++ knox/trunk/books/0.10.0/book.md Wed Nov  9 02:19:04 2016
@@ -41,7 +41,8 @@
     * #[Advanced LDAP Authentication]
     * #[LDAP Authentication Caching]
     * #[LDAP Group Lookup]
-    * #[Identity Assertion]
+    * #[LDAP Group Lookup]
+    * #[PAM based Authentication]
     * #[Authorization]
     * #[Secure Clusters]
     * #[High Availability]

Modified: knox/trunk/books/0.10.0/book_gateway-details.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/book_gateway-details.md?rev=1768819&r1=1768818&r2=1768819&view=diff
==============================================================================
--- knox/trunk/books/0.10.0/book_gateway-details.md (original)
+++ knox/trunk/books/0.10.0/book_gateway-details.md Wed Nov  9 02:19:04 2016
@@ -86,6 +86,7 @@ In the Hortonworks Sandbox Ambari might
 <<config_advanced_ldap.md>>
 <<config_ldap_authc_cache.md>>
 <<config_ldap_group_lookup.md>>
+<<config_pam_authn.md>>
 <<config_id_assertion.md>>
 <<config_authz.md>>
 <<config_kerberos.md>>

Added: knox/trunk/books/0.10.0/config_pam_authn.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/config_pam_authn.md?rev=1768819&view=auto
==============================================================================
--- knox/trunk/books/0.10.0/config_pam_authn.md (added)
+++ knox/trunk/books/0.10.0/config_pam_authn.md Wed Nov  9 02:19:04 2016
@@ -0,0 +1,82 @@
+<!---
+   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.
+--->
+
+### PAM based Authentication ###
+
+There is a large number of pluggable authentication modules available on many linux installations
and from vendors of authentication solutions that are great to leverage for authenticating
access to Hadoop through the Knox Gateway. In addition to LDAP support described in this guide,
the ShiroProvider also includes support for PAM based authentication for unix based systems.
+
+This opens up the integration possibilities to many other readily available authentication
mechanisms as well as other implementations for LDAP based authentication. More flexibility
may be available through various PAM modules for group lookup, more complicated LDAP schemas
or other areas where the KnoxLdapRealm is not sufficient.
+
+#### Configuration ####
+##### Overview #####
+The primary motivation for leveraging PAM based authentication is to provide the ability
to use the configuration provided by existing PAM modules that are available in a system's
/etc/pam.d/ directory. Therefore, the solution provided here is as simple as possible in order
to allow the PAM module config itself to be the source of truth. What we do need to configure
is the fact that we are using PAM through the main.pamRealm parameter and the KnoxPamRealm
classname and the particular PAM module to use with the main.pamRealm.service parameter in
the below example we have 'login'.
+
+    <provider> 
+       <role>authentication</role> 
+       <name>ShiroProvider</name> 
+       <enabled>true</enabled> 
+       <param> 
+            <name>sessionTimeout</name> 
+            <value>30</value>
+        </param>                                              
+        <param>
+            <name>main.pamRealm</name> 
+            <value>org.apache.hadoop.gateway.shirorealm.KnoxPamRealm</value>
+        </param> 
+        <param>                                                    
+           <name>main.pamRealm.service</name> 
+           <value>login</value> </param>
+        <param>                                                    
+           <name>urls./**</name> 
+           <value>authcBasic</value> 
+       </param>
+    </provider>
+  
+
+As a non-normative example of a PAM config file see the below from my macbook /etc/pam.d/login:
+
+    # login: auth account password session
+    auth       optional       pam_krb5.so use_kcminit
+    auth       optional       pam_ntlm.so try_first_pass
+    auth       optional       pam_mount.so try_first_pass
+    auth       required       pam_opendirectory.so try_first_pass
+    account    required       pam_nologin.so
+    account    required       pam_opendirectory.so
+    password   required       pam_opendirectory.so
+    session    required       pam_launchd.so
+    session    required       pam_uwtmp.so
+    session    optional       pam_mount.so
+
+The first four fields are: service-name, module-type, control-flag and module-filename. The
fifth and greater fields are for optional arguments that are specific to the individual authentication
modules.
+
+The second field in the configuration file is the module-type, it indicates which of the
four PAM management services the corresponding module will provide to the application. Our
sample configuration file refers to all four groups:
+
+* auth: identifies the PAMs that are invoked when the application calls pam_authenticate()
and pam_setcred().
+* account: maps to the pam_acct_mgmt() function.
+* session: indicates the mapping for the pam_open_session() and pam_close_session() calls.
+* password: group refers to the pam_chauthtok() function.
+
+Generally, you only need to supply mappings for the functions that are needed by a specific
application. For example, the standard password changing application, passwd, only requires
a password group entry; any other entries are ignored.
+
+The third field indicates what action is to be taken based on the success or failure of the
corresponding module. Choices for tokens to fill this field are:
+
+* requisite: Failure instantly returns control to the application indicating the nature of
the first module failure.
+* required: All these modules are required to succeed for libpam to return success to the
application.
+* sufficient: Given that all preceding modules have succeeded, the success of this module
leads to an immediate and successful return to the application (failure of this module is
ignored).
+* optional: The success or failure of this module is generally not recorded.
+
+The fourth field contains the name of the loadable module, pam_*.so. For the sake of readability,
the full pathname of each module is not given. Before Linux-PAM-0.56 was released, there was
no support for a default authentication-module directory. If you have an earlier version of
Linux-PAM installed, you will have to specify the full path for each of the modules. Your
distribution most likely placed these modules exclusively in one of the following directories:
/lib/security/ or /usr/lib/security/.
\ No newline at end of file



Mime
View raw message