# README * [📖 Docs for Elasticsearch plugin](/develop/elasticsearch) * [📖 Docs for Kibana plugin](/develop/kibana) The documentation of an open source product should also be open source! Found a problem? Edit the file directly from GitHub! ## Getting started * [🚀 Kibana Multi-User with ROR PRO](/develop/examples/multiuser_guide) * [🚀 Kibana Multi-Tenancy with ROR Enterprise](/develop/examples/multitenancy_guide) * [🚀 ECK with ROR](/develop/eck) [⬅️ Elasticsearch plugin project](https://github.com/sscarduzio/elasticsearch-readonlyrest-plugin) (Github) # For Elasticsearch ## Overview ReadonlyREST is a light-weight Elasticsearch plugin that adds encryption, authentication, authorization and access control capabilities to Elasticsearch embedded REST API. The core of this plugin is an ACL engine that checks each incoming request through a sequence of **rules** a bit like a firewall. There are a dozen rules that can be grouped in sequences of blocks and form a powerful representation of a logic chain. The Elasticsearch plugin known as `ReadonlyREST Free` is released under the GPLv3 license, or alternatively a commercial license (see [ReadonlyREST Embedded](https://readonlyrest.com/embedded)) and lays the technological foundations for the companion Kibana plugin which is released in two versions: [ReadonlyREST PRO](https://readonlyrest.com/pro) and [ReadonlyREST Enterprise](https://readonlyrest.com/enterprise). Unlike the Elasticsearch plugin, the Kibana plugins are commercial only. But rely on the Elasticsearch plugin in order to work. For a description of the Kibana plugins, skip to the [dedicated documentation page](/develop/kibana) instead. ### ReadonlyREST Free plugin for Elasticsearch In this document, we are going to describe how to operate the Elasticsearch plugin in all its features. Once installed, this plugin will greatly extend the Elasticsearch HTTP API (port 9200), adding numerous extra capabilities: * **Encryption**: transform the Elasticsearch API from HTTP to HTTPS * **Authentication**: require credentials * **Authorization**: declare groups of users, permissions and partial access to indices. * **Access control**: complex logic can be modeled using an ACL (access control list) written in YAML. * **Audit events**: a trace of the access requests can be logged to a file or index (or both). #### Flow of a Search Request The following diagram models an instance of Elasticsearch with the ReadonlyREST plugin installed and configured with SSL encryption and an ACL with at least one "allow" type ACL block. ![readonlyrest request processing diagram](/files/C6wi5xgsdjWb5TYxbxvF) 1. The User Agent (i.e. cURL, Kibana) sends a search request to Elasticsearch using port 9200 and the HTTPS URL schema. 2. The HTTPS filter in the ReadonlyREST plugin unwraps the SSL layer and hands over the request to the Elasticsearch HTTP stack 3. The HTTP stack in Elasticsearch parses the HTTP request 4. The HTTP handler in Elasticsearch extracts the indices, action, request type, and creates a `SearchRequest` (internal Elasticsearch format). 5. The SearchRequest goes through the ACL (access control list), external systems like LDAP can be asynchronously queried, and an exit result is eventually produced. 6. The exit result is used by the audit event serializer, to write a record to index and/or Elasticsearch log file 7. If no ACL block was matched, or if a `type: forbid` block was matched, ReadonlyREST does not forward the search request to the search engine and creates an "unauthorized" HTTP response. 8. In case the ACL matches a `type: allow` block, the request is forwarded to the search engine 9. The Elasticsearch code creates a search response containing the results of the query 10. The search response is converted to an HTTP response by the Elasticsearch code 11. The HTTP response flows back to ReadonlyREST's HTTPS filter and to the User agent ## Installation and Operations ### Running with Docker The simplest method to run Elasticsearch with the ReadonlyREST plugin is to use one of our docker images which you can find on [Docker Hub](https://hub.docker.com/r/beshultd/elasticsearch-readonlyrest): ```bash docker run -u root -p 9200:9200 -e "I_UNDERSTAND_AND_ACCEPT_ES_PATCHING=yes" -e "KIBANA_USER_PASS=kibana" -e "ADMIN_USER_PASS=admin" -e "discovery.type=single-node" beshultd/elasticsearch-readonlyrest:8.14.3-ror-latest ``` OR with [Docker Compose](https://docs.docker.com/compose/): ```yaml # docker-compose.yml file content services: es-ror: image: beshultd/elasticsearch-readonlyrest:8.14.3-ror-latest user: "0:0" ports: - "9200:9200" environment: - I_UNDERSTAND_AND_ACCEPT_ES_PATCHING=yes - KIBANA_USER_PASS=kibana - ADMIN_USER_PASS=admin - discovery.type=single-node ``` (To run the docker-compose.yml call `docker compose up`) Any of these methods, runs Elasticsearch container with ReadonlyREST with [init settings](https://github.com/sscarduzio/elasticsearch-readonlyrest-plugin/blob/develop/docker-image/init-readonlyrest.yml). When the service is started you can test it using curl or Postman: ``` curl -v -u admin:admin https://localhost:9200 ``` #### Customizing ROR settings You can create locally customized `readonlyrest.yml` file and mount it as a [docker volume](https://docs.docker.com/storage/volumes/). Assuming that your ROR settings file is located in `/tmp/my-readonlyrest.yml` you can use it like that: ```bash docker run -u root -p 9200:9200 -e "discovery.type=single-node" -e "I_UNDERSTAND_AND_ACCEPT_ES_PATCHING=yes" -v /tmp/my-readonlyrest.yml:/etc/share/elasticsearch/config/readonlyrest.yml beshultd/elasticsearch-readonlyrest:8.14.3-ror-latest ``` OR ```yaml # docker-compose.yml file content services: es-ror: image: beshultd/elasticsearch-readonlyrest:8.14.3-ror-latest user: "0:0" ports: - "9200:9200" environment: - I_UNDERSTAND_AND_ACCEPT_ES_PATCHING=yes - KIBANA_USER_PASS=kibana - ADMIN_USER_PASS=admin - discovery.type=single-node volumes: - ./my-readonlyrest.yml:/etc/share/elasticsearch/config/readonlyrest.yml # we assume that the `my-readonlyrest.yml` file is in the same folder as `docker-compose.yml` file is ``` #### ### Installing the plugin To install the ReadonlyREST plugin for Elasticsearch: #### 1. Obtain the build From the [official download page](https://readonlyrest.com/download). Select your Elasticsearch version and send yourself a link to the compatible ReadonlyREST zip file. #### 2. Install the build ```bash bin/elasticsearch-plugin install file:///tmp/readonlyrest-X.Y.Z_esW.Q.U.zip ``` Notice how we need to type in the format `file://` + absolute path (yes, with three slashes). ``` @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: plugin requires additional permissions @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ ``` When prompted about additional permissions, answer **y**. #### 3. Patch Elasticsearch If you are using Elasticsearch 6.7.0 or newer, you need **an extra post-installation step**. Depending on the [Elasticsearch version](https://github.com/sscarduzio/elasticsearch-readonlyrest-plugin/blob/master/ror-tools-core/src/main/scala/tech/beshu/ror/tools/core/patches), this command might tweak the main Elasticsearch installation files and/or copy some jars to `plugins/readonlyrest` directory. ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar patch --I_UNDERSTAND_AND_ACCEPT_ES_PATCHING=yes ``` **⚠️IMPORTANT**: The command above runs in silent mode with the `--I_UNDERSTAND_AND_ACCEPT_ES_PATCHING=yes` flag. Without this flag, the patcher runs in interactive mode and will prompt you to confirm that you understand and accept the implications of ES patching. **⚠️IMPORTANT**: for Elasticsearch 8.3.x or newer, the patching operation requires `root` user privileges. You can verify if Elasticsearch was correctly patched using the command `verify`: ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar verify ``` Please note that the tool assumes that you run it from the root of your ES installation directory or the default installation directory is `/usr/share/elasticsearch`. But if you want or need, you can instruct it where your Elasticsearch is installed by executing one of the tool's command with the `--es-path` parameter: ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar patch --es-path /my/custom/path/to/es/folder ``` or ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar verify --es-path /my/custom/path/to/es/folder ``` **NB:** In case of any problems with the `ror-tools`, please call: ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar --help ``` #### 4. Create settings file Create and edit the `readonlyrest.yml` settings file in the **same directory where `elasticsearch.yml` is found**: ```bash vim $ES_PATH_CONF/conf/readonlyrest.yml ``` Now write some basic settings, just to get started. In this example, we are going to tell ReadonlyREST to require HTTP Basic Authentication for all the HTTP requests, and return `401 Unauthorized` otherwise. ```yaml readonlyrest: access_control_rules: - name: "Require HTTP Basic Auth" type: allow auth_key: user:password ``` #### 5. Start Elasticsearch ```bash bin/elasticsearch ``` or: ```bash service start elasticsearch ``` Depending on your environment. Now you should be able to see the logs and ReadonlyREST-related lines like the one below: ``` [2018-09-18T13:56:25,275][INFO ][o.e.p.PluginsService ] [c3RKGFJ] loaded plugin [readonlyrest] ``` #### 7. Test everything is working The following command should succeed, and the response should show a status code 200. ```bash curl -vvv -u user:password "http://localhost:9200/_cat/indices" ``` The following command should not succeed, and the response should show a status code 401 ```bash curl -vvv "http://localhost:9200/_cat/indices" ``` ### Upgrading the plugin To upgrade ReadonlyREST for Elasticsearch: #### 1. Stop Elasticsearch. Either kill the process manually, or use: ```bash service stop elasticsearch ``` depending on your environment. #### 2. Unpatch Elasticsearch If you are using Elasticsearch 6.7.0 or newer, you need **an extra pre-uninstallation step**. This will remove all previously copied jars from ROR's installation directory. ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar unpatch ``` You can verify if Elasticsearch was correctly unpatched using the command `verify`: ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar verify ``` **NB:** In case of any problems with the `ror-tools`, please call: ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar --help ``` #### 3. Uninstall ReadonlyREST ```bash bin/elasticsearch-plugin remove readonlyrest ``` #### 4. Install the new version of ReadonlyREST into Elasticsearch. ```bash bin/elasticsearch-plugin install file:///readonlyrest-_es.zip ``` e.g. ```bash bin/elasticsearch-plugin install file:///tmp/readonlyrest-1.56.0_es8.12.2.zip ``` #### 5. Patch Elasticsearch If you are using Elasticsearch 6.7.0 or newer, you need **an extra post-installation step**. Depending on the [Elasticsearch version](https://github.com/sscarduzio/elasticsearch-readonlyrest-plugin/blob/master/ror-tools-core/src/main/scala/tech/beshu/ror/tools/core/patches), this command might tweak the main Elasticsearch installation files and/or copy some jars to the `plugins/readonlyrest` directory. ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar patch --I_UNDERSTAND_AND_ACCEPT_ES_PATCHING=yes ``` **⚠️IMPORTANT**: The command above runs in silent mode with the `--I_UNDERSTAND_AND_ACCEPT_ES_PATCHING=yes` flag. Without this flag, the patcher runs in interactive mode and will prompt you to confirm that you understand and accept the implications of ES patching. **⚠️IMPORTANT**: For Elasticsearch 8.3.x or newer, the patching operation requires `root` user privileges. You can verify if Elasticsearch was correctly patched using the command `verify`: ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar verify ``` **NB:** In case of any problems with the `ror-tools`, please call: ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar --help ``` #### 6. Restart Elasticsearch ```bash bin/elasticsearch ``` or: ```bash service start elasticsearch ``` Depending on your environment. Now you should be able to see the logs and ReadonlyREST-related lines like the one below: ``` [2024-03-14T20:21:49,589][INFO ][t.b.r.b.RorInstance ] [ROR_SINGLE_1] ReadonlyREST was loaded ... ``` ### Removing the plugin #### 1. Stop Elasticsearch. Either kill the process manually, or use: ```bash service stop elasticsearch ``` depending on your environment. #### 2. Unpatch Elasticsearch If you are using Elasticsearch 6.7.0 or newer, you need **an extra pre-uninstallation step**. This will remove all previously copied jars from ROR's installation directory. ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar unpatch ``` You can verify if Elasticsearch was correctly unpatched using the command `verify`: ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar verify ``` **NB:** In case of any problems with the `ror-tools`, please call: ```bash jdk/bin/java -jar plugins/readonlyrest/ror-tools.jar --help ``` #### 3. Uninstall ReadonlyREST from Elasticsearch: ```bash bin/elasticsearch-plugin remove readonlyrest ``` #### 4. Start Elasticsearch. ```bash bin/elasticsearch ``` or: ```bash service start elasticsearch ``` Depending on your environment. ### Upgrading Elasticsearch The ReadonlyREST plugin version must always match the currently installed Elasticsearch version. As a result, if you want to upgrade Elasticsearch: 1. Before upgrading Elasticsearch, unpatch and uninstall the ReadonlyREST plugin according to the instructions: * [Unpatch Elasticsearch and uninstall the plugin](#removing-the-plugin) 2. Upgrade Elasticsearch. 3. After upgrading Elasticsearch, install the matching version of the ReadonlyREST plugin and patch according to the instructions: * [Install matching plugin version and patch Elasticsearch](#installing-the-plugin) {% hint style="warning" %} Upgrading Elasticsearch without following the instructions above may cause corruption of the ES installation and inability to patch the upgraded version. {% endhint %} ### Deploying ReadonlyREST in a stable production cluster Unless some advanced features are being used (see below), this Elasticsearch plugin operates like a lightweight, stateless filter glued in front of Elasticsearch HTTP API. Therefore it's sufficient to install the plugin **only in the nodes that expose the HTTP interface** (port 9200). Installing ReadonlyREST in a dedicated node has numerous advantages: * No need to restart all nodes, only the one you have installed the plugin into. * No need to restart all nodes to update the security settings * No need to restart all nodes when a security update is out * Less complexity on the actual cluster nodes. For example, if we want to move to HTTPS all the traffic coming from Logstash into a 9-node Elasticsearch cluster which has been running stable in production for a while, it's not necessary to install the ReadonlyREST plugin in all the nodes. Creating a dedicated, lightweight ES node where to install ReadonlyREST: 1. (Optional) [disable the HTTP interface](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-http.html#_disable_http) from all the existing nodes 2. Create a new, lightweight, dedicated node without shards, nor master eligibility. 3. Configure ReadonlyREST with SSL [encryption](#encryption) in the new node 4. Configure Logstash to connect to the new node directly in HTTPS. #### An exception **⚠️IMPORTANT** By default when the `fields` [rule](#fields) is used, it's required to install the ReadonlyREST plugin in all the data nodes. ## Elasticsearch Configuration ReadonlyREST uses two distinct kinds of settings: * **ACL settings** — the access control rules defined in `readonlyrest.yml` (or stored in an Elasticsearch index). Every node in the cluster must share the same ACL settings. Subscribers of the [PRO](https://readonlyrest.com/pro) or [Enterprise](https://readonlyrest.com/enterprise) Kibana plugin can also reload ACL settings at runtime through the GUI (see [Cluster-wide Settings VS readonlyrest.yml](/develop/kibana#cluster-wide-settings-vs-readonlyrestyml)) or via the [ReadonlyREST API](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/readonlyrest-api.md). * **Node settings** — settings placed in `elasticsearch.yml` that are specific to each Elasticsearch node. They control how ROR behaves during startup, where to look for ACL settings, and how SSL is configured. These settings are read once at node startup and are not shared between nodes. The sections below describe the node settings that go into `elasticsearch.yml`. > **Note:** All ROR node settings described below can also be provided as JVM system properties (e.g. `-Dreadonlyrest.settings.index_name=.my-ror-index`), using the same dot-separated key that appears in the YAML. ### Encryption SSL/TLS encryption protects data in transit between clients and Elasticsearch. ReadonlyREST supports two independent encryption layers: 1. **External REST API** — client ↔ Elasticsearch traffic (port 9200) 2. **Internode transport** — node ↔ node traffic (port 9300) #### Choosing between ReadonlyREST SSL and XPack Security SSL There are two ways to configure SSL in an Elasticsearch cluster running ReadonlyREST: * **ReadonlyREST SSL** — SSL provided by the ReadonlyREST plugin itself (described in the subsections below). * **XPack Security SSL** — SSL provided by Elasticsearch's built-in `xpack.security` module. The choice depends on whether `xpack.security.enabled` is set to `true` or `false` in `elasticsearch.yml`: | `xpack.security.enabled` | SSL to use | | ------------------------ | ------------------ | | `false` | ReadonlyREST SSL | | `true` | XPack Security SSL | **Why does this matter?** During its patching step, ReadonlyREST deactivates XPack Security's authentication and authorization features — these are replaced by ROR's ACL engine. However, **XPack SSL is not deactivated**. This means that when `xpack.security.enabled: true`, XPack SSL is still fully active and must be configured through Elasticsearch's standard mechanism, not through ROR. > **Recommendation:** Because `xpack.security` enables features used by Elasticsearch and Kibana (e.g. API keys, token service, certain Kibana integrations), it should not be disabled without a clear reason. If there is no specific requirement to disable it, prefer leaving `xpack.security.enabled: true` and use XPack Security SSL. #### XPack Security SSL (when `xpack.security.enabled: true`) When `xpack.security.enabled` is `true`, configure SSL by following the official Elasticsearch documentation: * [Set up basic security (internode TLS)](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-basic-setup.html) * [Set up basic security plus HTTPS (REST API TLS)](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-basic-setup-https.html) ROR's ACL will handle authentication and authorization, while XPack manages the SSL layer transparently. #### ReadonlyREST SSL (when `xpack.security.enabled: false`) The following subsections describe how to configure SSL using ReadonlyREST's own SSL implementation. This applies only when `xpack.security.enabled` is set to `false` in `elasticsearch.yml`. > **Configuration placement:** All SSL settings — including `http.type`, `transport.type`, `readonlyrest.ssl.*`, and `readonlyrest.ssl_internode.*` — must be placed in `elasticsearch.yml`. **External REST API** Encrypts traffic between clients and Elasticsearch on port 9200. Add the following to your `elasticsearch.yml`. **Keystore option (JKS or PKCS#12):** ```yaml http.type: ssl_netty4 readonlyrest.ssl.keystore_file: "keystore.jks" # also accepts .p12 (PKCS#12) readonlyrest.ssl.keystore_pass: "" readonlyrest.ssl.key_pass: "" readonlyrest.ssl.key_alias: "my-server-cert" # optional; if omitted, ROR uses the first alias found in the keystore # Optional: restrict accepted TLS versions and cipher suites readonlyrest.ssl.allowed_protocols: [TLSv1.2, TLSv1.3] readonlyrest.ssl.allowed_ciphers: [TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256] # Optional: mutual TLS — require clients to present a certificate readonlyrest.ssl.client_authentication: false # default # Optional: custom trust anchor for client certificates (defaults to JVM truststore) readonlyrest.ssl.truststore_file: "truststore.jks" readonlyrest.ssl.truststore_pass: "" ``` **PEM option (preferred):** ```yaml http.type: ssl_netty4 readonlyrest.ssl.server_certificate_key_file: "private_key.pem" readonlyrest.ssl.server_certificate_file: "fullchain.pem" # Optional: custom trust anchor for client certificates readonlyrest.ssl.client_trusted_certificate_file: "trusted_certs.pem" ``` All certificate files must be placed in the same directory as `elasticsearch.yml`. **Verify SSL is working** After restarting Elasticsearch, confirm SSL is active by querying the cluster health endpoint: ```bash # Full validation with a custom CA (self-signed or internal CA) curl --cacert /path/to/ca-chain.pem \ https://your-domain:9200/_cluster/health \ -u admin:your_password ``` If your certificate was issued by a public CA (Let's Encrypt or any commercial CA), the system trust store is sufficient and `--cacert` can be omitted: ```bash curl https://your-domain:9200/_cluster/health -u admin:your_password ``` Expected result: HTTP 200 with a JSON body containing `"status":"green"` or `"status":"yellow"`. **Internode communication — transport module** Encrypts traffic between nodes in the Elasticsearch cluster on port 9300. This configuration must be added to all nodes in the cluster. **`elasticsearch.yml`:** ```yaml transport.type: ror_ssl_internode readonlyrest.ssl_internode.keystore_file: "keystore.jks" # also accepts .p12 (PKCS#12) readonlyrest.ssl_internode.keystore_pass: "" readonlyrest.ssl_internode.key_pass: "" readonlyrest.ssl_internode.key_alias: "my-node-cert" # optional; if omitted, ROR uses the first alias found in the keystore ``` The keystore file must be placed in the same directory as `elasticsearch.yml`. **Internode communication with XPack nodes** It is possible to set up internode SSL between ROR nodes (with `xpack.security.enabled: false`) and XPack nodes. This requires ES 6.7.0 or newer. Generate a certificate for the ROR node following the [Elasticsearch certificate generation guide](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-basic-setup.html#generate-certificates). The generated `elastic-certificates.p12` can then be used in the ROR node: ```yaml readonlyrest.ssl_internode.enable: true readonlyrest.ssl_internode.keystore_file: "elastic-certificates.p12" readonlyrest.ssl_internode.keystore_pass: "" readonlyrest.ssl_internode.key_pass: "" readonlyrest.ssl_internode.truststore_file: "elastic-certificates.p12" readonlyrest.ssl_internode.truststore_pass: "" readonlyrest.ssl_internode.client_authentication: true # default: false readonlyrest.ssl_internode.certificate_verification: true readonlyrest.ssl_internode.hostname_verification: false # default: false ``` **Certificate verification** By default, certificate verification is disabled for internode SSL. This means any certificate is accepted without validation — useful in local or test environments. In production, it is advised to enable this option. ```yaml readonlyrest.ssl_internode.certificate_verification: true ``` This option applies to internode SSL only. **Hostname verification** By default, hostname verification is disabled. This means the hostname or IP address is not checked against the names in the certificate. > **Production:** Enable hostname verification alongside certificate verification for full transport security. ```yaml readonlyrest.ssl_internode.hostname_verification: true ``` **Client authentication** By default, the server does not request a client certificate. When enabled, Elasticsearch verifies the client's identity via mutual TLS. For external REST API: ```yaml readonlyrest.ssl.client_authentication: true ``` For internode communication: ```yaml readonlyrest.ssl_internode.client_authentication: true ``` **Allowed protocols and ciphers** Optionally, restrict the accepted TLS versions and cipher suites. Connections from clients not supporting the listed values will be dropped. For external REST API: ```yaml readonlyrest.ssl.allowed_protocols: [TLSv1.2, TLSv1.3] readonlyrest.ssl.allowed_ciphers: [TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256] ``` For internode communication: ```yaml readonlyrest.ssl_internode.allowed_protocols: [TLSv1.2, TLSv1.3] readonlyrest.ssl_internode.allowed_ciphers: [TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256] ``` ReadonlyREST logs available ciphers and protocols supported by the current JVM at startup: ``` [2018-01-03T10:09:38,683][INFO ][t.b.r.e.SSLTransportNetty4] ROR SSL: Available ciphers: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA [2018-01-03T10:09:38,684][INFO ][t.b.r.e.SSLTransportNetty4] ROR SSL: Restricting to ciphers: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [2018-01-03T10:09:38,684][INFO ][t.b.r.e.SSLTransportNetty4] ROR SSL: Available SSL protocols: TLSv1,TLSv1.1,TLSv1.2 [2018-01-03T10:09:38,685][INFO ][t.b.r.e.SSLTransportNetty4] ROR SSL: Restricting to SSL protocols: TLSv1.2 ``` **Custom truststore** Replaces the default JVM truststore. The truststore file must be placed in the same directory as `elasticsearch.yml`. For external REST API: ```yaml readonlyrest.ssl.truststore_file: "truststore.jks" readonlyrest.ssl.truststore_pass: "" ``` For internode communication: ```yaml readonlyrest.ssl_internode.truststore_file: "truststore.jks" readonlyrest.ssl_internode.truststore_pass: "" ``` When not specified, ReadonlyREST uses the default JVM truststore. **Using Let's Encrypt** Shows how to use Let's Encrypt certificates with ReadonlyREST. The same approach applies to certificates from other providers. You can use PEM files directly without creating a keystore — see the PEM option in the [External REST API](#external-rest-api) section above. In that case, only step 1 below is needed. **1. Obtain certificates** ```bash certbot certonly --standalone -d DOMAIN.TLD -d DOMAIN_2.TLD --email EMAIL@EMAIL.TLD ``` Change to the certificate directory (typically `/etc/letsencrypt/live/DOMAIN.TLD`). The files you need are `fullchain.pem` and `privkey.pem`. **2. Create a PKCS#12 keystore** ```bash openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out keystore.p12 -name ror ``` You will be prompted to set a password for the `.p12` file. Remember it — you will need it in the next step. **3. Convert to JKS (optional)** Skip this step if you use `keystore.p12` directly — ReadonlyREST supports both PKCS#12 and JKS formats. ```bash keytool -importkeystore \ -srckeystore keystore.p12 \ -srcstoretype PKCS12 \ -srcstorepass STORE_PASS \ # password set in step 2 -destkeystore keystore.jks \ -deststorepass PASSWORD_STORE \ # protects keystore.jks → readonlyrest.ssl.keystore_pass -destkeypass PASSWORD_KEYPASS \ # protects the private key entry → readonlyrest.ssl.key_pass -alias ror ``` > `PASSWORD_STORE` and `PASSWORD_KEYPASS` can be the same value — most deployments use a single password for simplicity. `STORE_PASS` must match the password set in step 2. The resulting keystore maps to your ROR configuration as follows: ```yaml readonlyrest.ssl.keystore_file: "keystore.jks" readonlyrest.ssl.keystore_pass: "PASSWORD_STORE" # -deststorepass from step 3 readonlyrest.ssl.key_pass: "PASSWORD_KEYPASS" # -destkeypass from step 3 ``` If you get `java.io.IOException: failed to decrypt safe contents entry: javax.crypto.BadPaddingException: Given final block not properly padded`, the `STORE_PASS` value does not match the password set in step 2. (Credits for the original JKS tutorial to [Maximilian Boehm](https://maximilian-boehm.com)) **FIPS mode** If you need FIPS 140-2 compliant SSL, ReadonlyREST supports it via the BouncyCastle library and BCFKS keystore format. See [FIPS mode](/develop/elasticsearch/fips) for setup instructions. ### ACL settings source configuration By default, ROR looks for ACL settings in a `readonlyrest.yml` file located next to `elasticsearch.yml`, and also watches a dedicated Elasticsearch index for settings updates. The following options let you customize this behavior. #### Settings file and index ```yaml readonlyrest: settings: index_name: .my-ror-index # default: .readonlyrest file_path: /custom/readonlyrest.yml # default: /readonlyrest.yml max_size: 10 MB # default: 3 MB — maximum allowed size of ACL settings loaded from the index ``` #### Index loading strategy When loading from index (the default), ROR polls the index periodically and retries on failure during startup. Both the poll interval and the startup retry behavior can be tuned: ```yaml readonlyrest: load_from_index: poll_interval: 5s # how often to check the index for ACL settings changes (default: 5s, set to 0s to disable polling) initial_loading_retry_strategy: initial_delay: 5s # delay before the first attempt to load from the index at startup (default: 5s) attempts_interval: 5s # interval between retry attempts if the index is not yet available (default: 5s) attempts_count: 5 # maximum number of retry attempts before falling back to file (default: 5) ``` Setting `poll_interval` to `0s` disables periodic polling — ROR will load ACL settings from the index once at startup and will not check for changes until the node is restarted. #### Force loading from file When set to `true`, ROR will only load ACL settings from the file and will never attempt to read from the Elasticsearch index. This is typically used during recovery when in-index settings have become corrupted — see [Malformed in-index settings](/develop/kibana#malformed-in-index-settings). ```yaml readonlyrest: force_load_from_file: true ``` Default: `false`. ### Request handling during ES startup Each incoming request to the Elasticsearch node passes to the installed plugin. During Elasticsearch node startup, the plugin rejects incoming requests until it is fully initialized. The plugin rejects such requests with `403` forbidden responses by default. To change this behavior, add the following to `elasticsearch.yml`: ```yaml readonlyrest: not_started_response_code: 503 failed_to_start_response_code: 503 ``` `not_started_response_code` — HTTP code returned while the plugin has not yet finished starting. Allowed values: `403` (default), `503`. `failed_to_start_response_code` — HTTP code returned when the plugin failed to start (e.g. due to a malformed ACL). Allowed values: `403` (default), `503`. ## ReadonlyREST ACL ### ACL basics The core of this plugin is an ACL (access control list). A logic structure very similar to the one found in firewalls. The ACL is part of the plugin configuration, and it's written in YAML. * The ACL is composed of an *ordered* sequence of named **blocks** * Each block contains some **rules**, and a policy (forbid or allow) * HTTP requests run through the blocks, starting from the first, * The *first* block that satisfies *all the rules* decides if to forbid or allow the request (according to its policy). * If none of the blocks is matched, the request is rejected **⚠️IMPORTANT**: The ACL blocks are **evaluated sequentially**, therefore **the ordering of the ACL blocks is crucial**. The order of the rules inside an ACL block instead, is irrelevant. ```yaml readonlyrest: access_control_rules: - name: "Block 1 - only Logstash indices are accessible" type: allow # <-- default policy type is "allow", so this line could be omitted indices: ["logstash-*"] # <-- This is a rule - name: "Block 2 - Blocking everything from a network" type: forbid hosts: ["10.0.0.0/24"] # <-- this is a rule ``` *An Example of the Access Control List (ACL) made of 2 blocks.* The YAML snippet above, like all of this plugin's settings should be saved inside the `readonlyrest.yml` file. Create this file **on the same path where `elasticsearch.yml` is found**. **TIP**: If you are a subscriber of the [PRO](https://readonlyrest.com/pro) or [Enterprise](https://readonlyrest.com/enterprise) Kibana plugin, you can edit and refresh the settings through a GUI. For more on this, see the [documentation for the ReadonlyREST plugin for Kibana](/develop/kibana). ### Blocks of rules Every block **must** have at least the `name` field, and optionally a `type` field valued either "allow" or "forbid". If you omit the `type`, your block will be treated as `type: allow` by default. Keep in mind that ReadonlyREST ACL is a white list, so by default all request are blocked, unless you specify a block of rules that allows all or some requests. * `name` will appear in logs, so keep it short and distinctive. * `type` can be either `allow` or `forbid`. Can be omitted, default is `allow`. ```yaml - name: "Block 1 - Allowing anything from localhost" type: allow # In real life now you should increase the specificity by adding rules here (otherwise this block will allow all requests!) ``` *Example: the simplest example of an allow block.* #### Unauthorized response configuration When the request does not match any of the ACL blocks or the request matches the block with the `forbid` policy, the plugin rejects such requests with the `403` response code and `forbidden` content. You can change the content of the response as follows: ```yaml readonlyrest: global_settings: response_if_req_forbidden: Forbidden by ReadonlyREST ES plugin # custom response for all forbidden requests access_control_rules: - name: "Block 1" type: # extended format for `type` property policy: allow indices: ["logstash-*"] - name: "Block 2" type: # extended format for `type` property policy: forbid # response returned when a request matches 'Block 2' (setting on the block level takes precedence over the global setting) response_message: "You are unauthorized to access this resource" indices: ["templates-*"] ``` See also [response\_if\_req\_forbidden](#response_if_req_forbidden) section. ### Rules ReadonlyREST access control rules can be divided into the following categories: * Authentication & Authorization rules * Elasticsearch level rules * Kibana-related rules * HTTP level rules * Network level rules Please refrain from using HTTP level rules to protect certain indices or limit what people can do to an index. The level of control at this level is really coarse, especially because Elasticsearch REST API does not always respect RESTful principles. This makes of HTTP a bad abstraction level to write ACLs in Elasticsearch all together. The only **clean and exhaustive** way to implement access control is to reason about requests **AFTER ElasticSearch has parsed** them. Only then, the list of affected **indices** and the **action** will be known for sure. See **Elasticsearch level** rules. #### Authentication & Authorization rules This section contains description of rules that can be used to authenticate and/or authorize users. Most of the following rules use HTTP Basic Auth, so the credentials are passed with the `Authorization` header and they can be easily decoded when the request is intercepted by a malicious third party. Please note that this authentication method is secure only if SSL is enabled. **`auth_key`** `auth_key: sales:p455wd` It's an authentication rule that accepts [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). Configure this value *in clear text*. Clients will need to provide the header e.g. `Authorization: Basic c2FsZXM6cDQ1NXdk` where "c2FsZXM6cDQ1NXdk" is Base64 for "sales:p455wd". **⚠️IMPORTANT**: this rule is handy just for tests, replace it with another rule that hashes credentials, like: `auth_key_sha512`, or `auth_key_unix`. [Impersonation](/develop/kibana/impersonation) is supported by this rule without an extra configuration. **`auth_key_sha512`** `auth_key_sha512: 280ac6f...94bf9` The authentication rule that accepts [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). The value is a string like `username:password` *hashed in* [*SHA512*](https://md5calc.com/hash/sha512). Clients will need to provide the usual Authorization header. There are also available other rules with less secure SHA algorithms `auth_key_sha256` and `auth_key_sha1`. The rules support also alternative syntax, where only password is hashed, eg: `auth_key_sha512: "admin:280ac6f...94bf9"` In the example below `admin` is the username and `280ac6f...94bf9` is the hashed secret. [Impersonation](/develop/kibana/impersonation) is supported by these rules by default. **`auth_key_pbkdf2`** `auth_key_pbkdf2: "KhIxF5EEYkH5GPX51zTRIR4cHqhpRVALSmTaWE18mZEL2KqCkRMeMU4GR848mGq4SDtNvsybtJ/sZBuX6oFaSg=="` # logstash:logstash `auth_key_pbkdf2: "logstash:JltDNAoXNtc7MIBs2FYlW0o1f815ucj+bel3drdAk2yOufg2PNfQ51qr0EQ6RSkojw/DzrDLFDeXONumzwKjOA=="` # logstash:logstash The authentication rule that accepts [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). The value is hashed in the same way as it's done in `auth_key_sha512` rule, but it uses [*PBKDF2*](https://en.wikipedia.org/wiki/PBKDF2) key derivation function. At the moment there is no way to configure it, so during the hash generation, the user has to take into consideration the following PBKDF2 input parameters values: | Input parameter | Value | Comment | | --------------------- | -------------------------- | --------------------------------------------------------------------------- | | Pseudorandom function | HmacSHA512 | | | Salt | use hashed value as a salt | eg. hashed value = `logstash:logstash`, use `logstash:logstash` as the salt | | Iterations count | 10000 | | | Derived key length | 512 | bits | The hash can be calculated using [this calculator](https://8gwifi.org/pbkdf.jsp) (notice that the salt has to base Base64 encoded). [Impersonation](/develop/kibana/impersonation) is supported by this rule without an extra configuration. **`auth_key_unix`** `auth_key_unix: test:$6$rounds=65535$d07dnv4N$QeErsDT9Mz.ZoEPXW3dwQGL7tzwRz.eOrTBepIwfGEwdUAYSy/NirGoOaNyPx8lqiR6DYRSsDzVvVbhP4Y9wf0 # Hashed for "test:test"` **⚠️IMPORTANT** this hashing algorithm is **very CPU intensive**, so we implemented a caching mechanism around it. However, this will not protect Elasticsearch from a DoS attack with a high number of requests with random credentials. This is authentication rule that is based on `/etc/shadow` file syntax. If you configured sha512 encryption with 65535 rounds on your system the hash in /etc/shadow for the account `test:test` will be `test:$6$rounds=65535$d07dnv4N$QeErsDT9Mz.ZoEPXW3dwQGL7tzwRz.eOrTBepIwfGEwdUAYSy/NirGoOaNyPx8lqiR6DYRSsDzVvVbhP4Y9wf0` ```yaml readonlyrest: access_control_rules: - name: Accept requests from users in group team1 on index1 groups_any_of: ["team1"] indices: ["index1"] users: - username: test auth_key_unix: test:$6$rounds=65535$d07dnv4N$QeErsDT9Mz.ZoEPXW3dwQGL7tzwRz.eOrTBepIwfGEwdUAYSy/NirGoOaNyPx8lqiR6DYRSsDzVvVbhP4Y9wf0 #test:test groups: ["team1"] ``` You can generate the hash with **mkpasswd** Linux command, you need whois package `apt-get install whois` (or equivalent) `mkpasswd -m sha-512 -R 65534` Also you can generate the hash with a python script (works on Linux): ```python #!/usr/bin/python import crypt import random import sys import string def sha512_crypt(password, salt=None, rounds=None): if salt is None: rand = random.SystemRandom() salt = ''.join([rand.choice(string.ascii_letters + string.digits) for _ in range(8)]) prefix = '$6$' if rounds is not None: rounds = max(1000, min(999999999, rounds or 5000)) prefix += 'rounds={0}$'.format(rounds) return crypt.crypt(password, prefix + salt) if __name__ == '__main__': if len(sys.argv) > 1: print sha512_crypt(sys.argv[1], rounds=65635) else: print "Argument is missing, " ``` **Finally you have to put your username at the beginning of the hash with ":" separator** `test:$6$rounds=65535$d07dnv4N$QeErsDT9Mz.ZoEPXW3dwQGL7tzwRz.eOrTBepIwfGEwdUAYSy/NirGoOaNyPx8lqiR6DYRSsDzVvVbhP4Y9wf0` For example, `test` is the username and `$6$rounds=65535$d07dnv4N$QeErsDT9Mz.ZoEPXW3dwQGL7tzwRz.eOrTBepIwfGEwdUAYSy/NirGoOaNyPx8lqiR6DYRSsDzVvVbhP4Y9wf0` is the hash for `test` (the password is identical to the username in this example). [Impersonation](/develop/kibana/impersonation) is supported by this rule without an extra configuration. **`token_authentication`** An authentication rule that accepts a token sent in the HTTP header (`Authorization` by default). There are two modes of operation: **static token** and **Elasticsearch-native token** (service token or API key). **Static token** ```yaml token_authentication: type: "static" token: "Bearer abc123XYZ" # required, expected HTTP header content containing the token username: "john" # required, the username assigned after successful authentication header: x-custom-authorization # optional, defaults to 'Authorization' ``` The rule matches when the value of the configured header equals the `token` field exactly. For example, for `Authorization: Bearer AAEAAWVsYXN0aWMva2liYW5hL3Rva2Vu`, the `token` value is `Bearer AAEAAWVsYXN0aWMva2liYW5hL3Rva2Vu`. **Elasticsearch service token or API key (Fleet support)** ROR integrates with Elasticsearch's [service token](https://www.elastic.co/guide/en/elasticsearch/reference/current/service-accounts.html) and [API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) APIs to support Elastic Fleet. When `type` is set to `service-token` or `api-key`, ROR delegates token validation to Elasticsearch rather than comparing against a static value. ```yaml token_authentication: type: "service-token" # or "api-key" username: fleet # required, the username assigned after successful authentication header: x-custom-authorization # optional, defaults to 'Authorization' ``` * `service-token` — validates against Elasticsearch service accounts (used by Fleet Server). * `api-key` — validates against Elasticsearch API keys (used by Fleet-enrolled agents). For a complete Fleet setup — including the required `forbid` block for token/API-key management actions and the full set of Fleet index patterns — see the [Elastic Fleet with ReadonlyREST](/develop/elasticsearch/fleet) guide. For a complete walkthrough including credential flow, the `forbid` block rationale, and a runnable example, see the [Elastic Fleet guide](/develop/examples/fleet). [Impersonation](/develop/kibana/impersonation) is supported by this rule without an extra configuration. **`proxy_auth: "*"`** `proxy_auth: "*"` Delegated authentication. Trust that a reverse proxy has taken care of authenticating the request and has written the resolved user name into the `X-Forwarded-User` header. The value "\*" in the example, will let this rule match any username value contained in the `X-Forwarded-User` header. If you are using this technique for authentication using our **Kibana** plugins, don't forget to add this snippet to `conf/kibana.yml`: `readonlyrest_kbn.proxy_auth_passthrough: true` So that Kibana will forward the necessary headers to Elasticsearch. [Impersonation](/develop/kibana/impersonation) is supported by this rule without an extra configuration. **Groups rules** The ACL block will match, when the user belongs to groups matching the specified conditions. The groups rules use the user definitions from [the `users` section](#users-and-groups). In that section, we define static users (and we assign groups to them) or we can authorize dynamic users (and we can map the external groups to the local groups). * the first step of the groups subrules is authorizing the user * after this step, we have an authorized user with information about the authorized groups to which the user belongs * then we check whether the authorized user groups are permitted in context of the rule **`groups_any_of`** The ACL block will match when the user belongs to any of the specified groups (boolean OR logic). Simplified syntax: ```yaml groups_any_of: ["group1", "group2"] ``` Extended syntax: ```yaml groups: any_of: ["group1", "group2"] ``` **`groups_all_of`** This rule is very similar to the above defined `groups_any_of` rule, but this time ALL the groups listed in the array are required (boolean AND logic), as opposed to at least one (boolean OR logic) of the `any_of` rule. Simplified syntax: ```yaml groups_all_of: ["group1", "group2"] ``` Extended syntax: ```yaml groups: all_of: ["group1", "group2"] ``` **`groups_not_any_of`** The ACL block will match when the user belongs to NONE of the specified groups. Simplified syntax: ```yaml groups_not_any_of: ["group1", "group2"] ``` Extended syntax: ```yaml groups: not_any_of: ["group1", "group2"] ``` Looking at the examples above: * ACL block will MATCH for user that belongs to `group0` * ACL block will NOT MATCH for user that belongs only to `group1` * ACL block will NOT MATCH for user that belongs only to `group2` * ACL block will NOT MATCH for user that belongs to both `group1` and `group2` * ACL block will NOT MATCH for user that belongs to `group0`, `group1` and `group2` **`groups_not_all_of`** The ACL block will match when the user does not belong to all the specified groups. Simplified syntax: ```yaml groups_not_all_of: ["group1", "group2"] ``` Extended syntax: ```yaml groups: not_all_of: ["group1", "group2"] ``` Looking at the example above: * ACL block will MATCH for user that belongs to `group0` * ACL block will MATCH for user that belongs only to `group1` * ACL block will MATCH for user that belongs only to `group2` * ACL block will NOT MATCH for user that belongs to both `group1` and `group2` * ACL block will NOT MATCH for user that belongs to `group0`, `group1` and `group2` **groups\_combined** Logic conditions can be combined inside a single ACL block. It applies only to combining one positive logic (`all_of`/`any_of`) with one negative logic (`not_all_of`/`not_any_of`) The ACL block will match, when both conditions are met. ```yaml groups: any_of: ["group1", "group2", "group3"] not_all_of: ["group1", "group2"] ``` Looking at the example above: * ACL block will NOT MATCH for user that belongs only to `group0` (because the `any_of` logic is not satisfied) * ACL block will MATCH for user that belongs only to `group1` (the `any_of` logic is satisfied, the `not_all_of` too, because the user is not member of `group2`) * ACL block will MATCH for user that belongs to `group1` and `group3` for the same reason * ACL block will NOT MATCH for user that belongs to `group1` and `group2` (the `any_of` logic is satisfied, but `not_all_of` is not) **User management** In the `users` section, each entry tells us that: * A given user with a username matching one of patterns in the `username` array ... * belongs to the local groups listed in the `groups` array (example 1 & 2 below) OR belongs to local groups that are result of ["detailed group mapping"](/develop/elasticsearch/groups-rule-mapping) between local group ID and external groups (example 3 below). * when they can be authenticated and (if authorization rule is present) authorized by the present rule(s). In general it looks like this: ```yaml ... - name: "ACL block with groups rule" indices: [x, y] groups_any_of: ["local_group1"] # this group ID is defined in the "users" section users: - username: ["pattern1", "pattern2", ...] groups: ["local_group1", "local_group2", ...] : ... - username: ["pattern1", "pattern2", ...] groups: ["local_group1", "local_group2", ...] : ... : ... - username: ["pattern1", "pattern2", ...] groups: - local_group1: ["external_group1", "external_group2"] - local_group2: ["external_group2"] : ... # `ldap_auth` or `jwt_auth` or `ror_kbn_auth` ``` For details see [User management](#users-and-groups). [Impersonation](/develop/kibana/impersonation) support depends on authentication and authorization rules used in `users` section. For more information on the ROR's authorization rules, see [Authorization rules details](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md) **`ldap_authentication`** simple version: `ldap_authentication: ldap1` extended version: ```yaml ldap_authentication: name: ldap1 cache_ttl: 10 sec ``` It handles LDAP authentication only using the configured LDAP connector (here `ldap1`). Check the [LDAP connector section](#ldap-connector) to see how to configure the connector. **`ldap_authorization`** ```yaml ldap_authorization: name: "ldap1" groups_any_of: ["group3"] cache_ttl: 10 sec ``` * It handles LDAP authorization only using the configured LDAP connector (here `ldap1`). * Groups logic syntax can be uses as part of this rule, as described in the [Checking groups logic section](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md#checking-groups-logic) * It matches when previously authenticated user has groups in LDAP and when he belongs to at least one of the configured `groups_any_of` (OR logic). Alternatively, `all_of`/`not_any_of`/`not_all_of`/combined logic can be used to require users to meet certain conditions concerning group membership, as described [here](#groups_combined) * **⚠️IMPORTANT** the negative groups logic (`not_any_of`/`not_all_of`) cannot be used, when `server_side_groups_filtering` is enabled for LDAP. In that case please use the combined logic, for example with `any_of` positive logic. * Check the [LDAP connector section](#ldap-connector) to see how to configure the connector. **`ldap_auth`** Shorthand rule that combines `ldap_authentication` and `ldap_authorization` rules together. It handles both authentication and authorization using the configured LDAP connector (here `ldap1`). ```yaml ldap_auth: name: "ldap1" groups_any_of: ["group1", "group2"] ``` The same functionality can be achieved using the two rules described below: ```yaml ldap_authentication: ldap1 ldap_authorization: name: "ldap1" groups_any_of: ["group1", "group2"] # match when user belongs to at least one group ``` In both `ldap_auth`and `ldap_authorization`, the `groups` clause can be replaced by `group_and` to require the valid LDAP user must belong to all the listed groups: ```yaml ldap_auth: name: "ldap1" groups_all_of: ["group1", "group2"] # match when user belongs to ALL listed groups ``` Or equivalently: ```yaml ldap_authentication: ldap1 ldap_authorization: name: "ldap1" groups_all_of: ["group1", "group2"] # match when user belongs to ALL listed groups ``` See the dedicated [LDAP section](#ldap-connector) [Impersonation](/develop/kibana/impersonation) support by LDAP rules requires to add [an extra configuration](/develop/kibana/impersonation#defining-mocks-of-the-external-services-optional). * Groups logic syntax can be uses as part of this rule, as described in the [Checking groups logic section](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md#checking-groups-logic) * For more information on the ROR's authorization rules, see [Authorization rules details](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md) **`jwt_authentication`** See below, the dedicated [JSON Web Tokens section](#json-web-token-jwt-auth). It's an authentication rule. [Impersonation](/develop/kibana/impersonation) is not currently supported by this rule. ```yaml readonlyrest: access_control_rules: - name: Valid JWT token kibana: access: ro jwt_authentication: name: "jwt_provider_1" jwt: - name: jwt_provider_1 signature_key: "your_signature_min_256_chars" user_claim: email ``` **`jwt_authorization`** See below, the dedicated [JSON Web Tokens section](#json-web-token-jwt-auth). It's an authorization rule. [Impersonation](/develop/kibana/impersonation) is not currently supported by this rule. * Groups logic syntax can be uses as part of this rule, as described in the [Checking groups logic section](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md#checking-groups-logic) * For more information on the ROR's authorization rules, see [Authorization rules details](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md) ```yaml readonlyrest: access_control_rules: - name: Valid JWT token with a writer group kibana: access: rw jwt_authorization: name: "jwt_provider_1" groups_any_of: ["writer"] - name: Valid JWT token with a viewer and writer groups kibana: access: rw jwt_authorization: name: "jwt_provider_1" groups_all_of: ["writer", "viewer"] jwt: - name: jwt_provider_1 signature_key: "your_signature_min_256_chars" group_ids_claim: resource_access.client_app.group_ids ``` **`jwt_auth`** See below, the dedicated [JSON Web Tokens section](#json-web-token-jwt-auth). It's an authentication and authorization rule at the same time. [Impersonation](/develop/kibana/impersonation) is not currently supported by this rule. * Groups logic syntax can be uses as part of this rule, as described in the [Checking groups logic section](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md#checking-groups-logic) * For more information on the ROR's authorization rules, see [Authorization rules details](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md) ```yaml readonlyrest: access_control_rules: - name: Valid JWT token with a viewer and writer groups kibana: access: rw jwt_auth: name: "jwt_provider_1" groups_all_of: ["writer", "viewer"] jwt: - name: jwt_provider_1 signature_key: "your_signature_min_256_chars" user_claim: email group_ids_claim: resource_access.client_app.group_ids ``` **`external_authentication`** Used to delegate authentication to another server that supports HTTP Basic Auth. See below, the dedicated [External BASIC Auth section](#external-basic-auth) [Impersonation](/develop/kibana/impersonation) support by this rule requires to add [an extra configuration](/develop/kibana/impersonation#defining-mocks-of-the-external-services-optional). For more information on the ROR's authorization rules, see [Authorization rules details](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md) **`groups_provider_authorization`** Used to delegate groups resolution for a user to a JSON microservice. See below, the dedicated [Groups Provider Authorization section](#custom-groups-providers) [Impersonation](/develop/kibana/impersonation) support by this rule requires to add [an extra configuration](/develop/kibana/impersonation#defining-mocks-of-the-external-services-optional). * Groups logic syntax can be uses as part of this rule, as described in the [Checking groups logic section](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md#checking-groups-logic) * For more information on the ROR's authorization rules, see [Authorization rules details](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md) **`ror_kbn_authentication`** ([Enterprise](https://readonlyrest.com/enterprise)) For [Enterprise](https://readonlyrest.com/enterprise) customers only, required for SAML authentication. From ROR's perspective it authenticates users. ```yaml readonlyrest: access_control_rules: - name: "ReadonlyREST Enterprise instance" ror_kbn_authentication: name: "kbn1" ror_kbn: - name: kbn1 signature_key: "shared_secret_kibana1" # <- use environmental variables for better security! ``` It handles authentication only using the configured ROR KBN connector (here `kbn1`). Continue reading about this in the kibana plugin documentation, in the dedicated [SAML section](/develop/kibana#saml) [Impersonation](/develop/kibana/impersonation) is currently not supported by this rule. **`ror_kbn_authorization`** ([Enterprise](https://readonlyrest.com/enterprise)) For [Enterprise](https://readonlyrest.com/enterprise) customers only. From ROR's perspective it authorizes users. ```yaml readonlyrest: access_control_rules: - name: "ReadonlyREST Enterprise instance #1" ror_kbn_authorization: name: "kbn1" groups_any_of: ["SAML_GRP_1", "SAML_GRP_2"] # <- use this field when a user should belong to at least one of the configured groups - name: "ReadonlyREST Enterprise instance #1 - two groups required" ror_kbn_authorization: name: "kbn1" groups_all_of: ["SAML_GRP_1", "SAML_GRP_2"] # <- use this field when a user should belong to all configured groups ror_kbn: - name: kbn1 signature_key: "shared_secret_kibana1" # <- use environmental variables for better security! - name: kbn2 signature_key: "shared_secret_kibana2" # <- use environmental variables for better security! ``` It handles authorization only using the configured ROR KBN connector (here `kbn1` and `kbn2`). Continue reading about this in the kibana plugin documentation, in the dedicated [SAML section](/develop/kibana#saml) [Impersonation](/develop/kibana/impersonation) is currently not supported by this rule. * Groups logic syntax can be uses as part of this rule, as described in the [Checking groups logic section](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md#checking-groups-logic) * For more information on the ROR's authorization rules, see [Authorization rules details](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md) **`ror_kbn_auth`** ([Enterprise](https://readonlyrest.com/enterprise)) For [Enterprise](https://readonlyrest.com/enterprise) customers only, required for SAML authentication. From ROR's perspective it authenticates and authorize users. ```yaml readonlyrest: access_control_rules: - name: "ReadonlyREST Enterprise instance #1" ror_kbn_auth: name: "kbn1" groups_any_of: ["SAML_GRP_1", "SAML_GRP_2"] # <- use this field when a user should belong to at least one of the configured groups - name: "ReadonlyREST Enterprise instance #1 - two groups required" ror_kbn_auth: name: "kbn1" groups_all_of: ["SAML_GRP_1", "SAML_GRP_2"] # <- use this field when a user should belong to all configured groups ror_kbn: - name: kbn1 signature_key: "shared_secret_kibana1" # <- use environmental variables for better security! - name: kbn2 signature_key: "shared_secret_kibana2" # <- use environmental variables for better security! ``` This authentication and authorization connector represents the secure channel (based on JWT tokens) of signed messages necessary for our Enterprise Kibana plugin to securely pass back to ES the username and groups information coming from browser-driven authentication protocols like SAML Continue reading about this in the kibana plugin documentation, in the dedicated [SAML section](/develop/kibana#saml) [Impersonation](/develop/kibana/impersonation) is currently not supported by this rule. * Groups logic syntax can be uses as part of this rule, as described in the [Checking groups logic section](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md#checking-groups-logic) * For more information on the ROR's authorization rules, see [Authorization rules details](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/authorization-rules-details.md) **`users`** `users: ["root", "*@mydomain.com"]` It's NOT an authentication rule, but it can be used to limit access to of specific users whose username is contained or matches the patterns in the array. This rule is independent from the authentication method chosen, so it will work well in conjunction LDAP, JWT, proxy\_auth, and all others. The rule won't be matched if there won't be an authenticated user by some other authentication rule (it means that to make sense, it should always be used in conjunction with some authentication rule). For example: ```yaml readonlyrest: access_control_rules: - name: "JWT auth for viewer group (role), limited to certain usernames" kibana: access: ro users: ["root", "*@mydomain.com"] jwt_auth: name: "jwt_provider_1" groups_any_of: ["viewer"] ``` #### Kibana-related rules **`kibana`** The `kibana` rule underpins all ROR Kibana-related settings that may be needed to provide great user experience. ```yaml kibana: access: ro # required index: ".kibana_custom_index" # optional template_index: ".kibana_template" # optional hide_apps: [ "Security", "Enterprise Search"] # optional metadata: dept: "@{jwt:tech.beshu.department}" alert_message: "Dear @{acl:current_group} users, you are viewing dashboards for indices @{acl:available_groups}_logstash-*" ``` When `access: api_only` is used, `allowed_api_paths` can additionally be specified: ```yaml kibana: access: api_only # required for allowed_api_paths allowed_api_paths: # optional, only valid with access: api_only - "^/api/spaces/.*$" - http_method: POST http_path: "^/api/saved_objects/.*$" ``` The rule consists of several sub-rules: **`access`** Enables the minimum set of Elasticsearch `actions` necessary for browsers to sustain a Kibana session, and rejects any other unrelated actions. This "macro" rule allows the minimum set of actions necessary for a browser to use Kibana. It allows a set of actions towards the designated kibana index (see [`kibana.index`](#index)), plus a stricter subset of read-only actions towards other indices, which are considered "data indices". The idea is that with one single sub-rule we allow the bare minimum set of index+action combinations necessary to support a Kibana browsing session. Possible access levels: * `ro_strict`: the browser has a read-only view on Kibana dashboards and settings and all other indices. * `ro`: some write requests can go through to the `kibana_index` index so that the UI state in "Discover" can be saved and new short urls can be created. * `rw`: some more requests will be allowed towards the `kibana_index` index only, so Kibana dashboards and settings can be modified. * `admin`: like `rw`, but has additional permissions to save security settings in the ReadonlyREST PRO/Enterprise app * `api_only`: only [Kibana REST API](https://www.elastic.co/guide/en/kibana/current/api.html) actions are allowed, login via browser is always denied. * `unrestricted`: no action is restricted. **NB:** The `admin` access level does not mean the user will be allowed to access all indices/actions. It's just like "rw" with settings changes privileges. If you truly require unrestricted access for your Kibana user, including ReadonlyREST PRO/Enterprise app, set `kibana.access: unrestricted`. You can use this rule with the `users` rule to restrict access to selected admins. This sub-rule is often used with the `indices` rule, to limit the data a user is able to see represented on the dashboards. In that case do not forget to allow the custom kibana index in the `indices` rule! **`index`** ([Enterprise](https://readonlyrest.com/enterprise)) **Default value is `.kibana`** Specify to what index we expect Kibana to attempt to read/write its settings (use this together with `kibana.index` setting in the `kibana.yml` file) This value directly affects how `kibana.access` works because at all the access levels (yes, even admin), `kibana.access` sub-rule will **NOT** match any *write* request in indices that are not the designated kibana index. If used in conjunction with ReadonlyREST Enterprise, this rule enables **multi tenancy**, because in ReadonlyREST, a tenancy is identified with a set of Kibana configurations, which are by design collected inside a kibana index (default: `.kibana`). It supports [dynamic variables](#dynamic-variables). **⚠️IMPORTANT** When you use the `kibana` rule together with the `indices` rule in the same block, you don't have to explicitly allow the Kibana-related indices in the list of allowed indices of the `indices` rule. ROR will do it for you automatically. Example: ```yaml - name: "::RW_USER::" auth_key: rw_user:pwd kibana: access: rw indices: ["r*"] # .kibana, .kibana_8.10.4, .kibana_task_manager, etc are allowed here, because there is the `kibana` rule present in the same block ``` **`template_index`** ([Enterprise](https://readonlyrest.com/enterprise)) Used to pre-populate tenancies with default kibana objects, like dashboards and visualizations. Thus providing a starting point for new tenants that will avoid the bad user experience of logging for the first time and finding a completely empty Kibana. It supports [dynamic variables](#dynamic-variables). **`hide_apps`** ([PRO](https://readonlyrest.com/pro)) Specify which Kibana apps and menu items should be hidden. This feature will work in ReadonlyREST PRO and Enterprise. For more information on the ROR's Kibana Hide Apps feature, see [Hiding Kibana Apps](/develop/kibana#hiding-kibana-apps). **`allowed_api_paths`** **Only valid when `access: api_only`.** Used to define which parts of [Kibana REST API](https://www.elastic.co/guide/en/kibana/current/api.html) can be used. The sub-rule requires to define a list of [regular expressions](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) which describes the API paths. Additionally, when you would like to restrict only specific HTTP methods of the API, you can use the extended format of the sub-rule: ```yaml kibana: access: api_only allowed_api_paths: # optional - http_method: POST http_path: "^/api/saved_objects/.*$" ``` **`metadata`** ([Enterprise](https://readonlyrest.com/enterprise)) User to define the Custom ROR Kibana Metadata which can be used in [Custom middleware](/develop/kibana#custom-middleware). The `kibana.metadata` in ReadonlyREST settings is an unstructured YAML object. It supports [dynamic variables](#dynamic-variables). Sample usage: ```yaml kibana: [...] metadata: alert_message: "Dear @{acl:current_group} users, you are viewing dashboards for indices @{acl:available_groups}_logstash-*" ``` `alert_message` Metadata can be used on the Kibana side to display information to the user on login to the Kibana. Declare custom Kibana JS file `readonlyrest_kbn.kibana_custom_js_inject_file: '/path/to/custom_kibana.js'`. it's injected at the end of the HTML Body tag of the Kibana UI frontend code. ```js const alertMessage = window.ROR_METADATA.customMetadata && window.ROR_METADATA.customMetadata.alert_message; if (alertMessage) { alert(alertMessage); } ``` #### Elasticsearch level rules **`indices`** `indices: ["sales", "logstash-*"]` Matches if the request involves a set of indices (or aliases, or data streams) whose name is "sales", or starts with the string "logstash-", or a combination of both. If a request involves a wildcard (i.e. "logstash-\*", "\*"), this is first expanded to the list of available indices, and then treated normally as follows: * Requests that do not involve any indices (cluster admin, etc) result in a "match". * Requests that involve only allowed indices result in a "match". * Requests that involve a mix of allowed and not-allowed indices, are rewritten to only involve allowed indices, and result in a "match". * Requests that involve only not-allowed indices result in a "no match". And the ACL evaluation moves on to the next block. The rejection message and HTTP status code returned to the requester are chosen carefully with the main intent to simulate not-allowed indices do not exist at all. The rule has also an extended version: ```yaml indices: patterns: ["sales", "logstash-*"]` must_involve_indices: false ``` The definition above has the same meaning as the shortest version shown at the beginning of this section. By default the rule will be matched when a request doesn't involve indices (eg. /\_cat/nodes request). But we can change the behaviour by configuring `must_involve_indices: true` - in this case the request above will be rejected by the rule. **In detail, with examples** In ReadonlyREST we roughly classify requests as: * "read": the request will not change the data or the configuration of the cluster * "write": when allowed, the request changes the internal state of the cluster or the data. If a **read request** involves some indices they have permissions for and some indices that they do NOT have permission for, the request is **rewritten** to involve only the subset of indices they have permission for. This is behaviour is very useful in Kibana: **different** users can see the **same** dashboards, but they are filled with a different, overlapping, or identical data set (according to the indices permissions). When the subset of indices is empty, it means that user are not allowed to access requested indices. In multitenancy environment we should consider two options: * requested indices don't exist * requested indices exist but the current user is not authorized to access them For both of these cases ROR is going to return HTTP 404 or HTTP 200 with an empty response. The same behaviour will be observed for ES with ROR disabled (for nonexistent index). If an index does exist, but a user is not authorized to access it, ROR is going to pretend that the index doesn't exist and a response will be the same like the index actually did not exist. See [detailed example](https://github.com/beshu-tech/readonlyrest-docs/tree/c53dbf8e6d8fa97f505b0513ac57d3738a2a9356/elasticsearch-details/index-not-found-examples.md). It's also worth mentioning, that when `global_settings.prompt_for_basic_auth` is set to `true` (that is disabled by default), ROR will return 401 instead of 404 HTTP status code. It is relevant for users who don't use ROR Kibana's plugin and would like to take advantage of default Kibana's behavior which shows the native browser basic auth dialog, when it receives HTTP 401 response (see [the example](#prompt_for_basic_auth)). If a **write request** wants to write to indices they don't have permission for, the write request is rejected. **Requests related to templates** Templates are also connected with indices, but rather indirectly. An index template has index patterns and could also have aliases. During an index template creation or modification, ROR checks if index patterns and aliases, defined in a request body, are allowed. When a user tries to remove or get template by name, ROR checks if the template can be considered as allowed for the user, and based on that information, it allows/forbids to remove or see it. See [details](https://github.com/beshu-tech/readonlyrest-docs/tree/c53dbf8e6d8fa97f505b0513ac57d3738a2a9356/elasticsearch-details/indices-rule-templates.md). **`actions`** `actions: ["indices:data/read/*"]` Match if the request action starts with "indices:data/read/". In Elasticsearch, each request carries only one action. We extracted from Elasticsearch source code the full list of valid action strings as of all Elasticsearch versions. Please see the [dedicated section to find the actions list of your specific Elasticsearch version](https://github.com/beshu-tech/readonlyrest-docs/tree/master/actionstrings). Example actions (see above for the full list): ``` "cluster:admin/data_frame/delete" "cluster:admin/data_frame/preview" ... "cluster:monitor/data_frame/stats/get" "cluster:monitor/health" "cluster:monitor/main" "cluster:monitor/nodes/hot_threads" "cluster:monitor/nodes/info" ... "indices:admin/aliases" "indices:admin/aliases/get" "indices:admin/analyze" ... "indices:data/read/get" "indices:data/read/mget" "indices:data/read/msearch" "indices:data/read/msearch/template" ... "indices:data/write/bulk" "indices:data/write/bulk_shard_operations[s]" "indices:data/write/delete" "indices:data/write/delete/byquery" "indices:data/write/index" "indices:data/write/reindex" ... many more... ``` **`snapshots`** `snapshots: ["snap_@{user}_*"]` Restrict what snapshots names can be saved or restored **`repositories`** `repositories: ["repo_@{user}_*"]` Restrict what repositories can snapshots be saved into **`data_streams`** `data_streams: ["ds_@{user}_*"]` Restrict what data stream names can be created, deleted, or modified **`filter`** `filter: '{"query_string":{"query":"user:@{user}"}}'` This rule enables **Document Level Security (DLS)**. That is: return only the documents that satisfy the boolean query provided as an argument. This rule lets you filter the results of a read request using a boolean query. You can use *dynamic variables* i.e. `@{user}` (see dedicated paragraph) to inject a user name or some header values in the query, or even environmental variables. **Example: per-user index segmentation** In the index "test-dls", each user can only search documents whose field "user" matches their user name. I.e. A user with username "paul" requesting all documents in "test-dls" index, won't see returned a document containing a field `"user": "jeff"` . ```yaml - name: "::PER-USER INDEX SEGMENTATION::" proxy_auth: "*" indices: ["test-dls"] filter: '{"bool": { "must": { "match": { "user": "@{user}" }}}}' ``` **Example 2: Prevent search of "classified" documents.** In this example, we want to avoid that users belonging to group "press" can see any document that has a field "access\_level" with the value "CLASSIFIED". And this policy is applied to all indices (no indices rule is specified). ```yaml - name: "::Press::" groups_any_of: ["press"] filter: '{"bool": { "must_not": { "match": { "access_level": "CLASSIFIED" }}}}' ``` **⚠️IMPORTANT** The `filter`and `fields` rules will only affect "read" requests, therefore "write" requests **will not match** because otherwise it would implicitly allow clients to "write" without the filtering restriction. For reference, this behaviour is identical to x-pack and search guard. **⚠️IMPORTANT** Beginning with version 1.27.0 all ROR internal requests from kibana will not match blocks containing `filter` and/or `fields` rules. There requests are used to perform kibana login and dynamic config reload. If you want to allow write requests (i.e. for Kibana sessions), just duplicate the ACL block, have the first one with `filter` and/or `fields` rule, and the second one without. **`fields`** This rule enables **Field Level Security (FLS)**. That is: * for responses where fields with values are returned (e.g. Search/Get API) - filter and show only allowed fields * make not allowed fields unsearchable - used in QueryDSL requests (e.g. Search/MSearch API) do not have impact on search result. In other words: FLS protects from usage some not allowed fields for a certain user. From user's perspective it seems like such fields are nonexistent. **Definition** Field rule definition consists of two parts: * A non empty list of fields (blacklisted or whitelisted) names. Supports wildcards and user runtime variables. * The FLS engine definition (global setting, optional). See: [engine details](https://github.com/beshu-tech/readonlyrest-docs/tree/c53dbf8e6d8fa97f505b0513ac57d3738a2a9356/elasticsearch-details/fls-engine.md). **⚠️IMPORTANT** With default FLS engine it's required to install ReadonlyREST plugin in all the data nodes. Different configurations allowing to avoid such requirement are described in [engine details](https://github.com/beshu-tech/readonlyrest-docs/tree/c53dbf8e6d8fa97f505b0513ac57d3738a2a9356/elasticsearch-details/fls-engine.md). **Field names** Fields can be defined using two access modes: blacklist and whitelist. **Blacklist mode (recommended)** Specifies which fields should not be allowed prefixed with `~` (other fields from mapping become allowed implicitly). Example: `fields: ["~excluded_fields_prefix_*", "~excluded_field", "~another_excluded_field.nested_field"]` Return documents but deprived of the fields that: * start with `excluded_fields_prefix_` * are equal to `excluded_field` * are equal to `another_excluded_field.nested_field` **Whitelist mode** Specifies which fields should be allowed explicitly (other fields from mapping become not allowed implicitly). Example: `fields: ["allowed_fields_prefix_*", "_*", "allowed_field.nested_field.text"]` Return documents deprived of all the fields, except the ones that: * start with `allowed_fields_prefix_` * start with underscore * are equal to `allowed_field.nested_field.text` **NB:** You can only provide a full black list or white list. Grey lists (i.e. `["~a", "b"]`) are invalid settings and ROR will refuse to boot up if this condition is detected. Example: hide prices from catalogue indices ```yaml - name: "External users - hide prices" fields: ["~price"] indices: ["catalogue_*"] ``` **⚠️IMPORTANT** Any metadata fields e.g. `_id` or `_index` can not be used in `fields` rule. **⚠️IMPORTANT** The `filter`and `fields` rules will only affect "read" requests, therefore "write" requests **will not match** because otherwise it would implicitly allow clients to "write" without the filtering restriction. For reference, this behaviour is identical to x-pack and search guard. **⚠️IMPORTANT** Beginning with version 1.27.0 all ROR internal requests from kibana will not match blocks containing `filter` and/or `fields` rules. There requests are used to perform kibana login and dynamic config reload. If you want to allow write requests (i.e. for Kibana sessions), just duplicate the ACL block, have the first one with `filter` and/or `fields` rule, and the second one without. **Configuring an ACL with filter/fields rules when using Kibana** A normal Kibana session interacts with Elasticsearch using a mix of actions which we can roughly group in two macro categories of "read" and "write" actions. However the `fields` and `filter` rules will **only match read requests**. They will also block ROR internal request used to log in to kibana and reload config. This means that a complete Kibana session cannot anymore be entirely matched by a single ACL block like it normally would. For example, this ACL block would perfectly support a complete Kibana session. That is, 100% of the actions (browser HTTP requests) would be allowed by this ACL block. ```yaml - name: "::RW_USER::" auth_key: rw_user:pwd kibana: access: rw indices: ["r*"] ``` However, when we introduce a filter (or fields) rule, this block will be able to match only some of the actions (only the "read" ones). ```yaml - name: "::RW_USER::" auth_key: rw_user:pwd kibana: access: rw # <-- won't work because of `filter` rule present in block (it mismatches RW requests) indices: ["r*"] filter: '{"query_string":{"query":"DestCountry:FR"}}' # <-- will reject all write requests! :( ``` The solution is to duplicate the block. The first one will intercept (and filter!) the read requests. The second one will intercept the remaining actions. Both ACL blocks together will entirely support a whole Kibana session. ```yaml - name: "::RW_USER (filter read requests)::" auth_key: rw_user:pwd indices: ["r*"] # <-- KIBANA-RELATED INDICES WON"T BE FILTERED HERE! filter: '{"query_string":{"query":"DestCountry:FR"}}' - name: "::RW_USER (allow remaining requests)::" auth_key: rw_user:pwd kibana: access: rw indices: ["r*"] # <-- KIBANA-RELATED INDICES ARE IMPLICITLY ALLOWED! (because of the presence of the `kibana` rule in the same block) ``` **NB:** Look at how we **make sure that the requests to ".kibana" won't get filtered** by specifying an `indices` rule in the first block. Here is another example, a bit more complex. Look at how we can duplicate the "PERSONAL\_GRP" ACL block so that the read requests to the "r\*" indices can be filtered, and all the other requests can be intercepted by the second rule (which is identical to the one we had before the duplication). Before adding the `filter` rule: ```yaml - name: "::PERSONAL_GRP::" groups_any_of: ["Personal"] kibana: access: rw index: ".kibana_@{user}" hide_apps: ["readonlyrest_kbn", "timelion"] indices: ["r*"] ``` After adding the `filter` rule (using the block duplication strategy). ```yaml - name: "::PERSONAL_GRP (FILTERED SEARCH)::" groups_any_of: ["Personal"] indices: [ "r*" ] filter: '{"query_string":{"query":"DestCountry:FR"}}' - name: "::PERSONAL_GRP::" groups_any_of: ["Personal"] indices: ["r*"] kibana: access: rw index: ".kibana_@{user}" hide_apps: ["readonlyrest_kbn", "timelion"] ``` **`response_fields`** This rule allows filtering Elasticsearch responses using a list of fields. It works in very similar way to `fields` rule. In contrast to `fields` rule, which filters out document fields, this rule filters out response fields. It **doesn't make use of Field Level Security (FLS)** and can be applied to every response returned by Elasticsearch. It can be configured in two modes: * *whitelist* allowing only the defined fields from the response object * *blacklist* filtering out (removing) only the defined fields from the response object **Blacklist mode** Specifies which fields should be filtered out by adding the \~ prefix to the field name. Other fields in the response will be implicitly allowed. For example: `response_fields: ["~excluded_fields_prefix_*", "~excluded_field", "~another_excluded_field.nested_field"]` The above will return the usual response object, but deprived (if found) of the fields that: * start with `excluded_fields_prefix_` * are equal to `excluded_field` * are equal to `another_excluded_field.nested_field` **Wildcard across nested fields** It's possible to use the `*` character to intercept nested fields. Imagine having this document: ```json { "_index":"kafka-both", "_type":"_doc", "_id":"460D9", "_score":8.649008, "_source":{ "session_id":64124.0, "country":"something", "resp":{ "credit_card_confidential": "378282246310005" "proc_time":0.02, "type":"spelling", "raw_text":{ "proc_time":0.02, "system_entities":{ "phone_number_confidential":[ { "unit":"Number", "string":"666", "value":666 } ] } } } } } ``` You can write this `fields` rule containing a pattern that uses the `*` right after the `~`: ```yml fields: ["~*_confidential"] ``` Now the search response will omit the string field `credit_card_confidential`, and the whole object `resp.raw_text.phone_number_confidential`, or any other field whose name ends in "\_confidential", regardless of their type or if and how deeply it's nested. **Whitelist mode** In this mode rule is configured to filter out each field that isn't defined in the rule. `response_fields: ["allowed_fields_prefix_*", "_*", "allowed_field.nested_field.text"]` Return response deprived of all the fields, except the ones that: * start with `allowed_fields_prefix_` * start with underscore * are equal to `allowed_field.nested_field.text` **NB:** You can only provide a full black list or white list. Grey lists (i.e. `["~a", "b"]`) are invalid settings and ROR will refuse to boot up if this condition is detected. *Example*: allow only `cluster_name` and `status` field in cluster health response: Without any filtering response from `/_cluster/health` looks more or less like: ```json { "cluster_name": "ROR_SINGLE", "status": "yellow", "timed_out": false, "number_of_nodes": 1, "number_of_data_nodes": 1, "active_primary_shards": 2, "active_shards": 2, "relocating_shards": 0, "initializing_shards": 0, "unassigned_shards": 2, "delayed_unassigned_shards": 0, "number_of_pending_tasks": 0, "number_of_in_flight_fetch": 0, "task_max_waiting_in_queue_millis": 0, "active_shards_percent_as_number": 50.0 } ``` but after configuring such rule: ```yaml - name: "Filter cluster health response" uri_re: "^/_cluster/health" response_fields: ["cluster_name", "status"] ``` response from above will look like: ```json { "cluster_name": "ROR_SINGLE", "status": "yellow" } ``` **NB:** Any response field can be filtered using this rule. #### HTTP Level rules **`x_forwarded_for`** `x_forwarded_for: ["192.168.1.0/24"]` Behaves exactly like `hosts`, but gets the source IP address (a.k.a. origin address, `OA` in logs) inside the `X-Forwarded-For` header only (useful replacement to `hosts`rule when requests come through a load balancer like AWS ELB) **Load balancers** This is a nice tip if your Elasticsearch is behind a load balancer. If you want to match all the requests that come through the load balancer, use `x_forwarded_for: ["0.0.0.0/0"]`. This will match the requests with a valid IP address as a value of the `X-Forwarded-For` header. **DNS lookup caching** It's worth to note that resolutions of DNS are going to be cached by JVM. By default successfully resolved IPs will be cached forever (until Elasticsearch is restarted) for security reasons. However, this may not always be the desired behaviour, and it can be changed by adding the following JVM options either in the jvm.options file or declaring the ES\_JAVA\_OPTS environment variable: `sun.net.inetaddr.ttl=TTL_VALUE` (or/and `sun.net.inetaddr.negative.ttl=TTL_VALUE`). More details about the problem can be found [here](https://www.ibm.com/support/pages/understanding-tuning-and-testing-inetaddress-class-and-cache). **`methods`** `methods: [GET, DELETE]` Match requests with HTTP methods specified in the list. N.B. Elasticsearch HTTP stack does not make any difference between HEAD and GET, so all the HEAD request will appear as GET. **`headers_and` (or `headers`)** `headers: ["h1:x*y","~h2:*xy"]` Match if **all** the HTTP headers in the request match the defined patterns in headers rule. This is useful in conjunction with [proxy\_auth](#proxy_auth), to carry authorization information (i.e. headers: `x-usr-group: admins`). The `~` sign is a pattern negation, so eg. `~h2:*xy` means: match if h2 header's value does not match the pattern \*xy, or `h2` is not present at all. **`headers_or`** `headers_or: ["x-myheader:val*","~header2:*xy"]` Match if **at least one** the specified HTTP headers `key:value` pairs is matched. **`uri_re`** `uri_re: ["^/secret-index/.*", "^/some-index/.*"]` **☠️HACKY (try to use indices/actions rule instead)** Match if **at least one** specified regular expression matches requested URI. **`maxBodyLength`** `maxBodyLength: 0` Match requests having a request body length less or equal to an integer. Use `0` to match only requests without body. **NB**: Elasticsearch HTTP API breaks the specifications, nad GET requests **might** have a body length greater than zero. **`api_keys`** `api_keys: [123456, abcdefg]` A list of api keys expected in the header `X-Api-Key` **`session_max_idle`** `session_max_idle: 1h` **⚠️DEPRECATED** Browser session timeout (via cookie). Example values 1w (one week), 10s (10 seconds), 7d (7 days), etc. NB: not available for Elasticsearch 2.x. #### Transport level rules These are the most basic rules. It is possible to allow/forbid requests originating from a list of IP addresses, host names or IP networks (in slash notation). **`hosts`** `hosts: ["10.0.0.0/24"]` Match a request whose **origin** IP address (also called origin address, or `OA` in logs) matches one of the specified IP addresses or subnets. **`accept_x-forwarded-for_header`** `accept_x-forwarded-for_header: false` **⚠️DEPRECATED (use `x_forwarded_for instead`)** A modifier for `hosts` rule: if the origin IP won't match, fallback to check the `X-Forwarded-For` header **`hosts_local`** `hosts_local: ["127.0.0.1", "127.0.0.2"]` Match a request whose **destination** IP address (called `DA` in logs) matches one of the specified IP addresses or subnets. This finds application when Elasticsearch HTTP API is bound to multiple IP addresses. #### Ancillary block settings **`verbosity`** `verbosity: error` Don't spam elasticsearch log file printing log lines for requests that match this block. Defaults to `info`. ### Users and Groups Sometimes we want to make allow/forbid decisions according to the username associated to a HTTP request. The extraction of the user identity (username) can be done via HTTP Basic Auth (Authorization header) or delegated to a reverse proxy (see `proxy_auth` rule). The validation of the said credentials can be carried on locally with hard coded credential hashes (see `auth_key_sha256` rule), via one or more LDAP server, or we can forward the Authorization header to an external web server and examine the HTTP status code (see `external_authentication`). Optionally we can introduce the notion of groups (see them as bags of users). The aim of having groups is to write a very specific block once, and being able to allow multiple usernames that satisfy the block. Groups can be declared and associated to users statically in the readonlyrest.yml file. Alternatively, groups for a given username can be retrieved from an LDAP server or from a LDAP server, or a custom JSON/XML service. You can mix and match the techniques to satisfy your requirements. For example, you can configure ReadonlyREST to: * Extract the username from X-Forwarded-User * Resolve groups associated to said user through a JSON microservice Another example: * Extract the username from Authorization header (HTTP Basic Auth) * Validate said username's password via LDAP server * resolve groups associated to the user from groups defined in readonlyrest.yml More examples are shown below together with a sample configuration. #### Local users and groups The `groups` rule accepts a list of group IDs. This rule will match if the resolved username (i.e. via `auth_key`) is associated with the given groups. In this example, usernames `alice` and `claire` are statically associated with group IDs.\ The username `bob` is statically associated with [structered groups](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/structured-groups.md)(a special syntax for defining groups, which may be helpful in the case of the Enterprise Kibana plugin) ```yaml access_control_rules: - name: Accept requests from users in group team1 on index1 type: allow # Optional, defaults to "allow" will omit now on. groups_any_of: ["team1"] indices: ["index1"] - name: Accept requests from users in group team2 on index2 groups_any_of: ["team2"] indices: ["index2"] - name: Accept requests from users in groups team1 OR team2 on index3 groups_any_of: ["team1", "team2"] indices: ["index3"] - name: Accept requests from users in groups team4 OR team5 on index3 groups_any_of: ["team4", "team5"] indices: ["index3"] - name: Accept requests from users in groups team1 AND team2 on index3 groups_all_of: ["team1", "team2"] indices: ["index3"] users: - username: "alice" groups: ["team1"] # group id - a value that ROR operates in groups rules auth_key: alice:p455phrase - username: "bob" # structured group syntax, useful in case of tenancy selector in Kibana Enterprise plugin groups: - id: "team2" # group id name: "Team 2" # group name - `Team 2` will be visible in the tenancy selector for the 'team2' group - id: "team4" # group id name: "Team 4" # group name - `Team 4` will be visible in the tenancy selector for the 'team4' group auth_key: bob:s3cr37 - username: "claire" groups: ["team1", "team5"] # group ids auth_key_sha256: e0bba5fda92dbb0570fd2e729a3c8ed6b1d52b380581f32427a38e396ba28ec6 #claire:p455key ``` *Example: rules are associated to groups (instead of users) and users-group association is declared separately later under `users:`* #### Group mapping Sometimes we'd like to take advantage of groups (roles) existing in external systems (like LDAP). We can do that in `users` section too. It's possible to map external groups to local ones. For details see [External to local groups mapping ](/develop/elasticsearch/groups-rule-mapping). #### Username case sensitivity ReadonlyREST can cooperate with services that operate in a case-insensitive way. For this case, ROR has a toggleable username case sensitivity option. For details, see the [username\_case\_sensitivity section](#username_case_sensitivity) in Global Settings. #### Static variables Anywhere in `readonlyrest.yml` you can use the expression `${env:MY_ENV_VAR}` to replace in place the environmental variables. This is very useful for injecting credentials like LDAP bind passwords, especially in Docker. For example, here we declare an environment variable, and we write `${env:LDAP_PASSWORD}` in our settings: ```bash $ export LDAP_PASSWORD=S3cr3tP4ss $ cat readonlyrest.yml ``` ```yaml ldaps: - name: ldap1 host: "ldap1.example.com" port: 389 ssl_enabled: false ssl_trust_all_certs: true bind_dn: "cn=admin,dc=example,dc=com" bind_password: "${env:LDAP_PASSWORD}" users: search_user_base_DN: "ou=People,dc=example,dc=com" ``` And ReadonlyREST ES will load "S3cr3tP4ss" as `bind_password`. #### Dynamic variables One of the neatest features in ReadonlyREST is that you can use dynamic variables inside most values of the following rules: `data_streams`, `indices`, `users`, `fields`, `filter`, `repositories`, `hosts`, `hosts_local`, `snapshots`, `response_fields`, `uri_re`, `x_forwarded_for`, `hosts_local`, `hosts`, `kibana.index`, `kibana.template_index`, `kibana.metadata`, [groups rules](#groups-rules). The variables are related to different contexts: * `acl` - the context of data collected in authentication and authorization rules of the current block: * `@{acl:user}` gets replaced with the username of the successfully authenticated user. Using this variable is allowed only in blocks where one of the rules is an authentication rule of course it must be a rule different from the one containing the given variable. * `@{acl:current_group}` is the group ID explicitly requested by the tenancy selector in ReadonlyREST Enterprise plugin when using multi-tenancy. * `@{acl:available_groups}` gets replaced with available group IDs found in the authorization rule (because by default dynamic variables are resolved to a string, the variable resolved value will contain groups surrounded with double quotes and joined with a comma) * `header` - the context of ES HTTP request headers * `@{header:}` gets replaced with the value of the HTTP header with name `` included in the incoming request (useful when reverse proxies handle authentication) * `jwt` - the context of JWT header value * `@{jwt:}` get replaced with value (or values) found in the JWT claim under the given JSON path **Dynamic variables exploding** A value resolved from a dynamic variable is a string. Some rules, like `indices` one, have multivalue context (you can configure several indices names in it). Let's assume we have a request with the header: `APPS: app1,app2,app3`. Doing something like this: ```yaml indices: ["logstash_@{header:apps}"] ``` We should expect it to be resolved to: ```yaml indices: ["logstash_app1,app2,app3"] ``` for this particular request. No, it wouldn't be helpful at all. But there is an `explode` function for dynamic variables. Doing: ```yaml indices: ["logstash_@explode{header:apps}"] ``` we should get: ```yaml indices: ["logstash_app1", "logstash_app2", "logstash_app3"] ``` which looks more useful! So, as we've seen, the `explode` attribute of a dynamic variable rule can be used to split a string with comma-separated values into an array of strings. But it can only be used in a rule with multi value context. **Usage examples** **Indices from user name** You can let users authenticate externally, i.e. via LDAP, and use their user name string inside the `indices` rule. ```yaml readonlyrest: access_control_rules: - name: "Users can see only their logstash indices" # i.e. alice can see alice_logstash-20170922 ldap_authentication: name: "myLDAP" indices: ["@{acl:user}_logstash-*"] # LDAP connector settings omitted, see LDAP section below.. ``` **Indices from available groups** You can let users authorize externally, i.e. via LDAP, and use their group strings inside the `indices` rule. ```yaml readonlyrest: access_control_rules: - name: "Users can see only logstash indices for their departments" # i.e. alice belongs to 'dev' and 'ops' department groups, so she can see dev_logstash-20170922, ops_logstash-20170922 ldap_auth: name: "myLDAP" groups_any_of: ["dev", "ops", "qa"] indices: ["@explode{acl:available_groups}_logstash-*"] # i.e when available_groups=[dev, ops] we will get indices: ["dev_logstash-*", "ops_logstash-*"] # LDAP connector settings omitted, see LDAP section below.. ``` **Filter from available groups** You can let users authorize externally, i.e. via LDAP, and use their group strings inside the `filter` rule. ```yaml readonlyrest: access_control_rules: - name: "Users can only see documents related to their departments" # i.e. alice belongs to 'dev' and 'ops' department groups, so she can see documents where "department" field is equal 'dev' or 'ops' ldap_auth: name: "myLDAP" groups_any_of: ["dev", "ops", "qa"] filter: '{ "terms": { "department": [@{acl:available_groups}] }}' # i.e. from available_groups=[dev, ops] we will get filter: '{ "terms": { "department": ["dev","ops"] }}' indices: ["logstash-*"] # LDAP connector settings omitted, see LDAP section below.. ``` **Uri regex matching user's current group** You can let users authorize externally, i.e. via LDAP, and use their group inside the `uri_re` rule. ```yaml readonlyrest: access_control_rules: - name: "Users can access uri with value containing user's current group, i.e. user with group 'g1' can access: '/path/g1/some_thing'" ldap_authorization: name: "ldap1" groups_any_of: ["g1", "g2", "g3"] uri_re: ["^/path/@{acl:current_group}/.*"] # LDAP connector settings omitted, see LDAP section below.. ``` **Kibana index from headers** Imagine that we delegate authentication to a reverse proxy, so we know that only authenticated users will ever reach Elasticsearch. We can tell the reverse proxy (i.e. Nginx) to inject a header called `x-nginx-user` containing the username. ```yaml readonlyrest: access_control_rules: - name: "Identify a personal kibana index where each user is supposed to save their dashboards" kibana: access: rw index: ".kibana_@{header:x-nginx-user}" ``` **Dynamic variables from JWT claims** The JWT token is an authentication string passed generally as a header or a query parameter to the web browser. If you squint, you can see it's a concatenation of three base64 encoded strings. If you base64 decode the middle string, you can see the "claims object". That is the object containing the current user's metadata. Here is an example of JWT claims object. ```javascript { "user": "jdoe", "display_name": "John Doe", "department": "infosec", "allowedIndices": ["x", "y"] } ``` Here follow some examples of how to use JWT claims as dynamic variables in ReadonlyREST ACL blocks, notice the "jwt:" prefix: ```yaml # Using JWT claims as dynamic variables indices: [ "idx_@{jwt:department}", "idx_other" ] # claims = { "user": "u1", "department": "infosec"} # -> indices: ["idx_infosec", "idx_other"] # Using nested values in JWT using JSONPATH as dynamic variables indices: [ "idx_@{jwt:jsonpath.to.department}", "idx_other"] # claims = { "jsonpath": {"to": { "department": "infosec" }}} # -> indices: ["idx_infosec", "idx_other"] # Referencing array-typed values from JWT claims will expand in a list of strings indices: [ "idx_@explode{jwt:allowedIndices}", "idx_other"] # claims = {"username": "u1", "allowedIndices": ["x", "y"] } # -> indices: ["idx_x", "idx_y", "idx_other"] # Explode operator will generate an array of strings from a comma-separated string indices: ["logstash_@explode{x-indices_csv_string}*", "idx_other"] # HTTP Headers: [{ "x-indices_csv_string": "a,b"}] # -> indices: ["logstash_a*", "logstash_b*", "idx_other"] ``` #### Variables functions A value resolved from a variable may not be valid in some contexts. Sometimes, the value from the variable needs some preprocessing before usage. For example, a HTTP header value containing the uppercase characters is a wrong candidate for the index name because it has to be a lowercase string. We introduced variable functions to overcome these limitations. They allow modification of the variable values during the variable resolution (both, [static](#static-variables) and [dynamic](#dynamic-variables) variables are supported). With their help, you can use the HTTP header `X-Forwarded-User: James` containing uppercase characters in the `indices` rule: ```yaml indices: [ 'index_@{header:x-forwarded-user}#{to_lowercase}' ] # @{header:x-forwarded-user} is replaced by HTTP header value 'James', and then the given function chain (function `to_lowercase` converting all characters to lowercase) is applied to the header value ``` which resolves to: ```yaml indices: [ 'index_james' ] ``` **Syntax** In general, functions syntax is as follows: `function_name("arg1","arg2")` * `function_name` - a function that you want to apply * `(...)` - function call parentheses (they may be omitted when the function has no args) * `arg1`, `arg2` - arguments passed to function. They should be surrounded by `"`. If your argument contains a special character (`"` or `}`), you can escape it with a `\`, e.g. (`function_a("\}")`) You can chain functions with the `.` operator (functions are applied in order from left to right): `function_a("arg1").function_b.function_c("arg1")` To apply functions to the variable, you need to use the `#` operator and enter your code in `{ }` braces: ``` @{--variable-definition--}#{--functions-chain--} ``` ```yaml # Using JWT claims as dynamic variables with variable function indices: [ "idx_@{jwt:department}#{to_lowercase}", "idx_other" ] # claims = { "user": "u1", "department": "Infosec"} # -> indices: ["idx_infosec", "idx_other"] ``` **Supported functions** Currently, we support functions like this: * `replace_all(regex,replacement)` - Replaces each substring of the variable string that matches the given regular expression with the given replacement. Params: * `regex` - the [regular expression](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) to which the variable string is to be matched * `replacement` - the string to be substituted for each match Usage: ```yaml indices: [ 'index_@{header:app}#{replace_all("team","group")}' ] ``` * `replace_first(regex,replacement)` - Replaces the first substring of the variable string that matches the given regular expression with the given replacement. Params: * `regex` - the [regular expression](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) to which the variable string is to be matched * `replacement` - the string to be substituted for each match Usage example: ```yaml indices: [ 'index_@{header:app}#{replace_first("^team","group")}' ] ``` * `to_lowercase` - Converts all characters in the variable string to lower case Usage example: ```yaml indices: [ 'index_@{header:app}#{to_lowercase}' ] ``` * `to_uppercase` - Converts all characters in the variable string to upper case Usage example: ```yaml groups_any_of: [ 'x1', '@{header:group}#{to_uppercase}' ] ``` **💡 Didn't find the function you are looking for?** We can easily extend the function list. If you need any new function/mechanism that cannot be obtained using the supported functions, let us know about it in our [forum](https://forum.readonlyrest.com/). We will consider adding the proper implementation. **Variable function aliases** Sometimes, the function chain may be very complex or occur multiple times in ACL. In this case, you can use a `function aliases` to simplify configuration management. The function alias allows you to export your function chain outside the ACL. Then you can substitute your function via alias `func(alias_name)`. Let's assume that we have the following configuration, and we want to introduce some function aliases: ```yaml readonlyrest: access_control_rules: - name: Alice indices: ['index_@{header:group}#{to_lowercase.replace_all("\\d","x")}'] auth_key: alice:p455phrase - name: Bob indices: ['index_@{header:group}#{to_lowercase.replace_all("\\d","x").replace_first("^team","")}'] auth_key: bob:s3cr37 ``` You can define function aliases in the `readonlyrest.variables_function_aliases` section and substitute functions code with `func(alias)`: ```yaml readonlyrest: variables_function_aliases: - custom_replace: 'to_lowercase.replace_all("\\d","x")' # convert to lower case and replace digits with x - skip_team_prefix: 'replace_first("^team","")' access_control_rules: - name: Alice indices: ['index_@{header:group}#{func(custom_replace)}'] auth_key: alice:p455phrase - name: Bob indices: ['index_@{header:group}#{func(custom_replace).func(skip_team_prefix)}'] auth_key: bob:s3cr37 ``` #### LDAP connector The authentication and authorization rules for LDAP (`ldap_auth`, `ldap_authentication`, `ldap_authorization`) defined in the rules section, always need to contain a reference by name to one LDAP connector. One or more LDAP connectors need to be defined in the section "ldaps" of the ACL. **Configuration notes** If you would like to experiment with LDAP and need a development server, you can stand up an OpenLDAP server configuring it using our schema file, which can be found in [our tests](https://github.com/sscarduzio/elasticsearch-readonlyrest-plugin/blob/develop/core/src/test/resources/test_example.ldif)). **Technical configuration** There are also plenty of technical settings which can be useful: * an LDAP server address: * single host: * `host` (String, required) - LDAP server address * `port` (Integer, optional, default: `389`) - LDAP server port * `ssl_enabled` (Boolean, optional, default: `true`) - enables or disables SSL for LDAP connection * several hosts: * `hosts` (List, required) - list of LDAP server addresses. The address should look like this `ldap://[HOST]:[PORT]` or/and `ldaps://[HOST]:[PORT]` * `ha` (enum: \[`FAILOVER`, `ROUND_ROBIN`], optional, default: `FAILOVER`) - provides high availability strategy for LDAP * auto-discovery: * `server_discovery` (Boolean|YAML object, optional, default: `false`) - for details see [LDAP server discovery section](#ldap-server-discovery) * `connection_pool_size` (Integer, optional, default: `30`) - indicates how many connections LDAP connector should create to LDAP server * `connection_timeout` (Duration, optional, default: `10 sec`) - instructs connector how long it should wait for the connection to LDAP server * `request_timeout` (Duration, optional, default: `10 sec`) - instructs connector how long it should wait for receiving a whole response from LDAP server * `connection_health_check_interval` (Duration, optional, default: `120 sec`) - defines how often the LDAP connection pool should perform health checks on idle connections. Health checks proactively detect and replace stale connections before they cause authentication failures. * `connection_max_age` (Duration, optional, default: `10 min`) - defines the maximum age of a connection in the pool. Connections older than this value are automatically replaced with fresh ones, preventing stale connection issues. This works in conjunction with `connection_health_check_interval` to maintain a healthy connection pool. * `ssl_trust_all_certs` (Boolean, optional, default: `false`) - if it is set to `true`, untrusted certificates will be accepted * `ignore_ldap_connectivity_problems` (Boolean, optional, default: `false`) - when it is set to `true`, it allows ROR to function even when LDAP server is unreachable. Rules using unreachable LDAP servers won't match. By default, ROR starts only after it's able to connect to each server * `cache_ttl` (Duration, optional, default: `0 sec`) - tells how long LDAP connector should cache queries results (for default see [caching section](#caching)) * `circuit_breaker` (YAML object, optional, default: `max_retries: 10`, `reset_duration: 10 sec`) - for details see [circuit breaker section](#circuit-breaker) **Query configuration** Usually, we would like to configure three main things for defining the way LDAP users and groups are queried: 1. a way to **authenticate client** (LDAP binding; used by all LDAP rules): * `bind_dn` (string, optional, default: \[not present]) - a username used to connect to the LDAP service. We can skip this setting when our LDAP service allows for anonymous binding * `bind_password` (string, optional, default: \[not present]) - a password used to connect to the LDAP service. We can skip this setting when our LDAP service allows for anonymous binding 2. a way to **search users**. In ROR it can be done using the following YAML keys (under the `users` section) (used by all LDAP rules): * `search_user_base_DN` (string, required) - should refer to the base Distinguished Name of the users to be authenticated * `user_id_attribute` (string, optional, default: `uid`) - should refer to a unique ID for the user within the base DN * `skip_user_search` (boolean, optional, default: `false`) - when you set `user_id_attribute: "cn"` you may want to skip the user search. This optimizes the authentication, which is done in two steps (searching for a user DN and authenticating the user with a given DN). If you configure it to be `true`, the user's DN will be `cn={user_login},{search_user_base_DN}`. 3. a way to **search user groups** (NOT used by [`ldap_authentication`](#ldap_authentication) rule). You can configure all properties under the `groups` section in LDAP connector configuration. In ROR, depending on LDAP schema, a relation between users and groups can be defined in: 1. Group entry - it has an attribute that refers to User entries (`mode: search_groups_in_group_entries`this is the default): * `search_groups_base_DN` (required) - should refer to the base Distinguished ID of the groups to which these users may belong * `group_id_attribute` (string, optional, default: `cn`) - is the LDAP group object attribute that contains the IDs of the ROR groups * `group_name_attribute` (string, optional, default: group\_id\_attribute) - is the LDAP group object attribute that contains the [name](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/structured-groups.md) of the ROR groups * `unique_member_attribute` (string, optional, default: `uniqueMember`) - is the LDAP group object attribute that contains the IDs of the ROR groups * `group_search_filter` (string, optional, default: `(cn=*)`) - is the LDAP search filter (or filters) to limit the user groups returned by LDAP. By default, this filter will be joined (with `&`) with `unique_member_attribute=user_dn` filter resulting in this LDAP search filter: `(&YOUR_GROUP_SEARCH_FILTER(unique_member_attribute=user_dn))`. * `group_attribute_is_dn` (boolean, optional, default: `true`) - * when `true` the search filter will look like that: `(&YOUR_GROUP_SEARCH_FILTER(unique_member_attribute={USER_DN}))` * then `false` the search filer will look like that: `(&YOUR_GROUP_SEARCH_FILTER(unique_member_attribute={USER_ID_ATTRIBUTE_VALUE}))` * `server_side_groups_filtering` (boolean, optional, default: `false`) - by default ROR's LDAP connector asks for all groups of the given user. The group filtering is done on ROR's side. It allows ROR to cache them efficiently. But in some cases (e.g. when the user has hundreds of groups), it's better to filter them on the LDAP server side. If this setting is `true`, LDAP will only be queried for a certain subset of the user groups (defined by the `groups_any_of`/`groups_all_of` subrule of the `ldap_authorization`/`ldap_auth` rule). Note, however, that ONLY the returned subset of the user's groups is cached. See [groups caching details](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/caching.md#group-caching) for a deep explanation. * `nested_groups_depth` (positive int, optional, no default) - it defines how deep ROR should ask LDAP to extract the nested LDAP groups. See the [nested groups support section](#nested-ldap-groups-support) for details. 2. User entry - it has an attribute that refers to Group entries (`mode: search_groups_in_user_entries` has to be set to use this strategy): * `search_groups_base_DN` (string, required) - should refer to the base Distinguished ID of the groups to which these users may belong * `group_id_attribute` (string, optional, default: `cn`) - is the LDAP group object attribute that contains the IDs of the ROR groups * `groups_from_user_attribute` (string, optional, default: `memberOf`) - is the LDAP user object attribute that contains the names of the ROR groups * `group_search_filter` (string, optional, default: `(objectClass=*)`) is the LDAP search filter (or filters) to limit the user groups returned by LDAP * `nested_groups_depth` (positive int, optional, no default) - it defines how deep ROR should ask LDAP to extract the nested LDAP groups. When this setting is configured, ROR needs to know what group's attribute holds the parent group ID - it can be set using `unique_member_attribute` (the default is the `uniqueMember` value). See the [nested groups support section](#nested-ldap-groups-support) for details. Examples: ``` group_search_filter: "(objectClass=group)" group_search_filter: "(objectClass=group)(cn=application*)" group_search_filter: "(cn=*)" # basically no group filtering ``` **Caching** Too many calls made by ROR to our LDAP service can sometimes be problematic (eg. when one LDAP connector is used in many rules). The problem can be simply solved by using caching functionality. Caching can be configured per LDAP connector or per LDAP rule (see [`ldap_auth`](#ldap_auth), [`ldap_authentication`](#ldap_authentication), [`ldap_authorization`](#ldap_authorization) rules). By default cache is disabled. We can enable it by setting `cache_ttl` > `0 sec`. In the cache will be stored only results of successful requests - info about authentication results and/or returned LDAP groups for the given credentials. When LDAP connector level cache is used any rule that uses the connector can take advantage of cached results. When we configure `cache_ttl` at the LDAP rule level, the results of LDAP calls made by the rule will be stored in the cache. Other LDAP rules won't have access to this cache. See [caching details](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/caching.md) for deep explanation. **Circuit Breaker** The LDAP connector is equipped by default with a circuit breaker functionality. The circuit breaker can disable the connector from sending new requests to the server when it doesn't respond properly. After receiving a configurable number of failed responses in a row, the circuit breaker feature disables sending any new requests by terminating them immediately with an exception. After a configurable amount of time, the circuit breaker feature allows one request to pass again. If it succeeds, the connector goes back to normal operation. If not, a test request is sent again after a configurable amount of time. A general description of the concept could be found on [wiki](https://en.wikipedia.org/wiki/Circuit_breaker_design_pattern) and more about specific implementation could be found in [library documentation](https://monix.io/docs/current/catnap/circuit-breaker.html). The circuit breaker feature can be customized to adapt to specific needs using the following configuration parameters: * `max_retries` is the number of failed responses in a row that will trigger the circuit breaker. * `reset_duration` defines how long the circuit breaker feature will block the incoming requests before starting to send one test request. to the LDAP server. **LDAP Server discovery** The LDAP connector can get all LDAP hostnames from the DNS server rather than from the configuration file. By default `_ldap._tcp` SRV records are used for that, but any other SRV record can be configured. The simplest configuration example of an LDAP connector instance using server discovery is: ```yaml - name: ldap server_discovery: true users: search_user_base_DN: "ou=People,dc=example2,dc=com" groups: search_groups_base_DN: "ou=Groups,dc=example2,dc=com" ``` This configuration is using the system DNS to fetch all the `_ldap._tcp` SRV records which are expected to contain the hostname and port of all the LDAP servers we should connect to. Each SRV record also has priority and weight assigned to it which determine the order in which they should be contacted. Records with a lower priority value will be used before those with a higher priority value. The weight will be used if there are multiple service records with the same priority, and it controls how likely each record is to be chosen. A record with a weight of 2 is twice as likely to be chosen as a record with the same priority and a weight of 1. The server discovery mechanism can be optionally configured further, by adding a few more configuration parameters, all of which are optional: * `record_name` - DNS SRV record name. By default it's `_ldap._tcp`, but could be `_ldap._tcp.domainname` or any custom value. * `dns_url` - Address of non-default DNS server in form `dns://IP[:PORT]`. By default, the system DNS is used. * `ttl` - DNS cache timeout. Specifies how long values from DNS will be kept in the cache. Default is 1h. * `use_ssl` - Use `true` when SSL should be used for LDAP connections. Default is `false` which means that SSL won't be used. Example: ```yaml - name: ldap server_discovery: record_name: "_ldap._tcp.example.com" dns_url: "dns://192.168.1.100" ttl: "3 hours" use_ssl: true users: search_user_base_DN: "ou=People,dc=example2,dc=com" groups: search_groups_base_DN: "ou=Groups,dc=example2,dc=com" ``` **Nested LDAP groups support** Let's imagine we have the following groups in LDAP: * `employees` * `it` * `developers` * `sales` * `managers` And there is `John Dev` who is assigned to `developers` groups and `Alize Man` whos group is `managers`. Moreover, we know that: * to `it` group belongs all users who are `developers` * to `sales` group belongs all users who are `managers` * to `employees` groups belongs all users who are from `it` or `sales` The groups configuration like the above, in ROR, we call nested LDAP groups. By default, when ROR searches for eg. `John Dev`'s groups, it is going to get the `developers` group only. But taking into consideration the nested groups configuration, we know that `John Dev` belongs to the following groups: `developers`, `it` & `employees`. Sometimes it'd be nice to have them all available in ROR's LDAP authorization rule. ROR extracts nested groups by making additional search queries to LDAP. It asks LDAP: *tell me which groups `developers` belongs to?*. LDAP should return: `it`. Then ROR asks again: *so, tell me which groups `it` belongs to?*. LDAP answers: `employees`. And again, ROR asks: *Tell me which groups `empoyees` belongs to?*. LDAP should say: *no groups found*. And this is the point where ROR stops. ROR did additional 3 queries to LDAP to establish that `John Dev` belongs additionally to `it` and `employees` group. As you probably noticed, enabling nested groups extraction can be costly. ROR obviously tries to do its best to reduce the cost eg. by caching (if cache is enabled) or extracting each unique group always only once during the groups call handling. To reduce the cost more, you can define the depth of the extraction by providing `nested_groups_depth` (the presence of the setting enables the feature, so you have to configure it to enable the nested groups extraction). Let's say we configured it like that: `nested_groups_depth: 1`. In the example above ROR asks only once: *tell me which groups `developers` belongs to?*. After the LDAP's response: `it` there won't be any more queries. That's because of the depth equaled 1. **ROR with LDAP - examples** In this example, users' credentials are validated via LDAP. The groups associated with each validated user, are resolved using the same LDAP server. **Simpler: authentication and authorization in one rule** ```yaml readonlyrest: access_control_rules: - name: Accept requests from users in group team1 on index1 type: allow # Optional, defaults to "allow", will omit from now on. ldap_auth: name: "ldap1" # ldap name from below 'ldaps' section groups_any_of: ["g1", "g2"] # group within 'ou=Groups,dc=example,dc=com' indices: ["index1"] - name: Accept requests from users in group team2 on index2 ldap_auth: name: "ldap2" groups_any_of: ["g3"] cache_ttl_in_sec: 60 indices: ["index2"] ldaps: - name: ldap1 host: "ldap1.example.com" port: 389 ssl_enabled: false ssl_trust_all_certs: true ignore_ldap_connectivity_problems: true bind_dn: "cn=admin,dc=example,dc=com" bind_password: "password" users: search_user_base_DN: "ou=People,dc=example,dc=com" user_id_attribute: "uid" groups: mode: 'search_groups_in_group_entries' # available options: 'search_groups_in_group_entries' (default), 'search_groups_in_user_entries' search_groups_base_DN: "ou=Groups,dc=example,dc=com" unique_member_attribute: "uniqueMember" group_search_filter: "(objectClass=group)(cn=application*)" group_id_attribute: "cn" connection_pool_size: 20 connection_timeout: 1s request_timeout: 2s connection_health_check_interval: 30s connection_max_age: 5min cache_ttl: 60s circuit_breaker: max_retries: 2 reset_duration: 5s # High availability LDAP settings (using "hosts", rather than "host") - name: ldap2 hosts: - "ldaps://ssl-ldap2.foo.com:636" - "ldaps://ssl-ldap3.foo.com:636" ha: "ROUND_ROBIN" users: search_user_base_DN: "ou=People,dc=example2,dc=com" groups: search_groups_base_DN: "ou=Groups,dc=example2,dc=com" # Server discovery variant - name: ldap3 server_discovery: true users: search_user_base_DN: "ou=People,dc=example2,dc=com" groups: search_groups_base_DN: "ou=Groups,dc=example2,dc=com" ``` **Advanced: authentication and authorization in separate rules** ```yaml readonlyrest: global_settings: response_if_req_forbidden: Forbidden by ReadonlyREST ES plugin access_control_rules: - name: Accept requests to index1 from users with valid LDAP credentials, belonging to LDAP group'team1' ldap_authentication: "ldap1" ldap_authorization: name: "ldap1" # ldap name from 'ldaps' section groups_any_of: ["g1", "g2"] # group within 'ou=Groups,dc=example dc=com' indices: ["index1"] - name: Accept requests to index2 from users with valid LDAP credentials, belonging to LDAP group 'team2' ldap_authentication: name: "ldap2" cache_ttl: 60s ldap_authorization: name: "ldap2" groups_any_of: ["g3"] cache_ttl: 60s indices: ["index2"] ldaps: - name: ldap1 host: "ldap1.example.com" port: 389 ssl_enabled: false ssl_trust_all_certs: true ignore_ldap_connectivity_problems: true bind_dn: "cn=admin,dc=example,dc=com" bind_password: "password" users: search_user_base_DN: "ou=People,dc=example,dc=com" user_id_attribute: "uid" groups: search_groups_base_DN: "ou=Groups,dc=example,dc=com" unique_member_attribute: "uniqueMember" connection_pool_size: 20 connection_timeout: 1s request_timeout: 2s connection_health_check_interval: 30s connection_max_age: 5min cache_ttl: 60s # High availability LDAP settings (using "hosts", rather than "host") - name: ldap2 hosts: - "ldaps://ssl-ldap2.foo.com:636" - "ldaps://ssl-ldap3.foo.com:636" ha: "ROUND_ROBIN" users: search_user_base_DN: "ou=People,dc=example2,dc=com" groups: search_groups_base_DN: "ou=Groups,dc=example2,dc=com" ``` #### External Basic Auth ReadonlyREST will forward the received `Authorization` header to a website of choice and evaluate the returned HTTP status code to verify the provided credentials. This is useful if you already have a web server with all the credentials configured and the credentials are passed over the `Authorization` header. ```yaml readonlyrest: access_control_rules: - name: "::Tweets::" methods: GET indices: ["twitter"] external_authentication: "ext1" - name: "::Facebook posts::" methods: GET indices: ["facebook"] external_authentication: service: "ext2" cache_ttl_in_sec: 60 external_authentication_service_configs: - name: "ext1" authentication_endpoint: "http://external-website1:8080/auth1" success_status_code: 200 cache_ttl_in_sec: 60 http_connection_settings: validate: false # SSL certificate validation (default to true) connection_timeout_in_sec: 1 # default 2 socket_timeout_in_sec: 2 # default 5 connection_request_timeout_in_sec: 1 # default 5 connection_pool_size: 20 # default 30 - name: "ext2" authentication_endpoint: "http://external-website2:8080/auth2" success_status_code: 204 cache_ttl_in_sec: 60 ``` To define an external authentication service the user should specify: * `name` for service (then this name is used as id in `service` attribute of `external_authentication` rule) * `authentication_endpoint` (GET request) * `success_status_code` - authentication response success status code Cache can be defined at the service level or/and at the rule level. In the example, both are shown, but you might opt for setting up either. #### Custom groups providers This external authorization connector makes it possible to resolve to what groups a users belong, using an external JSON or XML service. ```yaml readonlyrest: access_control_rules: - name: "::Tweets::" methods: GET indices: ["twitter"] proxy_auth: proxy_auth_config: "proxy1" users: ["*"] groups_provider_authorization: user_groups_provider: "GroupsService" groups_any_of: ["group3"] - name: "::Facebook posts::" methods: GET indices: ["facebook"] proxy_auth: proxy_auth_config: "proxy1" users: ["*"] groups_provider_authorization: user_groups_provider: "GroupsService" groups_any_of: ["group1"] cache_ttl_in_sec: 60 proxy_auth_configs: - name: "proxy1" user_id_header: "X-Auth-Token" user_groups_providers: - name: GroupsService groups_endpoint: "http://localhost:8080/groups" auth_token_name: "token" auth_token_passed_as: QUERY_PARAM # HEADER OR QUERY_PARAM response_groups_ids_json_path: "$..groups[?(@.id)].id" # JSON-path style, see https://github.com/json-path/JsonPath response_groups_names_json_path: "$..groups[?(@.name)].name" # optional, JSON-path style, see https://github.com/json-path/JsonPath cache_ttl_in_sec: 60 http_connection_settings: connection_timeout_in_sec: 1 socket_timeout_in_sec: 2 connection_request_timeout_in_sec: 2 connection_pool_size: 20 ``` In example above, a user is authenticated by reverse proxy and then external service is asked for groups for that user. If groups returned by the service contain any group declared in `groups` list, user is authorized and rule matches. Also in this rule, the `groups` clause can be replaced by `group_and` to require the user must belong to all the listed groups: ```yaml groups_provider_authorization: user_groups_provider: "GroupsService" groups_all_of: ["group1", "group2"] # match when user belongs to ALL listed groups ``` To define user groups provider you should specify: * `name` - (string, required) - identifier of the service which needs to be passed in the `groups_provider_authorization` rule (`user_groups_provider` attribute) * `groups_endpoint` - (string, required) - service with groups endpoint * `auth_token_name` - (string, required) - user identifier will be passed with this name * `auth_token_passed_as` - (string, required, can be one of `HEADER` or `QUERY_PARAM`) - the way how user identifier is passed to the service * `http_method` - (string, optional, can be one of `GET` (default), `POST`) - HTTP method used to send request * `response_group_ids_json_path`,`response_groups_json_path` (string, required) - response can be unrestricted, but you have to specify [JSON Path](https://github.com/json-path/JsonPath) for group ID list * `response_group_names_json_path` (string, optional, default: `response_group_ids_json_path`)- [JSON Path](https://github.com/json-path/JsonPath) for [groups name](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/structured-groups.md) list (both arrays, available at `response_group_ids_json_path` and `response_group_names_json_path`, have to have the same length and have the same order) As usual, the cache behaviour can be defined at service level or/and at rule level. #### JSON Web Token (JWT) Auth The information about the username can be extracted from the "claims" inside a JSON Web Token. Here is an example. ```yaml readonlyrest: access_control_rules: - name: Valid JWT token with a viewer group kibana: access: ro jwt_auth: name: "jwt_provider_1" groups_any_of: ["viewer"] - name: Valid JWT token with a writer group kibana: access: rw jwt_auth: name: "jwt_provider_1" groups_any_of: ["writer"] - name: Valid JWT token with a viewer and writer groups kibana: access: rw jwt_auth: name: "jwt_provider_1" groups_all_of: ["writer", "viewer"] jwt: - name: jwt_provider_1 signature_algo: HMAC # can be NONE, RSA, HMAC (default), and EC signature_key: "your_signature_min_256_chars" user_claim: email group_ids_claim: resource_access.client_app.group_ids # JSON-path style, see https://github.com/json-path/JsonPath group_names_claim: resource_access.client_app.group_names # optional, JSON-path style, see https://github.com/json-path/JsonPath header_name: Authorization ``` You can verify groups assigned to the user with the groups logic (`groups_any_of`/`groups_all_of`/`groups_not_any_of`/`groups_not_all_of`/`groups_combined`) described in the [Groups logic](#user_belongs_to_groups) section. To define JWT provider, you need to provide: * `name` - (string, required) - identifier of the JWT provider, which needs to be passed in the `jwt_auth` rule * `user_claim` - (string, optional) - indicates which field in the JSON will be interpreted as the username. To define the claim path, use [JSON-path](https://github.com/json-path/JsonPath) syntax. * `group_ids_claim` (string, optional) - indicates which field in the JSON will be interpreted as the group ID. To define the claim path, use [JSON-path](https://github.com/json-path/JsonPath) syntax. * `group_names_claim` (string, optional, defaults to `group_ids_claim`) - indicates which field in the JSON will be interpreted as the [group name](https://github.com/beshu-tech/readonlyrest-docs/tree/develop/details/structured-groups.md). To define the claim path, use [JSON-path](https://github.com/json-path/JsonPath) syntax. * `header_name` (string, optional, defaults to `Authorization`) - HTTP header name carrying the JWT Token, can be used if we expect the JWT Token in a custom header (i.e. [Google Cloud IAP signed headers](https://cloud.google.com/iap/docs/signed-headers-howto)). * `signature_key` (string, required) - shared secret between the issuer of the JWT and ReadonlyREST. It is used to verify the cryptographical "paternity" of the message. * `signature_algo` (string, optional, can be one of `NONE`, `RSA`, `HMAC` (default), and `EC`) - indicates the family of cryptographic algorithms used to validate the JWT. **⚠️IMPORTANT**: As described above, both claim names (`user_claim` and `group_ids_claim`) are optional, but: * `jwt_authentication` rule requires `user_claim` to be defined in the JWT provider * `jwt_authorization` rule requires `group_ids_claim` to be defined in the JWT provider * `jwt_auth` rule requires both those settings **Accepted signature\_algo values** The value of this configuration represents the cryptographic family of the JWT protocol. Use the below table to tell what value you should configure, given a JWT token sample. You can decode sample JWT token using an [online tool](https://jwt.io/). | Algorithm declared in JWT token | `signature_algo` value | | ------------------------------- | ---------------------- | | NONE | **None** | | HS256 | **HMAC** | | HS384 | **HMAC** | | HS512 | **HMAC** | | RS256 | **RSA** | | RS384 | **RSA** | | RS512 | **RSA** | | PS256 | **RSA** | | PS384 | **RSA** | | PS512 | **RSA** | | ES256 | **EC** | | ES384 | **EC** | | ES512 | **EC** | ### Audit ReadonlyREST can gather audit events that contain information regarding a request and its processing by the system, which can then be forwarded to predefined outputs. You can use the available information from the audit events to construct interesting visual representations, such as Kibana dashboards or any other visualization tool. For details see [Audit configuration](/develop/elasticsearch/audit). ### Other settings #### Disabling ReadonlyREST ACL The ReadonlyREST ACL can be temporarily disabled without uninstalling the plugin by setting `readonlyrest.enable: false` in the configuration. The default value is `true`. When disabled, all requests will bypass the ACL rules. Example: ```yaml readonlyrest: enable: false ``` #### Global settings The `readonlyrest.global_settings` section contains various settings that affect different parts of the ACL: **`prompt_for_basic_auth`** When set to `true`, ROR will return HTTP 401 instead of 403 when authentication fails. This prompts browsers to show a basic auth dialog. This is particularly useful when not using ReadonlyREST Kibana plugin and wanting to take advantage of Kibana's default behavior. Defaults to `false`. But we don't recommend to change this default behaviour. Example: ```yaml readonlyrest: global_settings: prompt_for_basic_auth: true ``` **`response_if_req_forbidden`** Customize the response message returned when a request is forbidden by any ACL block. This can be overridden at the block level using the `type.response_message` setting (see section on [Unauthorized response configuration](#unauthorized-response-configuration)). Defaults to "Forbidden by ReadonlyREST ES plugin". Example: ```yaml readonlyrest: global_settings: response_if_req_forbidden: "You shall not pass!" ``` **`fls_engine`** Specifies which Field Level Security engine to use for document filtering. Can be either "es\_with\_lucene" (default) or "es". This setting determines how ReadonlyREST handles field-level security with the [`fields` rule](#fields). * **es\_with\_lucene** (default): Hybrid approach where most FLS operations are handled by Elasticsearch, with Lucene as a fallback for complex cases. Provides full functionality but requires ReadonlyREST to be installed on all nodes. * **es**: FLS is handled only by Elasticsearch without Lucene fallback. This mode doesn't require ReadonlyREST on all nodes but has limitations for certain request types. For detailed information about capabilities and limitations of each engine, see [FLS engine documentation](/develop/elasticsearch/fls-engine). Example: ```yaml readonlyrest: global_settings: fls_engine: es ``` **`username_case_sensitivity`** Controls username comparison behavior across all authentication rules. Can be either "case\_sensitive" (default) or "case\_insensitive". Useful when integrating with case-insensitive systems. Example: ```yaml readonlyrest: global_settings: username_case_sensitivity: case_insensitive ``` **`users_section_duplicate_usernames_detection`** When enabled, ROR validates the `users` section during startup to ensure there are no duplicate usernames defined. This helps prevent configuration errors. Defaults to `true`. In some scenarios you may want to disable it. Example: ```yaml readonlyrest: global_settings: users_section_duplicate_usernames_detection: false ``` ### ACL Troubleshooting The main issues seen in support cases: * Bad ordering or ACL blocks. Remember that the ACL is evaluated sequentially, block by block. And the first block whose rules all match is accepted. * Users don't know how to read the `HIS` field in the logs, which instead is crucial because it contains a trace of the evaluation of rules and blocks. * LDAP configuration: LDAP is tricky to configure in any system. Configure ES root logger to `DEBUG` editing `$ES_PATH_CONF/config/log4j2.properties` to see a trace of the LDAP messages. #### Interpreting ACL logs ReadonlyREST prints a log line for each incoming request (this can be selectively avoided on ACL block level using the `verbosity` rule). **Allowed requests** This is an example of a request that matched an ACL block (allowed) and has been let through to Elasticsearch. > ALLOWED by { name: 'Admins', policy: ALLOW, rules: \[groups\_any\_of, kibana] } req={ ID:44d12d75-4340-4e3e-9507-5bb439db9d80-1159548962#7510, TYP:SearchRequest, CGR:\, USR:admin, BRS:true, ACT:indices:data/read/search, OA:192.168.65.1/32, XFF:null, DA:172.19.0.2/32, IDX:*, MET:GET, PTH:/\_search, CNT:\, HDR:Accept=*/*, User-Agent=curl/8.7.1, Host=localhost:19200, Authorization=, HIS:\[KIBANA: NOT\_MATCHED (AUTH\_FAIL (Username mismatch)) -> RULES:\[auth\_key->false]], \[Admins: MATCHED -> RULES:\[groups\_any\_of->true, kibana->true] RESOLVED:\[user=admin;group=Administrators;av\_groups=Administrators;indices=*;kibana\_idx=.kibana]], } **Explanation** The log line immediately states that this request has been allowed by an ACL block called "Admins". Immediately follows a summary of the requests' anatomy. The format is semi-structured, and it's intended for humans to read quickly, it's not JSON, or anything else. Similar information gets logged in JSON format via [audit events](#audit) feature described ealier. Here is a glossary: * `ID`: ReadonlyREST-level request id * `TYP`: String, the name of the Java class that internally represent the request type (very useful for debug) * `CGR`: String, the request carries a "current group" header (used for multi-tenancy). * `USR`: String, the user name ReadonlyREST was able to extract from Basic Auth, JWT, LDAP, or other methods as specified in the ACL. * `BRS`: Boolean, an heuristic attempt to tell if the request comes from a browser. * `ACT`: String, the elasticsearch level action associated with the request. For a list of actions, see our [actions rule docs](#actions). * `OA`: IP Address, originating address (source address) of the TCP connection underlying the http session. * `IDX`: Strings array: the list of indices affected by this request. * `MET`: String, HTTP Method * `CNT`: String, HTTP body content. Comes as a summary of its length, full body of the request is available in debug mode. * `HDR`: String array, list of HTTP headers, headers' content is available in debug mode. * `HIS`: Chronologically ordered history of the ACL blocks and their rules being evaluated. When a block is `NOT_MATCHED`, the denial cause appears in parentheses after the block name (e.g. `AUTH_FAIL(...)`, `GROUPS_AUTH_FAIL(...)`, `AUTHZ_FAIL`, `IDX_NOT_FOUND`). See [Denial causes in HIS](#denial-causes-in-his) for a full reference. In the example, the block `Admins` is allowing the request because all the rules in this block evaluate to `true`. **Forbidden requests** This is an example of a request that gets forbidden by ReadonlyREST ACL. ``` FORBIDDEN by default req={ ID:af26efdb-9193-424d-8dc9-d2cda617842a-1466512324#7967, TYP:SearchRequest, CGR:, USR:admin (attempted), BRS:true, ACT:indices:data/read/search, OA:192.168.65.1/32, XFF:null, DA:172.19.0.2/32, IDX:*, MET:GET, PTH:/_search, CNT:, HDR:Accept=*/*, User-Agent=curl/8.7.1, Host=localhost:19200, Authorization=, HIS:[KIBANA: NOT_MATCHED (AUTH_FAIL (Username mismatch)) -> RULES:[auth_key->false]], [Admins: NOT_MATCHED (GROUPS_AUTH_FAIL (admin:AUTH_FAIL (Invalid password); {user1,user2}:GROUPS_AUTH_FAIL (No user's groups allowed))) -> RULES:[groups_any_of->false]], [End users: NOT_MATCHED (GROUPS_AUTH_FAIL (admin:AUTH_FAIL (Invalid password); {user1,user2}:AUTH_FAIL (Username mismatch))) -> RULES:[groups_any_of->false]], [Business users: NOT_MATCHED (GROUPS_AUTH_FAIL (admin:AUTH_FAIL (Invalid password); user1:AUTH_FAIL (Username mismatch); user2:GROUPS_AUTH_FAIL (No user's groups allowed))) -> RULES:[groups_any_of->false]] } ``` The above rule gets forbidden "by default". This means that no ACL block has matched the request, so ReadonlyREST's default policy of rejection takes effect. **Requests finished with INDEX NOT FOUND** This is an example of such request: ``` INDEX NOT FOUND req={ ID:5cdbd3ec-2093-426d-85c9-b2d0be7361b5-746941746#8477, TYP:GetIndexRequest, CGR:, USR:user1 (attempted), BRS:true, ACT:indices:admin/get, OA:192.168.65.1/32, XFF:null, DA:172.19.0.2/32, IDX:nonexistent, MET:GET, PTH:/nonexistent, CNT:, HDR:Accept=*/*, User-Agent=curl/8.7.1, Host=localhost:19200, Authorization=, HIS:[KIBANA: NOT_MATCHED (AUTH_FAIL (Username mismatch)) -> RULES:[auth_key->false]], [Admins: NOT_MATCHED (GROUPS_AUTH_FAIL (admin:AUTH_FAIL (Username mismatch); {user1,user2}:GROUPS_AUTH_FAIL (No user's groups allowed))) -> RULES:[groups_any_of->false]], [End users: NOT_MATCHED (IDX_NOT_FOUND) -> RULES:[groups_any_of->true, kibana->true, indices->false]], [Business users: NOT_MATCHED (IDX_NOT_FOUND) -> RULES:[groups_any_of->true, kibana->true, indices->false]] } ``` The state above is only possible for read-only ES requests (ES requests which don't change ES cluster state) for a block containing an `indices` rule. If all other rules within the block are matched, but only the `indices` rule is mismatched, the final state of the block is forbidden due to an index not found. **Denial causes in `HIS`** When a block is `NOT_MATCHED`, a denial cause appears in parentheses after the block name. These causes make it straightforward to distinguish between authentication failures (wrong credentials) and authorization failures (missing permissions) without additional debugging. | Cause | Meaning | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `AUTH_FAIL(details)` | Authentication failed. The human-readable `details` string describes the specific reason (e.g. wrong username, bad password, missing credentials). | | `GROUPS_AUTH_FAIL(details)` | Groups-based authorization failed. The `details` string describes which user definitions were tried and why each one was rejected. | | `AUTHZ_FAIL` | A non-authentication rule (e.g. `indices`, `actions`) caused the block to be rejected. | | `IDX_NOT_FOUND` | All auth rules matched but the requested index does not exist. Applies only to read-only requests. | | `ALIAS_NOT_FOUND` | All auth rules matched but the requested alias does not exist. Applies only to read-only requests. | | `TPL_NOT_FOUND` | All auth rules matched but the requested index template does not exist. Applies only to read-only requests. | | `IMPERSONATION_NOT_SUPPORTED` | The rule being evaluated does not support impersonation, which was attempted by the request. | | `IMPERSONATION_NOT_ALLOWED` | Impersonation was attempted but the impersonator is not allowed to impersonate the target user under this block. | **`blocks_history` in audit logs** The same per-block information is also available in structured form in the `blocks_history` field of audit log entries. Each element in the array represents one evaluated ACL block: ```json "blocks_history": [ { "block_name": "KIBANA", "matched": false, "forbidden_cause": "AUTH_FAIL(Username mismatch)" }, { "block_name": "Admins", "matched": true, "forbidden_cause": null } ] ``` Each entry has three fields: * `block_name` — the name of the ACL block * `matched` — `true` if the block permitted the request, `false` if it was rejected * `forbidden_cause` — the denial reason in the same format as `HIS`, or `null` if the block matched #### Enabling debug logs You can configure Elasticsearch logging by editing the `$ES_PATH_CONF/log4j2.properties` file. See [the official Elasticsearch logging documentation](https://www.elastic.co/docs/deploy-manage/deploy/self-managed/configure-elasticsearch#logging) for details. **Global debug mode** To enable debug logging globally, set the root logger level to `debug`: ``` rootLogger.level = debug ``` **Only ReadonlyREST debug mode** To enable debug logging only for ReadonlyREST, append the following to `log4j2.properties`: ``` logger.ror.name=tech.beshu.ror logger.ror.level=debug ``` **Trick: log requests to different files** Use the following `log4j2.properties` snippet to write ReadonlyREST ACL/request logs to a dedicated rolling file: ``` # ReadonlyREST ACL/request log -> separate rolling file appender.readonlyrest_acl_rolling.type = RollingFile appender.readonlyrest_acl_rolling.name = readonlyrest_acl_rolling appender.readonlyrest_acl_rolling.fileName = ${sys:es.logs}_readonlyrest_acl.log appender.readonlyrest_acl_rolling.filePattern = ${sys:es.logs}_readonlyrest_acl-%d{yyyy-MM-dd}.log.gz appender.readonlyrest_acl_rolling.layout.type = PatternLayout appender.readonlyrest_acl_rolling.layout.pattern = [%d{ISO8601}][%-5p][%-25c] %marker%.-10000m%n appender.readonlyrest_acl_rolling.policies.type = Policies appender.readonlyrest_acl_rolling.policies.time.type = TimeBasedTriggeringPolicy appender.readonlyrest_acl_rolling.policies.time.interval = 1 appender.readonlyrest_acl_rolling.policies.time.modulate = true logger.readonlyrest_acl.name = tech.beshu.ror logger.readonlyrest_acl.level = info logger.readonlyrest_acl.appenderRef.readonlyrest_acl_rolling.ref = readonlyrest_acl_rolling logger.readonlyrest_acl.additivity = false # Optional: exclude noisy service users logger.readonlyrest_acl.filter.regex.type = RegexFilter logger.readonlyrest_acl.filter.regex.regex = .*USR:(kibana|beat|logstash),.* logger.readonlyrest_acl.filter.regex.onMatch = DENY logger.readonlyrest_acl.filter.regex.onMismatch = ACCEPT ``` This configuration keeps ReadonlyREST ACL/request entries out of the main Elasticsearch log and writes them to a separate daily-rotated file instead. ReadonlyREST logs one line per incoming request, and the tech.beshu.ror logger is the logger to target for this purpose. ## Licensing ### GPLv3 License ReadonlyREST Free (Elasticsearch plugin) is released under the GPLv3 license. For what this kind of software concerns, this is identical to GPLv2, that is, you can treat ReadonlyREST as you would treat Linux code. The big difference from Linux is that here you can ask for a commercial license and stop thinking about legal implications. Here is a practical summary of what dealing with GPLv3 means: #### You CAN * Distribute for free or commercially a version (partial or total) of this software (along with its license and attributions) as part of a product or solution that is also **released under GPL-compatible license**. Please notify us if you do so. * Use a modified version **internally to your company** without making your changes available under the GPLv3 license. * Distribute for free or commercially a modified version (partial or total) of this software, provided that the source is contributed back as pull request to the [original project](https://github.com/sscarduzio/elasticsearch-readonlyrest-plugin) or publicly made available under the GPLv3 or compatible license. #### You CANNOT * Sell or give away a modified version of the plugin (or parts of it, or any derived work) without publishing the modified source under GPLv3 compatible licenses. * Modify the code for a paying client without immediately contributing your changes back to this project's GitHub as a pull request, or alternatively publicly release said fork under GPLv3 or compatible license. #### GPLv3 license FAQ **1. Q**: I sell a proprietary software solution that already includes many other OSS components (i.e. Elasticsearch). Can I bundle also ReadonlyREST into it? > **A**: No, GPLv3 does not allow it. But hey, no problem, just go for the [Enterprise subscription](https://readonlyrest.com/enterprise). **2. Q**: I have a SaaS and we want to use a version of ReadonlyREST for Elasticsearch (as is, or modified), do I need a commercial license? > **A**: No, you don't. Go for it! However if you are using Kibana, consider the [Enterprise offer](https://readonlyrest.com/enterprise) which includes multi-tenancy. **3. Q**: I'm a consultant and I will charge my customer for modifying this software and they will not sell it as a product or part of their product. > **A**: This is fine with GPLv3. ### Dual-license Please don't hesitate to [contact us](mailto:info@readonlyrest.com) for a re-licensed copy of this source. Your success is what makes this project worthwhile, don't let legal issues slow you down. See [commercial license FAQ page](/develop/commercial) for more information. # Audit configuration ReadonlyREST can collect audit events containing information about a request and how the system has handled it and send them to configured outputs. Here is an example of the data points contained in each audit event. We can leverage all this information to build interesting Kibana dashboards, or any other visualization. ```json { "error_message": null, "headers": [ "Accept", "Authorization", "content-length", "Host", "User-Agent" ], "acl_history": "[[::LOGSTASH::->[auth_key->false]], [kibana->[auth_key->false]], [::RO::->[auth_key->false]], [::RW::->[kibana->true, indices->true, auth_key->true]]]", "origin": "127.0.0.1", "final_state": "ALLOWED", "task_id": 1158, "type": "SearchRequest", "req_method": "GET", "path": "/readonlyrest_audit-2017-06-29/_search?pretty", "indices": [ "readonlyrest_audit-2017-06-29" ], "@timestamp": "2017-06-30T09:41:58Z", "content_len_kb": 0, "error_type": null, "processingMillis": 0, "action": "indices:data/read/search", "matched_block": "::RW::", "id": "933409190-292622897#1158", "content_len": 0, "logged_user": "simone", "presented_identity": "simone" } ``` ## Configuration The audit outputs are disabled by default. To enable them, add `audit.enabled: true` and optionally configure `audit.outputs`. **Note**: Even when `audit.enabled` is `false` or not set, the built-in ACL log is a special case — it writes a human-readable decision line to Elasticsearch logs for every request by default. See [The default ACL log](#the-default-acl-log) below. The following is the explicit equivalent of the default behaviour when no `audit` section is configured at all: ```yaml readonlyrest: audit: enabled: false # audit outputs disabled default_acl_log_enabled: true # ACL log still fires for every request ``` When `audit.enabled: true` and no `outputs` are specified, ROR defaults to storing events in a local Elasticsearch index. ### Global audit settings ```yaml readonlyrest: audit: enabled: true # enable/disable the entire audit subsystem default_acl_log_enabled: true # enable/disable the built-in ACL log (default: true) outputs: - type: index name: my-index-sink # optional name, used for per-block sink routing ``` | Setting | Default | Description | | ------------------------- | ---------------------- | ------------------------------------------------ | | `enabled` | `false` | Master switch for the audit subsystem | | `default_acl_log_enabled` | `true` | Controls the built-in ACL log output (see below) | | `outputs` | default `index` output | List of audit outputs | Each entry in `outputs` accepts an optional `name` field. Names are only needed for per-block routing: when you want a specific block to send events to only a subset of outputs, you reference them by name using `enabled_audit_sinks` or `disabled_audit_sinks` (see [Block-level audit control](#block-level-audit-control)). If you do not need per-block routing, you can omit `name` from all outputs. ### The default ACL log When `default_acl_log_enabled: true` (the default), ROR writes a human-readable ACL decision line to Elasticsearch logs for every request, using the logger named `tech.beshu.ror.accesscontrol.logging.AccessControlListLoggingDecorator`. This happens regardless of whether any `outputs` are configured. The default ACL log is exposed as a named output with the reserved name `default_acl_log`. You can use this name in block-level `enabled_audit_sinks` and `disabled_audit_sinks` to include or exclude it from per-block routing: ```yaml readonlyrest: audit: enabled: true default_acl_log_enabled: true outputs: - type: index name: my-index-sink access_control_rules: - name: High-volume service account auth_key: svc:secret audit: # send events only to the index, skip the ACL log line for this noisy block enabled_audit_sinks: [my-index-sink] - name: Admin users auth_key: admin:admin # No audit section — all outputs active with default settings ``` To replace the default ACL log with a custom one — for example to send it to a different file — disable it globally and add a `log` output with the `acl` serializer: ```yaml readonlyrest: audit: enabled: true default_acl_log_enabled: false # turn off the built-in ACL log outputs: - type: log name: custom-acl-log logger_name: my.custom.acl.logger serializer: type: acl # reproduces the built-in ACL log format ``` `logger_name` is the log4j2 logger name that ROR uses when writing to this output (default: `readonlyrest_audit`). Setting a custom value lets you route these log lines to a dedicated appender in `log4j2.properties` — for example to write them to a separate file. See [Custom logging settings via log4j2](#custom-logging-settings-via-log4j2) for an example appender configuration. The `acl` serializer produces exactly the same single-line human-readable format as the built-in ACL log: a concise decision summary that includes the request identity, matched block, final state, and key request details. The format is unchanged compared to previous versions. ### Block-level audit control The `audit` section inside each `access_control_rules` block lets you tune audit behaviour per block. ```yaml access_control_rules: - name: Example block auth_key: user:pass audit: enabled: true # default: true — set to false to suppress all audit for this block log_allowed_events: true # default: true — set to false to suppress allowed-request events enabled_audit_sinks: [] # whitelist: only these named sinks receive events from this block disabled_audit_sinks: [] # blacklist: all sinks except these receive events from this block ``` | Setting | Default | Description | | ---------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | `true` | When `false`, no audit events are emitted when this block is matched, regardless of global settings | | `log_allowed_events` | `true` | When `false`, allowed requests matched by this block are not written to audit. Denied requests, errors, and index-not-found responses are always written | | `enabled_audit_sinks` | (all sinks) | Whitelist of sink names. Only the listed sinks receive events from this block. Use sink `name` values from `audit.outputs`, plus `default_acl_log` for the built-in ACL log | | `disabled_audit_sinks` | (none) | Blacklist of sink names. All sinks except the listed ones receive events from this block | `enabled_audit_sinks` and `disabled_audit_sinks` are mutually exclusive — you cannot specify both on the same block. **⚠️IMPORTANT**: When `audit.enabled: false` for a specific block, there will be no audit events at all when that block is matched — this suppresses both custom outputs and the default ACL log. **This is a change in behaviour from previous versions**, where block-level `audit: {enabled: false}` only suppressed the ES audit sinks while the ACL log continued to write. #### Per-sink routing example ```yaml readonlyrest: audit: enabled: true outputs: - type: index name: security-index - type: log name: ops-log access_control_rules: - name: Security-sensitive block auth_key: admin:admin audit: # Only write to the security index, skip the ops log and default ACL log enabled_audit_sinks: [security-index] - name: Noisy read-only block auth_key: reader:pass audit: # Skip allowed events entirely, errors still get written log_allowed_events: false # Write to ops log only, skip security index for this block enabled_audit_sinks: [ops-log] - name: Regular block auth_key: user:pass # No audit section = all sinks active with default settings ``` ### Multiple outputs You can configure multiple audit outputs, including mixing output types: ```yaml readonlyrest: audit: enabled: true outputs: - type: index name: audit-index - type: log name: audit-log - type: data_stream name: audit-stream enabled: false # this output is defined but currently disabled ``` Each output can be individually toggled with `enabled: true/false` (default: `true`). ### Backward compatibility The `verbosity: error` and `verbosity: info` block-level settings from earlier versions are still accepted. They are treated as aliases for `audit: {log_allowed_events: false}` and `audit: {log_allowed_events: true}` respectively. All other global audit settings (`audit.enabled`, `audit.outputs` and their sub-settings) are unchanged. Existing configurations that do not use the new settings will continue to work without modification. The `default_acl_log_enabled` setting defaults to `true`, so the ACL log continues to fire exactly as before for configurations that do not set it explicitly. ### The 'index' output specific configurations #### Custom audit indices name and time granularity By default, the ReadonlyREST audit index name template is `readonlyrest_audit-YYYY-MM-DD`. You can customize the name template using the `index_template` settings. Example: tell ROR to write on the monthly index. ```yaml readonlyrest: audit: enabled: true outputs: - type: index index_template: "'custom-prefix'-yyyy-MM" # <--monthly pattern ... ``` **⚠️IMPORTANT**: Notice the single quotes inside the double-quoted expression. This is the same syntax used for [Java's SimpleDateFormat](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html). #### Custom audit cluster It's possible to set up a custom audit cluster responsible for storing audit events. When a custom cluster is specified, items will be sent to defined cluster nodes instead of the local one. **⚠️IMPORTANT**: Audit events are sent to audit nodes using a round-robin strategy. All audit nodes must belong to the same Elasticsearch cluster. Otherwise, each audit cluster will contain only a subset of audit events. If you intend to send audit events to multiple clusters, define one output per Elasticsearch cluster. ```yaml readonlyrest: audit: enabled: true outputs: - type: index cluster: ["https://user1:password@auditNode1:9200", "https://user2:password@auditNode2:9200"] ... ``` Setting `audit.cluster` is optional, it accepts a non-empty list of audit cluster nodes URIs. ### The 'data\_stream' output specific configurations #### Custom audit data stream name To change the default data stream name `readonlyrest_audit`, add the following configuration to your `readonlyrest.yml` config: ```yaml readonlyrest: audit: enabled: true outputs: - type: data_stream data_stream: "custom_audit_data_stream" ``` Here, `custom_audit_data_stream` is the Elasticsearch data stream where audit events will be stored. If the specified data stream does not exist, it will be automatically created by the ReadonlyREST plugin. This creation process includes setting up the following components, each dedicated specifically to the configured data stream: * A dedicated Index Lifecycle Policy `({{data-stream-name}}-lifecycle-policy)`. * Necessary index settings and mappings (component templates: `{{data-stream-name}}-mappings` and `{{data-stream-name}}-settings`). * A customized Index Template (`{{data-stream-name}}-template`). #### Custom audit cluster It's possible to set a custom audit cluster responsible for audit events storage. When a custom cluster is specified, items will be sent to defined cluster nodes instead of the local one. **⚠️IMPORTANT**: Audit events are sent to audit nodes using a round-robin strategy. All audit nodes must belong to the same Elasticsearch cluster. Otherwise, each audit cluster will contain only a subset of audit events. If you intend to send audit events to multiple clusters, define one output per Elasticsearch cluster. ```yaml readonlyrest: audit: enabled: true outputs: - type: data_stream cluster: ["https://user1:password@auditNode1:9200", "https://user2:password@auditNode2:9200"] ... ``` Setting `audit.cluster` is optional, it accepts a non-empty list of audit cluster nodes URIs. #### Data stream settings Here are the default settings set for the audit data stream created by the ReadonlyREST plugin: ![Audit data stream](/files/aAeaNTBW2asbVdWZ2avB) ![Audit data stream template](/files/1rSw5sIVBmd0tqKeH0eL) ![Index lifecycle policy defaults](/files/dXNpJ46ftfDAFU7KlpDU) Managing Elasticsearch data streams, such as the ReadonlyREST audit data stream, should be customized based on your specific use case. Aspects like: * data retention policies (how long to keep and when to delete data), * migrating old indices into the new data stream, * handling transitions between different index lifecycle phases (e.g., hot, warm, cold, delete), depend on your business requirements, data volume and characteristics, and how the data is analyzed and used. Therefore, we encourage you to configure these settings yourself to best fit your needs. Elasticsearch provides flexible tools, like Index Lifecycle Management (ILM), that allow automating data management based on user-defined rules. Customizing your configuration helps optimize storage costs and search performance. You can manage and update settings related to your audit data stream directly from Kibana's **Index Management** UI. **Steps to Change Data Stream Settings using Kibana** 1. **Open Kibana and Navigate to Index Management** * In Kibana, go to **Management** > **Stack Management** > **Index Management**. * Select the **Data Streams** tab to see the list of available data streams. 2. **Select Your Audit Data Stream** * Find your audit data stream (e.g., `custom_audit_data_stream`) in the list. * Click on it to view details such as indices backing the data stream, mappings, and lifecycle policies. 3. **Edit Index Lifecycle Policy (ILM)** * If you want to update rollover criteria, retention period, or other lifecycle actions: * Navigate to **Index Lifecycle Policies** under **Stack Management**. * Select the ILM policy associated with your audit data stream. * Modify phases such as `hot`, `warm`, or `delete` to adjust settings like maximum size, max age, or deletion timing. * Save your changes — they will be applied automatically to the indices backing the data stream. 4. **Update Index Template** * To change index settings or mappings for new backing indices: * Go to **Index Templates** in Stack Management. * Locate the template associated with your audit data stream (usually matching the data stream name or pattern). * Edit the template's settings or mappings as needed. * Save the updated template; new indices created for the data stream will use these settings. 5. **Verify Changes** * After updating policies or templates, monitor your data stream to ensure rollover and retention behave as expected. * You can also query audit events via Kibana's Discover tab or using the Elasticsearch API. **Important Notes** * Changes to lifecycle policies and index templates affect **new indices** created after the update; existing indices are not modified retroactively. * To apply mapping changes to existing indices, you may need to reindex data. * Ensure you carefully test ILM and template changes in a staging environment before applying to production audit streams. #### Rolling Migration from `index` to `data_stream` To migrate ReadonlyREST audit logging from the `index` output type to `data_stream` in a **rolling update**, follow this safe, zero-downtime approach: 1. **Add `data_stream` as an Additional Output** Temporarily configure both `index` and `data_stream` outputs so that audit events are sent to both destinations: ```yaml readonlyrest: audit: enabled: true outputs: - type: index - type: data_stream # add data stream output type to your config data_stream: "custom_audit_data_stream" ``` > ✅ This ensures no audit logs are lost during the transition. 2. **Verify Data Stream Creation** ``` GET _data_stream/custom_audit_data_stream ``` Ensure the data stream is being created and audit events are flowing in. 3. **Monitor for Consistency** Use Kibana or the `_search` API to confirm that events are present in both audit indices and `custom_audit_data_stream`. 4. **(Optional) Backfill Historical Data** If you wish to migrate historical audit data from the old audit index, you can reindex it manually: ```json POST _reindex { "conflicts": "proceed", "source": { "index": "readonlyrest_audit-2025-06-07" }, "dest": { "index": "custom_audit_data_stream", "op_type": "create" } } ``` > ⚠️ Ensure both audit outputs have the same serializer for data consistency. > ⚠️ Data streams are append-only — use `"op_type": "create"` to avoid overwrites. > ⚠️ If the source index contains documents already present in the destination data stream, `"conflicts": "proceed"` will skip duplicates. 5. **Remove the `index` Output** After confirming successful logging to the data stream from all nodes, update your config to remove the `index` output: ```yaml readonlyrest: audit: enabled: true outputs: - type: data_stream data_stream: "custom_audit_data_stream" ``` 6. **Final Verification** Use Kibana dashboards, metrics, or direct queries to confirm that new audit events are flowing into the configured data stream. ### The 'log' output specific configurations The `log` output writes audit events to Elasticsearch log at INFO level using a dedicated logger. ```yaml readonlyrest: audit: enabled: true outputs: - type: log ... ``` #### Built-in rolling file appender For a self-contained rolling file output — without editing `log4j2.properties` — use the `file_appender` sub-section: ```yaml readonlyrest: audit: enabled: true outputs: - type: log name: rolling-audit file_appender: file_path: /var/log/elasticsearch/ror_audit.log # absolute path; directory must be writable max_file_size: "100MB" # accepted units: B, KB, MB, GB, TB max_files: 10 # number of rotated files to keep ``` When `file_appender` is present, ROR creates and manages the rolling appender internally, bypassing the default Elasticsearch log routing for this output. The `logger_name` setting is still accepted and used as the appender name. #### Custom logger name If you want to route log output through a specific log4j2 logger: ```yaml readonlyrest: audit: enabled: true outputs: - type: log logger_name: custom-logger-name ... ``` The default logger name is `readonlyrest_audit`. #### Custom logging settings via log4j2 For advanced log configuration — custom patterns, external syslog appenders, etc. — configure the logger in `$ES_PATH_CONF/config/log4j2.properties`. The logger name must match the `logger_name` value in the output config (or the default `readonlyrest_audit`): ``` appender.readonlyrest_audit_rolling.type = RollingFile appender.readonlyrest_audit_rolling.name = readonlyrest_audit_rolling appender.readonlyrest_audit_rolling.fileName = ${sys:es.logs.base_path}${sys:file.separator}readonlyrest_audit.log appender.readonlyrest_audit_rolling.layout.type = PatternLayout appender.readonlyrest_audit_rolling.layout.pattern = [%d{ISO8601}] %m%n appender.readonlyrest_audit_rolling.filePattern = readonlyrest_audit-%i.log.gz appender.readonlyrest_audit_rolling.policies.type = Policies appender.readonlyrest_audit_rolling.policies.size.type = SizeBasedTriggeringPolicy appender.readonlyrest_audit_rolling.policies.size.size = 1GB appender.readonlyrest_audit_rolling.strategy.type = DefaultRolloverStrategy appender.readonlyrest_audit_rolling.strategy.max = 4 # Logger name must match the one configured in readonlyrest.yml (or the default "readonlyrest_audit") logger.readonlyrest_audit.name = readonlyrest_audit logger.readonlyrest_audit.appenderRef.readonlyrest_audit_rolling.ref = readonlyrest_audit_rolling # set to false to use only desired appenders logger.readonlyrest_audit.additivity = false ``` #### ACL serializer The `log` output type supports a special `acl` serializer that reproduces the human-readable format written by the default ACL log. This is useful when you want to disable the built-in ACL log (`default_acl_log_enabled: false`) and replace it with a custom log sink that you can route per-block: ```yaml readonlyrest: audit: enabled: true default_acl_log_enabled: false outputs: - type: log name: custom-acl-log logger_name: my.acl.logger serializer: type: acl ``` The `acl` serializer type is only valid for `log` outputs. Attempting to use it with `index` or `data_stream` outputs will produce a configuration error. ## Extending audit events The audit events are JSON documents describing incoming requests and how the system has handled them. To create such events, we use a `serializer`, which is responsible for the event's serialization and filtering. The example [event](#audit) is in default format and was produced by the default serializer (`tech.beshu.ror.audit.instances.BlockVerbosityAwareAuditLogSerializer`). You can: * skip serializer configuration - in that case the default is `tech.beshu.ror.audit.instances.BlockVerbosityAwareAuditLogSerializer` ```yaml readonlyrest: audit: enabled: true outputs: - type: index ``` * use any of the predefined serializers ([see the list of predefined serializers](#predefined-serializers)) ```yaml readonlyrest: audit: enabled: true outputs: - type: index serializer: type: "static" class_name: "tech.beshu.ror.audit.instances.QueryAuditLogSerializer" # or any other serializer class ``` * use dynamic, configurable serializer - define JSON fields in ReadonlyREST settings (no implementation required, [see how to do it](#using-configurable-serializer)) * use ECS ([Elastic Common Schema](https://www.elastic.co/docs/reference/ecs)) serializer (no implementation required, [learn more about it](#using-ecs-serializer)) * implement and use your own serializer ([see how to implement a custom serializer](#custom-audit-event-serializer)) ### Predefined serializers: * `tech.beshu.ror.audit.instances.BlockVerbosityAwareAuditLogSerializer` * Serializes all non-`Allowed` events. * Serializes `Allowed` events only when the matched block has `log_allowed_events: true` (the default). * Recommended for standard audit logging, where full request body capture is not required. * Fields included: ``` match — whether the request matched a rule (boolean) matched_block_names - list of names of the blocks, that were matched (both forbidden and allowed) (array of strings) id — audit event identifier (string) final_state — final processing state (ALLOWED/FORBIDDEN/ERRORED/INDEX NOT EXIST) (string) @timestamp — event timestamp (ISO-8601 string) correlation_id — correlation identifier for tracing (string) processingMillis — request processing duration in milliseconds (number) error_type — type of error, if any (string) error_message — error message, if any (string) content_len — request body size in bytes (number) content_len_kb — request body size in kilobytes (number) type — request type (string) origin — client (remote) address (string) destination — server (local) address (string) xff — X-Forwarded-For HTTP header value (string) task_id — Elasticsearch task ID (number) req_method — HTTP request method (string) headers — HTTP header names (array of strings) path — HTTP request path (string) user — authenticated user (string) - deprecated field, please use `logged_user` or `presented_identity` logged_user — human-readable username (string) presented_identity — user identity that was presented with the request, e.g. basic auth username (string) impersonated_by — impersonating user, if applicable (string) action — Elasticsearch action name (string) indices — indices involved in the request (array of strings) acl_history — access control evaluation history (string) es_node_name — Elasticsearch node name (string) es_cluster_name — Elasticsearch cluster name (string) ``` * `tech.beshu.ror.audit.instances.QueryAuditLogSerializer` * Similar to the `BlockVerbosityAwareAuditLogSerializer` regarding `Allowed` event handling and included JSON fields. * Additionally, captures the full request body (`content` field) * Recommended for standard audit logging, where full request body capture is required. * `tech.beshu.ror.audit.instances.FullAuditLogSerializer` * Serializes all events of all types, including all `Allowed` events, regardless of the block's `log_allowed_events` setting. * Included fields are the same as for `BlockVerbosityAwareAuditLogSerializer` * Use this serializer, when you need complete coverage of all events. * `tech.beshu.ror.audit.instances.FullAuditLogWithQuerySerializer` * Serializes all events of all types, including all `Allowed` events, regardless of the block's `log_allowed_events` setting. * Included fields are the same as for `QueryAuditLogSerializer` (includes `content` field - full request body) * Use this serializer, when you need complete coverage of all events with full request body. ### Using configurable serializer: Configuration should look like that: ```yaml readonlyrest: audit: enabled: true outputs: - type: index serializer: type: "configurable" allowed_events_serialization_mode: "based_on_block_settings" # serialize Allowed events only from blocks with log_allowed_events: true (default); use "always" to serialize all Allowed events fields: # list of fields in the resulting JSON; placeholders (like {ES_NODE_NAME}) will be replaced with their corresponding values node_details: "{ES_CLUSTER_NAME}/{ES_NODE_NAME}" http_request: "{HTTP_METHOD} {HTTP_PATH}" tid: "{TASK_ID}" bytes: "{CONTENT_LENGTH_IN_BYTES}" ``` The configuration above corresponds to serialized event looking like that: ```json { "node_details": "mainEsCluster/esNode01", "http_request": "GET /_cat", "tid": 0, "bytes": 123 } ``` You can also define nested structure of fields, and use fixed text, number and boolean values: ```yaml fields: tid: "{TASK_ID}" es_details: node_name: "{ES_NODE_NAME}" cluster_name: "{ES_CLUSTER_NAME}" event_details: custom_system_id: 12345 # example of hardcoded number value, can also be a decimal number; in this example represents some hardcoded system id is_dev_environment: false # example of hardcoded boolean value; in this example represents flag marking the events from development environment http: request_description: "HTTP request: {HTTP_METHOD} {HTTP_PATH}" request_details: method: "{HTTP_METHOD}" path: "{HTTP_PATH}" ``` The configuration above corresponds to serialized event looking like that: ```json { "tid": 0, "es_details": { "node_name": "esNode01", "cluster_name": "mainEsCluster" }, "event_details": { "custom_system_id": 12345, "is_dev_environment": false, "http": { "request_description": "HTTP request: GET /_cat", "request_details": { "method": "GET", "path": "/_cat" } } } } ``` Available placeholders: ``` {IS_MATCHED} — whether the request matched a rule (boolean) {MATCHED_BLOCK_NAMES} — list of names of the blocks that were matched, both allowed and forbidden (array of strings) {ID} — audit event identifier (string) {FINAL_STATE} — final processing state (string) {ECS_EVENT_OUTCOME} - final processing state, mapped to ECS-compliant values: success/failure/unknown (string) {TIMESTAMP} — event timestamp (ISO-8601 string) {CORRELATION_ID} — correlation identifier for tracing (string) {PROCESSING_DURATION_MILLIS} — request processing duration in milliseconds (number) {PROCESSING_DURATION_NANOS} — request processing duration in nanoseconds (number) {ERROR_TYPE} — type of error, if any (string) {ERROR_MESSAGE} — error message, if any (string) {CONTENT_LENGTH_IN_BYTES} — request body size in bytes (number) {CONTENT_LENGTH_IN_KB} — request body size in kilobytes (number) {TYPE} — request type (string) {REMOTE_ADDRESS} — client (remote) address (string) {LOCAL_ADDRESS} — server (local) address (string) {X_FORWARDED_FOR_HTTP_HEADER} — `X-Forwarded-For` HTTP header value (string) {TASK_ID} — Elasticsearch task ID (number) {HTTP_METHOD} — HTTP request method (string) {HTTP_HEADER_NAMES} — HTTP header names (array of strings) {HTTP_PATH} — HTTP request path (string) {LOGGED_USER} — human-readable username (string) {PRESENTED_IDENTITY} — user identity that was presented with the request, e.g. basic auth username (string) {IMPERSONATED_BY_USER} — impersonating user, if applicable (string) {ACTION} — Elasticsearch action name (string) {INVOLVED_INDICES} — indices involved in the request (array of strings) {ACL_HISTORY} — access control evaluation history (string) {CONTENT} — request body content (string or object) {ES_NODE_NAME} — Elasticsearch node name (string) {ES_CLUSTER_NAME} — Elasticsearch cluster name (string) ``` ### Using ECS serializer: Configuration should look like that: ```yaml readonlyrest: audit: enabled: true outputs: - type: index serializer: type: "ecs" allowed_events_serialization_mode: "based_on_block_settings" # serialize Allowed events only from blocks with log_allowed_events: true (default); use "always" to serialize all Allowed events include_full_request_content: false # controls whether the full HTTP request body is included in the ECS audit log (http.request.body field), disabled by default ``` The configuration above corresponds to serialized event, compatible with ECS 1.6 schema, looking like that: ```json { "@timestamp": "2017-06-30T09:41:58Z", "trace" : { "id" : "correlation_id_123" }, "ecs" : { "version" : "1.6.0" }, "source" : { "address" : "192.168.0.123" }, "destination" : { "address" : "192.168.100.100" }, "http" : { "request" : { "method" : "GET", "body" : { "bytes" : 123, "content" : "Full content of the request" } } }, "event" : { "duration" : 5000000000, "reason" : "RRTestConfigRequest", "action" : "cluster:internal_ror/user_metadata/get", "id" : "trace_id_123", "outcome" : "failure" }, "error" : {}, "user" : { "effective" : { "name" : "impersonated_by_user" }, "name" : "logged_user" }, "url" : { "path" : "/path/to/resource" }, "labels" : { "es_cluster_name" : "testEsCluster", "es_task_id" : 123, "es_node_name" : "testEsNode", "ror_acl_history" : "historyEntry1, historyEntry2", "ror_detailed_reason" : "default", "ror_involved_indices" : [], "ror_final_state" : "FORBIDDEN" } } ``` The ECS schema is highly permissive and ambiguous. The ROR audit events can be mapped to ECS fields in multiple ways. If the provided ECS implementation does not suit your needs, you can define your own ECS-compliant serializer as `configurable` serializer. The provided ECS implementation is equivalent to `configurable` serializer shown below. You can [use and adjust it as needed](#using-configurable-serializer) in the configuration. ```yaml readonlyrest: audit: enabled: true outputs: - type: index serializer: type: "configurable" allowed_events_serialization_mode: "based_on_block_settings" fields: ecs: version: "1.6.0" trace: id: "{CORRELATION_ID}" url: path: "{HTTP_PATH}" source: address: "{REMOTE_ADDRESS}" destination: address: "{LOCAL_ADDRESS}" http: request: method: "{HTTP_METHOD}" body: # Warning: Enabling logging of the full HTTP request body is not recommended when requests # may contain sensitive data. It can also significantly increase the size of audit log entries. content: "{CONTENT}" bytes: "{CONTENT_LENGTH_IN_BYTES}" user: name: "{LOGGED_USER}" effective: name: "{IMPERSONATED_BY_USER}" event: id: "{ID}" duration: "{PROCESSING_DURATION_NANOS}" action: "{ACTION}" reason: "{TYPE}" outcome: "{ECS_EVENT_OUTCOME}" error: type: "{ERROR_TYPE}" message: "{ERROR_MESSAGE}" labels: x_forwarded_for: "{X_FORWARDED_FOR_HTTP_HEADER}" es_cluster_name: "{ES_CLUSTER_NAME}" es_node_name: "{ES_NODE_NAME}" es_task_id: "{TASK_ID}" ror_involved_indices: "{INVOLVED_INDICES}" ror_acl_history: "{ACL_HISTORY}" ror_final_state: "{FINAL_STATE}" ror_matched_block_names: "{MATCHED_BLOCK_NAMES}" ``` ### Custom audit event serializer You can write your own custom audit events serializer class, add it to the ROR plugin class path and configure it through the YAML settings. We provided 2 project examples with custom serializers (in Scala and Java). You can use them as an example to write yours in one of those languages. #### Create custom audit event serializer in Scala 1. Checkout `git clone git@github.com:sscarduzio/elasticsearch-readonlyrest-plugin.git` 2. Install SBT `https://www.scala-sbt.org/download.html` 3. Find and go to: `elasticsearch-readonlyrest-plugin/custom-audit-examples/ror-custom-scala-serializer/` 4. Create own serializer: * from scratch (example can be found in class `ScalaCustomAuditLogSerializer`) * extending default one (example can be found in class `ScalaCustomAuditLogSerializer`) 5. Build serializer JAR: `sbt assembly` 6. Jar can be find in: `elasticsearch-readonlyrest-plugin/custom-audit-examples/ror-custom-scala-serializer/target/scala-2.13/ror-custom-scala-serializer-1.0.0.jar` #### Create custom audit event serializer in Java 1. Checkout `git clone git@github.com:sscarduzio/elasticsearch-readonlyrest-plugin.git` 2. Install Maven `https://maven.apache.org/install.html` 3. Find and go to: `elasticsearch-readonlyrest-plugin/custom-audit-examples/ror-custom-java-serializer/` 4. Create own serializer: * from scratch (example can be found in class `JavaCustomAuditLogSerializer`) * extending default one (example can be found in class `JavaCustomAuditLogSerializer`) 5. Build serializer JAR: `mvn package` 6. Jar can be find in: `elasticsearch-readonlyrest-plugin/custom-audit-examples/ror-custom-java-serializer/target/ror-custom-java-serializer-1.0.0.jar` #### Configuration 1. mv ror-custom-java-serializer-1.0.0.jar plugins/readonlyrest/ 2. Your config/readonlyrest.yml should start like this ```yaml readonlyrest: audit: enabled: true outputs: - type: index serializer: type: "static" class_name: "JavaCustomAuditLogSerializer" # when your serializer class is not in default package, you should use full class name here (eg. "tech.beshu.ror.audit.instances.QueryAuditLogSerializer") ``` 3. Start elasticsearch (with ROR installed) and grep for: ``` [2023-03-26T16:28:40,471][INFO ][t.b.r.a.f.d.AuditingSettingsDecoder$] Using custom serializer: JavaCustomAuditLogSerializer ``` ## Protecting the audit index To prevent users from modifying or deleting audit data, add a `forbid` block to your `readonlyrest.yml` that blocks write and delete actions on the audit indices. ```yaml - name: "Protect audit index" type: forbid indices: ["readonlyrest_audit-*"] actions: - "indices:data/write/*" # index, update, delete, bulk, *_by_query, reindex-into - "indices:admin/delete" # delete the index - "indices:admin/close" # close (then could be re-opened writable) - "indices:admin/open" - "indices:admin/settings/*" # change settings (e.g. flip read-only / replicas) - "indices:admin/mapping/*" # mapping/put + mapping/auto_put (NOT mappings/get — that's read) - "indices:admin/aliases" # re-point / drop the audit aliases - "indices:admin/rollover" - "indices:admin/resize" # shrink / split / clone - "indices:admin/forcemerge" - "indices:admin/freeze" ``` **Placement:** ACL blocks are evaluated top-to-bottom and the first matching block wins. * If no user or service should be able to write to the audit index via the Elasticsearch API, place this block at the **very beginning** of the ACL. Audit events are written internally by the ReadonlyREST plugin and bypass the ACL entirely, so this does not affect audit collection. * If some identities (e.g. a dedicated audit reader service) require access that would conflict with this rule, place the `forbid` block after their `allow` blocks but before all other allow rules. The wildcard pattern `readonlyrest_audit-*` matches the default index name template. If you configured a custom `index_template` prefix, adjust the pattern accordingly. # External to local groups mapping The `groups` ACL rule accepts a list of group IDs. This rule will match on a requests in which the resolved username belongs at least to one of the listed groups. The association between usernames and groups is explicitly declared in the users section of the ACL. This is a list of usernames, and today, full wildcard patterns are also supported. In the `users` section, each entry requires: * an authentication rule: (I.e. one of the `auth_key_*` rules for local credentials, or `ldap_authentication`, `external_authentication`, etc) * a list of groups within the ones precendently inserted in the groups rules of the ACL blocks * optionally, an authorization rule (`ldap_authorization`, `groups_provider_authorization`, etc.) When the users section's `groups` rule and the authorization rule are used together, we obtain "group mapping". That is: we are effectively mapping remote groups to local groups. There are two types of mapping available: **common** and **detailed** group mappings. *Note:* the rule `ldap_auth` is the composition of `ldap_authentication` and `ldap_authorization`. So it can be used as a shortcut for both. ## Example ```yaml readonlyrest: access_control_rules: - name: "Viewer block" indices: ["logstash-viewers*"] groups_any_of: ["viewers"] - name: "DevOps block" indices: ["logstash-devops*"] groups_any_of: ["devops"] [...] users: # PLAIN LOCAL GROUPS EXAMPLE # Local user "joe" is associated to local group "editors" - username: "joe" groups: ["editors"] auth_key: joe:password # COMMON GROUP MAPPING EXAMPLE # Externally authenticated user + authorization via external groups provider + groups common mapping # Users belonging to "external_group1" OR "external_group2" are authorized as "viewers" AND "editors" in the ACL. - username: "*" groups: ["viewers", "editors"] external_authentication: "ext1" groups_provider_authorization: user_groups_provider: "ext2" groups_any_of: ["external_group1", "external_group2"] # DETAILED GROUP MAPPING EXAMPLE # LDAP authenticated user + authorization via LDAP + groups detailed mapping (any LDAP user is valid; groups from `ldap1` are mapped to local groups) # Users belonging to LDAP role `ldap_role_ops`, or any other LDAP role that matched `ldap_*_devops` pattern, will be mapped to "devops" local group # AND # Users belonging to LDAP `ldap_role_dev` are mapped to "developers" local group - username: "*" groups: - devops: ["ldap_role_ops", "ldap_*_devops"] - developers: ["ldap_role_dev"] ldap_auth: name: "ldap1" groups_any_of: ["ldap_*_devops", "ldap_role_ops", "ldap_role_dev"] # DETAILED GROUP MAPPING EXAMPLE (STRUCTURED GROUPS) # LDAP authenticated user + authorization via LDAP + groups detailed mapping (any LDAP user is valid; groups from `ldap1` are mapped to local groups) # Users belonging to LDAP role `ldap_role_ops`, or any other LDAP role that matched `ldap_*_devops` pattern, will be mapped to "devops" local group # AND # Users belonging to LDAP `ldap_role_dev` are mapped to "developers" local group - username: "*" groups: - local_group: id: "devops" name: "DevOps Group" external_group_ids: ["ldap_role_ops", "ldap_*_devops"] - local_group: id: "developers" name: "Developers Group" external_group_ids: ["ldap_role_dev"] ldap_auth: name: "ldap1" groups_any_of: ["ldap_*_devops", "ldap_role_ops", "ldap_role_dev"] external_authentication_service_configs: - name: "ext1" [...] user_groups_providers: - name: ext2 [...] ldaps: - name: ldap1 [...] ``` As we can see, there are two blocks in our ACL: 1. `Viewer block` allows all users, which belong to `viewers` group, to access indices matching pattern `logstash-viewers*` 2. `DevOps block` allows all users, which belong to `devops` group, to access indices matching pattern `logstash-devops*` ### Common mapping example ```yml - username: "*" groups: ["viewers", "editors"] external_authentication: "ext1" groups_provider_authorization: user_groups_provider: "ext2" groups_any_of: ["external_group1", "external_group2"] ``` `viewers`, `devops`, (unused in the ACL example), `editors` and `developers` are local groups. That is, they exist only at ROR's configuration level. But ROR can also integrate with external authorization systems like an LDAP or some REST service, where we can find similar concepts to ROR groups (eg. users in LDAP can have roles assigned). And sometimes we'd like to fulfil a requirement such as: > Users having usernames defined by a given pattern, and having a given set of roles, should have certain given ROR internal groups assigned. You can think about it as a mapping external groups to local ones. Let's go back to our example. In the second element of the `users` array, we declare that: * any user can be taken into consideration by this user definition * a user should be authenticated by an `external_authentication` rule which uses the `ext1` service * a user should be authorized by a `groups_provider_authorization` rule which uses the `ext2` service and such user belongs to at least one of `external_group1`, `external_group2` external groups. * if all the above conditions are true, we can assign `viewers`, `editors` groups to the user We have just "mapped" the external groups `external_group1`, `external_group2` returned by service `ext2` to the local ROR groups `viewers`, `editors`. ### Detailed mapping example ```yml - username: "*" groups: - devops: ["ldap_*_devops", "ldap_role_ops"] - developers: ["ldap_role_dev"] ldap_auth: name: "ldap1" groups_any_of: ["ldap_role_devops", "ldap_role_ops", "ldap_role_dev"] ``` The third element of `users` array (in the example above) is similar, but we use one rule which is authentication and authorization rule at the same time (it can authenticate a user and then authorize him). And that's how we defined the following mappings: * `ldap_role_ops` LDAP role, and any other LDAP role matching `ldap_*_devops` pattern, are mapped to `devops` ROR's local group * LDAP role `ldap_role_dev` is mapped to `developers` ROR's local group The "detailed" mapping offers a bit more structured approach to group mapping, and although less intuitive at first sight, it's more powerful and concise. # FIPS mode ## What is FIPS? According to [Wikipedia](https://en.wikipedia.org/wiki/Federal_Information_Processing_Standards) > Federal Information Processing Standards (FIPS) are publicly announced standards developed by the National Institute of Standards and Technology for use in computer systems by non-military American government agencies and government contractors. FIPS standards are issued to establish requirements for various purposes such as ensuring computer security and interoperability and are intended for cases in which suitable industry standards do not already exist. In short it is a thoroughly tested and verified set of standards which could be used to implement high level of security. In terms of software we are usually speaking specifically about FIPS 140-2. ReadonlyREST uses OpenSource [BouncyCastle](https://www.bouncycastle.org) library to provide FIPS 140-2 compliant algorithms. ## Is ReadonlyREST fully compliant to FIPS 140-2? At the moment, ReadonlyREST can be configured as FIPS compliant only from the "data in transit" standpoint. That is, the SSL encryption of the HTTP and transport interfaces. Other aspects remain to be covered: * Making all cryptographic algorithms FIPS compliant. * Enforcing more strict security policies across whole ROR plugin in FIPS mode. ## How to enable SSL FIPS compliance 1. Prepare keystore and truststore in BCFKS format which is FIPS compliant. Your existing JKS or PKCS12 keystore could be easily converted to BCFKS. Process is described [in this section](#how-to-convert-jkspkcs12-keystore-files-into-bcfks). > :warning: BCFKS format is supported only when FIPS mode is enabled. It won't be recognised otherwise. > :warning: When using FIPS mode using different password for specific keystore elements is not supported and `key_pass` configuration field is ignored. 1. Configure readonlyrest.yml to use new keystore and truststore. You will also need to add new configuration parameter `fips_mode`. Here's an example: ``` readonlyrest: fips_mode: SSL_ONLY ssl: enable: true keystore_file: "keystore.bcfks" keystore_pass: readonlyrest truststore_file: "truststore.bcfks" truststore_pass: readonlyrest ssl_internode: enable: true keystore_file: "keystore.bcfks" keystore_pass: readonlyrest truststore_file: "truststore.bcfks" truststore_pass: readonlyrest ``` 1. In case you are using ES >= 7.10 you need to modify `$JAVA_HOME/conf/security/java.policy` file and add this section at the end of it. This is required because otherwise Elasticsearch will not be able grant to our plugin all these permissions at the JVM level. ``` grant { permission org.bouncycastle.crypto.CryptoServicesPermission "exportSecretKey"; permission org.bouncycastle.crypto.CryptoServicesPermission "exportPrivateKey"; permission java.security.SecurityPermission "getProperty.jdk.tls.disabledAlgorithms"; permission java.security.SecurityPermission "getProperty.jdk.certpath.disabledAlgorithms"; permission java.security.SecurityPermission "getProperty.keystore.type.compat"; permission java.security.SecurityPermission "removeProvider.SunRsaSign"; permission java.security.SecurityPermission "removeProvider.SunJSSE"; permission java.io.FilePermission "${java.home}/lib/security/jssecacerts", "read"; permission java.io.FilePermission "${java.home}/lib/security/cacerts", "read"; permission java.security.SecurityPermission "getProperty.jdk.tls.server.defaultDHEParameters"; permission org.bouncycastle.crypto.CryptoServicesPermission "defaultRandomConfig"; }; ``` ## How to convert JKS/PKCS12 keystore files into BCFKS 1. Download the [jar with bc-fips](https://repo1.maven.org/maven2/org/bouncycastle/bc-fips/1.0.2.3/bc-fips-1.0.2.3.jar) library and place it preferably in the same directory where you store keystore files to convert. 2. Open your terminal and go to directory with the keystore to convert 3. Use keytool with following parameters to perform the conversion: ``` keytool \ -importkeystore \ -srckeystore SOURCE_KEYSTORE_FILENAME \ -destkeystore DEST_KEYSTORE_FILENAME \ -srcstoretype SOURCE_KEYSTORE_TYPE \ -deststoretype DEST_KEYSTORE_TYPE \ -srcstorepass SOURCE_KEYSTORE_PASSWORD \ -deststorepass DEST_KEYSTORE_PASSWORD \ -providerpath ./bc-fips-1.0.2.1.jar \ -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider ``` where: * SOURCE\_KEYSTORE\_FILENAME - filename of the keystore(or truststore) that you want to convert. * DEST\_KEYSTORE\_FILENAME - name of the output file. * SOURCE\_KEYSTORE\_TYPE - type of keystore to convert. Must be JKS or PKCS12. * DEST\_KEYSTORE\_TYPE - type of output keystore. Must be BCFKS. * SOURCE\_KEYSTORE\_PASSWORD - password protecting keystore to convert. * DEST\_KEYSTORE\_PASSWORD - password protecting output file. If you saved the bc-fips jar in a different path, remember to run it using the appropriate path instead of `./bc-fips-1.0.2.1.jar` # Elastic Fleet [Elastic Fleet](https://www.elastic.co/guide/en/fleet/current/fleet-overview.html) manages Elastic Agents centrally through Kibana. When Fleet is set up, it creates two kinds of dynamic Elasticsearch credentials that ReadonlyREST needs to recognize and validate: * **Service tokens** - used by Fleet Server to authenticate with Elasticsearch. These are created by Kibana during Fleet setup and belong to Elasticsearch's built-in `elastic/fleet-server` service account. * **API keys** - issued to each enrolled Elastic Agent. Fleet Server creates and rotates these automatically; each agent uses its own key to ship data. Because both credential types are generated at runtime (not known in advance), they cannot be matched with static `auth_key` or `auth_key_sha256` rules. Instead, ReadonlyREST's `token_authentication` rule with `type: service-token` or `type: api-key` delegates validation to Elasticsearch, which has the ground truth for both. ## ReadonlyREST settings ```yaml readonlyrest: access_control_rules: # 1. Kibana user - used by Kibana itself and by Fleet initialisation scripts. # No action or index restriction; Kibana needs unrestricted access during # Fleet setup (e.g. bootstrapping the Fleet Server service account). - name: "KIBANA" type: allow auth_key: kibana:kibana # 2. Fleet Server - authenticates using an Elasticsearch service token. # ReadonlyREST validates the token against Elasticsearch's service account API. # No action restriction: Fleet Server needs to call # cluster:admin/xpack/security/api_key/create to issue API keys to # enrolling agents. - name: "Fleet server" type: allow token_authentication: type: "service-token" username: "fleet" indices: - ".fleet-servers" - ".fleet-agents" - ".fleet-actions" - ".fleet-policies" - ".fleet-policies-leader" - ".fleet-enrollment-api-keys" # 3. Elastic Agents - each agent authenticates with its own API key, issued # and rotated by Fleet Server. ReadonlyREST validates the key against Elasticsearch # and grants access to the observability data-stream indices. - name: "Agents" type: allow token_authentication: type: "api-key" username: "fleet" indices: - ".apm-agent-configuration" - "metrics-*" - "traces-*" - "logs-*" # 4. Forbid direct token management - only Kibana and Fleet Server (matched # above) should create or revoke service tokens and API keys. This block # denies these actions for everyone else. - name: "Forbid access to service accounts and API keys" type: forbid actions: - "cluster:admin/xpack/security/service_account/*" - "cluster:admin/xpack/security/api_key/*" # 5. Admin user - full Kibana access. - name: "Admins" type: allow auth_key: admin:admin kibana: access: admin ``` ## How Fleet credentials flow through ReadonlyREST 1. **Kibana creates a service token** - during Fleet setup, Kibana calls `cluster:admin/xpack/security/service_account/*` to create the Fleet Server service token. This request is authenticated by the `KIBANA` block. 2. **Fleet Server creates API keys** - Fleet Server uses its service token to call `cluster:admin/xpack/security/api_key/create`, issuing an API key to each enrolling agent. This request is authenticated by the `Fleet server` block. 3. **Elastic Agents use their API keys** - each agent presents its API key on every request to ship data to Elasticsearch. These requests are authenticated by the `Agents` block. ## Why the `forbid` block is necessary Only Kibana and Fleet Server should be able to create service tokens and API keys - no other user needs these actions. The `KIBANA` and `Fleet server` blocks already permit these calls for the accounts that legitimately need them. The `forbid` block sits below those blocks and denies any remaining request that targets service-account or API-key management actions, preventing other authenticated users from creating, revoking or listing credentials. ## Credential rotation You do not need to put service tokens or API key values into `readonlyrest.yml`. ReadonlyREST never sees or stores them - it asks Elasticsearch to validate each token on the fly. This means: * Fleet Server can rotate its service token without any ReadonlyREST config change. * Agents can be enrolled, unenrolled, and re-keyed without touching ReadonlyREST. * The only things that must stay in sync with your deployment are the **index patterns** in the `service-token` and `api-key` blocks. ## Setting up Fleet Server and Elastic Agent Configuring Fleet Server and enrolling Elastic Agents is covered in the [official Elastic Fleet documentation](https://www.elastic.co/guide/en/fleet/current/fleet-server.html). APM agent setup is documented in the [APM quick-start guide](https://www.elastic.co/guide/en/apm/guide/current/apm-quick-start.html). ## Running the example A full working example with Elasticsearch, Kibana (both with ReadonlyREST), Fleet Server, an Elastic Agent (APM), a demo Node.js app, and a traffic simulator is available in the [readonlyrest-examples](https://github.com/beshu-tech/readonlyrest-examples/tree/master/examples/fleet) repository: ```bash curl -sL https://raw.githubusercontent.com/beshu-tech/readonlyrest-examples/master/quickstart.sh | bash -s fleet ``` Once running, log into Kibana and navigate to **Management → Fleet** to see the enrolled agent and its policy, or to **Observability → APM** for traces from the demo application. # FLS engine Applicable in the context of the [`fields` rule](/develop/elasticsearch#fields) FLS engine specifies how ROR handles field-level security internally. Previously FLS was based entirely on [Lucene](https://en.wikipedia.org/wiki/Apache_Lucene) - that's why ROR needed to be installed on all nodes to make the `fields` rule work properly. Now the `fields` rule is more flexible and part of FLS responsibilities is handled solely by ES. Increasing ES usage and reducing Lucene exploitation in FLS implementation makes the rule more efficient. Unfortunately, a few FLS functionalities still have to be handled at the Lucene level, and cannot benefit of the new ES level implementation (see supported at ES level [requests](#ES-limitations) ) Lucene is still used by `fields` rule when ES is not able to handle a request properly (as kind of a fallback). ## Configuration FLS engine can be configured with global, optional property `fls_engine` set under the `readonlyrest.global_settings` section. There are two engines available: * **es\_with\_lucene** (default) **⚠️IMPORTANT** As Lucene is part of this engine, the ReadonlyREST plugin still needs to be installed in all the cluster nodes that contain data. Default hybrid approach - the major part of FLS is handled by ES. Corner cases are passed to Lucene. This solution handles all requests properly being more performant than the old full Lucene-based approach. * **es** FLS is handled only by ES, without fallback to Lucene. When ES is not able to handle FLS properly, the `fields` rule is not matched. In the `es` engine, FLS is not available for some types of requests (requirements listed below). The major advantage of this approach is to not rely on Lucene, so **ROR doesn't need to be installed on all nodes**. If a lack of full FLS support is unacceptable and all type of requests needs to be handled properly (rule matching, no rejection) it's advised to use a more reliable `es_with_lucene` engine. ## ES limitations Supported by `es` FLS engine requests are: * all Get/MGet API requests * Search/MSearch/AsyncSearch API requests with the following restrictions: * not using script fields * the used query is one of * common terms * match bool * match * match phrase * match phrase prefix * exists * fuzzy * prefix * range * regexp * term * wildcard * terms set * bool * boosting * constant score * dis max * the defined query doesn't use wildcards in field names * defined compound queries using only listed above supported queries as inner queries * the Search request doesn't use scroll If the request doesn't meet above requirements (e.g. it's using `query_string` or script fields), the `es` engine will reject it. Example configuration (ROR using `es` FLS engine): ```yaml readonlyrest: global_settings: fls_engine: "es" access_control_rules: - name: "user_using_fields" auth_key: user:pass fields: ["~someNotAllowedField"] ``` Property `fls_engine` can be omitted, then by default, ROR uses `es_with_lucene` FLS engine. # Indices rule - Index not found scenario Examples: > Let's assume that our ES cluster has 2 indices: `index_a` and `index_b`. At the same time we have two users: `userA` and `userB`. We'd like to give `userA` access to index `index_a`, and `userB` to `index_b`. `userA` should not see or be even aware of `index_b` and vice versa. We'd like to give each of them a feeling that they are alone on the cluster. > > ROR `readonlyrest.yml` configuration may look like this: > > ```yaml > readonlyrest: > enable: true > access_control_rules: > > - name: "user A indices" > indices: ["index_a"] > auth_key: userA:secret > > - name: "user B indices" > indices: ["indexB"] > auth_key: userB:secret > ``` > > We can test if `userA` is able to reach `index_a`: > > ``` > $ curl -v -u userA:secret "http://127.0.0.1:9200/index_a?pretty" > HTTP/1.1 200 OK > content-type: application/json; charset=UTF-8 > content-length: 611 > > { > "index_a" : { > "aliases" : { }, > "mappings" : { ... } > "settings" : { ... } > } > } > ``` > > It looks like he is. So far, so good. Let's try to access nonexistent index (we know, that index with name `nonexistent` for sure doesn't exist on our cluster): > > ``` > $ curl -i -u userA:secret "http://127.0.0.1:9200/nonexistent?pretty" 18:15:28 > HTTP/1.1 404 Not Found > content-type: application/json; charset=UTF-8 > content-length: 634 > > { > "error" : { > "root_cause" : [ ... ], > "type" : "index_not_found_exception", > "reason" : "no such index [nonexistent_ROR_ZA1FXDsR7M]", > "resource.type" : "index_or_alias", > "resource.id" : "nonexistent_ROR_ZA1FXDsR7M", > "index_uuid" : "_na_", > "index" : "nonexistent_ROR_ZA1FXDsR7M" > }, > "status" : 404 > } > ``` > > The response is pretty straight forward - the index doesn't exist. But, let's see what happens, when the same user, `userA`, will try to get `index_b`: > > ``` > $ curl -v -u userA:secret "http://127.0.0.1:9200/index_b?pretty" > HTTP/1.1 404 Not Found > content-type: application/json; charset=UTF-8 > content-length: 610 > > { > "error" : { > "root_cause" : [ ... ], > "type" : "index_not_found_exception", > "reason" : "no such index [index_b_ROR_QcskliAl8A]", > "resource.type" : "index_or_alias", > "resource.id" : "index_b_ROR_QcskliAl8A", > "index_uuid" : "_na_", > "index" : "index_b_ROR_QcskliAl8A" > }, > "status" : 404 > } > ``` > > As we can see `userA` is not able to get `index_b`. But the response is HTTP 404 Not Found - it means that the index doesn't exist. > > So, the response is the same as we get if the called index really doesn't exist. Thanks to the described behaviour, `userA` is not aware that on the cluster there are any other indices but the ones he was given access to. > > > note: > > > > Careful reader may notice that, in example above, `userA` was getting `index_b`, but the response says that there is no `index_b_ROR_QcskliAl8Aindex_b_ROR_QcskliAl8A` index. It's the trick ROR does to fool ES and be sure that asking index, which the user should not be allowed to see, won't be reached by him. > > But we should also consider the other case - using an index name with wildcard. So, `userA` will try to get all indices which names match `index*` pattern: > > ``` > $ curl -i -u userA:secret "http://127.0.0.1:9200/index*?pretty" 19:58:29 > HTTP/1.1 200 OK > content-type: application/json; charset=UTF-8 > content-length: 611 > > { > "index_a" : { > "aliases" : { }, > "mappings" : { ... }, > "settings" : { ... } > } > } > ``` > > Response is exactly like we'd expect - only `index_a` was returned. But what if nothing matches our index name pattern? > > ``` > $ curl -i -u userA:secret "http://127.0.0.1:9200/index_userA*?pretty" 20:05:10 > HTTP/1.1 200 OK > content-type: application/json; charset=UTF-8 > content-length: 4 > > { } > ``` > > Response is empty list. Now, let's see what happens when an index name pattern matches an index which is not authorized for a user who asks about it. > > ``` > $ curl -i -u userA:secret "http://127.0.0.1:9200/index_b*?pretty" 20:14:34 > HTTP/1.1 200 OK > content-type: application/json; charset=UTF-8 > content-length: 4 > > { } > ``` > > As we see, response is the same as we have experienced when there was really no index matching the pattern. Also here a user has a feeling that only his indices are present on a cluster. # Indices rule - ES Templates handling
A ROR configuration for all examples below (click to expand) ```yaml readonlyrest: access_control_rules: - name: "admin block" verbosity: error type: allow auth_key: admin:admin - name: "dev1 block" indices: ["idev1", "idev1_*"] auth_key: dev1:test - name: "dev2 block" indices: ["idev2", "idev2_*"] auth_key: dev2:test ```
## Index templates An `indices` rule takes into consideration index patterns and aliases which are a part of a template definition. We should consider four types of template related requests: ### Create an index template The request will be allowed when all of following conditions are met: * a template with requested name does not exist (if it does, it's rather a template modification, than a creation), * all index patterns of the new, requested template are allowed, * all aliases of the new, requested template are allowed.
Example (click to expand) Let's try to add an index template. We can see, using `admin` account, that there are no templates defined yet. ``` $ curl -vk -u admin:admin "http://localhost:9200/_index_template?pretty" HTTP/1.1 200 OK content-type: application/json; charset=UTF-8 { "index_templates" : [ ] } ``` Now, let's use `dev1` user account to create an index template `temp1`: ``` $ curl -vk -u dev1:test -XPUT "http://127.0.0.1:9200/_index_template/test?pretty" -H "Content-Type: application/json" -d \ '{ "index_patterns":["index*"], "template": { "aliases": { "dev1_index": {}, "dev2_index": {} } } }' HTTP/1.1 403 Forbidden content-type: application/json; charset=UTF-8 { "error" : { "root_cause" : [ { "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"] } ], "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"], "status" : 403 } } ``` Oh, something went wrong. It seems that, a user `dev1` is not allowed to add this template. Let's check ROR logs to figure out why: FORBIDDEN by default req={ ID:193441275-173645661#8, TYP:PutComposableIndexTemplateAction$Request, CGR:N/A, USR:dev1 (attempted), BRS:true, KDX:null, ACT:indices:admin/index\_template/put, OA:127.0.0.1/32, XFF:null, DA:127.0.0.1/32, `IDX:index*,dev2_index,dev1_index`, MET:PUT, `PTH:/_index_template/test`, CNT:\ , HDR:Accept=*/*, Authorization=, Content-Length=157, Content-Type=application/json, Host=127.0.0.1:9200, User-Agent=curl/7.64.1, HIS:\[CONTAINER ADMIN-> RULES:\[auth\_key->false] RESOLVED:\[indices=index\*,dev2\_index,dev1\_index;template=ADD(test:index\*:dev2\_index,dev1\_index)]], `[dev1 block-> RULES:[auth_key->true, indices->false]` RESOLVED:\[user=dev1;indices=index\*,dev2\_index,dev1\_index;template=ADD(test:index\*:dev2\_index,dev1\_index)]], \[dev2 block-> RULES:\[auth\_key->false] RESOLVED:\[indices=index\*,dev2\_index,dev1\_index;template=ADD(test:index\*:dev2\_index,dev1\_index)]], } We can see that our request was forbidden - credentials were OK, but `indices` rule was not matched in `dev1 block`. We can see also that ROR found 3 indices which are related to the request: * `index*` - an index pattern from our request * `dev1_index` - a first alias from out request * `dev2_index` - a second alias from out request When we take a look at indices configured in `indices` rule for our user, we can see that, he has an access only to `idev1` and `idev1_*` indices. Now, it's pretty much obvious why the request was blocked - the user has no access to index pattern and aliases used in the request. Let's try to fix that: ``` $ curl -vk -u dev1:test -XPUT "http://127.0.0.1:9200/_index_template/test?pretty" -H "Content-Type: application/json" -d \ '{ "index_patterns":["idev1_test*"], "template": { "aliases": { "idev1": {}, "idev1_test": {} } } }' HTTP/1.1 200 OK content-type: application/json; charset=UTF-8 { "acknowledged" : true } ``` Hooray! The index template was added. This time ROR allowed us to do so. It's because `dev1` user has an access to index pattern `idev1_test*`, because it is contained in `idev1_*`. Used aliases are also allowed.
### Modify an index template The request will be allowed when all of following conditions are met: * a template with requested name does exist, * all index patterns of the existing template are allowed, * all aliases of the existing template are allowed, * all index patterns of the requested template are allowed, * all aliases of the requested template are allowed.
Example (click to expand) Let's assume the user `dev1` would like to modify the previously created template, because the index pattern is too detailed: ``` $ curl -vk -u dev1:test -XPUT "http://127.0.0.1:9200/_index_template/test?pretty" -H "Content-Type: application/json" -d \ '{ "index_patterns":["idev*"], "template": { "aliases": { "idev1": {}, "idev1_test": {} } } }' HTTP/1.1 403 Forbidden content-type: application/json; charset=UTF-8 { "error" : { "root_cause" : [ { "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"] } ], "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"], "status" : 403 } } ``` Ups! Something is wrong. Let's check the ROR forbidden log: FORBIDDEN by default req={ ID:918326057-1726421783#75, TYP:PutComposableIndexTemplateAction$Request, CGR:N/A, USR:dev1 (attempted), BRS:true, KDX:null, ACT:indices:admin/index\_template/put, OA:127.0.0.1/32, XFF:null, DA:127.0.0.1/32, `IDX:idev*,idev1,idev1_test`, MET:PUT, PTH:/\_index\_template/test, CNT:\ , HDR:Accept=*/*, Authorization=, Content-Length=151, Content-Type=application/json, Host=127.0.0.1:9200, User-Agent=curl/7.64.1, HIS:\[CONTAINER ADMIN-> RULES:\[auth\_key->false] RESOLVED:\[indices=idev\*,idev1,idev1\_test;template=ADD(test:idev\*:idev1,idev1\_test)]], `[dev1 block-> RULES:[auth_key->true, indices->false]` RESOLVED:\[user=dev1;indices=idev\*,idev1,idev1\_test;template=ADD(test:idev\*:idev1,idev1\_test)]], \[dev2 block-> RULES:\[auth\_key->false] RESOLVED:\[indices=idev\*,idev1,idev1\_test;template=ADD(test:idev\*:idev1,idev1\_test)]], } We can see that `indices` rule hasn't not been matched. Looking at the IDX section, we can figure out that the index pattern we requested `idev*`, cannot be allowed. `idev*` is too generic, because in the `indices` list we have `["idev1", "idev1_*"]`. Let's try to fix that: ``` $ curl -vk -u dev1:test -XPUT "http://127.0.0.1:9200/_index_template/test?pretty" -H "Content-Type: application/json" -d \ '{ "index_patterns":["idev1_*"], "template": { "aliases": { "idev1": {}, "idev1_test": {} } } }' HTTP/1.1 200 OK content-type: application/json; charset=UTF-8 { "acknowledged" : true } ``` Yeah, now it works. Let's check if the template is modified (we will use `admin` user to do so): ``` $ curl -vk -u admin:admin "http://127.0.0.1:9200/_index_template?pretty" HTTP/1.1 200 OK content-type: application/json; charset=UTF-8 { "error" : { "root_cause" : [ { "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"] } ], "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"], "status" : 403 } } ``` All is good. We have only one template and the modifications was applied. So far, so good. But we can wonder what happens if `dev2` will try to modify (or override) template `temp`? Let's check: ``` $ curl -vk -u dev2:test -XPUT "http://127.0.0.1:9200/_index_template/test?pretty" -H "Content-Type: application/json" -d \ '{ "index_patterns":["idev2_*"], "template": { "aliases": { "idev2": {}, "idev2_test": {} } } }' HTTP/1.1 403 Forbidden content-type: application/json; charset=UTF-8 { "error" : { "root_cause" : [ { "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"] } ], "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"], "status" : 403 } } ``` Yes! This is something what we wanted like to see. Even if the request was correct and the user `dev2` has an access to the requested index pattern and aliases, the request was forbidden. Obviously, there is already existed template `temp` which has the index pattern and aliases, which are not allowed for `dev2`. ROR deduces that `dev2` cannot be considered as someone how can modify/overwrite it. Pretty awesome. Won't `dev2` also be able to remove it? We'll see in next section ...
### Delete an index template The request will be allowed when template does not exist OR all of the following conditions are met: * a template with requested name does exist, * all index patterns of the existing template are allowed, * all aliases of the existing template are allowed.
Example (click to expand) In the last section we wondered, if ROR will be able to block removing the template `temp` by the user `dev2`. Let's recall, that we proved that the user is not able to modify this template, because ROR considers that he doesn't have permissions to change/remove it. ``` $ curl -vk -u dev2:test -XDELETE "http://127.0.0.1:9200/_index_template/test?pretty" HTTP/1.1 403 Forbidden content-type: application/json; charset=UTF-8 { "error" : { "root_cause" : [ { "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"] } ], "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"], "status" : 403 } } ``` Perfect! OK, but we also would like to know if `user1` will be able to remove his template. Let's check it: ``` $ curl -vk -u dev1:test -XDELETE "http://127.0.0.1:9200/_index_template/test?pretty" HTTP/1.1 200 OK content-type: application/json; charset=UTF-8 { "acknowledged" : true } ``` Great! Everything works.
### Get index templates At the moment ROR doesn't have `templates` rule (similar to `snapshots` or `repositories`), which allows to restrict which templates can be visible to the user (it is going to change in the future). But the `indices` rule is enough to filter templates based on index patterns in their definitions. An index template is considered to be visible for a user, when the user has access to AT LEAST ONE index pattern of the template's index pattern list. ROR is going to show the template but to hide the information about not allowed index patterns and not allowed aliases.
Example (click to expand) In previous sections we proved that ROR gets along with index templates adding, modifying and removing pretty well. Now, we'd like check what index templates are supposed to be visible for users. Let's assume we have 4 index templates: ``` $ curl -vk -u admin:admin "http://127.0.0.1:9200/_index_template?pretty" HTTP/1.1 200 OK content-type: application/json; charset=UTF-8 { "index_templates" : [ { "name" : "t1", "index_template" : { "index_patterns" : ["i*"], "template" : { "aliases" : { "idev2" : { }, "idev3" : { }, "idev1" : { } } }, "composed_of" : [ ] } }, { "name" : "t2", "index_template" : { "index_patterns" : ["idev1_*"], "template" : { "aliases" : { "admin_idev" : { }, "idev1" : { } } }, "composed_of" : [ ], "priority" : 1 } }, { "name" : "t3", "index_template" : { "index_patterns" : ["idev2_*"], "template" : { "aliases" : { "idev2" : { }, "admin_idev" : { } } }, "composed_of" : [ ], "priority" : 1 } }, { "name" : "t4", "index_template" : { "index_patterns" : ["idev1_*", "idev2_*"], "template" : { "aliases" : { "idev2" : { }, "admin_idev" : { }, "idev1" : { } } }, "composed_of" : [ ], "priority" : 2 } } ] } ``` `admin` has unrestricted access to all templates. Now, let's check which templates `dev` are supposed to see: ``` $ curl -vk -u dev1:test "http://127.0.0.1:9200/_index_template?pretty" HTTP/1.1 200 OK content-type: application/json; charset=UTF-8 { "index_templates" : [ { "name" : "t1", "index_template" : { "index_patterns" : ["i*"], "template" : { "aliases" : { "idev1" : { } } }, "composed_of" : [ ] } }, { "name" : "t2", "index_template" : { "index_patterns" : ["idev1_*"], "template" : { "aliases" : { "idev1" : { } } }, "composed_of" : [ ], "priority" : 1 } }, { "name" : "t4", "index_template" : { "index_patterns" : ["idev1_*"], "template" : { "aliases" : { "idev1" : { } } }, "composed_of" : [ ], "priority" : 2 } } ] } ``` Hmm, we can see many weird things here. Let's start with the simplest case: index template `t2` is allowed for the user, because the used index pattern is allowed by `indices` rule. But we can also see that user `dev1` is not aware of existence the `admin_idev` alias - it was filter out from the aliases list. The user has no access to the alias, so he should not be able to see it. What about the index template `t3`? `dev1` is not allowed to see it because the index pattern `idev2_*` is not allowed for him. It was also pretty much obvious! The next is `t4`. When `admin` had listed index templates, we saw that template `t4` has 2 index patterns. But `dev1` can see only one. This is great, because he has an access to a part of that template, so he definitely should be able to see it. ROR behaviour here is pretty neat - it allows the user to see a template with filtered, not allowed parts of it, but at the same time, the user doesn't have permissions to modify/remove the template (Don't believe me? Go ahead and check!) And the last one to explain - `t1`. The index pattern of the template is `i*`. Obviously user `dev1` has no access to it, because his allowed indices are `idev1, idev1_*`. But if we imagine all possible values generated from pattern `i*` and all possible values generated from `idev1, idev1_*`, we can notice that the latter will be a subset of the first. It means that this template can be interesting for the user `dev1`, because it will ba applied to indices created by him. That's why ROR decides to show it.
## Component templates Component templates doesn't have index patterns but could have aliases. So, in this case, we should also consider four types of template related requests: ### Create a component template The request will be allowed when all of following conditions are met: * a template with requested name does not exist (if it does, it's rather a template modification, than a creation), * all aliases of the new, requested template are allowed.
Example (click to expand) Unlike index templates, component templates don't have index patterns. But they still have aliases. So, their behaviour according to an aliases usage is quite similar, but there are several differences which are worth mentioning. Let's check if `dev1` user can create a component template: ``` $ curl -vk -u dev1:test "http://localhost:9200/_component_template/ctemp1?pretty" -XPUT -H "Content-Type: application/json" -d \ '{ "template": { "settings": { "index.number_of_replicas": 0 }, "aliases": { "idev1": {}, "idev2": {} } } }' HTTP/1.1 403 Forbidden content-type: application/json; charset=UTF-8 { "error" : { "root_cause" : [ { "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"] } ], "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"], "status" : 403 } } ``` Oh, user `dev1` is not allowed to create this template. But wait! It looks like we have the same problem as had while creating index template. Alias `idev2` is not allowed. Let's try to do the same without this alias: ``` $ curl -vk -u dev1:test "http://localhost:9200/_component_template/ctemp1?pretty" -XPUT -H "Content-Type: application/json" -d \ '{ "template": { "settings": { "index.number_of_replicas": 0 }, "aliases": { "idev1": {} } } }' HTTP/1.1 200 OK content-type: application/json; charset=UTF-8 { "acknowledged" : true } ``` Ha! As expected. A user has to have access to all aliases during adding a component template which has aliases defined. *Note* If a component template doesn't involve aliases, there is no restriction from ROR side to add one. It can be changed in future, when we add sth like `templates` rule.
### Modify a component template The request will be allowed when all of following conditions are met: * a template with requested name does exist, * all aliases of the existing template are allowed, * all aliases of the requested template are allowed.
Example (click to expand) In the previous example, user `dev1` created the component template `ctemp1` with one alias `idev1`. Let's check if user `dev2` will be able to modify it: ``` $ curl -vk -u dev2:test "http://localhost:9200/_component_template/ctemp1?pretty" -XPUT -H "Content-Type: application/json" -d \ '{ "template": { "settings": { "index.number_of_replicas": 0 }, "aliases": { "idev2": {} } } }' HTTP/1.1 403 Forbidden content-type: application/json; charset=UTF-8 { "error" : { "root_cause" : [ { "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"] } ], "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"], "status" : 403 } } ``` No. And this is a good behaviour, because `dev2` doesn't have an access to the alias `idev1` which the `ctemp1` has. ROR assumes, that he cannot modify the component template (please notice, that the same request will be allowed when a different, nonexistent component template name is used). I can assure you that `dev1` is able to modify the template (you can check if you want).
### Delete a component template The request will be allowed when template does not exist OR all of the following conditions are met: * a template with requested name does exist, * all aliases of the existing template are allowed.
Example (click to expand) If you read the previous example, you won't find anything interesting here. A component template can be removed only by someone whom ROR considers to have modification rights of the template. See that `dev2` is not able to remove `ctemp1`: ``` $ curl -vk -u dev2:test -XDELETE "http://localhost:9200/_component_template/ctemp1?pretty" HTTP/1.1 403 Forbidden content-type: application/json; charset=UTF-8 { "error" : { "root_cause" : [ { "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"] } ], "reason" : "forbidden", "due_to" : ["OPERATION_NOT_ALLOWED"], "status" : 403 } } ``` I told you. But please remember that only aliases are checked by ROR when it's trying to figure out modification rights of a component template. If a component template doesn't have any aliases, it can be modified or deleted by any user.
### Get component templates At the moment there is no way to restrict which component templates can be visible to the user (it is going to change in the future - see a corresponding index template section). But ROR is going to hide the information about not allowed aliases of returned component templates.
Example (click to expand) A careful reader can guess that ROR won't forbid showing component templates. But similar to indices templates, ROR will filter out aliases list depending on an aliases accessability of current user. Let's see an example: ``` $ curl -vk -u admin:admin "http://localhost:9200/_component_template?pretty" HTTP/1.1 200 OK content-type: application/json; charset=UTF-8 { "component_templates" : [ { "name" : "ctemp2", "component_template" : { "template" : { "settings" : { "index" : { "number_of_replicas" : "0" } }, "aliases" : { "idev2" : { } } } } }, { "name" : "ctemp1", "component_template" : { "template" : { "settings" : { "index" : { "number_of_replicas" : "0" } }, "aliases" : { "idev1" : { } } } } } ] } ``` We can see that we have two component templates. `ctemp1` has alias `idev1` and `ctemp2` alias `idev2`. Let check what templates `dev1` user will be able to see: ``` $ curl -vk -u dev1:test "http://localhost:9200/_component_template?pretty" HTTP/1.1 200 OK content-type: application/json; charset=UTF-8 { "component_templates" : [ { "name" : "ctemp2", "component_template" : { "template" : { "settings" : { "index" : { "number_of_replicas" : "0" } }, "aliases" : { } } } }, { "name" : "ctemp1", "component_template" : { "template" : { "settings" : { "index" : { "number_of_replicas" : "0" } }, "aliases" : { "idev1" : { } } } } } ] } ``` We can see that he is able to see all component templates, but `ctemp2` doesn't have `idev2` alias. User `dev1` has no access to the alias, so response returned by ROR doesn't contain the alias. Similar behaviour we will observe when `dev2` user will try to get all templates.
## Troubleshooting To figure out why the template is not returned or/and cannot be altered, you should [enable a DEBUG log level](/develop/elasticsearch#acl-troubleshooting) and check your logs. ROR logs each step of template request handling in the `indices` rule, so detailed description should explain the given template is not allowed. # For Kibana User manual for ReadonlyREST Enterprise/PRO/Free 🧙 **Are you using Kibana version 7.8.x or older? Go to the** [**old platform manual page**](/develop/kibana/kibana-7.8.x-and-older)**.** ## Overview ReadonlyREST plugin for Kibana is not open source, and it's offered as part of the [ReadonlyREST PRO](https://readonlyrest.com/pro) and [ReadonlyREST ENTERPRISE](https://readonlyrest.com/enterprise), and [ReadonlyREST Free](https://readonlyrest.com/free) packages. See product descriptions and a comparison chart on the official [ReadonlyREST website](https://readonlyrest.com) ReadonlyREST plugins for Kibana **always require** the ReadonlyREST open-source plugin to be installed in the Elasticsearch nodes your Kibana instance(s) will connect to. Installation of ReadonlyREST is not required on all Elasticsearch nodes. It's mandatory to be installed only on the nodes where you intend to secure the HTTP interface. ### After purchasing If you haven't installed it yet, download the latest [universal build](https://docs.readonlyrest.com/universal-builds) from our [download page](https://readonlyrest.com/download/) and install it manually. Alternatively, see below if you want to install it directly via the command line without downloading it from the browser. Once the universal build plugin for Kibana is installed, you can activate it using an **activation key**. You can get one of these in the [ReadonlyREST customer portal](https://readonlyrest.com/customer) if you are a subscriber, otherwise, use the same portal to get a trial activation key (for PRO or Enterprise) for 30 days evaluation. ### Version strings All our plugins include in their file name a version string. For example, the file `readonlyrest-1.46.0_es8.6.0.zip` has a version string `1.46.0_es8.6.0`. #### Reading version strings Given the version string `1.46.0_es8.6.0` * ReadonlyREST plugin code version `1.46.0` * Works only with Elasticsearch/Kibana version `8.6.0` The "es" stands for "Elastic stack" which used to mean the family of products made by Elastic which get released at the same time under the same version number. This was chosen **before** Elastic renamed their X-Pack commercial offer to Elastic Stack. To be clear, there is no affiliation between ReadonlyREST and Elastic, or their commercial products. #### Universal Kibana plugin version strings Our Kibana plugin file naming follows very similar rules: I.e. `readonlyrest_kbn_universal-1.46.0_es8.6.0.zip` * ReadonlyREST PRO plugin version 1.46.0 * Works only with Kibana version 8.6.0 ### When an update is out You will receive another email notification that a new deliverable is available. If the update contains a security fix, it is very important that you take action and **update the plugin immediately**. ## Installation and Operations ### Running with Docker The simplest method to run Kibana with the ReadonlyREST plugin is to use one of our docker images which you can find on [Docker Hub](https://hub.docker.com/r/beshultd/kibana-readonlyrest). In the example below we will use [Docker Compose](https://docs.docker.com/compose/): ```yaml # docker-compose.yml file content services: kbn-ror: image: beshultd/kibana-readonlyrest:8.14.3-ror-latest user: "0:0" ports: - "5601:5601" environment: - I_UNDERSTAND_AND_ACCEPT_KBN_PATCHING=yes - ELASTICSEARCH_HOSTS=https://es-ror:9200 - ELASTICSEARCH_USERNAME=kibana - ELASTICSEARCH_PASSWORD=kibana - ELASTICSEARCH_SSL_VERIFICATIONMODE=none - readonlyrest_kbn__cookiePass=abcd1234abcd1234abcd1234abcd1234 # this is an equivalent of the `readonlyrest_kbn.cookiePass` setting defined in kibana.yml depends_on: - es-ror es-ror: image: beshultd/elasticsearch-readonlyrest:8.14.3-ror-latest user: "0:0" ports: - "9200:9200" environment: - I_UNDERSTAND_AND_ACCEPT_ES_PATCHING=yes - KIBANA_USER_PASS=kibana - ADMIN_USER_PASS=admin - discovery.type=single-node ``` It can be run like this: ```bash docker-compose up ``` It will run Kibana container with ReadonlyREST connected with the single ES node (with ReadonlyREST too). You can access Kibana by calling `http://localhost:5601` in the browser (use `admin:admin` credentials to log in). #### Customizing ROR Kibana settings All config options are described in the [configuration section](#configuration) below. In general, you will use the `kibana.yml` file to configure ROR Kibana settings. But in the case, of the ROR Docker image, you can pass any ROR settings as ENV - just remember to replace `.` (dot) with `__` (double underscore). E.g. to configure `readonlyrest_kbn.store_sessions_in_index: true` pass `readonlyrest_kbn__store_sessions_in_index=true` ENV. ### Installation You can install this as a normal Kibana plugin using the `bin/kibana-plugin` utility. Let's see the two ways to use this utility with ReadonlyREST. {% hint style="warning" %} **Don't forget** After Kibana 7.9.x, it's necessary to [patch](#patching-kibana) Kibana after you install, otherwise ReadonlyREST will NOT work. {% endhint %} #### Installing via URL This installation method is more practical if your Kibana server is connected to the internet. Please note that this will always download the latest version of Kibana plugin available for the current supported Elasticsearch version. ```bash bin/kibana-plugin install "https://portal.readonlyrest.com/download/kbn?edition=kbn_universal&email=" # ReadonlyREST Universal Kibana plugin ``` If you want to download the latest version of the plugin for a specific version of Kibana, then use the query parameter `esVersion` to specify your required Kibana version. ```bash bin/kibana-plugin install "https://portal.readonlyrest.com/download/kbn?edition=kbn_universal&esVersion=7.6.1&email=" ``` If you want to download an older version of the plugin for a specific version of Elasticsearch, then use the query parameter `pluginVersion` along with `esVersion`. Please note that you can only go so far back with plugin versions. [Let us know](https://readonlyrest.com/contact) if you can't download a specific one. ```bash bin/kibana-plugin install "https://portal.readonlyrest.com/download/kbn?edition=kbn_universal&esVersion=8.6.0&pluginVersion=1.46.0&email=" ``` It's possible to add an extra query parameter (`checksum=true`) to any download URL to obtain a `sha1` checksum of the corresponding deliverable. For example: ```bash curl -vvv "https://portal.readonlyrest.com/download/kbn?esVersion=8.6.0&pluginVersion=1.46.0&email=your@emailaddress.com&edition=kbn_universal&checksum=true" [...] curl -vvv "https://portal.readonlyrest.com/download/es?esVersion=8.6.0&pluginVersion=1.46.0&checksum=true" [...] ``` Now you are ready to [patch Kibana](#patching-kibana). #### Installing from a zip file ```bash bin/kibana-plugin install file:///home/user/downloads/readonlyrest_kbn-X.Y.Z_esW.Q.U.zip ``` Notice how we need to type in the format `file://` + absolute path (yes, with three slashes). #### Patching Kibana If you are using Kibana 7.9.x or newer, you need **an extra post-installation step**. This will slightly modify some core Kibana files. **Before Kibana 8.15.0** ```bash node/bin/node plugins/readonlyrestkbn/ror-tools.js patch ``` **For Kibana 8.15.0 and never** **For Linux** ```bash node/glibc-217/bin/node plugins/readonlyrestkbn/ror-tools.js patch ``` **For macOS** ```bash node/default/bin/node plugins/readonlyrestkbn/ror-tools.js patch ``` **For Windows** ```shell node\default\node plugins\readonlyrestkbn\ror-tools.js patch ``` **Patching Kibana acknowledgment in a silent mode** To apply patches in Kibana using a script in non-interactive mode (bypassing prompts), you have two options: * Using `--I_UNDERSTAND_AND_ACCEPT_KBN_PATCHING=yes` Script Argument: ```shell node/bin/node plugins/readonlyrestkbn/ror-tools.js patch --I_UNDERSTAND_AND_ACCEPT_KBN_PATCHING=yes # This example applies to Kibana before 8.15.0. Be sure to use the correct Node.js path based on the Kibana version and your operating system. ``` * Using environment variable: Define `I_UNDERSTAND_AND_ACCEPT_KBN_PATCHING=yes` env variable and run patching script as usual #### Unpatching Kibana If you are using Kibana 7.9.x or newer, you need **an extra pre-uninstallation step**. This will restore the core Kibana files to the original state. **Before Kibana 8.15.0** ```bash node/bin/node plugins/readonlyrestkbn/ror-tools.js unpatch ``` **For Kibana 8.15.0 and never** **For Linux** ```bash node/glibc-217/bin/node plugins/readonlyrestkbn/ror-tools.js unpatch ``` **For macOS** ```bash node/default/bin/node plugins/readonlyrestkbn/ror-tools.js unpatch ``` **For Windows** ```shell node\default\node plugins\readonlyrestkbn\ror-tools.js unpatch ``` #### Configuring Kibana For the activation key persistence after upgrading the license to PRO or Enterprise edition, From readonlyREST version 1.51.0 `readonlyrest_kbn.cookiePass` is a required `kibana.yml` config parameter. It needs to be configured also in case of a free license. #### Uninstalling {% hint style="info" %} To uninstall, you should unpatch Kibana first, then uninstall the ReadonlyREST plugin. However, **the Kibana plugin system uninstallation process is highly unreliable**. So we highly recommend throwing away the entire Kibana directory and starting from scratch. Ideally, use ephemeral docker containers. Need inspiration? Try the [ROR Docker demo](https://github.com/sscarduzio/ror-docker-demo)! {% endhint %} To bring Kibana to its pre-patching original state, it's possible to unpatch. **Before Kibana 8.15.0** ```bash node/bin/node plugins/readonlyrestkbn/ror-tools.js unpatch bin/kibana-plugin remove readonlyrestkbn ``` **For Kibana 8.15.0 and never** **For Linux** ```bash node/glibc-217/bin/node plugins/readonlyrestkbn/ror-tools.js unpatch bin/kibana-plugin remove readonlyrestkbn ``` **For macOS** ```bash node/default/bin/node plugins/readonlyrestkbn/ror-tools.js unpatch bin/kibana-plugin remove readonlyrestkbn ``` **For Windows** ```shell node\default\node plugins\readonlyrestkbn\ror-tools.js unpatch bin/kibana-plugin remove readonlyrestkbn ``` And the classic uninstall command... ```bash bin/kibana-plugin remove readonlyrest_kbn ``` #### Upgrading Kibana The ReadonlyREST plugin version must always match the currently installed Kibana version. As a result, if you want to upgrade Kibana with ROR plugin installed: 1. Before upgrading Kibana, unpatch and uninstall the ReadonlyREST plugin according to the instructions: * [Unpatch Kibana](#unpatching-kibana) * [Uninstall the plugin](#uninstalling) 2. Upgrade Kibana. 3. After upgrading Kibana, install the matching version of the ReadonlyREST plugin and patch according to the instructions: * [Install matching plugin version](#installation) * [Patch Kibana](#patching-kibana) {% hint style="warning" %} Upgrading Kibana without following the instructions above may cause corruption of the Kibana installation and inability to patch the upgraded version. {% endhint %} #### Upgrading ReadonlyREST plugin To upgrade to a new version of ReadonlyREST plugin for Kibana, you should: * [Unpatch Kibana](#unpatching-kibana) * [Uninstall](#uninstalling) the old plugin * [Install](#installation) the new one * [Patch Kibana](#patching-kibana) * Restart Kibana #### Major version upgrades when using multi-tenancy If you use multi-tenancy (Enterprise only), you will have one or more tenancy-specific Kibana indices beyond the main `.kibana` (e.g. `.kibana_tenant1`, `.kibana_tenant2`, etc.). The first time you run Kibana after a major version upgrade (e.g. upgrading from Kibana 7.17.7 to Kibana 8.0.0), Kibana will run a [saved objects migration](https://www.elastic.co/guide/en/kibana/current/saved-object-migrations.html) on the default `.kibana` index, or whatever it finds configured as `kibana.index` in `kibana.yml`. Now, because you may have multiple Kibana indices containing saved objects, you should apply the "saved object migration" to those indices as well. ReadonlyREST Enterprise will automatically make sure a tenancy index is migrated to satisfy the current Kibana version **right before every time it's being used.** For example, after a tenant logs in, before the Kibana session is started, or when a user changes tenancy with the tenancy switcher, the tenancy index gets created if absent, checked and migrated if necessary. These logs mean that migration started correctly: ``` [savedobjects-service] Waiting until all Elasticsearch nodes are compatible with Kibana before starting saved objects migrations... [savedobjects-service] Starting saved objects migrations [savedobjects-service] [.kibana] INIT -> CREATE_NEW_TARGET. took: 27ms. [savedobjects-service] [.kibana_task_manager] INIT -> CREATE_NEW_TARGET. took: 29ms. [savedobjects-service] [.kibana_task_manager] CREATE_NEW_TARGET -> MARK_VERSION_INDEX_READY. took: 82ms. [savedobjects-service] [.kibana] CREATE_NEW_TARGET -> MARK_VERSION_INDEX_READY. took: 95ms. [savedobjects-service] [.kibana_task_manager] MARK_VERSION_INDEX_READY -> DONE. took: 23ms. [savedobjects-service] [.kibana_task_manager] Migration completed after 135ms [savedobjects-service] [.kibana] MARK_VERSION_INDEX_READY -> DONE. took: 20ms. [savedobjects-service] [.kibana] Migration completed after 143ms ``` Now Kibana will have migrated the tenancy index, like it did with the main `.kibana` index. #### Using ROR with a reverse proxy ROR - just like Kibana itself - is meant to be used either with a proxy or without one. * If you decide to set the `server.basePath` property in `kibana.yml` and set `server.rewriteBasePath` into a `true`, ROR will be accessed directly and via a reverse proxy, * If you decide to rewrite the base path manually by your reverse proxy and set the `server.rewriteBasePath` property in `kibana.yml` into a `false`, be sure to access ROR via a proxy, as it will not work properly when accessed directly. ## Configuration ReadonlyREST for Kibana is almost entirely remote-controlled from the Elasticsearch configuration. Login credentials, hidden Kibana apps, etc. are all going to be configured from the Elasticearch side via the usual "rules". This means the configuration will be kept all in one place and if you used ReadonlyREST before, it will be also very familiar. ### ROR Settings in kibana.yml * `readonlyrest_kbn.logLevel: `: for extra visibility set debug or (rarely) trace. Keep in mind `trace` could leak secrets into logs, so be careful. * `readonlyrest_kbn.logPrettyPrintEnabled: true|false`: if you want to see pretty-printed or compact logs. * [session configuration](#session-configuration) * [UI customisation](#login-screen-tweaking) * [custom middleware](#custom-middleware) > In this document, every time you will encounter references to "readonlyrest.yml" or "elasticsearch.yml", we will be referring to the configuration files **in the Elasticsearch plugin** (our Kibana plugins do not need a "readonlyrest.yml"). In general, by design, we tend to concentrate all configuration within the main plugin (the Elasticsearch one) as much as possible. ### Kibana configuration Activate authentication for the Kibana server: let the Kibana daemon connect to Elasticsearch using one of the following methods: * a pair of credentials defined in `readonlyrest.yml` (see above, the ::KIBANA-SRV:: block). * [a service account token](https://www.elastic.co/guide/en/elasticsearch/reference/current/service-accounts.html#service-accounts-tokens) generated for Kibana, defined in `readonlyrest.yml` (see above, the ::KIBANA-SRV-TOKEN:: block). Open up `conf/kibana.yml` and add the following: ```yaml # Kibana server use the ::KIBANA-SRV:: basic auth credentials elasticsearch.username: "kibana" elasticsearch.password: "kibana" # Kibana server use the ::KIBANA-SRV-TOKEN:: token value (without the bearer scheme) # use the following setting instead of the 'elasticsearch.username' and the 'elasticsearch.password' # elasticsearch.serviceAccountToken: AAEAAWVsYXN0aWMva2liYW5hL3Rva2VuXzE6MVhQUXRubWhRd3FxUmlzNmhFVVZQdw # ReadonlyREST required properties readonlyrest_kbn.cookiePass: '12312313123213123213123abcdefghijklm' ``` And of course, also make sure `elasticsearch.url` points to the designated Elasticsearch instance (check also the http or https) ### Cluster-wide Settings VS readonlyrest.yml ([PRO](https://readonlyrest.com/pro)) Our Kibana plugins introduce a "ReadonlyREST" Kibana app. From here, you can edit the security settings of the whole Elasticsearch cluster, and they will take effect within 10 seconds in all Elasticsearch cluster nodes without the need to restart them. When you change the security settings from the Kibana app, they will be saved in a special index called ".readonlyrest", so all the Elasticsearch nodes will pick them up. You can customize the name of the index by setting `readonlyrest.settings_index: .my_custom_readonlyrest` in the `elasticsearch.yml` file (remember to set the same value for all your ES nodes). When an Elasticsearch node restarts, the order of settings evaluation is the following: 1. Attempt to find valid settings in readonlyrest.yml 2. If none is found, look inside elasticsearch.yml 3. Once successfully bootstrapped using file-based settings, attempt to read ".readonlyrest" index 4. If the index exists and contains valid settings, override file-based settings with the ones from the index. 5. Pressing "save" in the cluster-wide settings app, will **not overwrite the readonlyrest.yml** file. Best practices: * Build and update your production security settings from the Kibana app (will be saved in index) * Protect the ".readonlyrest" Kibana index with an ACL rule #### Loading settings: order of precedence As you read, there are two possible places where the settings can be read from: * `readonlyrest.yml` a file the user needs to create in the same directory where `elasticsearch.yml` is found. * `.readonlyrest` index. Our Kibana plugins' GUI (PRO/Enterprise) is programmed to write this index. When the ES plugin boots up, it follows some logic to evaluate where to read the YAML settings from. The following diagram shows how that works. ![config loading diagram](/files/7iuaj1fPpwOLSwymxLzO) #### Malformed in-index settings If for some reason the in-index settings get corrupted and ROR can't parse them, then neither settings from file or in-index settings can be loaded, so ES can't start. In this case, ES would print a message like: ``` Loading ReadonlyREST settings from index failed: Settings config content is malformed. Details: while scanning a quoted scalar in 'reader', line 9, column 17: auth_key: "admin:container ^ ``` To recover from this state, set `readonlyrest.force_load_from_file: true` in `elasticsearch.yml` on one node `es1`. Example recovery settings: elasticsearch.yml ```yaml [...] readonlyrest: force_load_from_file: true ``` readonlyrest.yml ```yaml readonlyrest: access_control_rules: - name: "::ADMIN recover::" auth_key: admin:dev indices: ["*"] ``` Then remove the in-index settings index manually. ```bash curl -X DELETE "admin:dev@es1:9200/.readonlyrest?pretty" ``` Now you can restore your settings to `readonlyrest.yml`, remove `readonlyrest.force_load_from_file: true` `from elasticsearch.yml` and restart the node. ### Example: multiuser ELK This configuration will work in PRO and Enterprise editions. This is a typical example of a configuration snippet to add at the end of your `readonlyrest.yml` (the settings file of the Elasticsearch plugin), to support ReadonlyREST PRO. ```yaml readonlyrest: access_control_rules: - name: "::LOGSTASH::" auth_key: logstash:logstash actions: ["indices:data/read/*","indices:data/write/*","indices:admin/template/*","indices:admin/create"] indices: ["logstash-*"] - name: "::KIBANA-SRV::" auth_key: kibana:kibana # use the following block instead of the `::KIBANA-SRV::` block if you use service account tokens (see https://www.elastic.co/guide/en/elasticsearch/reference/current/service-accounts.html) # #- name: "::KIBANA-SRV-TOKEN::" # token_authentication: # token: "Bearer AAEAAWVsYXN0aWMva2liYW5hL3Rva2VuXzE6MVhQUXRubWhRd3FxUmlzNmhFVVZQdw" # generated token for Kibana # username: kibana - name: "::RO::" auth_key: ro:dev indices: ["logstash-*"] kibana: access: ro hide_apps: [ "Security", "Enterprise Search"] - name: "::RW::" auth_key: rw:dev indices: ["logstash-*"] kibana: access: rw hide_apps: [ "Security", "Enterprise Search"] - name: "::ADMIN::" auth_key: admin:dev # KIBANA ADMIN ACCESS NEEDED TO EDIT SECURITY SETTINGS IN ROR KIBANA APP! kibana: access: admin - name: "::WEBSITE SEARCH BOX::" indices: ["public"] actions: ["indices:data/read/*"] ``` ### Very important #### ACL blocks ordering matters > Blocks related to the authentication of the users should be at the top of the ACL One of the most common mistakes is forgetting that the ACL blocks are evaluated in order from the first to the last. So, some requests with credentials can be let through from one of the first blocks and come back to Kibana with no user identity metadata associated. Take this example of a troublesome ACL: ```yaml # PROBLEMATIC SETTINGS (EXAMPLE) ⚠️ access_control_rules: - name: "::FIRST BLOCK::" hosts: ["127.0.0.1"] actions: [...] - name: "::ADMIN::" auth_key: admin:dev kibana: access: admin ``` The user will be able to login because the login request will be allowed by the first ACL block. But the ACL will not have resolved any metadata about the user identity (credentials checking was ignored)! This means the response to the Kibana login request will contain no user identity metadata (username, hidden apps, etc) and ReadonlyREST for Kibana won't be able to function correctly. The solution to this is to reorder the ACL blocks, so the ones that authenticate Kibana users are on the top. ```yaml # SOLUTION: KIBANA USER AUTH RELATED BLOCKS GO FIRST! ✅👍 access_control_rules: - name: "::ADMIN::" auth_key: admin:dev kibana: access: admin - name: "::FIRST BLOCK::" hosts: ["127.0.0.1"] actions: [...] ``` ### SSL/TLS server You can configure Kibana with the ReadonlyREST plugin to accept SSL connection the same way you would with vanilla Kibana configuration. For example, in `kibana.yml`: ```yaml server.ssl.enabled: true server.ssl.keystore.path: "/usr/share/kibana/config/certificates/kibana-server.p12" server.ssl.keystore.password: "" server.ssl.supportedProtocols: ["TLSv1.2", "TLSv1.3"] ``` #### Secure cookies ReadonlyREST will set the "secure" flag to its Kibana session cookie ("ror-cookie") automatically when SSL is enabled in Kibana.\ \ This is because modern browsers like Chrome won't accept "secure"-flagged cookies if the website is not HTTPS. However, a common situation is when SSL is configured in a reverse proxy (SSL termination): so the browser will interact with Kibana using HTTPS. But because ROR doesn't know it, it will still serve session cookies without the "secure" flag.\ \ In this case, you can force ReadonlyREST to create "secure"-flagged cookies by adding this line in `kibana.yml`: ```yaml xpack.security.secureCookies: true ``` ### Load balancers These features will work with all ReadonlyREST Editions #### Enable health check endpoint Normally a load balancer needs a health check URL to see if the instance is still running, you can whitelist this Kibana path so the load balancer avoids a redirection to `/login`. Edit `kibana.yml` ``` readonlyrest_kbn.whitelistedPaths: [".*/api/status$"] ``` #### Session management with multiple Kibana instances Each Kibana node stores user sessions in memory. This will cause problems when using multiple Kibana instances behind a load balancer (especially without sticky sessions), as there would be no synchronization between nodes' session cache. To avoid this, session synchronization via an Elasticsearch index should be enabled. Follow these steps: 1. Come up with a string of at least 32 characters length or more to be used as the shared cookie encryption key, called `cookiePass`. 2. Open up `conf/kibana.yml` and add: * `readonlyrest_kbn.cookiePass: "generatedStringIn1step"` (example: "12345678901234567890123456789012") * `readonlyrest_kbn.cookieName` (custom cookie name - this property is optional; if not specified default cookie name would be `rorCookie`) * `readonlyrest_kbn.store_sessions_in_index: true` (enable session storage in index) * `readonlyrest_kbn.sessions_index_name: "someCustomIndexName"` (index name - this property is optional; if not specified default index would be `.readonlyrest_kbn_sessions`) * `readonlyrest_kbn.sessions_refresh_after: 5000` (time in milliseconds, describes how often sessions should be fetched from ES and refreshed for each node - optional, by default 2 seconds) * `readonlyrest_kbn.sessions_probe_interval_seconds: 120` (default 60s) how often should the browser poll Kibana to check if their session is still valid. Raise this value if you connect to Kibana through slow networks (i.e. VPN), or have very slow-loading dashboards. 3. Add the above config in all Kibana nodes behind the load balancer, and restart them. {% hint style="warning" %} From ReadonlyREST version 1.51.0 `readonlyrest_kbn.cookiePass` is a required `kibana.yml` config parameter. {% endhint %} ### Session Configuration #### Session timeout When a user logs in, ReadonlyREST writes an encrypted cookie in the browser. The session lifetime can be configured with the following key in `kibana.yml`: ```yaml readonlyrest_kbn.session_timeout_minutes: 480 # defaults to 4320 (3 days) ``` This is a sliding inactivity window — each user action resets the clock. #### Automatic Session cleanup All expired Index or In-memory sessions, determined by an `expiresAt` date that falls prior to the current time and date, will be systematically cleaned. The parameters for this automated session cleanup procedure can be adjusted within the `kibana.yml` configuration file. ```yaml readonlyrest_kbn.sessions_cleanup_interval: '1h' # Default to 1d ``` **Automatic Session cleanup options** You can defines interval as: | Value | Description | Example | | ----- | ----------- | ------- | | s | seconds | "1s" | | m | minutes | "1m" | | h | hours | "1h" | | d | days | "1d" | #### Clearing session history By default, all session data (search history, dev tool command history, etc.) is wiped from the browser whenever a new user logs in or a user changes tenancy. To override this behavior: ```yaml readonlyrest_kbn.clearSessionOnEvents: ["never"] ``` Possible values: `"login"`, `"tenancyHop"`, `"never"`. #### Cookie settings ReadonlyREST sets the following security flags on every session cookie: | Flag | Default | Notes | | ---------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HttpOnly` | `true` (always) | Cannot be disabled. | | `Secure` | `true` when TLS is active | Automatically enabled when Kibana is configured with SSL, or when `readonlyrest_kbn.cookies.secure: true` is set explicitly (required for NGINX SSL termination). | | `SameSite` | `Lax` | Configurable to `Strict` (recommended for management interfaces) or `None`. | The following cookie attributes are configurable in `kibana.yml`: | Setting | Default | Notes | | ----------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `readonlyrest_kbn.cookieName` | `rorCookie` | Name of the session cookie. | | `readonlyrest_kbn.cookiePass` | *(required)* | Minimum 32-character secret used to encrypt the cookie. Required since ROR 1.51.0. | | `readonlyrest_kbn.cookies.secure` | auto | Set to `true` to force the `Secure` flag when SSL is terminated at a reverse proxy (i.e. Kibana runs over plain HTTP internally). | | `readonlyrest_kbn.cookies.sameSite` | `Lax` | Controls the `SameSite` attribute. Accepted values: `strict`, `lax`, `none`. Use `none` together with `secure: true` for cross-domain iframe embedding. | Example `kibana.yml`: ```yaml readonlyrest_kbn.cookieName: rorCookie readonlyrest_kbn.cookiePass: readonlyrest_kbn.cookies.sameSite: strict # lax | strict | none readonlyrest_kbn.cookies.secure: true # explicit override for reverse-proxy setups ``` The `HttpOnly` flag is always set and cannot be disabled. The `Secure` flag is set automatically when Kibana is configured with SSL. *** ### Terminate Kibana on ES high-watermark When enabled, Kibana will exit if the connected Elasticsearch cluster reports a disk high‑watermark condition. This is useful to prevent Kibana from running in a degraded state when Elasticsearch is unable to allocate shards due to insufficient disk space. ```yaml # kibana.yml # If set to true, Kibana will exit when Elasticsearch reports a disk high-watermark condition. readonlyrest_kbn.diskThresholdVerificationEnabled: false # default: true ``` ## Authentication ReadonlyREST Kibana supports several methods for authenticating users at the Kibana layer. When a user logs in through one of these methods, Kibana establishes a session and forwards the verified identity to Elasticsearch. On the Elasticsearch side, ReadonlyREST must be configured to trust this forwarded identity using the appropriate rule: | Kibana authentication method | Required ROR ES rule | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Proxy Auth | [`proxy_auth`](/develop/elasticsearch#proxy_auth) | | SAML / OIDC | [`ror_kbn_authentication`](/develop/elasticsearch#ror_kbn_authentication), [`ror_kbn_authorization`](/develop/elasticsearch#ror_kbn_authorization), or [`ror_kbn_auth`](/develop/elasticsearch#ror_kbn_auth) | | Standard login form (Basic auth) | No Kibana-level auth config needed — handled directly in ROR ES via `auth_key`, `ldap_authentication`, etc. | This is why SAML and OIDC sections below each contain an "Elasticsearch side" configuration step: the two plugins must share a secret so the identity can flow securely between them. ### Proxy Auth This feature will work in all ReadonlyREST editions. ROR for Elasticsearch can delegate authentication to a reverse proxy which will enforce some kind of authentication, and pass the successfully authenticated user's name inside an `X-Forwarded-User` header. > Today, it's possible to skip the regular ROR login form and use the "delegated authentication" technique in ROR for Kibana as well. 1. Configure ROR for ES to expect delegated authentication (see [`proxy_auth` rule](/develop/elasticsearch#proxy_auth)) in ROR for ES documentation. 2. Open up `conf/kibana.yml` and add `readonlyrest_kbn.proxy_auth_passthrough: true` Now ROR for Kibana will **skip the login form entirely**, and will only require that all incoming requests must carry an `X-Forwarded-User` header containing the user's name. Based on this identity, ROR for Kibana will build an encrypted cookie and handle your session normally. #### Custom Logout link This feature will work in all ReadonlyREST editions. Normally, when a user presses the logout button in ROR for Kibana, it deletes the encrypted cookie that represents the user's identity and the login form is shown. However, when the authentication is delegated to a proxy, the logout button needs to become a link to some URL capable to unregister the session a user-initiated within the proxy. For this, ROR for Kibana offers a way to customize the logout button's URL: 1. Find a link that will delete the reverse proxy's user session 2. Open up `conf/kibana.yml` and add `readonlyrest_kbn.custom_logout_link: https://..../logout` Now users who gained a session through delegated auth can also click on the logout button in ROR for Kibana and actually exit their session. #### Custom Login link This feature will work in all ReadonlyREST editions. When you delegate authentication to an external service, you can tell ReadonlyREST to skip the classic login form entirely and redirect users to your proxy or identity provider's login screen. To enable this: 1. Find your authentication proxy or identity provider login URL for the ROR app 2. Open up `conf/kibana.yml` and add `readonlyrest_kbn.custom_login_link: "https://../login"` The advantage of this approach is a streamlined user experience for users that login with an external IdP. The disadvantage is that you give up the possibility to log in as a local user in ROR, as the login form will be always skipped. #### Caveat Enabling proxy auth passthrough will relax the requirement to provide a password. Therefore, don't enable this option if you don't make sure Kibana can **only be accessed through the reverse proxy\***. ### JWT Token Forwarding as URL Query Parameter This feature will work in all ReadonlyREST editions. As an alternative to typing in credentials in the standard login form, it is possible to create an authenticated Kibana session by passing a JWT token as a query parameter in a URL. #### Configuration To enable this feature in ReadonlyREST, you need to: * Have JWT authentication configured in ReadonlyREST (modifying `readonlyrest.yml` or the cluster-wide settings UI in the Kibana plugin). [See how](/develop/elasticsearch#json-web-token-jwt-auth). * Specify the query parameter name in `kibana.yml` by adding the line `readonlyrest_kbn.jwt_query_param: "jwt"` as a string, in our case "jwt". #### In Action Once Kibana is restarted, you will be able to navigate to a link like this: ``` http://kibana:5601/login?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ ``` The following will happen: 1. The Kibana plugin will forward the JWT token found in the query parameter into the `Authorization` header in a request to Elasticsearch. 2. Elasticsearch will cryptographically authenticate and resolve the user's identity from the JWT claims. 3. Kibana will write an encrypted cookie in your browser and use that from now on for the length of the authenticated session. From here onwards, the session management will be identical to the normal login form flow. 4. When the user presses logout, Kibana will delete the cookie and redirect you to the login form, or whatever link you configured as `readonlyrest_kbn.custom_logout_link`. **Deep linking with JWT** Because the identity is embedded in the link, and ReadonlyREST is able to authenticate the request on the fly, the JWT authentication can be used in conjunction with the `nextUrl` query parameter for sharing deep links inside Kibana apps. **Anatomy of a JWT deep link** ``` http://kibana:5601/login?jwt=&nextUrl=urlEncode() ``` In JavaScript one can compose a JWT deep link as follows: ```javascript var absoluteKibanaPath = '/app/kibana#/visualize/edit/28dcde30-2258-11e8-82a3-af58d04b3c02?_g=()'; var url = 'http://kibana:5601/login?jwt=' + jwtToken + '&nextUrl=' + encodeURI(absoluteKibanaPath); console.log("Final JWT deep link: " + url) ``` The result may look something like this: ``` http://localhost:5601/login?nextUrl=%2Fapp%2Fkibana%23%2Fvisualize%2Fedit%2F28dcde30-2258-11e8-82a3-af58d04b3c02%3F_g%3D%28%29&jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ ``` ### Embedding Kibana Dashboard or Visualization with an iframe and JWT Authentication ([PRO](https://readonlyrest.com/pro)) You have the option to embed visualizations and dashboards inside iframes. For more information, refer to the [official Elastic documentation](https://www.elastic.co/guide/en/kibana/current/reporting-getting-started.html#embed-code). To add JWT authentication, modify the iframe `src` attribute as follows: Original iframe `src`: ```html ``` Modified iframe `src` with JWT: ```html ``` Replace with your actual JWT token to enable authentication. {% hint style="info" %} For a cross-domain iframe, you need to set the cookie sameSite: none and secure: true. You can do this via the kibana.yml configuration file by setting `readonlyrest_kbn.cookies.secure: true` and `readonlyrest_kbn.cookies.sameSite: 'none'`. {% endhint %} ### SAML ([Enterprise](https://readonlyrest.com/enterprise)) ReadonlyREST Enterprise supports service provider-initiated via SAML. This connector supports both SSO (single sign-on) and SLO (single log out). Here is how to configure it. #### Configure ReadonlyREST ES bridge In order for the user identity information to flow securely from Kibana to Elasticsearch, we need to set up the two plugins with a shared secret, that is: an arbitrarily long string. #### Elasticsearch side Edit `readonlyrest.yml` ```yaml readonlyrest: access_control_rules: - name: "::KIBANA-SRV::" auth_key: kibana:kibana # ... all usual blocks of rules... - name: "ReadonlyREST Enterprise instance #1" ror_kbn_authentication: name: "kbn1" ror_kbn: - name: kbn1 signature_key: "my_shared_secret_kibana1_(min 256 chars)" # <- use environmental variables for better security! ``` There are three rule types available, depending on what you want to achieve: * [ror\_kbn\_authentication](/develop/elasticsearch#ror_kbn_authentication) (handles only authentication) * [ror\_kbn\_authorization](/develop/elasticsearch#ror_kbn_authorization) (handles only authorization) * [ror\_kbn\_auth](/develop/elasticsearch#ror_kbn_auth) (authentication + authorization in a single rule) **⚠️IMPORTANT** Basic HTTP auth credentials for the Kibana server are **still needed** for now, due to how Kibana works. #### Kibana side Edit `kibana.yml` and append: ```yaml readonlyrest_kbn.auth: signature_key: "my_shared_secret_kibana1(min 256 chars)" saml_serv1: enabled: true type: saml issuer: ror buttonName: "Partner's SSO Login" entryPoint: 'https://my-saml-idp/saml2/http-post/sso' # <-- identity Provider's URL, to request to sign on kibanaExternalHost: 'my.public.hostname.com' # <-- public URL used by the Identity Provider to call back Kibana with the "assertion" message protocol: http # <-- is the Kibana server listening for "http" "https" connections? Default: http usernameParameter: 'nameID' groupsParameter: 'memberOf' logoutUrl: 'https://my-saml-idp/saml2/http-post/slo' cert: /etc/ror/integration/certs/dag.crt # <-- It can be also provided a string value # OPTIONAL, advanced parameters # decryptionCert: /etc/ror/integration/certs/pub.crt # decryptionPvk: /etc/ror/integration/certs/decrypt_pvk.crt # issuer: saml_sso_idp ``` * `issuer`: issuer string to supply to identity provider during sign-on request. Defaults to 'ror' * `disableRequestedAuthnContext`: if truthy, do not request a specific authentication context. This is known to help when authenticating against Active Directory (AD FS) servers. * `decryptionPvk`: Service Provider Private Key. A private key will be used to attempt to decrypt any encrypted assertions that are received. * `cert`: The downloadable certificate in IDP Metadata (file, absolute path) or single line string value For advanced SAML options, see [passport-saml documentation](https://github.com/bergie/passport-saml). #### Identity provider side 1. Enter the settings of your identity provider, and create a new app. 2. Configure it using the information found by connecting to `http://my.public.hostname.com/ror_kbn_saml_serv1/metadata.xml` Example response: ```xml urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress ``` 1. Create some users and some groups in the identity provider app 2. Check the user profile parameter names that the identity provider uses during the assertion callback ( **TIP**: set Kibana in debug mode so ReadonlyREST will print the user profile). 3. Match the name of the parameter used by the identity provider to carry the unique user ID (in the assertion message) to the `usernameParameter` kibana YAML setting. 4. If you want to use SAML for authorization, take care of matching also the `groupsParameter` to the parameter name found in the assertion message to the kibana YAML setting. #### Usage with Active Directory Federation Services To work properly with ADFS, ensure that you add the following to the configuration: ```yaml readonlyrest_kbn: auth: saml_adfs: authnContext: "http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows" # Name identifier format to request auth context.` identifierFormat: null # Name identifier format to request from identity provider.` [...] ``` #### Additional Parameters When configuring SAML authentication in ReadonlyREST Enterprise, you can provide additional parameters to customize the behavior of the SAML service provider integration. These parameters allow for fine-tuning the SAML integration to work with various identity providers and specific configurations You can find a list of all supported parameters in the [Passport-SAML Configuration Parameters documentation](https://github.com/node-saml/passport-saml/tree/3.x?tab=readme-ov-file#config-parameter-details) ```yaml readonlyrest_kbn: auth: saml_serv1: audience: "https://sp.example.com/metadata"` [...] ``` ### OpenID Connect (OIDC) ([Enterprise](https://readonlyrest.com/enterprise)) This feature will work in ReadonlyREST Enterprise. ReadonlyREST Enterprise supports OpenID Connect for both authentication and authorization. Here is how to configure it. #### Configure ReadonlyREST ES bridge This part is identical as seen in SAML connectors. In order for the user identity information to flow securely from Kibana to Elasticsearch, we need to set up the two plugins with a shared secret, that is: an arbitrarily long string. #### Elasticsearch side Edit `readonlyrest.yml` ```yaml readonlyrest: access_control_rules: - name: "::KIBANA-SRV::" auth_key: kibana:kibana # ... all usual blocks of rules... - name: "ReadonlyREST Enterprise instance #1" ror_kbn_authentication: name: "kbn1" ror_kbn: - name: kbn1 signature_key: "my_shared_secret_kibana1_(min 256 chars)" # <- use environmental variables for better security! ``` **⚠️IMPORTANT** the Basic HTTP auth credentials for the Kibana server are **still needed** for now, due to how Kibana works. If you have configured OIDC with the `groupsParameter` ( *See below* ), you can also restrict ACL to specific groups: ```yaml readonlyrest: access_control_rules: - name: "::KIBANA-SRV::" auth_key: kibana:kibana # ... all usual blocks of rules... - name: "ReadonlyREST Enterprise instance #1 for group 1" ror_kbn_auth: name: "kbn1" groups_any_of: ["group1"] - name: "ReadonlyREST Enterprise instance #1 for group 2" ror_kbn_auth: name: "kbn1" groups_any_of: ["group2"] ror_kbn: - name: kbn1 signature_key: "my_shared_secret_kibana1_(min 256 chars)" # <- use environmental variables for better security! ``` You may also use any custom claim from the OIDC `userinfo` token in ACL rules by using `{{jwt:assertion.}}` syntax. See the [Dynamic variables from JWT claims section](/develop/elasticsearch#usage-examples) for more information. ( **TIP** : Do not forget the `assertion` prefix in front of you jsonpath. ) #### Kibana side We will assume the OpenID identity provider responds to port 8080 of localhost. In our example, we used Keycloak, an open-source implementation of OpenID Connect identity provide. Edit `kibana.yml` and append: ```yaml readonlyrest_kbn.auth: signature_key: "my_shared_secret_kibana1(min 256 chars)" oidc_kc: buttonName: "KeyCloak OpenID" type: "oidc" issuer: 'http://localhost:8080/auth/realms/ror' authorizationURL: 'http://localhost:8080/auth/realms/ror/protocol/openid-connect/auth' tokenURL: 'http://localhost:8080/auth/realms/ror/protocol/openid-connect/token' userInfoURL: 'http://localhost:8080/auth/realms/ror/protocol/openid-connect/userinfo' clientID: 'ror_oidc' clientSecret: '9f1d39c8-a211-460a-84b6-0a4a1499c455' scope: 'openid profile roles role_list email' usernameParameter: 'preferred_username' groupsParameter: 'groups' kibanaExternalHost: 'localhost:5601' logoutUrl: 'http://localhost:8080/auth/realms/ror/protocol/openid-connect/logout' jwksURL: 'http://localhost:8080/auth/realms/ror/protocol/openid-connect/certs' ``` #### Identity provider side 1. Enter the settings interface of your identity provider, and create a new OpenID app. 2. The redirect URL should be configured as `http://localhost:5601/*` assuming Kibana is listening on localhost and on the default port. 3. Create some users and some groups in the identity provider if not present. 4. Check the user profile parameter names that the identity provider uses during the assertion callback ( **TIP**: set `readonlyrest_kbn.logLevel: debug` in kibana.yml, so you will see the user profile how it's received from the identity provider right in the logs). 5. Match the name of the parameter used by the identity provider to carry the unique user ID (in the assertion message) to the `usernameParameter` kibana YAML setting. 6. If you want to use OpenID for authorization, take care of matching also the `groupsParameter` to the parameter name found in the assertion message to the kibana YAML setting. ( **TIP**: the `groupsParameter` must be present in the `userinfo` token of your OIDC provider.) 7. If Kibana is accessed through a reverse proxy, kibanaExternalHost should be configured with the external hostname. if omitted, the default value is equal to `server.host:server.port` defined in kibana.yml. ( This parameter can be used also when Kibana is bound to 0.0.0.0, for example, if using docker.) #### Client Authentication Methods You can configure how the ReadonlyREST Kibana plugin sends `client_id` and `client_secret` to the identity provider using the option ```yaml readonlyrest_kbn: auth: oidc_kc: tokenEndpointAuthMethod: 'client_secret_post' #Available options: client_secret_basic (default) or client_secret_post [...] ``` There are two available methods for authentication: 1. **client\_secret\_basic** (default): The `client_id` and `client_secret` are sent using the Authorization header, as specified in [RFC 6749, Section 2.3.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1). Before sending, the `client_id` and `client_secret` are encoded. 2. **client\_secret\_post**: The `client_id` and `client_secret` are included in the request body, following the guidelines in [RFC 6749, Section 2.3.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1). In this method, the `client_id` and `client_secret` are not encoded before being sent. Choose this method when the OpenID Connect provider, such as [lemonLDAP::NG](https://lemonldap-ng.org/), cannot decode the encoded values. The following description explains the available options for the setting: #### User Info Source Methods You can configure where the ReadonlyREST Kibana plugin obtains the OIDC user profile information using the `userInfoSource` option in the `readonlyrest_kbn.auth.oidc_kc` block. There are three available methods: 1. **user\_info\_endpoint** (default):\ When set to `user_info_endpoint`, the plugin makes an additional call to the URL specified under `userInfoURL` to retrieve the most up-to-date user profile information from the OIDC provider. 2. **access\_token**:\ When set to `access_token`, the plugin extracts the user profile information directly from the access token. 3. **id\_token**:\ When set to `id_token`, the plugin extracts the user profile information directly from the ID token. For example, you can configure it as follows: ```yaml readonlyrest_kbn: auth: oidc_kc: userInfoSource: 'access_token' # Available options: 'user_info_endpoint' (default), 'access_token', 'id_token' ``` #### Additional Parameters When configuring OpenID Connect (OIDC) in ReadonlyREST Enterprise, you can provide additional parameters to customize the behavior of the OIDC client and issuer. These parameters allow for fine-tuning the OIDC integration to work with various providers and specific configurations. These additional parameters allow you to solve complex authentication scenarios, work with non-standard OIDC providers, and fine-tune the security and performance characteristics of your OIDC integration. **Issuer Additional Parameters** You can find a list of all supported parameters: For Kibana 7.12.0 and above: [documentation](https://github.com/panva/openid-client/tree/v5.7.1/docs#new-issuermetadata) For Kibana below 7.12.0: [documentation](https://github.com/panva/openid-client/tree/v4.9.1/docs#new-issuermetadata) ```yaml readonlyrest_kbn.auth: oidc_kc: [...] issuerAdditionalParameters: metadata: token_endpoint: 'https://custom-token-endpoint' jwks_uri: 'https://custom-jwks-uri' ``` #### Clock skew tolerance You can configure the clock tolerance (in seconds) to account for potential time discrepancies between the Kibana server and the OpenID Connect provider. This setting helps prevent authentication failures due to minor time differences. ```yaml readonlyrest_kbn.auth: oidc_kc: [...] clockToleranceSeconds: 5 # Default is 0 seconds ``` **Client Additional Parameters** You can find a list of all supported parameters: For Kibana 7.12.0 and above: [documentation](https://github.com/panva/openid-client/tree/v5.x/docs#new-clientmetadata-jwks-options) For Kibana below 7.12.0: [documentation](https://github.com/panva/openid-client/tree/v4.x/docs#new-clientmetadata-jwks-options) ```yaml readonlyrest_kbn.auth: oidc_kc: [...] clientAdditionalParameters: metadata: response_types: ['code'] redirect_uris: ['https://my-app/callback'] jwks: keys: - kty: 'RSA' use: 'sig' alg: 'RS256' kid: 'key1' n: 'PLACEHOLDER_TO_CHANGE_INTO_REAL_CERTIFICATE' e: 'AQAB' options: additionalAuthorizedParties: 'my-app' ``` ### Impersonation According to [Wikipedia](https://en.wikipedia.org/wiki/Impersonator): > An impersonator is someone who imitates or copies the behavior or actions of another. So, an impersonation can be understood as imitating behaviors or actions. In the context of ReadonlyREST: one user could imitate an action of another user. Why would we want it? Let's suppose the first user is an admin, who has just configured access for a new user. They would like to know if the rule(s) are configured correctly. And here comes the impersonation feature. The admin can impersonate the given user in Kibana and see what the user would see if they logged in themselves. ROR plugins support impersonation and provide UI for configuring a cluster before using it. Visit the [impersonation details page](/develop/kibana/impersonation) to know more. ## Multi-tenancy ### Multi-tenancy Kibana ([Enterprise](https://readonlyrest.com/enterprise)) ReadonlyREST Enterprise is capable of going beyond multi-user. Users or groups can be isolated into tenancies, so their dashboards and configurations won't mix. Behind each tenancy, there is a kibana index. #### What is a kibana index? In the vanilla Kibana, all the configuration objects are stored under an Elasticsearch index called `.kibana`, but with ReadonlyREST Enterprise installed, you can dynamically route Kibana into reading and writing to other indices entirely, for example `.kibana_tenancy1`. So when "tenancy1" is selected from the UI, Kibana hard reloads and all settings, dashboards, and visualizations are (potentially) different. A user can be associated to multiple tenancies, and if so, will be presented with a tenancy switcher in the UI. ![image](https://github.com/beshu-tech/readonlyrest-docs/assets/1327189/b07d27d3-310c-4754-a5c5-21b0fe3f3d45) Using this tool, they can hop between tenancies. Keep in mind that the ACL evaluation is slightly different when multi tenancy is activated: if a tenancy is selected, only blocks without `kibana.index` rule, or with the `kibana.index` [rule](https://docs.readonlyrest.com/elasticsearch#kibana) matching to the current teancy name will be evaluated. In ReadonlyREST Enterprise, multi-tenancy is activated by default. But if you want it to behave as in PRO/Free editions, you can disable it by writing into `kibana.yml`: ```yml readonlyrest_kbn.multiTenancyEnabled: false ``` ### Configuring Multi-tenancy ([Enterprise](https://readonlyrest.com/enterprise)) You can configure an ACL in multi tenancy mode by adding a few ACL blocks containing the `kibana.index` [rule](https://docs.readonlyrest.com/elasticsearch#kibana). See examples and further explanation under our [multi-tenancy guide](/develop/examples/multitenancy_guide). ### Extending the Kibana API with the x-ror-tenancy-id header ([Enterprise](https://readonlyrest.com/enterprise)) To target a specific tenant when making a [Kibana API](https://www.elastic.co/guide/en/kibana/current/api.html) request, include the custom HTTP header `x-ror-tenancy-id`. The value of this header should match one of the [groups rules](/develop/elasticsearch#groups-rules) id defined in your ACL configuration. The first group defined in the ACL for a specific user is used as the default tenancy id. example usage: ```bash curl -X GET "http://localhost:5601/api/saved_objects/_find?type=dashboard" \ -H "kbn-xsrf: true" \ -H "x-ror-tenancy-id: marketing-team" ``` #### No authentication rule defined The “problem with the configuration of authentication” error message is presented in ReadonlyREST Free/PRO/Enterprise when the login request is checked by the ACL and gets accepted by an ACL block with no authentication rule in it. An example of this would be: ```yaml readonlyrest: access_control_rules: - name: "LDAP Auth" ldap_authentication: ... - name: "Allow requests from localhost" hosts: ["127.0.0.1"] ``` Imagine you run Elasticsearch and Kibana on the same host: * the Kibana user login request comes to Elasticsearch * Credentials are wrong, and the first block does not match * The second block is then evaluated, and the request is allowed because of its origin IP As you can see, Elasticsearch has no user-related information (metadata) to return to Kibana, and the error “problem with the configuration of authentication ” is shown. In general, we highly discourage implementing access control using origin IPs alone, users should set up SSL, Basic HTTP auth in their agents in any case, even on localhost. The `hosts` rule would then be an extra protection. If this is not possible for very important reasons, then we would prevent any Kibana-originated request to match that rule by using the negated form of the [headers rule](/develop/elasticsearch#headers). I.e. readonlyrest.yml ```yaml - name: "Allow requests from localhost" hosts: ["127.0.0.1"] headers: [ "~x-from-kibana:true" ] ``` kibana.yml (append) ```yaml elasticsearch.customHeaders: {"x-from-kibana":"true"} ``` ### Tenancy index templating ([Enterprise](https://readonlyrest.com/enterprise)) This feature will work only with ReadonlyREST Enterprise When a tenant logs in for the first time, ReadonlyREST Enterprise will create the kibana index associated to the tenancy as per ACL. For example, it will create and initialize the ".kibana\_user1" index, where the tenant "user1" will store all the ["saved objects"](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html), that is: visualizations, dashboards, spaces, settings, data views, etc. The problem is that user1, and any other new users would login for the first time in to a completely blank Kibana. And this is particularly challenging if the tenant is supposed to be read-only (i.e. kibana.access: "ro") because they won't even have privileges to create their own index-pattern, let alone any dashboards. To fix this, ReadonlyREST Enterprise offers the possibility for administrators to create and curate a template kibana index from which all the Kibana objects will be copied over to the newly initialised tenancy. The objects in the templating index will be copied every time the user logs in (or changes tenancy with the tenancy selector), and **if the objects were already present, they will be overwritten**. The object overwrite is desirable because administrators would like to improve and enrich the content of the template tenancy over time, and these enhancements need to be propagated to the tenants. If the tenants were not read-only, and created other objects of their own (e.g. another space, another dashboard), these won't be deleted. #### Reset tenancy to template If you add `readonlyrest_kbn.resetKibanaIndexToTemplate: true` to `kibana.yml` your tenants will get their index deleted and reinitialized to the content in the kibana template index specified in `readonlyrest_kbn.kibanaIndexTemplate` every time they log in, or change tenancy using the tenancy selector. The reset tenancy to template only works if a valid kibana index template is specified. #### How to use tenancy templating An administrator will need to create the template tenancy, populate it with the default Kibana objects (index-patterns, dashboards) and configure ReadonlyREST Enterprise to take the index template it in use. Let's see this step by step: **Create the template tenancy** Let's start to add to our access control list (found in $ES\_PATH\_CONF/config/readonlyrest.yml, or ReadonlyREST App in Kibana) a local user "administrator" that will belong to two tenancies: the default one (stored in .kibana index), and the template one (stored in .kibana\_template index). ```yaml readonlyrest: audit: enabled: true outputs: - type: index access_control_rules: - name: "::KIBANA-SRV::" auth_key: kibana:kibana verbosity: error - name: "Admin Tenancy" groups_any_of: ["Admins"] verbosity: error kibana: access: admin index: ".kibana" - name: "Template Tenancy" groups_any_of: ["Template"] verbosity: error kibana: access: admin index: ".kibana_template" users: - username: administrator auth_key: administrator:dev groups: ["Admins", "Template"] # can hop between two tenancies with top-left drop-down menu ``` NB: If you know what you are doing, you can add a tenancy with kibana\_index: ".kibana\_template" adding a LDAP/SAML group to your administrative user. #### Configure the template tenancy Now login as administrator in Kibana, hop into the "Template" tenancy, and start configuring the default saved objects for your future tenants: add all the data views, create or import all the dashboards you want. #### Configure the template tenancy index in ReadonlyREST Enterprise Open kibana.yml and add the following line: ```yaml readonlyrest_kbn.kibanaIndexTemplate: ".kibana_template" ``` Now, ReadonlyREST Enterprise will look for the ".kibana\_template" index, and try to copy over all its documents every time a new kibana index is initialised to support a new tenancy. #### Try it out Restart Kibana with the new setting. Add a new tenancy to the ACL: ```yaml readonlyrest: audit: enabled: true outputs: - type: index access_control_rules: - name: "::KIBANA-SRV::" auth_key: kibana:kibana verbosity: error - name: "Admin Tenancy" groups_any_of: ["Admins"] verbosity: error kibana: access: admin index: ".kibana" - name: "Template Tenancy" groups_any_of: ["Template"] verbosity: error kibana: access: admin index: ".kibana_template" # Newly added tenant! - name: user1 auth_key: user1:passwd kibana: access: rw index: ".kibana_user1" users: - username: administrator auth_key: administrator:dev groups: ["Admins", "Template"] # can hop between two tenancies with top-left drop-down menu ``` Now try to login as user1, and ReadonlyREST Enterprise should initialize the index ".kibana\_user1" with all the index patterns and dashboards contained in the template tenancy. ### Tenant index configuration You can configure the `number_of_shards` and `number_of_replicas` for the tenant index via the `kibana.yml` file, allowing you to override the default index settings. This can be particularly useful in a single-node environment. ```yaml readonlyrest_kbn.tenantIndex.number_of_shards: 1 readonlyrest_kbn.tenantIndex.number_of_replicas: 0 ``` {% hint style="warning" %} These settings will overwrite the index template settings. {% endhint %} ## UI Customization ### Hiding Kibana Apps ([PRO](https://readonlyrest.com/pro)) Previously we needed to keep track and document all Kibana app IDs, and you had to look them up all the time. Now we made it simpler by letting you type the apps and submenu titles exactly as you see them in the UI. For example, this is how you hide the whole Enterprise Search submenu. ![kibana\_hide\_apps: \["Enterprise Search"\]](/files/-MXq6rKbbyqZPQtJVADZ) And this is how you hide only one app from the Enterprise Search menu: ![kibana\_hide\_apps: \["Enterprise Search|Workplace Search"\]](/files/-MXq7Z0f12aRqYchy1pX) More generally, either of these two ways will work: ```yaml kibana: hide_apps: [ "" ] ``` ```yaml kibana: hide_apps: [ "" ] ``` For example, the following is a valid rule: ```yaml kibana: hide_apps: [ "Security", "Management|Stack Management", "Enterprise Search" ] ``` There is also a way to use regular expression as a `kibana.hide_apps` value for example, you can hide all submenus except for the specific app ```yaml kibana: hide_apps: [ "/^Analytics\\|(?!(Maps)$).*$/"] ``` In this case, all analytics apps will be hidden except `Maps` **⚠️IMPORTANT** Pipe operator needs to be escaped correctly when it's declared in the regular expression `\\|`. The regular expression must be declared between double quote `"/