knox-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lmc...@apache.org
Subject svn commit: r1528277 - in /incubator/knox: site/books/knox-incubating-0-3-0/knox-incubating-0-3-0.html trunk/books/0.3.0/config_authn.md
Date Wed, 02 Oct 2013 00:01:58 GMT
Author: lmccay
Date: Wed Oct  2 00:01:58 2013
New Revision: 1528277

URL: http://svn.apache.org/r1528277
Log:
added authentication provider documentation

Modified:
    incubator/knox/site/books/knox-incubating-0-3-0/knox-incubating-0-3-0.html
    incubator/knox/trunk/books/0.3.0/config_authn.md

Modified: incubator/knox/site/books/knox-incubating-0-3-0/knox-incubating-0-3-0.html
URL: http://svn.apache.org/viewvc/incubator/knox/site/books/knox-incubating-0-3-0/knox-incubating-0-3-0.html?rev=1528277&r1=1528276&r2=1528277&view=diff
==============================================================================
--- incubator/knox/site/books/knox-incubating-0-3-0/knox-incubating-0-3-0.html (original)
+++ incubator/knox/site/books/knox-incubating-0-3-0/knox-incubating-0-3-0.html Wed Oct  2
00:01:58 2013
@@ -409,12 +409,72 @@ ip-10-39-107-209.ec2.internal
   <li>All security related artifacts are protected with the master secret</li>
   <li>Secrets used by the gateway itself are stored within the gateway credential store
and are the same across all gateway instances in the cluster of gateways</li>
   <li>Secrets used by providers within cluster topologies are stored in topology specific
credential stores and are the same for the same topology across the cluster of gateway instances.
 However, they are specific to the topology - so secrets for one hadoop cluster are different
from those of another.  This allows for fail-over from one gateway instance to another even
when encryption is being used while not allowing the compromise of one encryption key to expose
the data for all clusters.</li>
-</ol><p>NOTE: the SSL certificate will need special consideration depending on
the type of certificate. Wildcard certs may be able to be shared across all gateway instances
in a cluster. When certs are dedicated to specific machines the gateway identity store will
not be able to be blindly replicated as host name verification problems will ensue. Obviously,
trust-stores will need to be taken into account as well.</p><h3><a id="Authentication"></a>Authentication</h3><p>TODO</p><h4><a
id="LDAP+Configuration"></a>LDAP Configuration</h4><p>TODO</p><h5><a
id="Creation+of+the+Key+Store+with+self+signed+certificate+and+enabling+it+on+Jetty"></a>Creation
of the Key Store with self signed certificate and enabling it on Jetty</h5>
+</ol><p>NOTE: the SSL certificate will need special consideration depending on
the type of certificate. Wildcard certs may be able to be shared across all gateway instances
in a cluster. When certs are dedicated to specific machines the gateway identity store will
not be able to be blindly replicated as host name verification problems will ensue. Obviously,
trust-stores will need to be taken into account as well.</p><h3><a id="Authentication"></a>Authentication</h3><p>There
are two types of providers supported in Knox for establishing a user&rsquo;s identity:</p>
+<ol>
+  <li>Authentication Providers</li>
+  <li>Federation Providers</li>
+</ol><p>Authentication providers directly accept a user&rsquo;s credentials
and validates them against some particular user store. Federation providers, on the other
hand, validate a token that has been issued for the user by a trusted Identity Provider (IdP).</p><p>The
current release of Knox ships with an authentication provider based on the Apache Shiro project
and is initially configured for BASIC authentication against an LDAP store.</p><p>This
section will cover the general approach to leveraging Shiro within the bundled provider including:</p>
+<ol>
+  <li>General mapping of provider config to shiro.ini config</li>
+  <li>Specific configuration for the bundled BASIC/LDAP configuration</li>
+  <li>Some tips into what may need to be customized for your environment</li>
+  <li>How to setup the use of LDAP over SSL or LDAPS</li>
+</ol><h4><a id="General+Configuration+for+Shiro+Provider"></a>General
Configuration for Shiro Provider</h4><p>As is described in the configuration section
of this document, providers have a name-value based configuration - as is the common pattern
in the rest of Hadoop.</p><p>The following example shows the format of the configuration
for a given provider:</p>
+<pre><code>&lt;provider&gt;
+    &lt;role&gt;authentication&lt;/role&gt;
+    &lt;name&gt;ShiroProvider&lt;/name&gt;
+    &lt;enabled&gt;true&lt;/enabled&gt;
+    &lt;param&gt;
+        &lt;name&gt;{name}&lt;/name&gt;
+        &lt;value&gt;{value}&lt;/value&gt;
+    &lt;/param&gt;
+&lt;/provider&gt;
+</code></pre><p>Conversely, the Shiro provider currently expects a shiro.ini
file in the web-inf directory of the cluster specific web application.</p><p>The
following example illustrates a configuration of the bundled BASIC/LDAP authentication config
in a shiro.ini file:</p>
+<pre><code>[urls]
+/**=authcBasic
+[main]
+ldapRealm=org.apache.shiro.realm.ldap.JndiLdapRealm
+ldapRealm.contextFactory.authenticationMechanism=simple
+ldapRealm.contextFactory.url=ldap://localhost:33389
+ldapRealm.userDnTemplate=uid={0},ou=people,dc=hadoop,dc=apache,dc=org
+</code></pre><p>In order to fit into the context of an INI file format,
at deployment time we interrogate the paramaters provided in the provider configuration and
parse the INI section out of the paramter names. The following provider config illustrates
this approach. Notice that the section names in the above shiro.ini match the beginning of
the param names that are in the following config:</p>
+<pre><code>&lt;gateway&gt;
+    &lt;provider&gt;
+        &lt;role&gt;authentication&lt;/role&gt;
+        &lt;name&gt;ShiroProvider&lt;/name&gt;
+        &lt;enabled&gt;true&lt;/enabled&gt;
+        &lt;param&gt;
+            &lt;name&gt;main.ldapRealm&lt;/name&gt;
+            &lt;value&gt;org.apache.shiro.realm.ldap.JndiLdapRealm&lt;/value&gt;
+        &lt;/param&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;param&gt;
+            &lt;name&gt;main.ldapRealm.contextFactory.url&lt;/name&gt;
+            &lt;value&gt;ldap://localhost:33389&lt;/value&gt;
+        &lt;/param&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;param&gt;
+            &lt;name&gt;urls./**&lt;/name&gt;
+            &lt;value&gt;authcBasic&lt;/value&gt;
+        &lt;/param&gt;
+    &lt;/provider&gt;
+</code></pre><p>This happens to be the way that we are currently configuring
Shiro for BASIC/LDAP authenticatipon. This same config approach may be used to achieve other
authentication mechanisms or variations on this one. We however have not tested additional
uses for it for this release.</p><h4><a id="LDAP+Configuration"></a>LDAP
Configuration</h4><p>This section discusses the LDAP configuration used above
for the Shiro Provider. Some of these configuration elements will need to be customized to
reflect your deployment environment.</p><p><strong>main.ldapRealm</strong>
- this element indicates the fully qualified classname of the Shiro realm to be used in authenticating
the user. The classname provided by default in the sample is the <code>org.apache.shiro.realm.ldap.JndiLdapRealm</code>
this implementation provides us with the ability to authenticate but by default has authorization
disabled. In order to provide authorization - which is seen by Shiro as dependent on an LDAP
schem
 a that is specific to each organization - an extension of JndiLdapRealm is generally used
to override and implement the doGetAuhtorizationInfo method. In this particular release we
are providing a simple authorization provider that can be used along with the Shiro authentication
provider.</p><p><strong>main.ldapRealm.userDnTemplate</strong> - in
order to bind a simple username to an LDAP server that generally requires a full distinguished
name (DN), we must provide the template into which the simple username will be inserted. This
template allows for the creation of a DN by injecting the simple username into the common
name (CN) portion of the DN. <strong>This element will need to be customized to reflect
your deployment environment.</strong> The template provided in the sample is only an
example and is valid only within the LDAP schema distributed with Knox and is represented
by the users.ldif file in the {GATEWAY_HOME}conf directory.</p><p><strong>main.ldapRealm.contextFactory.url
 </strong> - this element is the URL that represents the host and port of LDAP server.
It also includes the scheme of the protocol to use. This may be either ldap or ldaps depending
on whether you are communicating with the LDAP over SSL (higly recommended). <strong>This
element will need to be cusomized to reflect your deployment environment.</strong>.</p><p><strong>main.ldapRealm.contextFactory.authenticationMechanism</strong>
- this element indicates the type of authentication that should be performed against the LDAP
server. The current default value is <code>simple</code> which indicates a simple
bind operation. This element should not need to be modified and no mechanism other than a
simple bind has been tested for this particular release.</p><p><strong>urls./</strong>**
- this element represents a single URL_Ant_Path_Expression and the value the Shiro filter
chain to apply to it. This particular sample indicates that all paths into the application
have the same Shiro filter ch
 ain applied. The paths are relative to the application context path. The use of the value
<code>authcBasic</code> here indicates that BASIC authentication is expected for
every path into the application. Adding an additional Shiro filter to that chain for validating
that the request isSecure() and over SSL can be achieved by changing the value to <code>ssl,
authcBasic</code>. It is not likely that you need to change this element for your environment.</p><h4><a
id="LDAP+over+SSL+(LDAPS)+Configuration"></a>LDAP over SSL (LDAPS) Configuration</h4><p>In
order to communicate with your LDAP server over SSL (again, highly recommended), you will
need to modify the topology file in a couple ways and possibly provision some keying material.</p>
+<ol>
+  <li><strong>main.ldapRealm.contextFactory.url</strong> must be changed
to have the <code>ldaps</code> protocol scheme and the port must be the SSL listener
port on your LDAP server.</li>
+  <li>Identity certificate (keypair) provisioned to LDAP server - your LDAP server
specific documentation should indicate what is requried for providing a cert or keypair to
represent the LDAP server identity to connecting clients.</li>
+  <li>Trusting the LDAP Server&rsquo;s public key - if the LDAP Server&rsquo;s
identity certificate is issued by a well known and trusted certificate authority and is already
represented in the JRE&rsquo;s cacerts truststore then you don&rsquo;t need to do
anything for trusting the LDAP server&rsquo;s cert. If, however, the cert is selfsigned
or issued by an untrusted authority you will need to either add it to the cacerts keystore
or to another truststore that you may direct Knox to utilize through a system property.</li>
+</ol><h1><a id="???????+-+I'm+not+sure+what+this+section+is+supposed+to+be+documenting"></a>???????
- I&rsquo;m not sure what this section is supposed to be documenting</h1><h5><a
id="Creation+of+the+Keystore+with+self+signed+certificate+and+enabling+it+on+Jetty"></a>Creation
of the Keystore with self signed certificate and enabling it on Jetty</h5>
 <pre><code>keytool -keystore keystore -alias jetty -genkey -keyalg RSA -storepass
secret
 </code></pre><p>See more here about <a href="http://wiki.eclipse.org/Jetty/Howto/Configure_SSL">Jetty
SSL setup</a></p><h5><a id="Shiro.ini+file+setup"></a>Shiro.ini
file setup</h5><h6><a id="Shiro.ini"></a>Shiro.ini</h6>
 <pre><code>[urls]
 /** = ssl, authc
-</code></pre><h4><a id="Session+Configuration"></a>Session
Configuration</h4><p>Knox maps each cluster topology to a web application and
leverages standard JavaEE session management.</p><p>To configure session idle
timeout for the topology, please specify value of parameter sessionTimeout for ShiroProvider
in your topology file. If you do not specify the value for this parameter, it defaults to
30minutes.</p><p>The definition would look like the following in the topoloogy
file:</p>
+</code></pre><h1><a id="END+???????"></a>END ???????</h1><h4><a
id="Session+Configuration"></a>Session Configuration</h4><p>Knox maps
each cluster topology to a web application and leverages standard JavaEE session management.</p><p>To
configure session idle timeout for the topology, please specify value of parameter sessionTimeout
for ShiroProvider in your topology file. If you do not specify the value for this parameter,
it defaults to 30minutes.</p><p>The definition would look like the following in
the topoloogy file:</p>
 <pre><code>...
 &lt;provider&gt;
             &lt;role&gt;authentication&lt;/role&gt;
@@ -429,6 +489,7 @@ ip-10-39-107-209.ec2.internal
                 &lt;name&gt;sessionTimeout&lt;/name&gt;
                 &lt;value&gt;30&lt;/value&gt;
             &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="Identity+Assertion"></a>Identity
Assertion</h3><p>The identity assertion provider within Knox plays the critical
role of communicating the identity principal to be used within the Hadoop cluster to represent
the identity that has been authenticated at the gateway.</p><p>The general responsibilities
of the identity assertion provider is to interrogate the current Java Subject that has been
established by the authentication or federation provider and:</p>
 <ol>

Modified: incubator/knox/trunk/books/0.3.0/config_authn.md
URL: http://svn.apache.org/viewvc/incubator/knox/trunk/books/0.3.0/config_authn.md?rev=1528277&r1=1528276&r2=1528277&view=diff
==============================================================================
--- incubator/knox/trunk/books/0.3.0/config_authn.md (original)
+++ incubator/knox/trunk/books/0.3.0/config_authn.md Wed Oct  2 00:01:58 2013
@@ -17,13 +17,106 @@
 
 ### Authentication ###
 
-TODO
+There are two types of providers supported in Knox for establishing a user's identity:
+
+1. Authentication Providers
+2. Federation Providers
+
+Authentication providers directly accept a user's credentials and validates them against
some particular user store. Federation providers, on the other hand, validate a token that
has been issued for the user by a trusted Identity Provider (IdP).
+
+The current release of Knox ships with an authentication provider based on the Apache Shiro
project and is initially configured for BASIC authentication against an LDAP store.
+
+This section will cover the general approach to leveraging Shiro within the bundled provider
including:
+
+1. General mapping of provider config to shiro.ini config
+2. Specific configuration for the bundled BASIC/LDAP configuration
+3. Some tips into what may need to be customized for your environment
+4. How to setup the use of LDAP over SSL or LDAPS
+
+#### General Configuration for Shiro Provider ####
+
+As is described in the configuration section of this document, providers have a name-value
based configuration - as is the common pattern in the rest of Hadoop.
+
+The following example shows the format of the configuration for a given provider:
+
+    <provider>
+        <role>authentication</role>
+        <name>ShiroProvider</name>
+        <enabled>true</enabled>
+        <param>
+            <name>{name}</name>
+            <value>{value}</value>
+        </param>
+    </provider>
+
+Conversely, the Shiro provider currently expects a shiro.ini file in the web-inf directory
of the cluster specific web application.
+
+The following example illustrates a configuration of the bundled BASIC/LDAP authentication
config in a shiro.ini file:
+
+	[urls]
+	/**=authcBasic
+	[main]
+	ldapRealm=org.apache.shiro.realm.ldap.JndiLdapRealm
+	ldapRealm.contextFactory.authenticationMechanism=simple
+	ldapRealm.contextFactory.url=ldap://localhost:33389
+	ldapRealm.userDnTemplate=uid={0},ou=people,dc=hadoop,dc=apache,dc=org
+
+In order to fit into the context of an INI file format, at deployment time we interrogate
the paramaters provided in the provider configuration and parse the INI section out of the
paramter names. The following provider config illustrates this approach. Notice that the section
names in the above shiro.ini match the beginning of the param names that are in the following
config:
+
+    <gateway>
+        <provider>
+            <role>authentication</role>
+            <name>ShiroProvider</name>
+            <enabled>true</enabled>
+            <param>
+                <name>main.ldapRealm</name>
+                <value>org.apache.shiro.realm.ldap.JndiLdapRealm</value>
+            </param>
+            <param>
+                <name>main.ldapRealm.userDnTemplate</name>
+                <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+            </param>
+            <param>
+                <name>main.ldapRealm.contextFactory.url</name>
+                <value>ldap://localhost:33389</value>
+            </param>
+            <param>
+                <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
+                <value>simple</value>
+            </param>
+            <param>
+                <name>urls./**</name>
+                <value>authcBasic</value>
+            </param>
+        </provider>
+
+This happens to be the way that we are currently configuring Shiro for BASIC/LDAP authenticatipon.
This same config approach may be used to achieve other authentication mechanisms or variations
on this one. We however have not tested additional uses for it for this release.
 
 #### LDAP Configuration ####
 
-TODO
+This section discusses the LDAP configuration used above for the Shiro Provider. Some of
these configuration elements will need to be customized to reflect your deployment environment.
 
-##### Creation of the Key Store with self signed certificate and enabling it on Jetty
+**main.ldapRealm** - this element indicates the fully qualified classname of the Shiro realm
to be used in authenticating the user. The classname provided by default in the sample is
the `org.apache.shiro.realm.ldap.JndiLdapRealm` this implementation provides us with the ability
to authenticate but by default has authorization disabled. In order to provide authorization
- which is seen by Shiro as dependent on an LDAP schema that is specific to each organization
- an extension of JndiLdapRealm is generally used to override and implement the doGetAuhtorizationInfo
method. In this particular release we are providing a simple authorization provider that can
be used along with the Shiro authentication provider.
+
+**main.ldapRealm.userDnTemplate** - in order to bind a simple username to an LDAP server
that generally requires a full distinguished name (DN), we must provide the template into
which the simple username will be inserted. This template allows for the creation of a DN
by injecting the simple username into the common name (CN) portion of the DN. **This element
will need to be customized to reflect your deployment environment.** The template provided
in the sample is only an example and is valid only within the LDAP schema distributed with
Knox and is represented by the users.ldif file in the {GATEWAY_HOME}conf directory.
+
+**main.ldapRealm.contextFactory.url** - this element is the URL that represents the host
and port of LDAP server. It also includes the scheme of the protocol to use. This may be either
ldap or ldaps depending on whether you are communicating with the LDAP over SSL (higly recommended).
**This element will need to be cusomized to reflect your deployment environment.**.
+
+**main.ldapRealm.contextFactory.authenticationMechanism** - this element indicates the type
of authentication that should be performed against the LDAP server. The current default value
is `simple` which indicates a simple bind operation. This element should not need to be modified
and no mechanism other than a simple bind has been tested for this particular release.
+
+**urls./**** - this element represents a single URL_Ant_Path_Expression and the value the
Shiro filter chain to apply to it. This particular sample indicates that all paths into the
application have the same Shiro filter chain applied. The paths are relative to the application
context path. The use of the value `authcBasic` here indicates that BASIC authentication is
expected for every path into the application. Adding an additional Shiro filter to that chain
for validating that the request isSecure() and over SSL can be achieved by changing the value
to `ssl, authcBasic`. It is not likely that you need to change this element for your environment.
+
+#### LDAP over SSL (LDAPS) Configuration ####
+In order to communicate with your LDAP server over SSL (again, highly recommended), you will
need to modify the topology file in a couple ways and possibly provision some keying material.
+
+1. **main.ldapRealm.contextFactory.url** must be changed to have the `ldaps` protocol scheme
and the port must be the SSL listener port on your LDAP server.
+2. Identity certificate (keypair) provisioned to LDAP server - your LDAP server specific
documentation should indicate what is requried for providing a cert or keypair to represent
the LDAP server identity to connecting clients.
+3. Trusting the LDAP Server's public key - if the LDAP Server's identity certificate is issued
by a well known and trusted certificate authority and is already represented in the JRE's
cacerts truststore then you don't need to do anything for trusting the LDAP server's cert.
If, however, the cert is selfsigned or issued by an untrusted authority you will need to either
add it to the cacerts keystore or to another truststore that you may direct Knox to utilize
through a system property.
+
+
+# ??????? - I'm not sure what this section is supposed to be documenting
+
+##### Creation of the Keystore with self signed certificate and enabling it on Jetty
 
     keytool -keystore keystore -alias jetty -genkey -keyalg RSA -storepass secret
 
@@ -36,6 +129,8 @@ See more here about [Jetty SSL setup](ht
     [urls]
     /** = ssl, authc
 
+# END ???????
+
 #### Session Configuration ####
 
 Knox maps each cluster topology to a web application and leverages standard JavaEE session
management.
@@ -58,6 +153,7 @@ The definition would look like the follo
                     <name>sessionTimeout</name>
                     <value>30</value>
                 </param>
+    <provider>
     ...
 
 



Mime
View raw message