XDR security

This page describes the login process between XDR nodes and how to set up access control.

Your cluster must have security enabled with a valid configuration file.

The login flow applies from each source node to each destination node independently. The xdr-client tend thread follows the login process as described in the following stages.

The login process establishes the connection from the source node to the destination node.

a. If the connection from the tend thread is successful, it logs an info message
Terminal window
```
INFO (xdr-client): (cluster.c:2278) connected to destdc 172.17.0.5:3116
```
b. If login fails, it retries the connection to the destination node.
Once the connection is established, it logs in to each destination node if access control is configured in the xdr dc sub-stanza.

a. If login is successful, it logs an info message.
Terminal window
```
INFO (xdr-client): (cluster.c:1539) logged in to node 172.17.0.5:3116 - session-ttl 120
```
b. If login fails, it logs warning messages then goes back to Step 1.
Terminal window
```
WARNING (xdr-client): (cluster.c:1470) login to node 172.17.0.5:3116 failed: 65
WARNING (xdr-client): (cluster.c:1470) (repeated:11) login to node 172.17.0.5:3116 failed: 65
```
c. If security is not enabled on the destination node, it logs an info message after successfully establishing the connection by the tend thread.
Terminal window
```
INFO (xdr-client): (cluster.c:1463) security not configured on node 172.17.0.5:3116
```
Once the login is successful, the access token is refreshed one minute before the session-ttl configured on the destination node during the login. It logs an info message.
Terminal window
```
INFO (xdr-client): (cluster.c:1045) refreshing session token for destdc 172.17.0.5:3116
```
a. If login succeeds during refreshing access token, it logs an info message.
Terminal window
```
INFO (xdr-client): (cluster.c:1539) logged in to node 172.17.0.5:3116 - session-ttl 120
```
b. If login fails during refreshing access token, it logs a warning message then goes back to Step 1.
Terminal window
```
WARNING (xdr-client): (cluster.c:1470) login to node 172.17.0.5:3116 failed: 65
```
If the connection is broken any time after successful establishment due to node (source or destination) restart or any other reason, it goes back to Step 1.

These log items and flow are limited to connections and login by the xdr-client tend thread. They do not include connections by other xdr-client threads.

Authorized user and password file

For either access control or LDAP, if the target cluster has security enabled, add the following parameters to the source cluster configuration. Make sure this file is adequately secured.

auth-mode specifies the mode of authentication.
auth-user specifies the name of a user with read/write permissions on the target cluster. Must be accompanied by auth-password-file and auth-mode.
auth-password-file points to a file that contains the password of the username specified in auth-user. The value of auth-password-file can also be stored in HashiCorp Vault. See Optional security with Vault integration.
In Database 6.4 and later, the value of auth-password-file can be fetched using the Secret Agent. See Integrating with secrets management services.

See examples of these parameters in Securing with access control and Securing with LDAP.

Contents of security configuration file

$ less /private/security-credentials-DC1.txt
passwordOnDestination

Securing with access control

For background on configuring Aerospike’s local-to-the-server user access control, see Configuring Access Control.

For an explanation of the auth-user and auth-password-file parameters, see Authorized user and password file.

DC sub-stanza for access control

xdr {
    dc dataCenter1 {
        node-address-port someIpAdress1 somePort1
           ...
           auth-mode internal
           auth-user somebodyOnDestination1
           # auth-user must be accompanied by auth-password-file
           auth-password-file /private/security-credentials-DC1.txt
           namespace someNamespace {
             ...
           }
        }
    dc dataCenter2 {
        node-address-port someIpAdress2 somePort2
           ...
           auth-mode internal
           auth-user somebodyOnDestination2
           # auth-user must be accompanied by auth-password-file
           auth-password-file /private/security-credentials-DC2.txt
           namespace someNamespace {
             ...
           }
        }
 }

Securing with access control using PKI (versions 5.7+)

The following example secures the connection with a TLS certificate and uses the common name (CN) in the certificate as username to authenticate at the destination cluster. No need to specify password in this mode as the TLS certificate validity authenticates the user.

xdr {
    dc dataCenter1 {
        node-address-port someIpAdress1 somePort1 someTlsNameDefinition1
        tls-name localTls
        auth-mode pki
        namespace someNamespace {
          ...
        }
    }
    ...
}

Securing with LDAP

For background about configuring LDAP, see Configuring LDAP.

For an explanation of the auth-user and auth-password-file parameter, see Authorized user and password file.
If you are using LDAP authentication, auth-mode must be set to external.

DC sub-stanza for LDAP with auth-mode external

xdr {
    dc dataCenter1 {
        node-address-port someIpAdress1 somePort1
           ...
           auth-mode external
           auth-user somebodyOnDestination1
           auth-password-file /private/security-credentials-DC1.txt
           namespace someNamespace {
             ...
           }
        }
 }

Securing with TLS

Consider implementing TLS among the cluster nodes. For details, see TLS Configuration.

TLS is configured in the tls stanza of the configuration file. This stanza defines variable names based on TLS certificates. In this example for XDR, the variable names someTlsNameDefinition... and localTls are variable references to TLS certificates you have installed on your system and configured in the tls stanza.
The xdr stanza only refers to those TLS variable name definitions.
Those TLS variable name definitions come after the port number of the node-address-port parameter.

The following example secures the connection with a TLS certificate and with LDAP user authentication auth-mode external.

xdr {
    dc dataCenter1 {
        node-address-port 10.0.0.100 4333 destination-cluster-tls-name
        tls-name this-cluster-tls-name
        auth-mode external // auth-mode only necessary if using security
        auth-user somebodyOnDestination1 // auth-user only necessary if using security
        auth-password-file /private/security-credentials-DC1.txt // auth-password-file only necessary if using security
        namespace someNamespace {
          ...
        }
    }
    ...
}