Initial contents for authentication using new integrated security. [#129183221]
Project: http://git-wip-us.apache.org/repos/asf/incubator-geode/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-geode/commit/f778e4a3 Tree: http://git-wip-us.apache.org/repos/asf/incubator-geode/tree/f778e4a3 Diff: http://git-wip-us.apache.org/repos/asf/incubator-geode/diff/f778e4a3 Branch: refs/staging/docs-grant1 Commit: f778e4a393ac7a59c2d0056c09872b057f6e0260 Parents: 4ad23a1 Author: Karen Miller <[email protected]> Authored: Thu Sep 8 14:25:48 2016 -0700 Committer: Karen Miller <[email protected]> Committed: Thu Sep 8 14:25:48 2016 -0700 ---------------------------------------------------------------------- .../authentication_overview.html.md.erb | 6 +- .../implementing_authentication.html.md.erb | 84 ++++++-------------- 2 files changed, 29 insertions(+), 61 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/f778e4a3/managing/security/authentication_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/managing/security/authentication_overview.html.md.erb b/managing/security/authentication_overview.html.md.erb index 8ab3558..ad3af66 100644 --- a/managing/security/authentication_overview.html.md.erb +++ b/managing/security/authentication_overview.html.md.erb @@ -2,11 +2,13 @@ title: Authentication --- -A distributed system using authentication verifies the identities of peers, clients, and and other communicating entities. +Authentication verifies the identities of components within the distributed +system such as peers, clients, and those connecting to a JMX manager. - **[Implementing Authentication](../../managing/security/implementing_authentication.html)** - Apache Geode provides a flexible framework for your security authentication plug-ins. You choose the method of authentication, such as LDAP or PKCS, and program the plug-ins accordingly. + All components of the distributed system authenticate the same way, + through a custom-written method. - **[Encrypting Passwords for Use in cache.xml](../../managing/security/encrypting_passwords.html)** http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/f778e4a3/managing/security/implementing_authentication.html.md.erb ---------------------------------------------------------------------- diff --git a/managing/security/implementing_authentication.html.md.erb b/managing/security/implementing_authentication.html.md.erb index e7ae1d1..9bbb9d3 100644 --- a/managing/security/implementing_authentication.html.md.erb +++ b/managing/security/implementing_authentication.html.md.erb @@ -2,69 +2,35 @@ title: Implementing Authentication --- -Apache Geode provides a flexible framework for your security authentication plug-ins. You choose the method of authentication, such as LDAP or PKCS, and program the plug-ins accordingly. +Authentication lends a measure of security to a distributed system +by verifying the identity of components as they connect to the system. +All components use the same authentication mechanism. ## How Authentication Works -Joining members provide credentials to existing members who check the credentials and either reject the joining member or approve it. +When a component initiates a connection to the distributed system, +the `SecurityManager.authenticate` method is invoked. +The component provides credentials in the form of `Properties`, +which are passed to the `authenticate` method. +The `authenticate` method is expected to either return an object +representing a principal or throw an `AuthenticationFailedException`. -If approved, the connection request returns a `java.security.Principal` object, used to identify the member in future operations. - -- Joining peer members are authenticated by the locator to which they connect. -- Clients are authenticated by their server during the connection initialization and for each operation request. -- Servers may be authenticated by their clients during the connection initialization. -- Depending on the member, the new member may in turn become an authenticator to other joining members. Members joining a system must trust that existing members are already authenticated. - -Locators maintain and distribute the authenticated member list. The distributed member list is also authenticated by all members, which prevents an unauthorized application from introducing itself into membership by distributing a member list that includes itself. - -<img src="../../images/security-1.gif" id="how_authentication_works__image_D3AE53AB4E0441A5A078E5D07EC20C5D" class="image" /> - -Geode authentication provides a flexible plug-in framework. Any security infrastructure can be plugged in to the system as long as the plug-ins implement the required Geode interfaces. -## Enable Authentication with Property Definitions ## Implement SecurityManager Interface -## <a id="implementing_authentication__section_0ECD014AA498429FA72B1DB8FB9C040B" class="no-quick-link"></a>Locators That Require Authentication - -Colocated locators, such as those started with the LocatorLauncher API, do not require security settings because they do not join the distributed system as individual members. - -All other standalone locators, including those started with the `gfsh start locator` command must be configured with the correct security settings. - -## <a id="how_authentication_works__section_3C5F1D7D27CC4C85B01F6F91AA602ED6" class="no-quick-link"></a>Client Authentication Options - -The Geode client can connect in two different ways: - -1. **Process level**. Each pool creates a configured minimum number of connections across the server group. The pool accesses the least loaded server for each cache operation. This type of connection is required. Process level connections represent the overall client process and are the default way a client accesses the server cache. -2. **User level**. Each client user/pool pair creates a connection to one server and then sticks with it for operations. If the server is unable to respond to a request, the pool selects a new one for the user. This type of connection is created *from* the process level connection. These connections represent individual users established within the client process. These connections are generally used by application servers or web servers that act as clients to Geode servers. A single application or web server process can service a large number of users, each with their own unique identification and with varied access permissions. - -By default, the server pools in clients use process level authentication. You can enable user level authentication by setting the poolâs multiuser-authentication attribute to true. Process level and user level pools can be used inside one client if needed. - -<img src="../../images/security-3.gif" id="how_authentication_works__image_A16EEDE08B0D480187F1C757E6A31140" class="image" /> - -## <a id="how_authentication_works__section_79E28941E4A74318AF3B4B85525F9CA9" class="no-quick-link"></a>Client Authentication Process - -The client authentication process occurs for each connection established by a pool, regardless of whether the pool is configured for process-wide or single user connections. All credentials are checked for each connection between client and server, including the server-to-client notification channel. - -1. When the client requests a new connection: - 1. The server authenticates the clientâs credentials and assigns it an internal principal, used to authorize client operations in the server cache - 2. The server generates a random unique identifier and returns it to the client to use in its next request - -2. For each operation request after the initial connection is established: - 1. The client sends the request with the unique identifier it received from the server in the last communication. - 2. The server verifies the identifier and processes the request, then responds with a new randomly generated unique identifier, for the client to include in its next request. - -This ever-changing identifier provides protection against replay attacks, because each client request must include the unique identifier. The server never processes the same request twice. For the most secure communication, add encryption, like Diffie-Hellman. - -If the connection fails after the client has sent a request and before the server can respond, the next server request fails due to an invalid unique identifier, and the client pool automatically establishes a new connection to the server system for the client. - -## <a id="how_authentication_works__section_05201B3F7B8D466C97EEE5235C749984" class="no-quick-link"></a>When a Member Fails to Join - -The following describe the scenarios that occur when a member fails to join: - -- Peer credentials are initialized and verified automatically when a member joins a distributed system. - - If a joining member has invalid credentials, the `CacheFactory.create` method throws an `AuthenticationFailedException`. - - If a joining member does not provide credentials, the request throws an `AuthenticationRequiredException`. -- Client credentials are initialized and verified automatically during the initial connection process. - - If client authentication fails due to invalid credentials, the server sends an `AUTHENTICATION_FAILED` message back to the client. The client handshake fails, and an `AuthenticationFailedException` is thrown for the current operation. - - If the client authentication fails due to missing credentials, the server sends a `NO_AUTHENTICATION` message back to the client. The client connection fails, and an `AuthenticationRequiredException` is thrown for the current operation. - +Complete these items to implement authentication. + +- Decide upon an authentication algorithm. +The [Authentication Example](authentication_examples.html) +stores a set of user name 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 +are a match for one of the stored pairs. +- Define the `security-manager` and `security-enabled-components` properties. +See [Enable Security with Property Definitions](enable_security.html) +for details about these properties. +- Implement the `authenticate` method of the `SecurityManager` interface. +- Define any extra resources that the implemented authentication algorithm +needs in order to make a decision.
