IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Back up a cluster’s configuration Restore a cluster’s security configuration »

› › ›

Back up a cluster’s security configuration

edit

Back up a cluster’s security configuration

edit

Security configuration information resides in two places: files and indices.

Back up file-based security configuration

edit

Elasticsearch security features are configured using the xpack.security namespace inside the elasticsearch.yml and elasticsearch.keystore files. In addition there are several other extra configuration files inside the same ES_PATH_CONF directory. These files define roles and role mappings and configure the file realm. Some of the settings specify file paths to security-sensitive data, such as TLS keys and certificates for the HTTP client and inter-node communication and private key files for SAML, OIDC and the Kerberos realms. All these are also stored inside ES_PATH_CONF; the path settings are relative.

The elasticsearch.keystore, TLS keys and SAML, OIDC, and Kerberos realms private key files require confidentiality. This is crucial when files are copied to the backup location, as this increases the surface for malicious snooping.

To back up all this configuration you can use a conventional file-based backup, as described in the previous section.

File backups must run on every cluster node.
File backups will store non-security configuration as well. Backing-up only security features configuration is not supported. A backup is a point in time record of state of the complete configuration.

Back up index-based security configuration

edit

Elasticsearch security features store system configuration data inside a dedicated index. This index is named .security-6 in the Elasticsearch 6.x versions and .security-7 in the 7.x releases. The .security alias always points to the appropriate index. This index contains the data which is not available in configuration files and cannot be reliably backed up using standard filesystem tools. This data describes:

the definition of users in the native realm (including hashed passwords)
role definitions (defined via the create roles API)
role mappings (defined via the create role mappings API)
application privileges
API keys

The .security index thus contains resources and definitions in addition to configuration information. All of that information is required in a complete security features backup.

Use the standard Elasticsearch snapshot functionality to backup .security, as you would for any other data index. For convenience, here are the complete steps:

Create a repository that you can use to backup the .security index. It is preferable to have a dedicated repository for this special index. If you wish, you can also snapshot the system indices for other Elastic Stack components to this repository.
```
PUT /_snapshot/my_backup
{
  "type": "fs",
  "settings": {
    "location": "my_backup_location"
  }
}
```
The user calling this API must have the elevated manage cluster privilege to prevent non-administrators exfiltrating data.
Create a user and assign it only the built-in snapshot_user role.

The following example creates a new user snapshot_user in the native realm, but it is not important which realm the user is a member of:
```
POST /_security/user/snapshot_user
{
  "password" : "secret",
  "roles" : [ "snapshot_user" ]
}
```

Create incremental snapshots authorized as snapshot_user.

The following example shows how to use the create snapshot API to backup the .security index to the my_backup repository:

PUT /_snapshot/my_backup/snapshot_1
{
  "indices": ".security",
  "include_global_state": true 
}

This parameter value captures all the persistent settings stored in the global cluster metadata as well as other configurations such as aliases and stored scripts. Note that this includes non-security configuration and that it complements but does not replace the filesystem configuration files backup.

The index format is only compatible within a single major version, and cannot be restored onto a version earlier than the version from which it originated. For example, you can restore a security snapshot from 6.6.0 into a 6.7.0 cluster, but you cannot restore it to a cluster running Elasticsearch 6.5.0 or 7.0.0.

Controlling access to the backup repository

edit

The snapshot of the security index will typically contain sensitive data such as user names and password hashes. Because passwords are stored using cryptographic hashes, the disclosure of a snapshot would not automatically enable a third party to authenticate as one of your users or use API keys. However, it would disclose confidential information.

It is also important that you protect the integrity of these backups in case you ever need to restore them. If a third party is able to modify the stored backups, they may be able to install a back door that would grant access if the snapshot is loaded into an Elasticsearch cluster.

We recommend that you:

Snapshot the .security index in a dedicated repository, where read and write access is strictly restricted and audited.
If there are indications that the snapshot has been read, change the passwords of the users in the native realm and revoke API keys.
If there are indications that the snapshot has been tampered with, do not restore it. There is currently no option for the restore process to detect malicious tampering.

« Back up a cluster’s configuration Restore a cluster’s security configuration »