Author: lmccay
Date: Tue Jan 26 18:35:52 2016
New Revision: 1726850
URL: http://svn.apache.org/viewvc?rev=1726850&view=rev
Log:
adjusted pac4j docs for KNOX-655 changes
Modified:
knox/site/books/knox-0-8-0/user-guide.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.8.0/config_pac4j_provider.md
Modified: knox/site/books/knox-0-8-0/user-guide.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-8-0/user-guide.html?rev=1726850&r1=1726849&r2=1726850&view=diff
==============================================================================
--- knox/site/books/knox-0-8-0/user-guide.html (original)
+++ knox/site/books/knox-0-8-0/user-guide.html Tue Jan 26 18:35:52 2016
@@ -2077,6 +2077,15 @@ APACHE_HOME/bin/apachectl -k stop
</p><p><a href="https://github.com/pac4j/pac4j";>pac4j</a> is a Java security
engine to authenticate users, get their profiles and manage their
authorizations in order to secure Java web applications.</p><p>It supports many
authentication mechanisms for UI and web services and is implemented by many
frameworks and tools.</p><p>For Knox, it is used as a federation provider to
support the OAuth, CAS, SAML and OpenID Connect protocols. It must be used for
SSO, in association with the KnoxSSO service and optionally with the
SSOCookieProvider for access to REST APIs.</p><h4><a
id="Configuration">Configuration</a> <a href="#Configuration"><img
src="markbook-section-link.png"/></a></h4><h5><a id="SSO+topology">SSO
topology</a> <a href="#SSO+topology"><img
src="markbook-section-link.png"/></a></h5><p>To enable SSO for REST API access
through the Knox gateway, you need to protect your Hadoop services with the the
SSOCookieProvider configured to use the KnoxSSO service (sandbox.xml topology):<
/p>
<pre><code><gateway>
<provider>
+ <role>webappsec</role>
+ <name>WebAppSec</name>
+ <enabled>true</enabled>
+ <param>
+ <name>cors.enabled</name>
+ <value>true</value>
+ </param>
+ </provider>
+ <provider>
<role>federation</role>
<name>SSOCookieProvider</name>
<enabled>true</enabled>
@@ -2130,8 +2139,12 @@ APACHE_HOME/bin/apachectl -k stop
<name>knoxsso.token.ttl</name>
<value>100000</value>
</param>
+ <param>
+ <name>knoxsso.redirect.whitelist.regex</name>
+
<value>^https?:\/\/(localhost|127\.0\.0\.1|0:0:0:0:0:0:0:1|::1):[0-9].*$</value>
+ </param>
</service>
-</code></pre><p>Notice that the pac4j callback url is the KnoxSSO url
(<code>pac4j.callbackUrl</code> parameter). An additional
<code>pac4j.cookie.domain.suffix</code> parameter allows you to define the
domain suffix for the pac4j cookies.</p><p>In this example, the pac4j provider
is configured to authenticate users via a CAS server hosted at: <a
href="https://casserverpac4j.herokuapp.com/login";>https://casserverpac4j.herokuapp.com/login</a>.</p><h5><a
id="Parameters">Parameters</a> <a href="#Parameters"><img
src="markbook-section-link.png"/></a></h5><p>You can define the identity
provider used for authentication with the appropriate parameters.</p><p>For
tests only, you can use a basic authentication where login equals password by
defining the following configuration:</p>
+</code></pre><p>Notice that the pac4j callback url is the KnoxSSO url
(<code>pac4j.callbackUrl</code> parameter). An additional
<code>pac4j.cookie.domain.suffix</code> parameter allows you to define the
domain suffix for the pac4j cookies.</p><p>In this example, the pac4j provider
is configured to authenticate users via a CAS server hosted at: <a
href="https://casserverpac4j.herokuapp.com/login";>https://casserverpac4j.herokuapp.com/login</a>.</p><h5><a
id="Parameters">Parameters</a> <a href="#Parameters"><img
src="markbook-section-link.png"/></a></h5><p>You can define the identity
provider or providers to be used for authentication with the appropriate
parameters. When configuring more than one identity provider there is a
mandatory parameter that must be defined to indicate the order in which the
providers should be engaged with the first in the comma separated list being
the default. Clients may indicate their desire to use one of the configured
clients with a query parameter call
ed client_name. When there is no client_name specified, the default (first)
provider is selected.</p><p>For tests only, you can use a basic authentication
where login equals password by defining the following configuration:</p>
<pre><code><param>
<name>clientName</name>
<value>testBasicAuth</value>
@@ -2228,7 +2241,7 @@ APACHE_HOME/bin/apachectl -k stop
</tbody>
</table>
<blockquote><p>Get more details on the <a
href="https://github.com/pac4j/pac4j/wiki/Clients#saml-support";>pac4j
wiki</a>.</p>
-</blockquote><h5><a id="For+OpenID+Connect+support:">For OpenID Connect
support:</a> <a href="#For+OpenID+Connect+support:"><img
src="markbook-section-link.png"/></a></h5>
+</blockquote><p>The SSO url in your SAML 2 provider config will need to
include a special query parameter that lets the pac4j provider know that the
request is coming back from the provider rather than from a redirect from a
KnoxSSO participating application. This query parameter is
“pac4jCallback=true”.</p><p>This results in a URL that looks
something like:</p><p><a
href="https://hostname:8443/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client";>https://hostname:8443/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client</a></p><p>This
also means that the SP Entity ID should also include this query parameter as
appropriate for your provider. Often something like the above URL is used for
both the SSO url and SP Entity ID.</p><h5><a
id="For+OpenID+Connect+support:">For OpenID Connect support:</a> <a
href="#For+OpenID+Connect+support:"><img
src="markbook-section-link.png"/></a></h5>
<table>
<thead>
<tr>
Modified: knox/site/index.html
URL:
http://svn.apache.org/viewvc/knox/site/index.html?rev=1726850&r1=1726849&r2=1726850&view=diff
==============================================================================
--- knox/site/index.html (original)
+++ knox/site/index.html Tue Jan 26 18:35:52 2016
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2016-01-17
+ | Generated by Apache Maven Doxia at 2016-01-26
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20160117" />
+ <meta name="Date-Revision-yyyymmdd" content="20160126" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – REST API Gateway for the Hadoop
Ecosystem</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published:
2016-01-17</li>
+ <li id="publishDate" class="pull-right">Last Published:
2016-01-26</li>
</ul>
</div>
Modified: knox/site/issue-tracking.html
URL:
http://svn.apache.org/viewvc/knox/site/issue-tracking.html?rev=1726850&r1=1726849&r2=1726850&view=diff
==============================================================================
--- knox/site/issue-tracking.html (original)
+++ knox/site/issue-tracking.html Tue Jan 26 18:35:52 2016
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2016-01-17
+ | Generated by Apache Maven Doxia at 2016-01-26
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20160117" />
+ <meta name="Date-Revision-yyyymmdd" content="20160126" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Issue Tracking</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published:
2016-01-17</li>
+ <li id="publishDate" class="pull-right">Last Published:
2016-01-26</li>
</ul>
</div>
Modified: knox/site/license.html
URL:
http://svn.apache.org/viewvc/knox/site/license.html?rev=1726850&r1=1726849&r2=1726850&view=diff
==============================================================================
--- knox/site/license.html (original)
+++ knox/site/license.html Tue Jan 26 18:35:52 2016
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2016-01-17
+ | Generated by Apache Maven Doxia at 2016-01-26
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20160117" />
+ <meta name="Date-Revision-yyyymmdd" content="20160126" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project License</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published:
2016-01-17</li>
+ <li id="publishDate" class="pull-right">Last Published:
2016-01-26</li>
</ul>
</div>
Modified: knox/site/mail-lists.html
URL:
http://svn.apache.org/viewvc/knox/site/mail-lists.html?rev=1726850&r1=1726849&r2=1726850&view=diff
==============================================================================
--- knox/site/mail-lists.html (original)
+++ knox/site/mail-lists.html Tue Jan 26 18:35:52 2016
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2016-01-17
+ | Generated by Apache Maven Doxia at 2016-01-26
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20160117" />
+ <meta name="Date-Revision-yyyymmdd" content="20160126" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Mailing Lists</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published:
2016-01-17</li>
+ <li id="publishDate" class="pull-right">Last Published:
2016-01-26</li>
</ul>
</div>
Modified: knox/site/project-info.html
URL:
http://svn.apache.org/viewvc/knox/site/project-info.html?rev=1726850&r1=1726849&r2=1726850&view=diff
==============================================================================
--- knox/site/project-info.html (original)
+++ knox/site/project-info.html Tue Jan 26 18:35:52 2016
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2016-01-17
+ | Generated by Apache Maven Doxia at 2016-01-26
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20160117" />
+ <meta name="Date-Revision-yyyymmdd" content="20160126" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Information</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published:
2016-01-17</li>
+ <li id="publishDate" class="pull-right">Last Published:
2016-01-26</li>
</ul>
</div>
Modified: knox/site/team-list.html
URL:
http://svn.apache.org/viewvc/knox/site/team-list.html?rev=1726850&r1=1726849&r2=1726850&view=diff
==============================================================================
--- knox/site/team-list.html (original)
+++ knox/site/team-list.html Tue Jan 26 18:35:52 2016
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2016-01-17
+ | Generated by Apache Maven Doxia at 2016-01-26
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20160117" />
+ <meta name="Date-Revision-yyyymmdd" content="20160126" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Team list</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published:
2016-01-17</li>
+ <li id="publishDate" class="pull-right">Last Published:
2016-01-26</li>
</ul>
</div>
Modified: knox/trunk/books/0.8.0/config_pac4j_provider.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/0.8.0/config_pac4j_provider.md?rev=1726850&r1=1726849&r2=1726850&view=diff
==============================================================================
--- knox/trunk/books/0.8.0/config_pac4j_provider.md (original)
+++ knox/trunk/books/0.8.0/config_pac4j_provider.md Tue Jan 26 18:35:52 2016
@@ -35,6 +35,15 @@ To enable SSO for REST API access throug
<gateway>
<provider>
+ <role>webappsec</role>
+ <name>WebAppSec</name>
+ <enabled>true</enabled>
+ <param>
+ <name>cors.enabled</name>
+ <value>true</value>
+ </param>
+ </provider>
+ <provider>
<role>federation</role>
<name>SSOCookieProvider</name>
<enabled>true</enabled>
@@ -90,6 +99,10 @@ and protect the KnoxSSO service by the p
<name>knoxsso.token.ttl</name>
<value>100000</value>
</param>
+ <param>
+ <name>knoxsso.redirect.whitelist.regex</name>
+
<value>^https?:\/\/(localhost|127\.0\.0\.1|0:0:0:0:0:0:0:1|::1):[0-9].*$</value>
+ </param>
</service>
Notice that the pac4j callback url is the KnoxSSO url (`pac4j.callbackUrl`
parameter). An additional `pac4j.cookie.domain.suffix` parameter allows you to
define the domain suffix for the pac4j cookies.
@@ -98,7 +111,8 @@ In this example, the pac4j provider is c
##### Parameters #####
-You can define the identity provider used for authentication with the
appropriate parameters.
+You can define the identity provider or providers to be used for
authentication with the appropriate parameters.
+When configuring more than one identity provider there is a mandatory
parameter that must be defined to indicate the order in which the providers
should be engaged with the first in the comma separated list being the default.
Clients may indicate their desire to use one of the configured clients with a
query parameter called client_name. When there is no client_name specified, the
default (first) provider is selected.
For tests only, you can use a basic authentication where login equals password
by defining the following configuration:
@@ -143,6 +157,15 @@ saml.serviceProviderMetadataPath | Path
> Get more details on the [pac4j
> wiki](https://github.com/pac4j/pac4j/wiki/Clients#saml-support).
+The SSO url in your SAML 2 provider config will need to include a special
query parameter that lets the pac4j provider know that the request is coming
back from the provider rather than from a redirect from a KnoxSSO participating
application. This query parameter is "pac4jCallback=true".
+
+This results in a URL that looks something like:
+
+
https://hostname:8443/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client
+
+This also means that the SP Entity ID should also include this query parameter
as appropriate for your provider.
+Often something like the above URL is used for both the SSO url and SP Entity
ID.
+
##### For OpenID Connect support:
Name | Value
