Author: more
Date: Mon Apr 1 15:33:32 2024
New Revision: 1916717
URL: http://svn.apache.org/viewvc?rev=1916717&view=rev
Log:
KNOX-3015 KNOX-3014 - Document path based authorization feature and
Unauthenticated paths support for Shiro provider
Modified:
knox/site/books/knox-2-1-0/user-guide.html
knox/site/index.html
knox/site/issue-management.html
knox/site/licenses.html
knox/site/mailing-lists.html
knox/site/project-info.html
knox/site/team.html
knox/trunk/books/2.1.0/book.md
knox/trunk/books/2.1.0/config_authn.md
knox/trunk/books/2.1.0/config_authz.md
Modified: knox/site/books/knox-2-1-0/user-guide.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-2-1-0/user-guide.html?rev=1916717&r1=1916716&r2=1916717&view=diff
==============================================================================
--- knox/site/books/knox-2-1-0/user-guide.html (original)
+++ knox/site/books/knox-2-1-0/user-guide.html Mon Apr 1 15:33:32 2024
@@ -81,7 +81,13 @@
<li><a href="#Knox+Auth+Service">Knox Auth Service</a></li>
</ul>
</li>
- <li><a href="#Authorization">Authorization</a></li>
+ <li><a href="#Authorization">Authorization</a>
+ <ul>
+ <li><a href="#Service+Level+Authorization">Service Level
Authorization</a></li>
+ <li><a href="#Composite+Authorization+Provider">Composite Authorization
Provider</a></li>
+ <li><a href="#Path+Based+Authorization">Path Based Authorization</a></li>
+ </ul>
+ </li>
<li><a href="#Identity+Assertion">Identity Assertion</a>
<ul>
<li><a href="#Default+Identity+Assertion+Provider">Default Identity
Assertion Provider</a></li>
@@ -3217,7 +3223,12 @@ ldapRealm.userDnTemplate=uid={0},ou=peop
<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
<code>users.ldif</code> file in the <code>{GATEWAY_HOME}/conf</code>
directory.</p>
<p><strong>main.ldapRealm.contextFactory.url</strong> - this element is the
URL that represents the host and port of the LDAP server. It also includes the
scheme of the protocol to use. This may be either <code>ldap</code> or
<code>ldaps</code> depending on whether you are communicating with the LDAP
over SSL (highly recommended). <strong>This element will need to be customized
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 chain 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>
+<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 chain 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>. This parameter can be used to exclude endpoints from
authentication, this is important in case of jwks endpoints which need not
require authentication. We have support for unauthenticated paths in other
authenitcation providers and this support can be extended here using the
<code>urls</code> parameter. Following is an example of how
<code>/knoxtoken/api/v1/jwks.json</code> en
dpoint can be excluded from authentication in shiro configuration.</p>
+<pre><code> <param>
+ <name>urls./knoxtoken/api/v1/jwks.json</name>
+ <value>anon</value>
+ </param>
+</code></pre>
<h4><a id="Active+Directory+-+Special+Note">Active Directory - Special
Note</a> <a href="#Active+Directory+-+Special+Note"><img
src="markbook-section-link.png"/></a></h4>
<p>You would use LDAP configuration as documented above to authenticate
against Active Directory as well.</p>
<p>Some Active Directory specific things to keep in mind:</p>
@@ -4819,6 +4830,94 @@ url -k --header "SM_USER: nobody@ca
<p>Note the comma separated list of provider names in composite.provider.names
param.</p>
<p>Also Note the use of those names as prefixes to the params to be set on the
respective providers.</p>
<p>The prefixes are removed and the expected param names are set on the actual
providers as appropriate.</p>
+<h3><a id="Path+Based+Authorization">Path Based Authorization</a> <a
href="#Path+Based+Authorization"><img src="markbook-section-link.png"/></a></h3>
+<p>Path based authorization (<code>PathAclsAuthz</code>) enforces Acls
authorization on a configured path. The semantics of Path based authorization
are similar to Acls authz. Authorization is done based on path matching similar
to rewrite rules. </p>
+<p>Format is very similar to AclsAuthz provider with an addition of path
argument. The format is <code>{path};{users};{groups}:{ips}</code>. For details
on the format please see <a href="#Service+Level+Authorization">Service Level
Authorization</a>. One important thing to note here is that the path is not
plural, there has to be one and only one path defined.</p>
+<p>In case one wants multiple paths they can define multiple rules with rule
name as a parameter e.g. <code>KNOXTOKEN.{rule_name}.path.acl</code></p>
+<p>Following are special cases for rule names:</p>
+<h4><a
id="This+rule+will+be+applied+to+ALL+services+defined+in+the+topology">This
rule will be applied to ALL services defined in the topology</a> <a
href="#This+rule+will+be+applied+to+ALL+services+defined+in+the+topology"><img
src="markbook-section-link.png"/></a></h4>
+<p>This rule be applied to all services in the topology. Which means any
service that has <code>api</code> as a context path needs the user to be
<code>admin</code> for successful authorization. </p>
+<pre><code> <provider>
+ <role>authorization</role>
+ <name>PathAclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>path.acl</name>
+ <value>https://*:*/**/api/**;admin;*;*</value>
+ </param>
+ </provider>
+</code></pre>
+<h4><a id="This+rule+will+be+applied+to+only+the+service+{service_name}">This
rule will be applied to only the service {service_name}</a> <a
href="#This+rule+will+be+applied+to+only+the+service+{service_name}"><img
src="markbook-section-link.png"/></a></h4>
+<p>This rule be applied to only <code>{service_name}</code> services in the
topology. Any request for <code>{service_name}</code> that has <code>api</code>
as a context path needs the user to be <code>admin</code> for successful
authorization. </p>
+<pre><code> <provider>
+ <role>authorization</role>
+ <name>PathAclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>{service_name}.path.acl</name>
+ <value>https://*:*/**/api/**;admin;*;*</value>
+ </param>
+ </provider>
+</code></pre>
+<h4><a id="ALL+of+these+rules+will+be+applied+to+service+{service_name}">ALL
of these rules will be applied to service {service_name}</a> <a
href="#ALL+of+these+rules+will+be+applied+to+service+{service_name}"><img
src="markbook-section-link.png"/></a></h4>
+<p><em>NOTE:</em> {rule_1} and {rule_2} should be any unique names. Similar to
previous cases for a service <code>{service_name}</code>, for any request to be
successful with <code>api</code> and <code>api2</code> as context paths, it
needs to have user <code>admin</code>. </p>
+<pre><code> <provider>
+ <role>authorization</role>
+ <name>PathAclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>{service_name}.{rule_1}.path.acl</name>
+ <value>https://*:*/**/api/**;admin;*;*</value>
+ </param>
+ <param>
+ <name>{service_name}.{rule_2}.path.acl</name>
+ <value>https://*:*/**/api2/**;admin;*;*</value>
+ </param>
+ </provider>
+</code></pre>
+<h4><a id="Examples">Examples</a> <a href="#Examples"><img
src="markbook-section-link.png"/></a></h4>
+<p>Following are concrete examples of the the above rules:</p>
+<h5><a
id="This+rule+will+be+applied+to+ALL+services+defined+in+the+topology">This
rule will be applied to ALL services defined in the topology</a> <a
href="#This+rule+will+be+applied+to+ALL+services+defined+in+the+topology"><img
src="markbook-section-link.png"/></a></h5>
+<pre><code> <provider>
+ <role>authorization</role>
+ <name>PathAclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>path.acl</name>
+
<value>https://*:*/**/knoxtoken/api/**;admin;*;*</value>
+ </param>
+ </provider>
+</code></pre>
+<h5><a id="This+rule+will+be+applied+to+only+to+KNOXTOKEN+service">This rule
will be applied to only to KNOXTOKEN service</a> <a
href="#This+rule+will+be+applied+to+only+to+KNOXTOKEN+service"><img
src="markbook-section-link.png"/></a></h5>
+<pre><code> <provider>
+ <role>authorization</role>
+ <name>PathAclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>KNOXTOKEN.path.acl</name>
+
<value>https://*:*/**/knoxtoken/api/**;admin;*;*</value>
+ </param>
+ </provider>
+</code></pre>
+<h5><a
id="All+of+these+rules+will+be+applied+to+only+to+KNOXTOKEN+service">All of
these rules will be applied to only to KNOXTOKEN service</a> <a
href="#All+of+these+rules+will+be+applied+to+only+to+KNOXTOKEN+service"><img
src="markbook-section-link.png"/></a></h5>
+<pre><code> <provider>
+ <role>authorization</role>
+ <name>PathAclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>KNOXTOKEN.rule_1.path.acl</name>
+
<value>https://*:*/**/knoxtoken/api/**;admin;*;*</value>
+ </param>
+ <param>
+ <name>KNOXTOKEN.rule_2.path.acl</name>
+
<value>https://*:*/**/knoxtoken/foo/**;knox;*;*</value>
+ </param>
+ <param>
+ <name>KNOXTOKEN.rule_3.path.acl</name>
+
<value>https://*:*/**/knoxtoken/bar/**;sam;admin;*</value>
+ </param>
+ </provider>
+</code></pre>
<h3><a id="Secure+Clusters">Secure Clusters</a> <a
href="#Secure+Clusters"><img src="markbook-section-link.png"/></a></h3>
<p>See the Hadoop documentation for setting up a secure Hadoop cluster <a
href="http://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/SecureMode.html";>http://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/SecureMode.html</a></p>
<p>Once you have a Hadoop cluster that is using Kerberos for authentication,
you have to do the following to configure Knox to work with that cluster.</p>
Modified: knox/site/index.html
URL:
http://svn.apache.org/viewvc/knox/site/index.html?rev=1916717&r1=1916716&r2=1916717&view=diff
==============================================================================
--- knox/site/index.html (original)
+++ knox/site/index.html Mon Apr 1 15:33:32 2024
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
src/site/markdown/index.md at 2024-02-08
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
src/site/markdown/index.md at 2024-04-01
| Rendered using Apache Maven Fluido Skin 1.7
-->
<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="20240208" />
+ <meta name="Date-Revision-yyyymmdd" content="20240401" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Announcing Apache Knox 1.6.1!</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -40,7 +40,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2024-02-08</li>
+ <li id="publishDate">Last Published: 2024-04-01</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/issue-management.html
URL:
http://svn.apache.org/viewvc/knox/site/issue-management.html?rev=1916717&r1=1916716&r2=1916717&view=diff
==============================================================================
--- knox/site/issue-management.html (original)
+++ knox/site/issue-management.html Mon Apr 1 15:33:32 2024
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:issue-management
at 2024-02-08
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:issue-management
at 2024-04-01
| Rendered using Apache Maven Fluido Skin 1.7
-->
<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="20240208" />
+ <meta name="Date-Revision-yyyymmdd" content="20240401" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Issue Management</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -40,7 +40,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2024-02-08</li>
+ <li id="publishDate">Last Published: 2024-04-01</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/licenses.html
URL:
http://svn.apache.org/viewvc/knox/site/licenses.html?rev=1916717&r1=1916716&r2=1916717&view=diff
==============================================================================
--- knox/site/licenses.html (original)
+++ knox/site/licenses.html Mon Apr 1 15:33:32 2024
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:licenses at
2024-02-08
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:licenses at
2024-04-01
| Rendered using Apache Maven Fluido Skin 1.7
-->
<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="20240208" />
+ <meta name="Date-Revision-yyyymmdd" content="20240401" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Licenses</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -40,7 +40,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2024-02-08</li>
+ <li id="publishDate">Last Published: 2024-04-01</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/mailing-lists.html
URL:
http://svn.apache.org/viewvc/knox/site/mailing-lists.html?rev=1916717&r1=1916716&r2=1916717&view=diff
==============================================================================
--- knox/site/mailing-lists.html (original)
+++ knox/site/mailing-lists.html Mon Apr 1 15:33:32 2024
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:mailing-lists
at 2024-02-08
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:mailing-lists
at 2024-04-01
| Rendered using Apache Maven Fluido Skin 1.7
-->
<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="20240208" />
+ <meta name="Date-Revision-yyyymmdd" content="20240401" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Mailing Lists</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -40,7 +40,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2024-02-08</li>
+ <li id="publishDate">Last Published: 2024-04-01</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/project-info.html
URL:
http://svn.apache.org/viewvc/knox/site/project-info.html?rev=1916717&r1=1916716&r2=1916717&view=diff
==============================================================================
--- knox/site/project-info.html (original)
+++ knox/site/project-info.html Mon Apr 1 15:33:32 2024
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-site-plugin:3.7.1:CategorySummaryDocumentRenderer
at 2024-02-08
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-site-plugin:3.7.1:CategorySummaryDocumentRenderer
at 2024-04-01
| Rendered using Apache Maven Fluido Skin 1.7
-->
<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="20240208" />
+ <meta name="Date-Revision-yyyymmdd" content="20240401" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Information</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -40,7 +40,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2024-02-08</li>
+ <li id="publishDate">Last Published: 2024-04-01</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/team.html
URL:
http://svn.apache.org/viewvc/knox/site/team.html?rev=1916717&r1=1916716&r2=1916717&view=diff
==============================================================================
--- knox/site/team.html (original)
+++ knox/site/team.html Mon Apr 1 15:33:32 2024
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:team at
2024-02-08
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:team at
2024-04-01
| Rendered using Apache Maven Fluido Skin 1.7
-->
<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="20240208" />
+ <meta name="Date-Revision-yyyymmdd" content="20240401" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Team</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -40,7 +40,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2024-02-08</li>
+ <li id="publishDate">Last Published: 2024-04-01</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/trunk/books/2.1.0/book.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/book.md?rev=1916717&r1=1916716&r2=1916717&view=diff
==============================================================================
--- knox/trunk/books/2.1.0/book.md (original)
+++ knox/trunk/books/2.1.0/book.md Mon Apr 1 15:33:32 2024
@@ -68,6 +68,9 @@
* #[TLS Client Certificate Provider]
* #[Knox Auth Service]
* #[Authorization]
+ * #[Service Level Authorization]
+ * #[Composite Authorization Provider]
+ * #[Path Based Authorization]
* #[Identity Assertion]
* #[Default Identity Assertion Provider]
* #[Concat Identity Assertion Provider]
Modified: knox/trunk/books/2.1.0/config_authn.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/config_authn.md?rev=1916717&r1=1916716&r2=1916717&view=diff
==============================================================================
--- knox/trunk/books/2.1.0/config_authn.md (original)
+++ knox/trunk/books/2.1.0/config_authn.md Mon Apr 1 15:33:32 2024
@@ -104,7 +104,12 @@ This section discusses the LDAP configur
**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.
+**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`. This parameter can be used to
exclude endpoints from authentication, this is important in case of jwks
endpoints which need not require authentication. We have support for
unauthenticated paths in other authenitcation providers and this support can be
extended here using the `urls` parameter. Following is an example of how
`/knoxtoken/api/v1/jwks.json` endpoint can be excluded from authentication in
shiro configur
ation.
+
+ <param>
+ <name>urls./knoxtoken/api/v1/jwks.json</name>
+ <value>anon</value>
+ </param>
#### Active Directory - Special Note ####
Modified: knox/trunk/books/2.1.0/config_authz.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/config_authz.md?rev=1916717&r1=1916716&r2=1916717&view=diff
==============================================================================
--- knox/trunk/books/2.1.0/config_authz.md (original)
+++ knox/trunk/books/2.1.0/config_authz.md Mon Apr 1 15:33:32 2024
@@ -356,3 +356,109 @@ Also Note the use of those names as pref
The prefixes are removed and the expected param names are set on the actual
providers as appropriate.
+### Path Based Authorization ###
+
+Path based authorization (`PathAclsAuthz`) enforces Acls authorization on a
configured path. The semantics of Path based authorization are similar to Acls
authz. Authorization is done based on path matching similar to rewrite rules.
+
+Format is very similar to AclsAuthz provider with an addition of path
argument. The format is
+`{path};{users};{groups}:{ips}`. For details on the format please see
#[Service Level Authorization].
+One important thing to note here is that the path is not plural, there has to
be one and only one path defined.
+
+In case one wants multiple paths they can define multiple rules with rule name
as a parameter e.g.
+`KNOXTOKEN.{rule_name}.path.acl`
+
+Following are special cases for rule names:
+#### This rule will be applied to ALL services defined in the topology ####
+This rule be applied to all services in the topology. Which means any service
that has `api`
+as a context path needs the user to be `admin` for successful authorization.
+
+ <provider>
+ <role>authorization</role>
+ <name>PathAclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>path.acl</name>
+ <value>https://*:*/**/api/**;admin;*;*</value>
+ </param>
+ </provider>
+
+#### This rule will be applied to only the service {service_name} ####
+This rule be applied to only `{service_name}` services in the topology. Any
request for `{service_name}` that has `api`
+as a context path needs the user to be `admin` for successful authorization.
+
+ <provider>
+ <role>authorization</role>
+ <name>PathAclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>{service_name}.path.acl</name>
+ <value>https://*:*/**/api/**;admin;*;*</value>
+ </param>
+ </provider>
+
+#### ALL of these rules will be applied to service {service_name} ####
+*NOTE:* {rule_1} and {rule_2} should be any unique names.
+Similar to previous cases for a service `{service_name}`, for any
+request to be successful with `api` and `api2` as context paths, it needs to
have user `admin`.
+
+ <provider>
+ <role>authorization</role>
+ <name>PathAclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>{service_name}.{rule_1}.path.acl</name>
+ <value>https://*:*/**/api/**;admin;*;*</value>
+ </param>
+ <param>
+ <name>{service_name}.{rule_2}.path.acl</name>
+ <value>https://*:*/**/api2/**;admin;*;*</value>
+ </param>
+ </provider>
+
+#### Examples ####
+Following are concrete examples of the the above rules:
+
+##### This rule will be applied to ALL services defined in the topology #####
+
+ <provider>
+ <role>authorization</role>
+ <name>PathAclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>path.acl</name>
+ <value>https://*:*/**/knoxtoken/api/**;admin;*;*</value>
+ </param>
+ </provider>
+
+##### This rule will be applied to only to KNOXTOKEN service #####
+
+ <provider>
+ <role>authorization</role>
+ <name>PathAclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>KNOXTOKEN.path.acl</name>
+ <value>https://*:*/**/knoxtoken/api/**;admin;*;*</value>
+ </param>
+ </provider>
+
+##### All of these rules will be applied to only to KNOXTOKEN service #####
+
+ <provider>
+ <role>authorization</role>
+ <name>PathAclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>KNOXTOKEN.rule_1.path.acl</name>
+ <value>https://*:*/**/knoxtoken/api/**;admin;*;*</value>
+ </param>
+ <param>
+ <name>KNOXTOKEN.rule_2.path.acl</name>
+ <value>https://*:*/**/knoxtoken/foo/**;knox;*;*</value>
+ </param>
+ <param>
+ <name>KNOXTOKEN.rule_3.path.acl</name>
+ <value>https://*:*/**/knoxtoken/bar/**;sam;admin;*</value>
+ </param>
+ </provider>
+
