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.clin...@gmail.com"
+
+LDAP Filter for doing a search to find the bind DN would be
+(&(email=bill.clin...@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.
