You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@knox.apache.org by pz...@apache.org on 2025/04/09 19:51:43 UTC
svn commit: r1924973 - in /knox: site/books/knox-2-1-0/user-guide.html trunk/books/2.1.0/config_mutual_authentication_ssl.md
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