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 2014/09/29 20:37:00 UTC
svn commit: r1628250 - in /knox: site/ site/books/knox-0-5-0/
trunk/books/0.5.0/
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
</param>
<provider>
...
-</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 "guest’,<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 = “guest”</p><p>LDAP Filter for doing a search to find the bind DN would be (&(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 = “<a href="mailto:bill.clinton@gmail.com">bill.clinton@gmail.com</a>”</p><p>LDAP Filter for doing a search
to find the bind DN would be (&(email=bill<a href="mailto:.clinton@gmail.com)(objectclass=person)">.clinton@gmail.com)(objectclass=person)</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><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 -->
+</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><!-- 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>
+</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 “hadoop”, and your topology file name is “hdp.xml”, 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 –cluster hdp –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> <provider>
<role>authentication</role>
<name>ShiroProvider</name>
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>
- | <span id="publishDate">Last Published: 2014-09-25</span>
+ | <span id="publishDate">Last Published: 2014-09-29</span>
| <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>
- | <span id="publishDate">Last Published: 2014-09-25</span>
+ | <span id="publishDate">Last Published: 2014-09-29</span>
| <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>
- | <span id="publishDate">Last Published: 2014-09-25</span>
+ | <span id="publishDate">Last Published: 2014-09-29</span>
| <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>
- | <span id="publishDate">Last Published: 2014-09-25</span>
+ | <span id="publishDate">Last Published: 2014-09-29</span>
| <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>
- | <span id="publishDate">Last Published: 2014-09-25</span>
+ | <span id="publishDate">Last Published: 2014-09-29</span>
| <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>
- | <span id="publishDate">Last Published: 2014-09-25</span>
+ | <span id="publishDate">Last Published: 2014-09-29</span>
| <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.