[geode] branch develop updated: GEODE-9628: Documentation fix for setting credentials in client (#6928)

[db...@apache.org]

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

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


The following commit(s) were added to refs/heads/develop by this push:
     new 091ee88  GEODE-9628: Documentation fix for setting credentials in client (#6928)
091ee88 is described below

commit 091ee88b4f1bd032ea5b1198a9bc3c73915d5bf9
Author: Dave Barnes <db...@apache.org>
AuthorDate: Tue Oct 5 09:22:33 2021 -0700

    GEODE-9628: Documentation fix for setting credentials in client (#6928)
    
    * GEODE-9568 Documentation fix for setting credentials in client (format & style)
---
 .../implementing_authentication.html.md.erb        | 221 +++++++++++----------
 1 file changed, 111 insertions(+), 110 deletions(-)

diff --git a/geode-docs/managing/security/implementing_authentication.html.md.erb b/geode-docs/managing/security/implementing_authentication.html.md.erb
index 6f02fc6..4429708 100644
--- a/geode-docs/managing/security/implementing_authentication.html.md.erb
+++ b/geode-docs/managing/security/implementing_authentication.html.md.erb
@@ -23,132 +23,133 @@ Authentication lends a measure of security to a cluster
 by verifying the identity of components as they connect to the system.
 All components use the same authentication mechanism.
 
-## How Authentication Works
+## <a id="authentication-how-it-works"></a>How Authentication Works
 
-When a component initiates a connection to the cluster,
-the `SecurityManager.authenticate` method is invoked.
-The component provides its credentials in the form of properties
-as a parameter to the `authenticate` method.
-The credential is presumed to be the two properties
-`security-username` and `security-password`.
+When a component initiates a connection to the cluster, the `SecurityManager.authenticate` method is invoked.
+The component provides its credentials in the form of properties as a parameter to the `authenticate` method.
+
+The credentials parameter is generated by the `security-client-auth-init` class's `getCredentials()` call,
+for example a token, a certificate, or a user/password combination.
 The `authenticate` method is expected to either return an object
 representing a principal or throw an `AuthenticationFailedException`.
 
-A well-designed `authenticate` method will have a set of known user and password pairs that can be
-compared to the credential presented or will have a way of obtaining those pairs.
+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.
 
-## How a Server Sets Its Credential
+## <a id="authentication-server-set-creds"></a>How a Server Sets Its Credentials
 
-In order to connect with a locator that does authentication,
-a server will need to set its credential, composed of the two properties
-`security-username` and `security-password`.
-Choose one of these two ways to accomplish this:
-
-- Set `security-username` and `security-password` in the server's
-`gfsecurity.properties` file that will be read upon server start up,
-as in the example
-
-    ``` pre
-    security-username=admin
-    security-password=xyz1234
-    ```
-    The user name and password are stored in the clear, so the
-    `gfsecurity.properties` file must be protected by restricting access with
-    file system permissions.
-
-- Implement `AuthInitialize` interface for the server.
-    
-    - Set the property `security-peer-auth-init`,
-    so that an object of the class that implements the `AuthInitialize`
-    interface will be instantiated.
-    Set the property to one of these two values:
-
-        - Set property `security-peer-auth-init` to the fully-qualified
-        class name that implements the `AuthInitialize` interface
-        as in the example
-
-        ``` pre
-        security-peer-auth-init=com.example.security.ServerAuthenticate
-        ```
-        - Set property `security-peer-auth-init` to the fully-qualified
-        method name of a method that instantiates an object of the class
-        that implements the `AuthInitialize` interface
-        as in the example
-
-        ``` pre
-        security-peer-auth-init=com.example.security.ServerAuthenticate.create
-        ```
-
-    - Implement the `getCredentials` method within the `AuthInitialize`
-    interface to acquire values for
-    the `security-username` and `security-password` properties
-    in whatever way it wishes.
-    It might look up values in a database or another external resource.
-
-Gateway senders and receivers communicate as a component of their
-server member.
-Therefore, the credential of the server become those of the gateway
-sender or receiver.
-
-## How a Client Cache Sets Its Credential
-
-In order to connect with a locator or a server that does authentication,
-a client will need to set its credential, composed of the two properties
+In order to connect with a locator that performs authentication,
+a server must set its credentials, a username and password specified as the two properties
 `security-username` and `security-password`.
-Follow these steps to accomplish this:
 
-- Implement `AuthInitialize` interface for the client.
+Choose one of two ways to set the server credentials:
+
+- Add settings to the server properties file, if the credentials comprise a simple username/password combination,  or
+- Implement the `AuthInitialize` interface for the server
+
+### <a id="authentication-setserverprops"></a>Add Settings to the Server Properties File
+
+Set `security-username` and `security-password` in the server's
+`gfsecurity.properties` file, which is read upon server startup.
+For example:
+
+``` pre
+security-username=admin
+security-password=xyz1234
+```
+The username and password are stored in the clear, so the
+`gfsecurity.properties` file must be protected by restricting access with
+file system permissions.
+
+### <a id="authentication-implementserverinterface"></a>Implement the AuthInitialize Interface for the Server
+
+To implement the `AuthInitialize` interface for the server, set the
+`security-peer-auth-init` property so that an object of the class that implements the `AuthInitialize`
+interface will be instantiated. There are two ways to do this:
+
+- You can set the `security-peer-auth-init` property to the fully-qualified class name that implements
+   the `AuthInitialize` interface as in the example
+
+  ``` pre
+  security-peer-auth-init=com.example.security.ServerAuthenticate
+  ```
+
+- You can set the `security-peer-auth-init` property to the fully-qualified method name of a method
+that instantiates an object of the class that implements the `AuthInitialize` interface as in the
+example
+
+  ``` pre
+  security-peer-auth-init=com.example.security.ServerAuthenticate.create
+  ```
+
+Implement the `getCredentials` method within the `AuthInitialize` interface to acquire values for
+the `security-username` and `security-password` properties in whatever way you wish.  For example,
+it might look up values in a database or another external resource.
+
+Gateway senders and receivers communicate as components of their respective server members. Therefore, the
+credentials of the server become those of the gateway sender or receiver.
+
+## <a id="authentication-client-set-creds"></a>How a Client Cache Sets its Credentials
+
+In order to connect with a locator or a server that performs authentication,
+a client must set its credentials. The credentials parameter is generated by the `security-client-auth-init` class's `getCredentials()` call,
+for example a token, a certificate, or a user/password combination.
+
+You must perform two actions to set to set the client credentials:
+
+- Implement the `AuthInitialize` interface for the client
+- Provide `Authinitialize.getCredentials()` with secure access to the client credentials
+
+### <a id="authentication-implementclientinterface"></a>Implement the AuthInitialize Interface for the Client
+
+To implement the `AuthInitialize` interface for the client, set the `security-client-auth-init` property,
+so that an object of the class that implements the `AuthInitialize` interface will be instantiated.
+There are two ways to do this:
+
+- You can set the `security-client-auth-init` property to the fully-qualified
+class name that implements the `AuthInitialize` interface as in the example:
+
+  ``` pre
+  security-client-auth-init=com.example.security.ClientAuthInitialize
+  ```
 
-    - Set the property `security-client-auth-init`,
-    so that an object of the class that implements the
-    `AuthInitialize` interface will be instantiated.
-    Set the property to one of these two values:
+- You can set the `security-client-auth-init` property to the fully-qualified
+name of a static method that instantiates an object of the class
+that implements the `AuthInitialize` interface as in the example
 
-        - Set property `security-client-auth-init` to the fully-qualified
-        class name that implements the `AuthInitialize` interface:
+  ``` pre
+  security-client-auth-init=com.example.security.ClientAuthInitialize.create
+  ```
 
-        ``` pre
-        security-client-auth-init=com.example.security.ClientAuthInitialize
-        ```
-        - Set property `security-client-auth-init` to the fully-qualified
-        name of a static method that instantiates an object of the class
-        that implements the `AuthInitialize` interface:
+Implement the `getCredentials()` method of the `AuthInitialize` interface for the client to acquire values for
+the `security-username` and `security-password` properties in whatever way
+wish. For example, it might look up values in a database or another external resource,
+or it might prompt for values.
 
-        ``` pre
-        security-client-auth-init=com.example.security.ClientAuthInitialize.create
-        ```
 
-    - Implement the `getCredentials` method of the `AuthInitialize` interface
-    for the client.
-    The implementation of `getCredentials` acquires values for
-    the `security-username` and `security-password` properties in whatever way
-    it wishes.
-    It might look up values in a database or another external resource,
-    or it might prompt for values.
+### <a id="authentication-provideclientcredaccess"></a>Provide Secure Access to Client Credentials
 
-- Set the `security-username` and `security-password` properties for the client
-  in a way that can be accessed by the `getCredentials` implementation in the
-  `AuthInitialize`. This can be done via the APIs, properties file or other external
-  sources:
+Set the `security-username` and `security-password` properties for the client in a way that can be
+accessed by the `getCredentials` implementation in `AuthInitialize`. This can be done via the APIs,
+properties file or other external sources:
 
-    ``` pre
-    Properties properties = new Properties();
-    properties.setProperty("security-username", "exampleuser23");
-    properties.setProperty("security-password", "xyz1234");
-    ClientCache cache = new ClientCacheFactory(properties).create();
-    ```
+``` pre
+Properties properties = new Properties();
+properties.setProperty("security-username", "exampleuser23");
+properties.setProperty("security-password", "xyz1234");
+ClientCache cache = new ClientCacheFactory(properties).create();
+```
 
-    Take care that credentials set in this manner are not accessible
-    to observers of the code.
- 
+For security, take care that credentials set in this manner are not accessible to observers of the code.
 
 
-## How Other Components Set Their Credentials
+## <a id="authentication-component-set-creds"></a>How Other Components Set Their Credentials
 
-`gfsh` prompts for the user name and password upon invocation of
-a`gfsh connect` command.
+`gfsh` prompts for the username and password upon invocation of
+a`gfsh connect` command. These username/password combinations will be provided as properties
+to the `authenticate` method in the keys of `security-username` and `security-password`.
 
-Pulse prompts for the user name and password upon start up.
+Pulse prompts for the username and password upon start up.
 
 Due to the stateless nature of the REST API,
 a web application or other component that speaks to a server or locator
@@ -156,18 +157,18 @@ via the REST API goes through authentication on each request.
 The header of the request needs to include attributes that define values for
 `security-username` and `security-password`.
 
-## Implement SecurityManager Interface
+## <a id="authentication-implement-security-mgr"></a>Implement SecurityManager Interface
 
 Complete these items to implement authentication done by either a
 locator or a server.
 
 - Decide upon an authentication algorithm.
 The [Authentication Example](authentication_examples.html)
-stores a set of user name and
+stores a set of username and
 password pairs that represent the identities of components
 that will connect to the system.
-This simplistic algorithm returns the user name as a principal
-if the user name and password passed to the `authenticate` method
+This simplistic algorithm returns the username as a principal
+if the username and password passed to the `authenticate` method
 are a match for one of the stored pairs.
 - Define the `security-manager` property.
 See [Enable Security with Property Definitions](enable_security.html)