> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security in a Distributed Environment

> In this article, we shall consider that each member of a cluster is a distributed cube.
> Moreover, we may use interchangeably the terms: distributed cube, member, or node to describe a
> member of the cluster. The last two terms are in line with the [JGroups](http://www.jgroups.org/)
> terminology, and arguably with distributed architectures in general.

Security in a distributed ActivePivot cluster, and more specifically access permission, can be
handled within ActivePivot.

There are two types of security you have to consider when working with a distributed
cluster:

* Cluster Security, a security layer designed to prevent unwanted cluster members from connecting
  to the cluster.
* User Security, a security layer designed to prevent a given user from authenticating to a
  specific node, which lets the developer take advantage of the Authentication Policies relevant for
  the ActivePivot server instance hosting that cube.

## Cluster Security

The first security layer is designed to prevent unwanted members from joining a given distributed
cluster.

It is already embedded within JGroups, the third-party library implementing the
communication layer that ActivePivot leverages for its distributed architecture feature.

### The Key-Based Authentication Token

Users have to define a key (as a String) in the JGroup configuration file (by default,
`protocol.xml`).

The protocol layer then encrypts this key, and adds it as a header in the JOIN\_REQUEST messages sent
by all the cubes to join the cluster. A member whose key does not match the keys of the
registered members will receive a security error and be treated as undesired.

> For this reason, all members of a cluster must be configured with the same private key within
> their respective `protocol.xml` configuration file.

For each cube, three additional parameters must be specified:

| Parameter   | Description                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| auth\_class | The location of the class that defines the security layer. Format: packageName.ClassName, as a string. |
| auth\_value | The key to encrypt, as a string.                                                                       |
| token\_hash | The name of the algorithm used to encrypt the key. MD5 and SHA are available.                          |

Configuration example:

```xml theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
<config>
  ...
  <AUTH auth_class="com.quartetfs.biz.pivot.distribution.security.impl.CustomAuthToken"
            auth_value="password"
            token_hash="MD5"/>
  ...
</config>
```

You can also use any of the classes defined by JGroups, detailed
[here](http://www.jgroups.org/javadoc/org/jgroups/auth/package-summary.html).

### Customization

ActivePivot fully supports Cluster Security customization. To create a security layer mechanism, follow these steps:

1. Create a new class that extends `org.jgroups.auth.AuthToken`.

2. Define the desired attributes and their setters.
   ```java theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
   class MyAuthToken extends org.jgroups.auth.AuthToken {
       protected String auth_value = null;
       protected String hash_type = "MD5";

       @Property
       public void setAuthValue(String auth_value) {
           this.auth_value = encrypt(auth_value);
       }

       @Property(name="token_hash")
       public void setHashType(String hash_type) {
           this.hash_type = hash_type;
       }

       ...
   }
   ```
   > The @Property annotation is mandatory

3. Implement the `authenticate` method, which validates if a node can join the cluster or not.

4. Implement an `encrypt` method if the user wants to encrypt the key.

5. Implement the `getName` method to return `this.getClass().getName()` (mandatory).

6. Implement `#writeTo(...)` and `#readFrom(...)` to serialize the token.

7. Match the `protocol.xml` fields with the correct attributes defined in the custom class.

### Simultaneous Authentication Mechanisms

You can define more than one authentication method in the `protocol.xml` file. To do so, each
AUTH element must have an `id` attribute with a unique integer value.

## User Security

Unlike Cluster Security, User Security has nothing to do with JGroups. It is related to
ActivePivot's usual authentication policy, the user's authentication to the data nodes.

First the user authenticates on a query node. The current implementation then forwards the username
to every other node in the cluster (the nodes that have cleared the Cluster Security layer) relevant
for each of the user's requests. This approach requires the user to authenticate on all the
different ActivePivot server instances.

### User Roles

ActivePivot's distributed architecture is seamlessly able to use the authorization mechanisms
defined outside of the distribution environment, which means that no additional configuration is
required other than the one already defined on a single cube.

A `IUserDetailsService` is still needed in a distributed environment. ActivePivot needs to
retrieve a user's information from his username, in case his permissions vary on an
application basis.