knox-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lmc...@apache.org
Subject svn commit: r1628250 - in /knox: site/ site/books/knox-0-5-0/ trunk/books/0.5.0/
Date Mon, 29 Sep 2014 18:37:00 GMT
Author: lmccay
Date: Mon Sep 29 18:36:59 2014
New Revision: 1628250

URL: http://svn.apache.org/r1628250
Log:
KNOX-388 - advanced ldap config and limitations clean up.

Added:
    knox/trunk/books/0.5.0/config_advanced_ldap.md
Modified:
    knox/site/books/knox-0-5-0/knox-0-5-0.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.5.0/book.md
    knox/trunk/books/0.5.0/book_gateway-details.md
    knox/trunk/books/0.5.0/book_limitations.md
    knox/trunk/books/0.5.0/config_authn.md

Modified: knox/site/books/knox-0-5-0/knox-0-5-0.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-5-0/knox-0-5-0.html?rev=1628250&r1=1628249&r2=1628250&view=diff
==============================================================================
--- knox/site/books/knox-0-5-0/knox-0-5-0.html (original)
+++ knox/site/books/knox-0-5-0/knox-0-5-0.html Mon Sep 29 18:36:59 2014
@@ -29,6 +29,7 @@
     <li><a href="#Knox+CLI">Knox CLI</a></li>
     <li><a href="#Admin+API">Admin API</a></li>
     <li><a href="#Authentication">Authentication</a></li>
+    <li><a href="#Advanced+LDAP+Authentication">Advanced LDAP Authentication</a></li>
     <li><a href="#LDAPGroupLookup">LDAPGroupLookup</a></li>
     <li><a href="#Identity+Assertion">Identity Assertion</a></li>
     <li><a href="#Authorization">Authorization</a></li>
@@ -672,7 +673,158 @@ ldapRealm.userDnTemplate=uid={0},ou=peop
     &lt;/param&gt;
 &lt;provider&gt;
 ...
-</code></pre><p>At present, ShiroProvider in Knox leverages JavaEE session
to maintain authentication state for a user across requests using JSESSIONID cookie. So, a
clieent that authenticated with Knox could pass the JSESSIONID cookie with repeated requests
as long as the session has not timed out instead of submitting userid/password with every
request. Presenting a valid session cookie in place of userid/password would also perform
better as additional credential store lookups are avoided.</p><h3><a id="LDAPGroupLookup"></a>LDAPGroupLookup</h3><p>Knox
can be configured to look up LDAP groups that the authenticated user belong to. Knox can look
up both Static LDAP Groups and Dynamic LDAP Groups. The looked up groups are populated as
Principal(s) in the Java Subject of authenticated user. Therefore service authorization rules
can be defined in terms of LDAPGroups looked up from LDAP directory.</p><p>To
look up LDAPGroups of autheticated user from LDAP, you have to use org.apache.ha
 doop.gateway.shirorealm.KnoxLdapRealm in Shiro configuration.</p><p>Please see
below a sample Shiro configuration snippet from a topology file that was tested looking LDAPGroups.</p>
+</code></pre><p>At present, ShiroProvider in Knox leverages JavaEE session
to maintain authentication state for a user across requests using JSESSIONID cookie. So, a
client that authenticated with Knox could pass the JSESSIONID cookie with repeated requests
as long as the session has not timed out instead of submitting userid/password with every
request. Presenting a valid session cookie in place of userid/password would also perform
better as additional credential store lookups are avoided.</p><h3><a id="Advanced+LDAP+Authentication"></a>Advanced
LDAP Authentication</h3><p>The default configuration computes the bind DN for
incoming user based on userDnTemplate. This does not work in enterprises where users could
belong to multiple branches of LDAP tree. You could instead enable advanced configuration
that would compute bind DN of incoming user with an LDAP search.</p><h4><a
id="Problem+with++userDnTemplate+based+Authentication"></a>Problem with userDnTemplate
based Authentication</
 h4><p>UserDnTemplate based authentication uses configuration parameter ldapRealm.userDnTemplate.
Typical value of userDNTemplate would look like uid={0},ou=people,dc=hadoop,dc=apache,dc=org.</p><p>To
compute bind DN of the client, we swap the place holder {0} with login id provided by the
client. For example, if the login id provided by the client is &quot;guest&rsquo;,<br/>the
computed bind DN would be uid=guest,ou=people,dc=hadoop,dc=apache,dc=org.</p><p>This
keeps configuration simple.</p><p>However, this does not work if users belong
to different branches of LDAP DIT. For example, if there are some users under ou=people,dc=hadoop,dc=apache,dc=org
and some users under ou=contractors,dc=hadoop,dc=apache,dc=org,<br/>we can not come
up with userDnTemplate that would work for all the users.</p><h4><a id="Using+advanced+LDAP+Authentication"></a>Using
advanced LDAP Authentication</h4><p>With advanced LDAP authentication, we find
the bind DN of the user by searching LDAP directory inste
 ad of interpolating bind DN from userDNTemplate. </p><h4><a id="Example+search+filter+to+find+the+client+bind+DN"></a>Example
search filter to find the client bind DN</h4><p>Assuming,<br/>ldapRealm.userSearchAttributeName=uid
ldapRealm.userObjectClass=person client specified login id = &ldquo;guest&rdquo;</p><p>LDAP
Filter for doing a search to find the bind DN would be (&amp;(uid=guest)(objectclass=person))</p><p>This
could find bind DN to be uid=guest,ou=people,dc=hadoop,dc=apache,dc=org</p><p>Please
note that the userSearchAttributeName need not be part of bindDN.</p><p>For example,
you could use </p><p>ldapRealm.userSearchAttributeName=email ldapRealm.userObjectClass=person
client specified login id = &ldquo;<a href="mailto:&#98;i&#108;&#x6c;&#x2e;&#x63;&#x6c;&#105;&#x6e;&#x74;o&#110;&#x40;&#103;m&#97;&#105;&#108;.&#99;o&#x6d;">&#98;i&#108;&#x6c;&#x2e;&#x63;&#x6c;&#105;&#x6e;&#x74;o&#110;&#x40;&#103;m&#97;&#105;&#108;.&#99;o&#x6d;</a>&rdquo;</p><p>LDAP
Filter for doing a search 
 to find the bind DN would be (&amp;(email=bill<a href="mailto:&#46;&#x63;&#x6c;&#105;&#110;t&#x6f;&#x6e;@&#103;&#x6d;&#x61;&#105;&#108;&#46;&#99;&#111;&#x6d;&#x29;&#40;&#111;&#98;&#106;&#x65;&#99;&#116;&#99;&#x6c;&#97;&#115;&#x73;&#61;&#x70;&#x65;&#x72;&#x73;&#111;&#x6e;&#41;">&#46;&#x63;&#x6c;&#105;&#110;t&#x6f;&#x6e;@&#103;&#x6d;&#x61;&#105;&#108;&#46;&#99;&#111;&#x6d;&#x29;&#40;&#111;&#98;&#106;&#x65;&#99;&#116;&#99;&#x6c;&#97;&#115;&#x73;&#61;&#x70;&#x65;&#x72;&#x73;&#111;&#x6e;&#41;</a>)</p><p>This
could find bind DN to be uid=billc,ou=contractors,dc=hadoop,dc=apache,dc=org</p><h4><a
id="Example+provider+configuration+to+use+advanced+LDAP+authentication"></a>Example
provider configuration to use advanced LDAP authentication</h4><p>The example
configuration appears verbose due to the presence of liberal comments and illustration of
optional parameters and default values. The configuration that you would use could be much
shorter if you rely on default values.</p><p><provider></p
 >
+<pre><code>&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;main.ldapRealm&lt;/name&gt;
+    &lt;value&gt;org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;param&gt;
+    &lt;name&gt;main.ldapContextFactory&lt;/name&gt;
+    &lt;value&gt;org.apache.hadoop.gateway.shirorealm.KnoxLdapContextFactory
+    &lt;/value&gt;
+&lt;/param&gt;
+
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.contextFactory&lt;/name&gt;
+    &lt;value&gt;$ldapContextFactory&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- update the value based on your ldap directory protocol, host and port --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.contextFactory.url&lt;/name&gt;
+    &lt;value&gt;ldap://hdp.example.com:389&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- optional, default value: simple
+     Update the value based on mechanisms supported by your ldap directory --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.contextFactory.authenticationMechanism&lt;/name&gt;
+    &lt;value&gt;simple&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- optional, default value: {0}
+   update the value based on your ldap DIT(directory information tree).
+   ignored if value is defined for main.ldapRealm.userSearchAttributeName --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.userDnTemplate&lt;/name&gt;
+    &lt;value&gt;uid={0},ou=people,dc=hadoop,dc=apache,dc=org&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- optional, default value: null
+     If you specify a value for this attribute, useDnTemplate 
+       specified above would be ignored and user bind DN would be computed using
+       ldap search
+     update the value based on your ldap DIT(directory information layout)
+     value of search attribute should identity the user uniquely --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.userSearchAttributeName&lt;/name&gt;
+    &lt;value&gt;uid&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- optional, default value: false  
+     If the value is true, groups in which user is a member are looked up 
+     from LDAP and made available  for service level authorization checks --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.authorizationEnabled&lt;/name&gt;
+    &lt;value&gt;true&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- bind DN used to search for groups and user bind DN.  
+     Required if a value is defined for main.ldapRealm.userSearchAttributeName
+     or if the value of main.ldapRealm.authorizationEnabled is true --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.contextFactory.systemUsername&lt;/name&gt;
+    &lt;value&gt;uid=guest,ou=people,dc=hadoop,dc=apache,dc=org&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- password for systemUserName.
+     Required if a value is defined for main.ldapRealm.userSearchAttributeName
+   or if the value of main.ldapRealm.authorizationEnabled is true --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.contextFactory.systemPassword&lt;/name&gt;
+    &lt;value&gt;${ALIAS=ldcSystemPassword}&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- optional, default value: simple
+     Update the value based on mechanisms supported by your ldap directory --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.contextFactory.systemAuthenticationMechanism&lt;/name&gt;
+    &lt;value&gt;simple&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- optional, default value: person
+     Objectclass to identify user entries in ldap, used to build search 
+       filter to search for user bind DN --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.userObjectClass&lt;/name&gt;
+    &lt;value&gt;person&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- search base used to search for user bind DN and groups --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.searchBase&lt;/name&gt;
+    &lt;value&gt;dc=hadoop,dc=apache,dc=org&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- search base used to search for user bind DN.
+     Defaults to the value of main.ldapRealm.searchBase. 
+     If main.ldapRealm.userSearchAttributeName is defined, 
+     vlaue for main.ldapRealm.searchBase  or main.ldapRealm.userSearchBase 
+     should be defined --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.userSearchBase&lt;/name&gt;
+    &lt;value&gt;dc=hadoop,dc=apache,dc=org&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- search base used to search for groups.
+     Defaults to the value of main.ldapRealm.searchBase.
+       If value of main.ldapRealm.authorizationEnabled is true,
+     vlaue for main.ldapRealm.searchBase  or main.ldapRealm.groupSearchBase should be defined
--&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.groupSearchBase&lt;/name&gt;
+    &lt;value&gt;dc=hadoop,dc=apache,dc=org&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- optional, default value: groupOfNames
+     Objectclass to identify group entries in ldap, used to build search 
+   filter to search for group entires --&gt; 
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.groupObjectClass&lt;/name&gt;
+    &lt;value&gt;groupOfNames&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- optional, default value: member
+     If value is memberUrl, we treat found groups as dynamic groups --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.memberAttribute&lt;/name&gt;
+    &lt;value&gt;member&lt;/value&gt;
+&lt;/param&gt;
+
+&lt;!-- optional, default value: uid={0}
+   Ignored if value is defined for main.ldapRealm.userSearchAttributeName --&gt;
+</code></pre><p><param>  <name>main.ldapRealm.memberAttributeValueTemplate</name>
 <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>  </param></p>
+<pre><code>&lt;!-- optional, default value: cn --&gt;
+&lt;param&gt;
+    &lt;name&gt;main.ldapRealm.groupIdAttribute&lt;/name&gt;
+    &lt;value&gt;cn&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;!-- optional, default value: 30min --&gt;
+&lt;param&gt;
+    &lt;name&gt;sessionTimeout&lt;/name&gt;
+    &lt;value&gt;30&lt;/value&gt;
+&lt;/param&gt;
+</code></pre><p></provider></p><h4><a id="Special+note+on+parameter+main.ldapRealm.contextFactory.systemPassword"></a>Special
note on parameter main.ldapRealm.contextFactory.systemPassword</h4><p>The value
for this could have one of the following 2 formats</p><p>plantextpassword ${ALIAS=ldcSystemPassword}</p><p>The
first format specifies the password in plain text in the provider configuration. Use of this
format should be limited for testing and troubleshooting.</p><p>We strongly recommend
using the second format ${ALIAS=ldcSystemPassword} n production. This format uses an alias
for the password stored in credential store. In the example ${ALIAS=ldcSystemPassword}, ldcSystemPassword
is the alias for the password stored in credential store.</p><p>Assuming plain
text password is &ldquo;hadoop&rdquo;, and your topology file name is &ldquo;hdp.xml&rdquo;,
you would use following command to create the right password alias in credential store.</p><p>$gateway_home/bin/knoxcli.sh
create-al
 ias ldcSystemPassword &ndash;cluster hdp &ndash;value hadoop</p><h3><a
id="LDAPGroupLookup"></a>LDAPGroupLookup</h3><p>Knox can be configured
to look up LDAP groups that the authenticated user belong to. Knox can look up both Static
LDAP Groups and Dynamic LDAP Groups. The looked up groups are populated as Principal(s) in
the Java Subject of authenticated user. Therefore service authorization rules can be defined
in terms of LDAPGroups looked up from LDAP directory.</p><p>To look up LDAPGroups
of autheticated user from LDAP, you have to use org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm
in Shiro configuration.</p><p>Please see below a sample Shiro configuration snippet
from a topology file that was tested looking LDAPGroups.</p>
 <pre><code>    &lt;provider&gt;
         &lt;role&gt;authentication&lt;/role&gt;
         &lt;name&gt;ShiroProvider&lt;/name&gt;

Modified: knox/site/index.html
URL: http://svn.apache.org/viewvc/knox/site/index.html?rev=1628250&r1=1628249&r2=1628250&view=diff
==============================================================================
--- knox/site/index.html (original)
+++ knox/site/index.html Mon Sep 29 18:36:59 2014
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2014-09-25 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2014-09-29 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
@@ -10,7 +10,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20140925" />
+    <meta name="Date-Revision-yyyymmdd" content="20140929" />
     <meta http-equiv="Content-Language" content="en" />
                                                     
 <script type="text/javascript">var _gaq = _gaq || [];
@@ -57,7 +57,7 @@
                         <a href="https://cwiki.apache.org/confluence/display/KNOX/Index"
class="externalLink" title="Wiki">Wiki</a>
               
                     
-                &nbsp;| <span id="publishDate">Last Published: 2014-09-25</span>
+                &nbsp;| <span id="publishDate">Last Published: 2014-09-29</span>
               &nbsp;| <span id="projectVersion">Version: 0.0.0-SNAPSHOT</span>
             </div>
       <div class="clear">

Modified: knox/site/issue-tracking.html
URL: http://svn.apache.org/viewvc/knox/site/issue-tracking.html?rev=1628250&r1=1628249&r2=1628250&view=diff
==============================================================================
--- knox/site/issue-tracking.html (original)
+++ knox/site/issue-tracking.html Mon Sep 29 18:36:59 2014
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2014-09-25 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2014-09-29 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
@@ -10,7 +10,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20140925" />
+    <meta name="Date-Revision-yyyymmdd" content="20140929" />
     <meta http-equiv="Content-Language" content="en" />
                                                     
 <script type="text/javascript">var _gaq = _gaq || [];
@@ -57,7 +57,7 @@
                         <a href="https://cwiki.apache.org/confluence/display/KNOX/Index"
class="externalLink" title="Wiki">Wiki</a>
               
                     
-                &nbsp;| <span id="publishDate">Last Published: 2014-09-25</span>
+                &nbsp;| <span id="publishDate">Last Published: 2014-09-29</span>
               &nbsp;| <span id="projectVersion">Version: 0.0.0-SNAPSHOT</span>
             </div>
       <div class="clear">

Modified: knox/site/license.html
URL: http://svn.apache.org/viewvc/knox/site/license.html?rev=1628250&r1=1628249&r2=1628250&view=diff
==============================================================================
--- knox/site/license.html (original)
+++ knox/site/license.html Mon Sep 29 18:36:59 2014
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2014-09-25 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2014-09-29 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
@@ -10,7 +10,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20140925" />
+    <meta name="Date-Revision-yyyymmdd" content="20140929" />
     <meta http-equiv="Content-Language" content="en" />
                                                     
 <script type="text/javascript">var _gaq = _gaq || [];
@@ -57,7 +57,7 @@
                         <a href="https://cwiki.apache.org/confluence/display/KNOX/Index"
class="externalLink" title="Wiki">Wiki</a>
               
                     
-                &nbsp;| <span id="publishDate">Last Published: 2014-09-25</span>
+                &nbsp;| <span id="publishDate">Last Published: 2014-09-29</span>
               &nbsp;| <span id="projectVersion">Version: 0.0.0-SNAPSHOT</span>
             </div>
       <div class="clear">

Modified: knox/site/mail-lists.html
URL: http://svn.apache.org/viewvc/knox/site/mail-lists.html?rev=1628250&r1=1628249&r2=1628250&view=diff
==============================================================================
--- knox/site/mail-lists.html (original)
+++ knox/site/mail-lists.html Mon Sep 29 18:36:59 2014
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2014-09-25 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2014-09-29 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
@@ -10,7 +10,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20140925" />
+    <meta name="Date-Revision-yyyymmdd" content="20140929" />
     <meta http-equiv="Content-Language" content="en" />
                                                     
 <script type="text/javascript">var _gaq = _gaq || [];
@@ -57,7 +57,7 @@
                         <a href="https://cwiki.apache.org/confluence/display/KNOX/Index"
class="externalLink" title="Wiki">Wiki</a>
               
                     
-                &nbsp;| <span id="publishDate">Last Published: 2014-09-25</span>
+                &nbsp;| <span id="publishDate">Last Published: 2014-09-29</span>
               &nbsp;| <span id="projectVersion">Version: 0.0.0-SNAPSHOT</span>
             </div>
       <div class="clear">

Modified: knox/site/project-info.html
URL: http://svn.apache.org/viewvc/knox/site/project-info.html?rev=1628250&r1=1628249&r2=1628250&view=diff
==============================================================================
--- knox/site/project-info.html (original)
+++ knox/site/project-info.html Mon Sep 29 18:36:59 2014
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2014-09-25 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2014-09-29 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
@@ -10,7 +10,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20140925" />
+    <meta name="Date-Revision-yyyymmdd" content="20140929" />
     <meta http-equiv="Content-Language" content="en" />
                                                     
 <script type="text/javascript">var _gaq = _gaq || [];
@@ -57,7 +57,7 @@
                         <a href="https://cwiki.apache.org/confluence/display/KNOX/Index"
class="externalLink" title="Wiki">Wiki</a>
               
                     
-                &nbsp;| <span id="publishDate">Last Published: 2014-09-25</span>
+                &nbsp;| <span id="publishDate">Last Published: 2014-09-29</span>
               &nbsp;| <span id="projectVersion">Version: 0.0.0-SNAPSHOT</span>
             </div>
       <div class="clear">

Modified: knox/site/team-list.html
URL: http://svn.apache.org/viewvc/knox/site/team-list.html?rev=1628250&r1=1628249&r2=1628250&view=diff
==============================================================================
--- knox/site/team-list.html (original)
+++ knox/site/team-list.html Mon Sep 29 18:36:59 2014
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2014-09-25 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 2014-09-29 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
@@ -10,7 +10,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20140925" />
+    <meta name="Date-Revision-yyyymmdd" content="20140929" />
     <meta http-equiv="Content-Language" content="en" />
                                                     
 <script type="text/javascript">var _gaq = _gaq || [];
@@ -57,7 +57,7 @@
                         <a href="https://cwiki.apache.org/confluence/display/KNOX/Index"
class="externalLink" title="Wiki">Wiki</a>
               
                     
-                &nbsp;| <span id="publishDate">Last Published: 2014-09-25</span>
+                &nbsp;| <span id="publishDate">Last Published: 2014-09-29</span>
               &nbsp;| <span id="projectVersion">Version: 0.0.0-SNAPSHOT</span>
             </div>
       <div class="clear">

Modified: knox/trunk/books/0.5.0/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.5.0/book.md?rev=1628250&r1=1628249&r2=1628250&view=diff
==============================================================================
--- knox/trunk/books/0.5.0/book.md (original)
+++ knox/trunk/books/0.5.0/book.md Mon Sep 29 18:36:59 2014
@@ -36,6 +36,7 @@
     * #[Knox CLI]
     * #[Admin API]
     * #[Authentication]
+    * #[Advanced LDAP Authentication]
     * #[LDAPGroupLookup]
     * #[Identity Assertion]
     * #[Authorization]

Modified: knox/trunk/books/0.5.0/book_gateway-details.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.5.0/book_gateway-details.md?rev=1628250&r1=1628249&r2=1628250&view=diff
==============================================================================
--- knox/trunk/books/0.5.0/book_gateway-details.md (original)
+++ knox/trunk/books/0.5.0/book_gateway-details.md Mon Sep 29 18:36:59 2014
@@ -79,6 +79,7 @@ Their values can also be provided via th
 <<knox_cli.md>>
 <<admin_api.md>>
 <<config_authn.md>>
+<<config_advanced_ldap.md>>
 <<config_ldap_group_lookup.md>>
 <<config_id_assertion.md>>
 <<config_authz.md>>

Modified: knox/trunk/books/0.5.0/book_limitations.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.5.0/book_limitations.md?rev=1628250&r1=1628249&r2=1628250&view=diff
==============================================================================
--- knox/trunk/books/0.5.0/book_limitations.md (original)
+++ knox/trunk/books/0.5.0/book_limitations.md Mon Sep 29 18:36:59 2014
@@ -20,22 +20,15 @@
 
 ### Secure Oozie POST/PUT Request Payload Size Restriction ###
 
-With one exception there are no know size limits for requests or responses payloads that
pass through the gateway.
+With one exception there are no known size limits for requests or responses payloads that
pass through the gateway.
 The exception involves POST or PUT request payload sizes for Oozie in a Kerberos secured
Hadoop cluster.
 In this one case there is currently a 4Kb payload size limit for the first request made to
the Hadoop cluster.
 This is a result of how the gateway negotiates a trust relationship between itself and the
cluster via SPNego.
 There is an undocumented configuration setting to modify this limit's value if required.
 In the future this will be made more easily configuration and at that time it will be documented.
 
-
-### LDAP Groups Acquisition from AD ###
-
-The LDAP authenticator currently does not "out of the box" support the acquisition of group
information from Microsoft Active Directory.
-Building this into the default implementation is on the roadmap.
-
-
 ### Group Membership Propagation ###
 
 Groups that are acquired via Shiro Group Lookup and/or Identity Assertion Group Principal
Mapping are not propagated to the Hadoop services.
-Therefore groups used for Service Level Authorization policy may not match those acquired
within the cluster via GroupMappingServiceProvider plugins.
+Therefore, groups used for Service Level Authorization policy may not match those acquired
within the cluster via GroupMappingServiceProvider plugins.
 

Added: knox/trunk/books/0.5.0/config_advanced_ldap.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.5.0/config_advanced_ldap.md?rev=1628250&view=auto
==============================================================================
--- knox/trunk/books/0.5.0/config_advanced_ldap.md (added)
+++ knox/trunk/books/0.5.0/config_advanced_ldap.md Mon Sep 29 18:36:59 2014
@@ -0,0 +1,243 @@
+### Advanced LDAP Authentication
+
+The default configuration computes the bind DN for incoming user based on userDnTemplate.
+This does not work in enterprises where users could belong to multiple branches of LDAP tree.
+You could instead enable advanced configuration that would compute bind DN of incoming user
with an LDAP search.
+
+#### Problem with  userDnTemplate based Authentication 
+
+UserDnTemplate based authentication uses configuration parameter ldapRealm.userDnTemplate.
+Typical value of userDNTemplate would look like uid={0},ou=people,dc=hadoop,dc=apache,dc=org.
+ 
+To compute bind DN of the client, we swap the place holder {0} with login id provided by
the client.
+For example, if the login id provided by the client is  "guest',  
+the computed bind DN would be uid=guest,ou=people,dc=hadoop,dc=apache,dc=org.
+ 
+This keeps configuration simple.
+
+However, this does not work if users belong to different branches of LDAP DIT.
+For example, if there are some users under ou=people,dc=hadoop,dc=apache,dc=org 
+and some users under ou=contractors,dc=hadoop,dc=apache,dc=org,  
+we can not come up with userDnTemplate that would work for all the users.
+
+#### Using advanced LDAP Authentication
+
+With advanced LDAP authentication, we find the bind DN of the user by searching LDAP directory
+instead of interpolating bind DN from userDNTemplate. 
+
+
+#### Example search filter to find the client bind DN
+ 
+Assuming,  
+ldapRealm.userSearchAttributeName=uid
+ldapRealm.userObjectClass=person
+client  specified login id =  "guest"
+ 
+LDAP Filter for doing a search to find the bind DN would be
+(&(uid=guest)(objectclass=person))
+
+This could find bind DN to be 
+uid=guest,ou=people,dc=hadoop,dc=apache,dc=org
+
+Please note that the userSearchAttributeName need not be part of bindDN.
+
+For example, you could use 
+
+ldapRealm.userSearchAttributeName=email
+ldapRealm.userObjectClass=person
+client  specified login id =  "bill.clinton@gmail.com"
+
+LDAP Filter for doing a search to find the bind DN would be
+(&(email=bill.clinton@gmail.com)(objectclass=person))
+
+This could find bind DN to be 
+uid=billc,ou=contractors,dc=hadoop,dc=apache,dc=org
+
+#### Example provider configuration to use advanced LDAP authentication
+
+The example configuration appears verbose due to the presence of liberal comments 
+and illustration of optional parameters and default values.
+The configuration that you would use could be much shorter if you rely on default values.
+
+<provider>
+
+	<role>authentication</role>
+	<name>ShiroProvider</name>
+	<enabled>true</enabled>
+
+	<param>
+		<name>main.ldapRealm</name>
+		<value>org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm</value>
+	</param>
+
+	<param>
+		<name>main.ldapContextFactory</name>
+		<value>org.apache.hadoop.gateway.shirorealm.KnoxLdapContextFactory
+		</value>
+	</param>
+
+	<param>
+		<name>main.ldapRealm.contextFactory</name>
+		<value>$ldapContextFactory</value>
+	</param>
+
+	<!-- update the value based on your ldap directory protocol, host and port -->
+	<param>
+		<name>main.ldapRealm.contextFactory.url</name>
+		<value>ldap://hdp.example.com:389</value>
+	</param>
+
+	<!-- optional, default value: simple
+	     Update the value based on mechanisms supported by your ldap directory -->
+	<param>
+		<name>main.ldapRealm.contextFactory.authenticationMechanism</name>
+		<value>simple</value>
+	</param>
+
+	<!-- optional, default value: {0}
+       update the value based on your ldap DIT(directory information tree).
+       ignored if value is defined for main.ldapRealm.userSearchAttributeName -->
+	<param>
+		<name>main.ldapRealm.userDnTemplate</name>
+		<value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+	</param>
+
+	<!-- optional, default value: null
+	     If you specify a value for this attribute, useDnTemplate 
+		   specified above would be ignored and user bind DN would be computed using
+		   ldap search
+	     update the value based on your ldap DIT(directory information layout)
+	     value of search attribute should identity the user uniquely -->
+	<param>
+		<name>main.ldapRealm.userSearchAttributeName</name>
+		<value>uid</value>
+	</param>
+
+	<!-- optional, default value: false  
+	     If the value is true, groups in which user is a member are looked up 
+	     from LDAP and made available  for service level authorization checks -->
+	<param>
+		<name>main.ldapRealm.authorizationEnabled</name>
+		<value>true</value>
+	</param>
+
+	<!-- bind DN used to search for groups and user bind DN.  
+	     Required if a value is defined for main.ldapRealm.userSearchAttributeName
+	     or if the value of main.ldapRealm.authorizationEnabled is true -->
+	<param>
+		<name>main.ldapRealm.contextFactory.systemUsername</name>
+		<value>uid=guest,ou=people,dc=hadoop,dc=apache,dc=org</value>
+	</param>
+
+	<!-- password for systemUserName.
+	     Required if a value is defined for main.ldapRealm.userSearchAttributeName
+       or if the value of main.ldapRealm.authorizationEnabled is true -->
+	<param>
+		<name>main.ldapRealm.contextFactory.systemPassword</name>
+		<value>${ALIAS=ldcSystemPassword}</value>
+	</param>
+
+	<!-- optional, default value: simple
+	     Update the value based on mechanisms supported by your ldap directory -->
+	<param>
+		<name>main.ldapRealm.contextFactory.systemAuthenticationMechanism</name>
+		<value>simple</value>
+	</param>
+
+	<!-- optional, default value: person
+	     Objectclass to identify user entries in ldap, used to build search 
+		   filter to search for user bind DN -->
+	<param>
+		<name>main.ldapRealm.userObjectClass</name>
+		<value>person</value>
+	</param>
+
+	<!-- search base used to search for user bind DN and groups -->
+	<param>
+		<name>main.ldapRealm.searchBase</name>
+		<value>dc=hadoop,dc=apache,dc=org</value>
+	</param>
+
+	<!-- search base used to search for user bind DN.
+	     Defaults to the value of main.ldapRealm.searchBase. 
+	     If main.ldapRealm.userSearchAttributeName is defined, 
+	     vlaue for main.ldapRealm.searchBase  or main.ldapRealm.userSearchBase 
+	     should be defined -->
+	<param>
+		<name>main.ldapRealm.userSearchBase</name>
+		<value>dc=hadoop,dc=apache,dc=org</value>
+	</param>
+
+	<!-- search base used to search for groups.
+	     Defaults to the value of main.ldapRealm.searchBase.
+		   If value of main.ldapRealm.authorizationEnabled is true,
+	     vlaue for main.ldapRealm.searchBase  or main.ldapRealm.groupSearchBase should be defined
-->
+	<param>
+		<name>main.ldapRealm.groupSearchBase</name>
+		<value>dc=hadoop,dc=apache,dc=org</value>
+	</param>
+
+	<!-- optional, default value: groupOfNames
+	     Objectclass to identify group entries in ldap, used to build search 
+       filter to search for group entires --> 
+	<param>
+		<name>main.ldapRealm.groupObjectClass</name>
+		<value>groupOfNames</value>
+	</param>
+  
+	<!-- optional, default value: member
+	     If value is memberUrl, we treat found groups as dynamic groups -->
+	<param>
+		<name>main.ldapRealm.memberAttribute</name>
+		<value>member</value>
+	</param>
+
+	<!-- optional, default value: uid={0}
+       Ignored if value is defined for main.ldapRealm.userSearchAttributeName -->
+  <param>
+    <name>main.ldapRealm.memberAttributeValueTemplate</name>
+    <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+  </param>
+  
+	<!-- optional, default value: cn -->
+	<param>
+		<name>main.ldapRealm.groupIdAttribute</name>
+		<value>cn</value>
+	</param>
+
+	<param>
+		<name>urls./**</name>
+		<value>authcBasic</value>
+	</param>
+
+	<!-- optional, default value: 30min -->
+	<param>
+		<name>sessionTimeout</name>
+		<value>30</value>
+	</param>
+
+</provider>
+
+#### Special note on parameter main.ldapRealm.contextFactory.systemPassword
+
+The value for this could have one of the following 2 formats
+
+plantextpassword
+${ALIAS=ldcSystemPassword}
+
+The first format specifies the password in plain text in the provider configuration.
+Use of this format should be limited for testing and troubleshooting.
+
+We strongly recommend using the second format ${ALIAS=ldcSystemPassword}
+n production. This format uses an alias for the password stored in credential store.
+In the example ${ALIAS=ldcSystemPassword}, 
+ldcSystemPassword is the alias for the password stored in credential store.
+
+Assuming plain text password is "hadoop", and your topology file name is "hdp.xml",
+you would use following command to create the right password alias in credential store.
+
+$gateway_home/bin/knoxcli.sh  create-alias ldcSystemPassword --cluster hdp --value hadoop
+
+
+
+

Modified: knox/trunk/books/0.5.0/config_authn.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.5.0/config_authn.md?rev=1628250&r1=1628249&r2=1628250&view=diff
==============================================================================
--- knox/trunk/books/0.5.0/config_authn.md (original)
+++ knox/trunk/books/0.5.0/config_authn.md Mon Sep 29 18:36:59 2014
@@ -155,7 +155,7 @@ The definition would look like the follo
     ...
 
 
-At present, ShiroProvider in Knox leverages JavaEE session to maintain authentication state
for a user across requests using JSESSIONID cookie.  So, a clieent that authenticated with
Knox could pass the JSESSIONID cookie with repeated requests as long as the session has not
timed out instead of submitting userid/password with every request.  Presenting a valid session
cookie in place of userid/password would also perform better as additional credential store
lookups are avoided.
+At present, ShiroProvider in Knox leverages JavaEE session to maintain authentication state
for a user across requests using JSESSIONID cookie.  So, a client that authenticated with
Knox could pass the JSESSIONID cookie with repeated requests as long as the session has not
timed out instead of submitting userid/password with every request.  Presenting a valid session
cookie in place of userid/password would also perform better as additional credential store
lookups are avoided.
 
 
 



Mime
View raw message