knox-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lmc...@apache.org
Subject svn commit: r1784342 - in /knox: site/books/knox-0-11-0/user-guide.html site/books/knox-0-12-0/user-guide.html trunk/books/0.11.0/config_knox_sso.md trunk/books/0.12.0/config_knox_sso.md
Date Sat, 25 Feb 2017 01:17:16 GMT
Author: lmccay
Date: Sat Feb 25 01:17:16 2017
New Revision: 1784342

URL: http://svn.apache.org/viewvc?rev=1784342&view=rev
Log:
added docs for KnoxSSO default form-based IdP

Modified:
    knox/site/books/knox-0-11-0/user-guide.html
    knox/site/books/knox-0-12-0/user-guide.html
    knox/trunk/books/0.11.0/config_knox_sso.md
    knox/trunk/books/0.12.0/config_knox_sso.md

Modified: knox/site/books/knox-0-11-0/user-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-11-0/user-guide.html?rev=1784342&r1=1784341&r2=1784342&view=diff
==============================================================================
--- knox/site/books/knox-0-11-0/user-guide.html (original)
+++ knox/site/books/knox-0-11-0/user-guide.html Sat Feb 25 01:17:16 2017
@@ -2766,7 +2766,61 @@ APACHE_HOME/bin/apachectl -k stop
 </table>
 <blockquote><p>Get more details on the <a href="https://github.com/pac4j/pac4j/wiki/Clients#openid-connect-support">pac4j
wiki</a>.</p>
 </blockquote><p>In fact, you can even define several identity providers at the
same time, the first being chosen by default unless you define a <code>client_name</code>
parameter to specify it (<code>FacebookClient</code>, <code>TwitterClient</code>,
<code>CasClient</code>, <code>SAML2Client</code> or <code>OidcClient</code>).</p><h5><a
id="UI+invocation">UI invocation</a> <a href="#UI+invocation"><img src="markbook-section-link.png"/></a></h5><p>In
a browser, when calling your Hadoop service (for example: <code>https://127.0.0.1:8443/gateway/sandbox/webhdfs/v1/tmp?op=LISTSTATUS</code>),
you are redirected to the identity provider for login. Then, after a successful authentication,
your are redirected back to your originally requested url and your KnoxSSO session is initialized.</p><h2><a
id="KnoxSSO+Setup+and+Configuration">KnoxSSO Setup and Configuration</a> <a href="#KnoxSSO+Setup+and+Configuration"><img
src="markbook-section-link.png"/></a></h2><h3><a id="Introduction">Introduct
 ion</a> <a href="#Introduction"><img src="markbook-section-link.png"/></a></h3>
-<hr/><p>Authentication of the Hadoop component UIs, and those of the overall
ecosystem, is usually limited to Kerberos (which requires SPNEGO to be configured for the
user&rsquo;s browser) and simple/psuedo. This often results in the UIs not being secured
- even in secured clusters. This is where KnoxSSO provides value by providing WebSSO capabilities
to the Hadoop cluster.</p><p>By leveraging the hadoop-auth module in Hadoop common,
we have introduced the ability to consume a common SSO cookie for web UIs while retaining
the non-web browser authentication through kerberos/SPNEGO. We do this by extending the AltKerberosAuthenticationHandler
class which provides the useragent based multiplexing. </p><p>We also provide
integration guidance within the developers guide for other applications to be able to participate
in these SSO capabilities.</p><p>The flexibility of the Apache Knox authentication
and federation providers allows KnoxSSO to provide a normalization of authentication even
 ts through token exchange resulting in a common JWT (JSON WebToken) based token.</p><p>KnoxSSO
provides an abstraction for integrating any number of authentication systems and SSO solutions
and enables participating web applications to scale to those solutions more easily. Without
the token exchange capabilities offered by KnoxSSO each component UI would need to integrate
with each desired solution on its own. With KnoxSSO they only need to integrate with the single
solution and common token.</p><p>This document describes the overall setup requirements
for KnoxSSO and participating applications.</p><h3><a id="KnoxSSO+Setup">KnoxSSO
Setup</a> <a href="#KnoxSSO+Setup"><img src="markbook-section-link.png"/></a></h3><h4><a
id="knoxsso.xml+Topology">knoxsso.xml Topology</a> <a href="#knoxsso.xml+Topology"><img
src="markbook-section-link.png"/></a></h4><p>To enable KnoxSSO, we use
the KnoxSSO topology for exposing an API that can be used to abstract the use of any number
of enterprise or 
 customer IDPs. By default, the knoxsso.xml file is configured for using the simple KnoxAuth
application for form-based authentication against LDAP/AD. By swapping the Shiro authentication
provider that is there out-of-the-box with another authentication or federation provider,
an admin may leverage many of the existing providers for SSO for the UI components that participate
in KnoxSSO.</p><p>Just as with any Knox service, the KNOXSSO service is protected
by the gateway providers defined above it. In this case, the ShiroProvider is taking care
of HTTP Basic Auth against LDAP for us. Once the user authenticates the request processing
continues to the KNOXSSO service that will create the required cookie and do the necessary
redirects.</p><p>The knoxsso.xml topology will result in a KnoxSSO URL that looks
something like:</p>
+<hr/><p>Authentication of the Hadoop component UIs, and those of the overall
ecosystem, is usually limited to Kerberos (which requires SPNEGO to be configured for the
user&rsquo;s browser) and simple/psuedo. This often results in the UIs not being secured
- even in secured clusters. This is where KnoxSSO provides value by providing WebSSO capabilities
to the Hadoop cluster.</p><p>By leveraging the hadoop-auth module in Hadoop common,
we have introduced the ability to consume a common SSO cookie for web UIs while retaining
the non-web browser authentication through kerberos/SPNEGO. We do this by extending the AltKerberosAuthenticationHandler
class which provides the useragent based multiplexing. </p><p>We also provide
integration guidance within the developers guide for other applications to be able to participate
in these SSO capabilities.</p><p>The flexibility of the Apache Knox authentication
and federation providers allows KnoxSSO to provide a normalization of authentication even
 ts through token exchange resulting in a common JWT (JSON WebToken) based token.</p><p>KnoxSSO
provides an abstraction for integrating any number of authentication systems and SSO solutions
and enables participating web applications to scale to those solutions more easily. Without
the token exchange capabilities offered by KnoxSSO each component UI would need to integrate
with each desired solution on its own. With KnoxSSO they only need to integrate with the single
solution and common token.</p><p>In addition, KnoxSSO comes with its own Form-based
IDP. This allows for easily integrating a form-based login with the enterprise AD/LDAP server.</p><p>This
document describes the overall setup requirements for KnoxSSO and participating applications.</p><h3><a
id="Form-based+IDP+Setup">Form-based IDP Setup</a> <a href="#Form-based+IDP+Setup"><img
src="markbook-section-link.png"/></a></h3><p>By default the knoxsso.xml
topology contains an application element for the knoxauth login applicat
 ion. This is a simple single page application for providing a login page and authenticating
the user with HTTP basic auth against AD/LDAP.</p>
+<pre><code>&lt;application&gt;
+    &lt;name&gt;knoxauth&lt;/name&gt;
+&lt;/application&gt;
+</code></pre><p>The Shiro Provider has specialized configuration beyond
the typical HTTP Basic authentication requirements for REST APIs or other non-knoxauth applications.
You will notice below that there are a couple additional elements - namely, <strong>redirectToUrl</strong>
and <strong>restrictedCookies with WWW-Authenticate</strong>. These are used to
short-circuit the browser&rsquo;s HTTP basic dialog challenge so that we can use a form
instead.</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;sessionTimeout&lt;/name&gt;
+      &lt;value&gt;30&lt;/value&gt;
+   &lt;/param&gt;
+   &lt;param&gt;
+      &lt;name&gt;redirectToUrl&lt;/name&gt;
+      &lt;value&gt;/gateway/knoxsso/knoxauth/login.html&lt;/value&gt;
+   &lt;/param&gt;
+   &lt;param&gt;
+      &lt;name&gt;restrictedCookies&lt;/name&gt;
+      &lt;value&gt;rememberme,WWW-Authenticate&lt;/value&gt;
+   &lt;/param&gt;
+   &lt;param&gt;
+      &lt;name&gt;main.ldapRealm&lt;/name&gt;
+      &lt;value&gt;org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm&lt;/value&gt;
+   &lt;/param&gt;
+   &lt;param&gt;
+      &lt;name&gt;main.ldapContextFactory&lt;/name&gt;
+      &lt;value&gt;org.apache.hadoop.gateway.shirorealm.KnoxLdapContextFactory&lt;/value&gt;
+   &lt;/param&gt;
+   &lt;param&gt;
+      &lt;name&gt;main.ldapRealm.contextFactory&lt;/name&gt;
+      &lt;value&gt;$ldapContextFactory&lt;/value&gt;
+   &lt;/param&gt;
+   &lt;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.authenticationCachingEnabled&lt;/name&gt;
+      &lt;value&gt;false&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><h3><a id="KnoxSSO+Service+Setup">KnoxSSO Service Setup</a>
<a href="#KnoxSSO+Service+Setup"><img src="markbook-section-link.png"/></a></h3><h4><a
id="knoxsso.xml+Topology">knoxsso.xml Topology</a> <a href="#knoxsso.xml+Topology"><img
src="markbook-section-link.png"/></a></h4><p>To enable KnoxSSO, we use
the KnoxSSO topology for exposing an API that can be used to abstract the use of any number
of enterprise or customer IDPs. By default, the knoxsso.xml file is configured for using the
simple KnoxAuth application for form-based authentication against LDAP/AD. By swapping the
Shiro authentication provider that is there out-of-the-box with another authentication or
federation provider, an admin may leverage many of the existing providers for SSO for the
UI components that participate in KnoxSSO.</p><p>Just as with any Knox service,
the KNOXSSO service is protected by the gateway providers defined above it. In this case,
the ShiroProvider is taking care of HTTP Basic Auth 
 against LDAP for us. Once the user authenticates the request processing continues to the
KNOXSSO service that will create the required cookie and do the necessary redirects.</p><p>The
knoxsso.xml topology will result in a KnoxSSO URL that looks something like:</p>
 <pre><code>https://{gateway_host}:{gateway_port}/gateway/knoxsso/api/v1/websso
 </code></pre><p>This URL is needed when configuring applications that participate
in KnoxSSO for a given deployment. We will refer to this as the Provider URL.</p><h4><a
id="KnoxSSO+Configuration+Parameters">KnoxSSO Configuration Parameters</a> <a
href="#KnoxSSO+Configuration+Parameters"><img src="markbook-section-link.png"/></a></h4>
 <table>

Modified: knox/site/books/knox-0-12-0/user-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/user-guide.html?rev=1784342&r1=1784341&r2=1784342&view=diff
==============================================================================
--- knox/site/books/knox-0-12-0/user-guide.html (original)
+++ knox/site/books/knox-0-12-0/user-guide.html Sat Feb 25 01:17:16 2017
@@ -2766,7 +2766,61 @@ APACHE_HOME/bin/apachectl -k stop
 </table>
 <blockquote><p>Get more details on the <a href="https://github.com/pac4j/pac4j/wiki/Clients#openid-connect-support">pac4j
wiki</a>.</p>
 </blockquote><p>In fact, you can even define several identity providers at the
same time, the first being chosen by default unless you define a <code>client_name</code>
parameter to specify it (<code>FacebookClient</code>, <code>TwitterClient</code>,
<code>CasClient</code>, <code>SAML2Client</code> or <code>OidcClient</code>).</p><h5><a
id="UI+invocation">UI invocation</a> <a href="#UI+invocation"><img src="markbook-section-link.png"/></a></h5><p>In
a browser, when calling your Hadoop service (for example: <code>https://127.0.0.1:8443/gateway/sandbox/webhdfs/v1/tmp?op=LISTSTATUS</code>),
you are redirected to the identity provider for login. Then, after a successful authentication,
your are redirected back to your originally requested url and your KnoxSSO session is initialized.</p><h2><a
id="KnoxSSO+Setup+and+Configuration">KnoxSSO Setup and Configuration</a> <a href="#KnoxSSO+Setup+and+Configuration"><img
src="markbook-section-link.png"/></a></h2><h3><a id="Introduction">Introduct
 ion</a> <a href="#Introduction"><img src="markbook-section-link.png"/></a></h3>
-<hr/><p>Authentication of the Hadoop component UIs, and those of the overall
ecosystem, is usually limited to Kerberos (which requires SPNEGO to be configured for the
user&rsquo;s browser) and simple/psuedo. This often results in the UIs not being secured
- even in secured clusters. This is where KnoxSSO provides value by providing WebSSO capabilities
to the Hadoop cluster.</p><p>By leveraging the hadoop-auth module in Hadoop common,
we have introduced the ability to consume a common SSO cookie for web UIs while retaining
the non-web browser authentication through kerberos/SPNEGO. We do this by extending the AltKerberosAuthenticationHandler
class which provides the useragent based multiplexing. </p><p>We also provide
integration guidance within the developers guide for other applications to be able to participate
in these SSO capabilities.</p><p>The flexibility of the Apache Knox authentication
and federation providers allows KnoxSSO to provide a normalization of authentication even
 ts through token exchange resulting in a common JWT (JSON WebToken) based token.</p><p>KnoxSSO
provides an abstraction for integrating any number of authentication systems and SSO solutions
and enables participating web applications to scale to those solutions more easily. Without
the token exchange capabilities offered by KnoxSSO each component UI would need to integrate
with each desired solution on its own. With KnoxSSO they only need to integrate with the single
solution and common token.</p><p>This document describes the overall setup requirements
for KnoxSSO and participating applications.</p><h3><a id="KnoxSSO+Setup">KnoxSSO
Setup</a> <a href="#KnoxSSO+Setup"><img src="markbook-section-link.png"/></a></h3><h4><a
id="knoxsso.xml+Topology">knoxsso.xml Topology</a> <a href="#knoxsso.xml+Topology"><img
src="markbook-section-link.png"/></a></h4><p>To enable KnoxSSO, we use
the KnoxSSO topology for exposing an API that can be used to abstract the use of any number
of enterprise or 
 customer IDPs. By default, the knoxsso.xml file is configured for using the simple KnoxAuth
application for form-based authentication against LDAP/AD. By swapping the Shiro authentication
provider that is there out-of-the-box with another authentication or federation provider,
an admin may leverage many of the existing providers for SSO for the UI components that participate
in KnoxSSO.</p><p>Just as with any Knox service, the KNOXSSO service is protected
by the gateway providers defined above it. In this case, the ShiroProvider is taking care
of HTTP Basic Auth against LDAP for us. Once the user authenticates the request processing
continues to the KNOXSSO service that will create the required cookie and do the necessary
redirects.</p><p>The knoxsso.xml topology will result in a KnoxSSO URL that looks
something like:</p>
+<hr/><p>Authentication of the Hadoop component UIs, and those of the overall
ecosystem, is usually limited to Kerberos (which requires SPNEGO to be configured for the
user&rsquo;s browser) and simple/psuedo. This often results in the UIs not being secured
- even in secured clusters. This is where KnoxSSO provides value by providing WebSSO capabilities
to the Hadoop cluster.</p><p>By leveraging the hadoop-auth module in Hadoop common,
we have introduced the ability to consume a common SSO cookie for web UIs while retaining
the non-web browser authentication through kerberos/SPNEGO. We do this by extending the AltKerberosAuthenticationHandler
class which provides the useragent based multiplexing. </p><p>We also provide
integration guidance within the developers guide for other applications to be able to participate
in these SSO capabilities.</p><p>The flexibility of the Apache Knox authentication
and federation providers allows KnoxSSO to provide a normalization of authentication even
 ts through token exchange resulting in a common JWT (JSON WebToken) based token.</p><p>KnoxSSO
provides an abstraction for integrating any number of authentication systems and SSO solutions
and enables participating web applications to scale to those solutions more easily. Without
the token exchange capabilities offered by KnoxSSO each component UI would need to integrate
with each desired solution on its own. With KnoxSSO they only need to integrate with the single
solution and common token.</p><p>In addition, KnoxSSO comes with its own Form-based
IDP. This allows for easily integrating a form-based login with the enterprise AD/LDAP server.</p><p>This
document describes the overall setup requirements for KnoxSSO and participating applications.</p><h3><a
id="Form-based+IDP+Setup">Form-based IDP Setup</a> <a href="#Form-based+IDP+Setup"><img
src="markbook-section-link.png"/></a></h3><p>By default the knoxsso.xml
topology contains an application element for the knoxauth login applicat
 ion. This is a simple single page application for providing a login page and authenticating
the user with HTTP basic auth against AD/LDAP.</p>
+<pre><code>&lt;application&gt;
+    &lt;name&gt;knoxauth&lt;/name&gt;
+&lt;/application&gt;
+</code></pre><p>The Shiro Provider has specialized configuration beyond
the typical HTTP Basic authentication requirements for REST APIs or other non-knoxauth applications.
You will notice below that there are a couple additional elements - namely, <strong>redirectToUrl</strong>
and <strong>restrictedCookies with WWW-Authenticate</strong>. These are used to
short-circuit the browser&rsquo;s HTTP basic dialog challenge so that we can use a form
instead.</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;sessionTimeout&lt;/name&gt;
+      &lt;value&gt;30&lt;/value&gt;
+   &lt;/param&gt;
+   &lt;param&gt;
+      &lt;name&gt;redirectToUrl&lt;/name&gt;
+      &lt;value&gt;/gateway/knoxsso/knoxauth/login.html&lt;/value&gt;
+   &lt;/param&gt;
+   &lt;param&gt;
+      &lt;name&gt;restrictedCookies&lt;/name&gt;
+      &lt;value&gt;rememberme,WWW-Authenticate&lt;/value&gt;
+   &lt;/param&gt;
+   &lt;param&gt;
+      &lt;name&gt;main.ldapRealm&lt;/name&gt;
+      &lt;value&gt;org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm&lt;/value&gt;
+   &lt;/param&gt;
+   &lt;param&gt;
+      &lt;name&gt;main.ldapContextFactory&lt;/name&gt;
+      &lt;value&gt;org.apache.hadoop.gateway.shirorealm.KnoxLdapContextFactory&lt;/value&gt;
+   &lt;/param&gt;
+   &lt;param&gt;
+      &lt;name&gt;main.ldapRealm.contextFactory&lt;/name&gt;
+      &lt;value&gt;$ldapContextFactory&lt;/value&gt;
+   &lt;/param&gt;
+   &lt;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.authenticationCachingEnabled&lt;/name&gt;
+      &lt;value&gt;false&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><h3><a id="KnoxSSO+Service+Setup">KnoxSSO Service Setup</a>
<a href="#KnoxSSO+Service+Setup"><img src="markbook-section-link.png"/></a></h3><h4><a
id="knoxsso.xml+Topology">knoxsso.xml Topology</a> <a href="#knoxsso.xml+Topology"><img
src="markbook-section-link.png"/></a></h4><p>To enable KnoxSSO, we use
the KnoxSSO topology for exposing an API that can be used to abstract the use of any number
of enterprise or customer IDPs. By default, the knoxsso.xml file is configured for using the
simple KnoxAuth application for form-based authentication against LDAP/AD. By swapping the
Shiro authentication provider that is there out-of-the-box with another authentication or
federation provider, an admin may leverage many of the existing providers for SSO for the
UI components that participate in KnoxSSO.</p><p>Just as with any Knox service,
the KNOXSSO service is protected by the gateway providers defined above it. In this case,
the ShiroProvider is taking care of HTTP Basic Auth 
 against LDAP for us. Once the user authenticates the request processing continues to the
KNOXSSO service that will create the required cookie and do the necessary redirects.</p><p>The
knoxsso.xml topology will result in a KnoxSSO URL that looks something like:</p>
 <pre><code>https://{gateway_host}:{gateway_port}/gateway/knoxsso/api/v1/websso
 </code></pre><p>This URL is needed when configuring applications that participate
in KnoxSSO for a given deployment. We will refer to this as the Provider URL.</p><h4><a
id="KnoxSSO+Configuration+Parameters">KnoxSSO Configuration Parameters</a> <a
href="#KnoxSSO+Configuration+Parameters"><img src="markbook-section-link.png"/></a></h4>
 <table>

Modified: knox/trunk/books/0.11.0/config_knox_sso.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.11.0/config_knox_sso.md?rev=1784342&r1=1784341&r2=1784342&view=diff
==============================================================================
--- knox/trunk/books/0.11.0/config_knox_sso.md (original)
+++ knox/trunk/books/0.11.0/config_knox_sso.md Sat Feb 25 01:17:16 2017
@@ -13,9 +13,70 @@ The flexibility of the Apache Knox authe
 
 KnoxSSO provides an abstraction for integrating any number of authentication systems and
SSO solutions and enables participating web applications to scale to those solutions more
easily. Without the token exchange capabilities offered by KnoxSSO each component UI would
need to integrate with each desired solution on its own. With KnoxSSO they only need to integrate
with the single solution and common token.
 
+In addition, KnoxSSO comes with its own Form-based IDP. This allows for easily integrating
a form-based login with the enterprise AD/LDAP server.
+
 This document describes the overall setup requirements for KnoxSSO and participating applications.
 
-### KnoxSSO Setup
+### Form-based IDP Setup
+By default the knoxsso.xml topology contains an application element for the knoxauth login
application. This is a simple single page application for providing a login page and authenticating
the user with HTTP basic auth against AD/LDAP.
+
+    <application>
+        <name>knoxauth</name>
+    </application>
+
+The Shiro Provider has specialized configuration beyond the typical HTTP Basic authentication
requirements for REST APIs or other non-knoxauth applications. You will notice below that
there are a couple additional elements - namely, **redirectToUrl** and **restrictedCookies
with WWW-Authenticate**. These are used to short-circuit the browser's HTTP basic dialog challenge
so that we can use a form instead.
+
+    <provider>
+       <role>authentication</role>
+       <name>ShiroProvider</name>
+       <enabled>true</enabled>
+       <param>
+          <name>sessionTimeout</name>
+          <value>30</value>
+       </param>
+       <param>
+          <name>redirectToUrl</name>
+          <value>/gateway/knoxsso/knoxauth/login.html</value>
+       </param>
+       <param>
+          <name>restrictedCookies</name>
+          <value>rememberme,WWW-Authenticate</value>
+       </param>
+       <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>
+       <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.authenticationCachingEnabled</name>
+          <value>false</value>
+       </param>
+       <param>
+          <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
+          <value>simple</value>
+       </param>
+       <param>
+          <name>urls./**</name>
+          <value>authcBasic</value>
+       </param>
+    </provider>
+
+### KnoxSSO Service Setup
 
 #### knoxsso.xml Topology
 To enable KnoxSSO, we use the KnoxSSO topology for exposing an API that can be used to abstract
the use of any number of enterprise or customer IDPs. By default, the knoxsso.xml file is
configured for using the simple KnoxAuth application for form-based authentication against
LDAP/AD. By swapping the Shiro authentication provider that is there out-of-the-box with another
authentication or federation provider, an admin may leverage many of the existing providers
for SSO for the UI components that participate in KnoxSSO.

Modified: knox/trunk/books/0.12.0/config_knox_sso.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/config_knox_sso.md?rev=1784342&r1=1784341&r2=1784342&view=diff
==============================================================================
--- knox/trunk/books/0.12.0/config_knox_sso.md (original)
+++ knox/trunk/books/0.12.0/config_knox_sso.md Sat Feb 25 01:17:16 2017
@@ -13,9 +13,70 @@ The flexibility of the Apache Knox authe
 
 KnoxSSO provides an abstraction for integrating any number of authentication systems and
SSO solutions and enables participating web applications to scale to those solutions more
easily. Without the token exchange capabilities offered by KnoxSSO each component UI would
need to integrate with each desired solution on its own. With KnoxSSO they only need to integrate
with the single solution and common token.
 
+In addition, KnoxSSO comes with its own Form-based IDP. This allows for easily integrating
a form-based login with the enterprise AD/LDAP server.
+
 This document describes the overall setup requirements for KnoxSSO and participating applications.
 
-### KnoxSSO Setup
+### Form-based IDP Setup
+By default the knoxsso.xml topology contains an application element for the knoxauth login
application. This is a simple single page application for providing a login page and authenticating
the user with HTTP basic auth against AD/LDAP.
+
+    <application>
+        <name>knoxauth</name>
+    </application>
+
+The Shiro Provider has specialized configuration beyond the typical HTTP Basic authentication
requirements for REST APIs or other non-knoxauth applications. You will notice below that
there are a couple additional elements - namely, **redirectToUrl** and **restrictedCookies
with WWW-Authenticate**. These are used to short-circuit the browser's HTTP basic dialog challenge
so that we can use a form instead.
+
+    <provider>
+       <role>authentication</role>
+       <name>ShiroProvider</name>
+       <enabled>true</enabled>
+       <param>
+          <name>sessionTimeout</name>
+          <value>30</value>
+       </param>
+       <param>
+          <name>redirectToUrl</name>
+          <value>/gateway/knoxsso/knoxauth/login.html</value>
+       </param>
+       <param>
+          <name>restrictedCookies</name>
+          <value>rememberme,WWW-Authenticate</value>
+       </param>
+       <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>
+       <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.authenticationCachingEnabled</name>
+          <value>false</value>
+       </param>
+       <param>
+          <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
+          <value>simple</value>
+       </param>
+       <param>
+          <name>urls./**</name>
+          <value>authcBasic</value>
+       </param>
+    </provider>
+
+### KnoxSSO Service Setup
 
 #### knoxsso.xml Topology
 To enable KnoxSSO, we use the KnoxSSO topology for exposing an API that can be used to abstract
the use of any number of enterprise or customer IDPs. By default, the knoxsso.xml file is
configured for using the simple KnoxAuth application for form-based authentication against
LDAP/AD. By swapping the Shiro authentication provider that is there out-of-the-box with another
authentication or federation provider, an admin may leverage many of the existing providers
for SSO for the UI components that participate in KnoxSSO.



Mime
View raw message