Author: lmccay
Date: Sun Mar 22 17:17:36 2015
New Revision: 1668415
URL: http://svn.apache.org/r1668415
Log:
KNOX-521 - document the implementation of new identity assertion providers
using the common base module
Modified:
knox/site/books/knox-0-6-0/dev-guide.html
knox/trunk/books/0.6.0/dev-guide/book.md
Modified: knox/site/books/knox-0-6-0/dev-guide.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-6-0/dev-guide.html?rev=1668415&r1=1668414&r2=1668415&view=diff
==============================================================================
--- knox/site/books/knox-0-6-0/dev-guide.html (original)
+++ knox/site/books/knox-0-6-0/dev-guide.html Sun Mar 22 17:17:36 2015
@@ -88,8 +88,16 @@
<td>The SPI for service and provider extensions. </td>
</tr>
<tr>
+ <td>gateway-provider-identity-assertion-common </td>
+ <td>The identity assertion provider base </td>
+ </tr>
+ <tr>
+ <td>gateway-provider-identity-assertion-concat </td>
+ <td>An identity assertion provider that facilitates prefix and suffix
concatenation.</td>
+ </tr>
+ <tr>
<td>gateway-provider-identity-assertion-pseudo </td>
- <td>The identity assertion provider. </td>
+ <td>The default identity assertion provider. </td>
</tr>
<tr>
<td>gateway-provider-jersey </td>
@@ -746,7 +754,67 @@ public void testDevGuideSampleWithEvalua
<encrypt-query/>
</rule>
</rules>
-</code></pre><h3><a id="Jersey+Provider"></a>Jersey
Provider</h3><p>TODO</p><h2><a id="Auditing"></a>Auditing</h2>
+</code></pre><h3><a id="Identity+Assertion+Provider"></a>Identity Assertion
Provider</h3><p>Adding a new identity assertion provider is as simple as
extending the AbstractIdentityAsserterDeploymentContributor and the
CommonIdentityAssertionFilter from the
gateway-provider-identity-assertion-common module to initialize any specific
configuration from filter init params and implement two methods:</p>
+<ol>
+ <li>String mapUserPrincipal(String principalName);</li>
+ <li>String[] mapGroupPrincipals(String principalName, Subject subject);</li>
+</ol><p>To implement a simple toUpper or toLower identity assertion
provider:</p>
+<pre><code class="java">package
org.apache.hadoop.gateway.identityasserter.caseshifter.filter;
+
+import
org.apache.hadoop.gateway.identityasserter.common.filter.AbstractIdentityAsserterDeploymentContributor;
+
+public class CaseShifterIdentityAsserterDeploymentContributor extends
AbstractIdentityAsserterDeploymentContributor {
+
+ @Override
+ public String getName() {
+ return "CaseShifter";
+ }
+
+ protected String getFilterClassname() {
+ return CaseShifterIdentityAssertionFilter.class.getName();
+ }
+}
+</code></pre><p>We merely need to provide the provider name for use in the
topology and the filter classname for the contributor to add to the filter
chain.</p><p>For the identity assertion filter itself it is just a matter of
extension and the implementation of the two methods described earlier:</p>
+<pre><code class="java">package
org.apache.hadoop.gateway.identityasserter.caseshifter.filter;
+
+import javax.security.auth.Subject;
+import javax.servlet.FilterConfig;
+import javax.servlet.ServletException;
+import
org.apache.hadoop.gateway.identityasserter.common.filter.CommonIdentityAssertionFilter;
+
+public class CaseShifterIdentityAssertionFilter extends
CommonIdentityAssertionFilter {
+ private boolean toUpper = false;
+
+ @Override
+ public void init(FilterConfig filterConfig) throws ServletException {
+ String upper = filterConfig.getInitParameter("caseshift.upper");
+ if ("true".equals(upper)) {
+ toUpper = true;
+ }
+ }
+
+ @Override
+ public String[] mapGroupPrincipals(String mappedPrincipalName, Subject
subject) {
+ return null;
+ }
+
+ @Override
+ public String mapUserPrincipal(String principalName) {
+ if (toUpper) {
+ principalName = principalName.toUpperCase();
+ }
+ else {
+ principalName = principalName.toLowerCase();
+ }
+ return principalName;
+ }
+}
+</code></pre><p>Note that the above: </p>
+<ol>
+ <li>looks for specific filter init parameters for configuration of whether
to convert to upper or to lower case</li>
+ <li>it no-ops the mapGroupPrincipals so that it returns null. This indicates
that there are no changes needed to the groups contained within the Subject. If
there are groups then they should be continued to flow through the system
unchanged. This is actually the same implementation as the base class and is
therefore not required to be overridden. We include it here for
illustration.</li>
+ <li>based upon the configuration interrogated in the init method the
principalName is convert to either upper or lower case.</li>
+</ol><p>That is the extent of what is needed to implement a new identity
assertion provider module.</p><h3><a id="Jersey+Provider"></a>Jersey
Provider</h3><p>TODO</p><h2><a id="Auditing"></a>Auditing</h2>
<pre><code class="java">public class AuditingSample {
private static Auditor AUDITOR =
AuditServiceFactory.getAuditService().getAuditor(
Modified: knox/trunk/books/0.6.0/dev-guide/book.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/0.6.0/dev-guide/book.md?rev=1668415&r1=1668414&r2=1668415&view=diff
==============================================================================
--- knox/trunk/books/0.6.0/dev-guide/book.md (original)
+++ knox/trunk/books/0.6.0/dev-guide/book.md Sun Mar 22 17:17:36 2015
@@ -102,7 +102,9 @@ This is also true of the other -release
| gateway-i18n-logging-log4j | The integration of i18n
logging with log4j. |
| gateway-i18n-logging-sl4j | The integration of i18n
logging with sl4j. |
| gateway-spi | The SPI for service and
provider extensions. |
-| gateway-provider-identity-assertion-pseudo | The identity assertion
provider. |
+| gateway-provider-identity-assertion-common | The identity assertion
provider base |
+| gateway-provider-identity-assertion-concat | An identity assertion
provider that facilitates prefix and suffix concatenation.|
+| gateway-provider-identity-assertion-pseudo | The default identity
assertion provider. |
| gateway-provider-jersey | The jersey display
provider. |
| gateway-provider-rewrite | The URL rewrite provider.
|
| gateway-provider-rewrite-func-hostmap-static | Host mapping function
extension to rewrite. |
@@ -1090,6 +1092,80 @@ TODO - Provide an lowercase step as an e
</rules>
```
+### Identity Assertion Provider ###
+Adding a new identity assertion provider is as simple as extending the
AbstractIdentityAsserterDeploymentContributor and the
CommonIdentityAssertionFilter from the
gateway-provider-identity-assertion-common module to initialize any specific
configuration from filter init params and implement two methods:
+
+1. String mapUserPrincipal(String principalName);
+2. String[] mapGroupPrincipals(String principalName, Subject subject);
+
+To implement a simple toUpper or toLower identity assertion provider:
+
+```java
+package org.apache.hadoop.gateway.identityasserter.caseshifter.filter;
+
+import
org.apache.hadoop.gateway.identityasserter.common.filter.AbstractIdentityAsserterDeploymentContributor;
+
+public class CaseShifterIdentityAsserterDeploymentContributor extends
AbstractIdentityAsserterDeploymentContributor {
+
+ @Override
+ public String getName() {
+ return "CaseShifter";
+ }
+
+ protected String getFilterClassname() {
+ return CaseShifterIdentityAssertionFilter.class.getName();
+ }
+}
+```
+We merely need to provide the provider name for use in the topology and the
filter classname for the contributor to add to the filter chain.
+
+For the identity assertion filter itself it is just a matter of extension and
the implementation of the two methods described earlier:
+
+```java
+package org.apache.hadoop.gateway.identityasserter.caseshifter.filter;
+
+import javax.security.auth.Subject;
+import javax.servlet.FilterConfig;
+import javax.servlet.ServletException;
+import
org.apache.hadoop.gateway.identityasserter.common.filter.CommonIdentityAssertionFilter;
+
+public class CaseShifterIdentityAssertionFilter extends
CommonIdentityAssertionFilter {
+ private boolean toUpper = false;
+
+ @Override
+ public void init(FilterConfig filterConfig) throws ServletException {
+ String upper = filterConfig.getInitParameter("caseshift.upper");
+ if ("true".equals(upper)) {
+ toUpper = true;
+ }
+ }
+
+ @Override
+ public String[] mapGroupPrincipals(String mappedPrincipalName, Subject
subject) {
+ return null;
+ }
+
+ @Override
+ public String mapUserPrincipal(String principalName) {
+ if (toUpper) {
+ principalName = principalName.toUpperCase();
+ }
+ else {
+ principalName = principalName.toLowerCase();
+ }
+ return principalName;
+ }
+}
+```
+
+Note that the above:
+
+1. looks for specific filter init parameters for configuration of whether to
convert to upper or to lower case
+2. it no-ops the mapGroupPrincipals so that it returns null. This indicates
that there are no changes needed to the groups contained within the Subject. If
there are groups then they should be continued to flow through the system
unchanged. This is actually the same implementation as the base class and is
therefore not required to be overridden. We include it here for illustration.
+3. based upon the configuration interrogated in the init method the
principalName is convert to either upper or lower case.
+
+That is the extent of what is needed to implement a new identity assertion
provider module.
+
### Jersey Provider ###
TODO
