<commit_before>---
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.

## <a id="implementing_authentication__section_C31BA8EEE6134F0EBE6761D70EF7DE41" class="no-quick-link"></a>Procedure

Use the following procedure to implement authentication in your Geode application:

1.  Determine the method of authentication, such as LDAP or PKCS, that you will use. It is assumed that you know how to use it.
2.  Determine any special properties required for your authentication's credentials initialization and decide how you will get the properties to the initialization method. Depending on how sensitive the properties are and on your application requirements, you may do a combination of these:
    -   Pass the additional properties through the `gemfire.properties` file (or `gfsecurity.properties` file if you are creating a special restricted access file for security configuration) settings or programmatically, using the `set` methods in the `ClientCacheFactory`, before the call to the `create` method. All properties starting with `security-` are automatically passed to the `AuthInitialize` implementation.
    -   Obtain the properties dynamically in the `AuthInitialize.getCredentials` method.

3.  For joining members, program and configure the credentials initialization plug-in:
    1.  Create an implementation of the Geode `com.gemstone.gemfire.security.AuthInitialize` interface.
        1.  Program a public static method to return an instance of the class.
        2.  Program the `getCredentials` method to create all properties required by the `Authorize` method via the member's credentials.

    2.  For peers and locators, set the `gemfire.properties` (or `gfsecurity.properties` file if you are creating a special restricted access file for security configuration) `security-peer-auth-init` to the fully qualified name of the static method you programmed that returns an instance of the class. In these examples, the method is named `create`. Example:

        ``` pre
        //Peer init example where myAuthInitImpl.create returns the 
        //instance of AuthInitialize 
        security-peer-auth-init=myAuthPkg.myAuthInitImpl.create
        ```

    3.  For clients, set the `gemfire.properties` (or `gfsecurity.properties` file if you are creating a special restricted access file for security configuration) `security-client-auth-init` to the fully qualified name of the method you programmed that returns an instance of the AuthInitialize class. Example:

        ``` pre
        //Client init example where myAuthInitImpl.create returns 
        //the instance of AuthInitialize 
        security-client-auth-init=myAuthPkg.myAuthInitImpl.create
        ```

    4.  For all members, set any additional `gemfire.properties` (or `gfsecurity.properties` file if you are creating a special restricted access file for security configuration) `security-*` properties required by your `AuthInitialize` implementation.

4.  For authorizing members, program and configure the credentials authorization plug-in:
    1.  Implement the Geode `com.gemstone.gemfire.security.Authenticator` interface:
        1.  Program a public static, zero-argument method to return an instance of the class.
        2.  Program the `authenticate` method to authenticate the credentials and return a `java.security.Principal` object.

    2.  For peers and locators set the `gemfire.properties` (or `gfsecurity.properties` file if you are creating a special restricted access file for security configuration) `security-peer-authenticator` to the fully qualified name of the method that returns an instance of the `Authenticator` class. Example:

        ``` pre
        //Peer auth example where myAuthenticatorImpl.create 
        //returns the instance of Authenticator
        security-peer-authenticator=myAuthPkg.myAuthenticatorImpl.create
        ```

    3.  For servers, set the `gemfire.properties` (or `gfsecurity.properties` file if you are creating a special restricted access file for security configuration)`security-client-authenticator` to the fully qualified name of the method that returns an instance of the Authenticator class. Example:

        ``` pre
        //Client auth example where myAuthenticatorImpl.create 
        //returns the instance of Authenticator
        security-client-authenticator=myAuthPkg.myAuthenticatorImpl.create
        ```

    4.  For all members, set any additional `gemfire.properties` (or `gfsecurity.properties` file if you are creating a special restricted access file for security configuration)`security-*` properties required by your `Authenticator` implementation.

5.  For all members, provide the list of authenticated locators in the `gemfire.properties`.

## <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.


# How Authentication Works

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.
-   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 an 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.

## <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.<commit_msg>Integrated Security: Update section organization for authentication.  Note that content of sections will be done as another task. [#128343687]<commit_after>---
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.

## How Authentication Works

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.
-   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 an 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.
{'fraction_non_alphanumeric': 0.045892427080545896, 'fraction_numerical': 0.017192935509767193, 'mean_word_length': 4.65179584120983, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 21, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7586910', 'n_tokens_mistral': 3534, 'n_tokens_neox': 3363, 'n_words': 1869}