[geode] branch support/1.15 updated: GEODE-10390: User guide: update authentication expiry instructions (#7809)

[db...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

dbarnes pushed a commit to branch support/1.15
in repository https://gitbox.apache.org/repos/asf/geode.git


The following commit(s) were added to refs/heads/support/1.15 by this push:
     new 81ae2db3e5 GEODE-10390: User guide: update authentication expiry instructions (#7809)
81ae2db3e5 is described below

commit 81ae2db3e54f093cb7d0bbcc6d462d4cf6141873
Author: Dave Barnes <db...@apache.org>
AuthorDate: Thu Jun 16 16:37:15 2022 -0700

    GEODE-10390: User guide: update authentication expiry instructions (#7809)
---
 .../implementing_authentication.html.md.erb        |  1 +
 .../implementing_authentication_expiry.html.md.erb | 22 +++++++++-------------
 2 files changed, 10 insertions(+), 13 deletions(-)

diff --git a/geode-docs/managing/security/implementing_authentication.html.md.erb b/geode-docs/managing/security/implementing_authentication.html.md.erb
index a79e5d14c6..972ed9d57a 100644
--- a/geode-docs/managing/security/implementing_authentication.html.md.erb
+++ b/geode-docs/managing/security/implementing_authentication.html.md.erb
@@ -36,6 +36,7 @@ which is discussed in detail in the [authorization](authorization_overview.html)
 
 In case of an `AuthenticationExpiredException` the <%=vars.product_name%> client code will make one automatic attempt
 to re-connect to the member that sent the exception.
+A `SecurityManager` implementation that supports reauthentication using expiring credentials must also support non-expiring credentials for cluster members.
 
 A well-designed `authenticate` method will have a set of known credentials, such as user and password pairs, that can be
 compared to the credentials presented or will have a way of obtaining those credentials.
diff --git a/geode-docs/managing/security/implementing_authentication_expiry.html.md.erb b/geode-docs/managing/security/implementing_authentication_expiry.html.md.erb
index b535f1afac..d6f5131249 100644
--- a/geode-docs/managing/security/implementing_authentication_expiry.html.md.erb
+++ b/geode-docs/managing/security/implementing_authentication_expiry.html.md.erb
@@ -19,15 +19,17 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
+Authentication expiry is supported only with client connections.
+The use of expirable credentials is most common when used in combination with token-based authentication and authorization.
 Authentication expiry makes it possible for cluster administrators to limit the life span of client
-and peer connections within the cluster. The use of expirable credentials is most common when used in
-combination with token based authentication and authorization.
+connections within the cluster.
 
-Client connections are notified of expiry through `AuthenticationExpiredException`,
+Client connections are notified of expiry by `AuthenticationExpiredException`,
 which is thrown in the implementations of `SecurityManager.authenticate` or `SecurityManager.authorize`.
 
-Clients will do one automatic attempt to reconnect. Upon receiving a second `AuthenticationExpiredException`
-the exception will be propagated up the chain for the user to handle. There are some differences in
+Upon receiving the AuthenticationExpiredException, clients will make one automatic attempt to gather new credentials and reconnect (AuthInitialize.getCredentials()).
+Upon receiving a second `AuthenticationExpiredException`
+the exception is thrown back to the user to handle. There are some differences in
 behavior between older and newer clients.
 
 **Support for Automatic	Reconnect**
@@ -56,15 +58,9 @@ The common cycle for authentication and authorization is the following:
 AuthInitialize.getCredentials(...) -> SecurityManager.authenticate(...) -> SecurityManager.authorize(...)
 ```
 
-Where `AuthInitialize.getCredentials()` provides the `security properties` for `SecurityManager.authenticate()`
-which in turn provides the `principal object` for `SecurityManager.authorize()`. It's important to
-understand that some time will pass between the `AuthInitialize.getCredentials()` call and the
-`SecurityManager.authorize()` call. The specific amount of time depends on the implementation and
-runtime environment details.
-
 In case of the use of an external token provider we assume that this token provider will be asked for
-a token in the `AuthInitialize.getCredentials()` call. A token provider can return existing tokens for
-a given user so it is recommended that implementers of the `AuthInitialize` and `SecurityManager`
+a token in the `AuthInitialize.getCredentials()` call. A token provider can return existing tokens (which are about to expire) for
+a given user, so it is recommended that implementers of the `AuthInitialize` and `SecurityManager`
 interfaces take imminent timeout and token refresh in consideration to avoid receiving multiple
 unintended `AuthenticationExpiredException`s in a row and having to deal with the propagation of these
 exceptions.