How Authentication Works

With authentication, joining members provide credentials to existing members who check the credentials and either reject the joining member or approve it. 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 .
  • Gateways mutually authenticate each other when they connect.

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 an member list that includes itself.



GemFire 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 GemFire interfaces.

Client Authentication Options

The GemFire 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 GemFire 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.



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.

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 DistributedSystem.connect 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.