The OpenSearch Security Plugin in Detail: Role-Based Access Control for Magento Search Clusters

1. Why access control is often neglected on Magento search clusters

In many Magento installations the search cluster runs without any authentication on the internal network, because setting up a security plugin initially feels like extra effort with no direct benefit. Once several systems start talking to the same cluster, though, such as the Magento indexer, a Kibana-like analytics tool, and external reporting scripts, the missing separation quickly turns into a real risk, since every access runs with full administrator rights.

The OpenSearch Security Plugin addresses exactly this problem by integrating authentication and authorization directly into the cluster, without requiring a separate proxy layer in front of it. For Magento operators that means the indexer service user only needs write access to its own catalog indices, while a reporting account can be limited to read-only access on selected fields.

2. Architecture of the Security Plugin: configuration files at a glance

The Security Plugin does not store its configuration in the central opensearch.yml, but in a dedicated set of YAML files under config/opensearch-security/: internal_users.yml for internal user accounts, roles.yml for the actual permission definitions, roles_mapping.yml for mapping users to roles, action_groups.yml for reusable permission bundles, and tenants.yml for tenant separation in dashboards.

These files are not read directly by the cluster, they have to be loaded into a special, hidden system index called .opendistro_security using the securityadmin.sh command line tool. Only after that does a change take effect on the running cluster, which is a common stumbling block when teams edit the YAML files but forget the upload step.

# config/opensearch-security/roles.yml (excerpt)
magento_indexer_role:
  cluster_permissions:
    - "cluster_composite_ops"
  index_permissions:
    - index_patterns:
        - "magento2_product_*"
        - "catalogsearch_fulltext_*"
      allowed_actions:
        - "indices:data/write/index"
        - "indices:data/write/bulk"
        - "indices:admin/create"
        - "indices:admin/mapping/put"

3. Difference from Elastic's X-Pack Security module

X-Pack Security has been enabled by default since Elasticsearch 8.x and is tightly integrated into the Elastic Stack, but is distributed under an Elastic-specific license whose basic functionality is free while advanced features such as field-level security were paid add-ons in older versions. Configuration mostly happens through the Kibana UI or the security API and is managed internally in a proprietary index that gets migrated automatically during cluster upgrades.

The OpenSearch Security Plugin takes a file-based, declarative approach instead: roles and mappings live as version-controllable YAML files that fit naturally into a Git repository and a CI pipeline like any other configuration file. For Magento projects with several environments that is a clear advantage, since staging and production roles can be deployed identically from the same source, whereas X-Pack Security often requires manual follow-up work through the Kibana UI.

4. Building a role-based access model for Magento

A practical model for a Magento search cluster consists of at least three roles: an indexer role with write access to the catalog indices, a read-only role for the actual storefront search, and an administrator role for cluster maintenance and mapping changes. Each of these roles is defined in roles.yml and then linked to concrete users or backend roles in roles_mapping.yml.

It matters to scope roles as tightly as possible: the Magento application server running storefront search only ever needs read access to the active catalog indices, never write or administration rights. If that user is compromised, the damage stays limited to read access, instead of handing an attacker the ability to delete indices or tamper with mappings.

# config/opensearch-security/roles_mapping.yml (excerpt)
magento_storefront_readonly:
  backend_roles: []
  users:
    - "magento_storefront"

magento_indexer_role:
  backend_roles: []
  users:
    - "magento_indexer_service"

5. Document-level and field-level security for catalog indices

Document-level security lets you restrict search results per role to a subset of documents, for example when a B2B Magento store maps several customer groups with different pricing structures onto the same index and an analytics team should only see products from one particular website. The restriction works through a plaintext query that gets attached as an additional filter on every search automatically.

Field-level security adds the same idea at the field level: a reporting account can be configured to see product names and categories, but have no access to internal calculation fields such as cost price or margin, which in some Magento installations end up as additional indexed attributes in the catalog index. Both mechanisms operate at query execution time and, on correctly built indices, cause no measurable performance loss.

{
  "index_permissions": [{
    "index_patterns": ["magento2_product_*"],
    "dls": "{\"term\": {\"website_id\": 2}}",
    "fls": ["name", "sku", "category_ids", "~cost_price", "~margin"],
    "allowed_actions": ["read"]
  }]
}

6. Configuring audit logging for compliance requirements

Audit logging records which user performed which action against the cluster and when, controlled through the config/opensearch-security/audit.yml file. For production Magento clusters it makes sense to log at least failed authentication attempts and all permission changes, while successful read access on storefront search is usually excluded because of its sheer volume.

Audit logs can be sent to a dedicated log file, a dedicated OpenSearch index, or directly to an external webhook target. For compliance requirements, such as an ISO 27001 certification, a separate index with its own retention period makes sense so audit data does not accidentally end up under the same deletion rules as the actual search indices.

# config/opensearch-security/audit.yml (excerpt)
audit:
  enable_rest: true
  disabled_rest_categories:
    - GRANTED_PRIVILEGES
  enable_transport: false
  resolve_bulk_requests: false
  log_request_body: false
  audit.log_request_body: false
config:
  type: internal_opensearch
  index: "security-auditlog-%{now/d}"

7. Transport encryption and TLS between nodes

The Security Plugin enforces node-to-node encryption via TLS by default, which requires every node to hold its own certificate plus a shared root certificate. For Magento clusters with several data nodes spread across different network segments this is not an optional hardening step, it prevents bulk indexing data from a reindex run being transmitted in plaintext over the internal network.

In addition to transport encryption, the REST interface that Magento uses to send its search requests should also be secured over HTTPS. In opensearch.yml this is enabled via plugins.security.ssl.http.enabled, and the Magento configuration needs its Elasticsearch connection scheme switched from http to https accordingly.

# opensearch.yml (excerpt)
plugins.security.ssl.transport.pemcert_filepath: node.pem
plugins.security.ssl.transport.pemkey_filepath: node-key.pem
plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem
plugins.security.ssl.transport.enforce_hostname_verification: true
plugins.security.ssl.http.enabled: true
plugins.security.ssl.http.pemcert_filepath: node-http.pem

8. Migration aspects when moving from Elasticsearch with X-Pack

When moving from Elasticsearch with active X-Pack Security to OpenSearch with the Security Plugin, roles and users cannot be taken over automatically, because the internal storage format differs. In practice a manual rebuild works best: existing X-Pack roles are exported through the Elasticsearch security API, rebuilt as OpenSearch YAML files, and loaded via securityadmin.sh.

A frequently overlooked point is that Magento itself does not ship any user management for the search cluster, it simply stores a username and password inside env.php. After migration this entry has to be updated to point at the newly created OpenSearch user, and testing storefront search on a staging environment before the production cutover is essential, since faulty role mappings otherwise only surface as empty search results once live.

# Load the new security configuration after editing the YAML files
./plugins/opensearch-security/tools/securityadmin.sh \
  -cd config/opensearch-security/ \
  -icl -nhnv \
  -cacert root-ca.pem \
  -cert admin.pem \
  -key admin-key.pem

9. Best practices and common pitfalls in production

The most frequent mistake is editing the YAML files but forgetting to call securityadmin.sh, which leaves the cluster running on its old configuration without any visible error. Equally critical is an overly permissive kibanaserver user, which in many default setups holds more rights than are actually needed for pure dashboard display.

For Magento operations it also pays to move the YAML files fully into infrastructure as code and roll out changes exclusively through the CI pipeline, instead of editing them manually on the server. That keeps a clear record of who changed which permission and when, and an accidentally forgotten upload gets caught in the pipeline step rather than at the next security audit.

10. Summary

11. FAQ: OpenSearch Security Plugin