trinodb · martint · Apr 27, 2022 · Apr 25, 2022
diff --git a/docs/src/main/sphinx/release/release-378.md b/docs/src/main/sphinx/release/release-378.md
@@ -11,8 +11,9 @@
 
 ## Security
 
-* Require value for the ``internal-communication.shared-secret`` configuration
-  property when authentication is enabled. ({issue}`11944`)
+* Require value for [the shared secret configuration for internal
+  communication](/security/internal-communication) when any authentication is
+  enabled. ({issue}`11944`)
 
 ## CLI
 

diff --git a/docs/src/main/sphinx/security.rst b/docs/src/main/sphinx/security.rst
@@ -20,6 +20,8 @@ Cluster access security
   security/inspect-pem
   security/inspect-jks
 
+.. _security-authentication:
+
 Authentication
 ==============
 

diff --git a/docs/src/main/sphinx/security/authentication-types.rst b/docs/src/main/sphinx/security/authentication-types.rst
@@ -4,7 +4,8 @@ Authentication types
 
 Trino supports multiple authentication types to ensure all users of the system
 are authenticated. Different authenticators allow user management in one or more
-systems. Using :doc:`TLS <tls>` is required for all authentications types.
+systems. Using :doc:`TLS <tls>` and :doc:`a configured shared secret
+</security/internal-communication>` are required for all authentications types.
 
 You can configure one or more authentication types with the
 ``http-server.authentication.type`` property. The following authentication types

diff --git a/docs/src/main/sphinx/security/certificate.rst b/docs/src/main/sphinx/security/certificate.rst
@@ -16,6 +16,9 @@ Trino server on initial connection.
     client certificates in order to use this authentication type. Consider
     instead using another :ref:`authentication type <cl-access-auth>`.
 
+Using :doc:`TLS <tls>` and :doc:`a configured shared secret
+</security/internal-communication>` is required for certificate authentication.
+
 Using certificate authentication
 --------------------------------
 

diff --git a/docs/src/main/sphinx/security/internal-communication.rst b/docs/src/main/sphinx/security/internal-communication.rst
@@ -6,12 +6,13 @@ The Trino cluster can be configured to use secured communication with internal
 authentication of the nodes in the cluster, and optionally added security with
 :ref:`TLS <glossTLS>`.
 
-Internal authentication
------------------------
+Shared secret for internal authentication
+-----------------------------------------
 
 Requests between Trino nodes are authenticated using a shared secret. For secure
-internal communication, the shared secret must be set to the same value on all
-nodes in the cluster:
+internal communication, and for any :ref:`external authentication
+<security-authentication>`, the shared secret must be set to the same value in
+:ref:`config.properties <config_properties>` on all nodes in the cluster:
 
 .. code-block:: text
 

diff --git a/docs/src/main/sphinx/security/jwt.rst b/docs/src/main/sphinx/security/jwt.rst
@@ -37,6 +37,9 @@ in a workflow like the following:
     between users and the Trino coordinator, where their new system submits
     queries on behalf of users.
 
+Using :doc:`TLS <tls>` and :doc:`a configured shared secret
+</security/internal-communication>` is required for JWT authentication.
+
 Using JWT authentication
 ------------------------
 

diff --git a/docs/src/main/sphinx/security/kerberos.rst b/docs/src/main/sphinx/security/kerberos.rst
@@ -6,11 +6,11 @@ Trino can be configured to enable Kerberos authentication over HTTPS for
 clients, such as the :doc:`Trino CLI </security/cli>`, or the JDBC and ODBC
 drivers.
 
-To enable Kerberos authentication for Trino, configuration changes are made on
-the Trino coordinator. No changes are required to the worker configuration.
-The worker nodes continue to connect to the coordinator over
-unauthenticated HTTP. However, if you want to secure the communication between
-Trino nodes with SSL/TLS, configure :doc:`/security/internal-communication`.
+To enable Kerberos authentication for Trino, Kerberos-related configuration
+changes are made on the Trino coordinator.
+
+Using :doc:`TLS <tls>` and :doc:`a configured shared secret
+</security/internal-communication>` is required for Kerberos authentication.
 
 Environment configuration
 -------------------------

diff --git a/docs/src/main/sphinx/security/ldap.rst b/docs/src/main/sphinx/security/ldap.rst
@@ -9,11 +9,11 @@ username and password is supported. The Trino client sends a username
 and password to the coordinator, and the coordinator validates these
 credentials using an external LDAP service.
 
-To enable LDAP authentication for Trino, configuration changes are made on
-the Trino coordinator. No changes are required to the worker configuration;
-only the communication from the clients to the coordinator is authenticated.
-However, if you want to secure the communication between
-Trino nodes with SSL/TLS configure :doc:`/security/internal-communication`.
+To enable LDAP authentication for Trino, LDAP-related configuration changes are
+made on the Trino coordinator.
+
+Using :doc:`TLS <tls>` and :doc:`a configured shared secret
+</security/internal-communication>` is required for LDAP authentication.
 
 Trino server configuration
 ---------------------------

diff --git a/docs/src/main/sphinx/security/oauth2.rst b/docs/src/main/sphinx/security/oauth2.rst
@@ -21,6 +21,9 @@ Set the callback/redirect URL to ``https://<trino-coordinator-domain-name>/oauth
 when configuring an OAuth 2.0 authorization server like an OpenID-connect
 provider.
 
+Using :doc:`TLS <tls>` and :doc:`a configured shared secret
+</security/internal-communication>` is required for OAuth 2.0 authentication.
+
 Trino server configuration
 --------------------------
 

diff --git a/docs/src/main/sphinx/security/overview.rst b/docs/src/main/sphinx/security/overview.rst
@@ -30,6 +30,8 @@ order of steps. Do not skip or combine steps.
      HTTPS, if possible.
    * Use a globally trusted TLS certificate.
 
+#. **Configure** a :doc:`a shared secret </security/internal-communication>`
+
 #. **Enable authentication**
 
    * Start with :doc:`password file authentication <password-file>` to get up

diff --git a/docs/src/main/sphinx/security/password-file.rst b/docs/src/main/sphinx/security/password-file.rst
@@ -11,6 +11,10 @@ Password file authentication is very similar to :doc:`ldap`. Please see
 the LDAP documentation for generic instructions on configuring the server
 and clients to use TLS and authenticate with a username and password.
 
+Using :doc:`TLS <tls>` and :doc:`a configured shared secret
+</security/internal-communication>` is required for password file
+authentication.
+
 Password authenticator configuration
 ------------------------------------
 

diff --git a/docs/src/main/sphinx/security/salesforce.rst b/docs/src/main/sphinx/security/salesforce.rst
@@ -16,6 +16,9 @@ basic credentials.  This can also be used to secure the :ref:`Web UI <web-ui-aut
     Salesforce data. Salesforce authentication is simply a means by which users
     can authenticate to Trino, similar to :doc:`ldap` or :doc:`password-file`.
 
+Using :doc:`TLS <tls>` and :doc:`a configured shared secret
+</security/internal-communication>` is required for Salesforce authentication.
+
 Salesforce authenticator configuration
 --------------------------------------