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 2016/11/09 02:19:05 UTC
svn commit: r1768819 - in /knox: site/ site/books/knox-0-10-0/
trunk/books/0.10.0/
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: {“Path”:“/user/bob”} As bob is a member of dynamic group “directors”, authorization provider states user should be member of group “directors”</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’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’.</p>
+<pre><code><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>
+</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 – 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 – 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 – 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 – 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 – 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 – 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