Author: pzampino
Date: Wed Apr 9 19:51:43 2025
New Revision: 1924973
URL: http://svn.apache.org/viewvc?rev=1924973&view=rev
Log:
Added KNOX-3126 content
Modified:
knox/site/books/knox-2-1-0/user-guide.html
knox/trunk/books/2.1.0/config_mutual_authentication_ssl.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=1924973&r1=1924972&r2=1924973&view=diff
==============================================================================
--- knox/site/books/knox-2-1-0/user-guide.html (original)
+++ knox/site/books/knox-2-1-0/user-guide.html Wed Apr 9 19:51:43 2025
@@ -6793,6 +6793,50 @@ Content-Length: 2048
<pre><code>knoxcli.sh create-alias {password-alias} --value {pwd}
</code></pre>
<p>The password alias name (<code>{password-alias}</code>) is set using
<code>gateway.truststore.password.alias</code>; else, the alias name of
“gateway-truststore-password” should be used.<br/>If a password is
not found using the provided (or default) alias name, then the Gateway’s
master secret will be used.</p>
+<h4><a id="Exclude+a+Topology+from+mTLS">Exclude a Topology from mTLS</a> <a
href="#Exclude+a+Topology+from+mTLS"><img
src="markbook-section-link.png"/></a></h4>
+<p>There is a possibility to exclude specific topologies from mutual
authentication.</p>
+<table>
+ <thead>
+ <tr>
+ <th>Configuration Element </th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>gateway.client.auth.needed</code></td>
+ <td>True - Indicating the need for client authentication.</td>
+ </tr>
+ <tr>
+ <td><code>gateway.port.mapping.enabled</code></td>
+ <td>True - Enabling the port mapping feature. It is turned on by
default.</td>
+ </tr>
+ <tr>
+ <td><code>gateway.port.mapping.{topologyName}</code></td>
+ <td>The port number that this topology will listen on.</td>
+ </tr>
+ <tr>
+ <td><code>gateway.client.auth.exclude</code></td>
+ <td>The names of the topologies separated by comma. These topologies
will be excluded from mTLS.</td>
+ </tr>
+ </tbody>
+</table>
+<p>To exclude a topology from mTLS we use the port mapping feature. The
<code>gateway.port.mapping.enabled</code> feature has to be enabled which is
the default behaviour and a port number has to be provided for the topology
with the <code>gateway.port.mapping.{topologyName}</code> property. The same
topology needs to be added to the <code>gateway.client.auth.exclude</code>
property.</p>
+<p>The below example excludes the <code>health</code> topology from mTLS on
the 9443 port.</p>
+<pre><code> <property>
+ <name>gateway.port.mapping.health</name>
+ <value>9443</value>
+ <description>Topology and Port mapping</description>
+ </property>
+ <property>
+ <name>gateway.client.auth.exclude</name>
+ <value>health</value>
+ <description>Topology excluded from mTLS</description>
+ </property>
+</code></pre>
+<p>An example how one can access the health topology on port 9443 without
mTLS.</p>
+<pre><code> https://{gateway-host}:9443/{gateway-path}/health
+</code></pre>
<h2><a id="TLS+Client+Certificate+Provider">TLS Client Certificate
Provider</a> <a href="#TLS+Client+Certificate+Provider"><img
src="markbook-section-link.png"/></a></h2>
<p>The TLS client certificate authentication provider enables establishing the
user based on the client provided TLS certificate. The user will be the DN from
the certificate. This provider requires that the gateway is configured to
require client authentication with either
<code>gateway.client.auth.wanted</code> or
<code>gateway.client.auth.needed</code> ( <a
href="#Mutual+Authentication+with+SSL">Mutual Authentication with SSL</a> ).</p>
<h3><a id="Configuration">Configuration</a> <a href="#Configuration"><img
src="markbook-section-link.png"/></a></h3>
Modified: knox/trunk/books/2.1.0/config_mutual_authentication_ssl.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/config_mutual_authentication_ssl.md?rev=1924973&r1=1924972&r2=1924973&view=diff
==============================================================================
--- knox/trunk/books/2.1.0/config_mutual_authentication_ssl.md (original)
+++ knox/trunk/books/2.1.0/config_mutual_authentication_ssl.md Wed Apr 9
19:51:43 2025
@@ -41,3 +41,33 @@ If the truststore password is different
The password alias name (`{password-alias}`) is set using
`gateway.truststore.password.alias`; else, the alias name of
"gateway-truststore-password" should be used.
If a password is not found using the provided (or default) alias name, then
the Gateway's master secret will be used.
+
+#### Exclude a Topology from mTLS ####
+
+There is a possibility to exclude specific topologies from mutual
authentication.
+
+Configuration Element | Description
+----------------------|----------------------
+`gateway.client.auth.needed`| True - Indicating the need for client
authentication.
+`gateway.port.mapping.enabled`| True - Enabling the port mapping feature. It
is turned on by default.
+`gateway.port.mapping.{topologyName}`| The port number that this topology will
listen on.
+`gateway.client.auth.exclude`| The names of the topologies separated by comma.
These topologies will be excluded from mTLS.
+
+To exclude a topology from mTLS we use the port mapping feature. The
`gateway.port.mapping.enabled` feature has to be enabled which is the default
behaviour and a port number has to be provided for the topology with the
`gateway.port.mapping.{topologyName}` property. The same topology needs to be
added to the `gateway.client.auth.exclude` property.
+
+The below example excludes the `health` topology from mTLS on the 9443 port.
+
+ <property>
+ <name>gateway.port.mapping.health</name>
+ <value>9443</value>
+ <description>Topology and Port mapping</description>
+ </property>
+ <property>
+ <name>gateway.client.auth.exclude</name>
+ <value>health</value>
+ <description>Topology excluded from mTLS</description>
+ </property>
+
+An example how one can access the health topology on port 9443 without mTLS.
+
+ https://{gateway-host}:9443/{gateway-path}/health
