From X-Pack to OpenSearch: Part 4 – Migrating DLS and FLS

This article describes how to migrate Document and Fieldlevel security settings from X-Pack Security to OpenSearch Security.

X-Pack DLS and FLS

In our last blog post, we discussed how to migrate simple roles from X-Pack Security to OpenSearch Security. In this blog post, we focus on Document level security (DLS) and Field level security (FLS) which are an optional part of the role definition.

Assume we have a role with query and field_security defined:

{
  "cluster":[
    "all"
  ],
  "indices":[
    {
      "names":[
        "index*",
        "some"
      ],
      "privileges":[
        "all"
      ],
      "query": {
        "match": {
          "category": "mycategory"
        }
      },
      "field_security" : {
        "grant" : [ "name", "phone*", "category", "product.asin" ]
      }
    }
  ]
}

The query part of the role definition restricts document to document that matches the query. Sometimes it’s called a “role query”.

The field_security part of the role definition restricts fields to fieldnames that match one of the grant expressions.

OpenSearch Security Roles

In OpenSearch Security, Document level security (DLS) and Field level security (FLS) also exist and will be configured similar to X-Pack.

A role in OpenSearch Security with DLS and FLS looks like this:

{
  "cluster_permissions":[
    "cluster_all"
  ],
  "index_permissions":[
    {
      "index_patterns":[
        "index*",
        "some"
      ],
      "allowed_actions":[
        "indices_all"
      ],
      "dls": "{\"match\": { \"category\": \"mycategory\"}}",
      "fls": [\"name\", \"phone*\", \"category\", \"product.asin\"]
    }
  ]
}

Migrate DLS and FLS

The first thing you need to do is to adapt the syntax of the role according to:

X-Pack Security	OpenSearch Security
`query`	`dls`
`field_security`	`fls`

The content of the query and field_security fields can be used without any modification. OpenSearch Security also supports the wildcard syntax and the dot notation.

Templating and Attribute-based Security

DLS queries can be parametrized in X-Pack Security and in OpenSearch Security. X-Pack names this functionality Templating whereas OpenSearch Security calls it Attribute-based security.

In X-Pack mustache expression can be used within the query definition like:

"query":{
  "template":{
    "source":{
      "match":{
        "category":""
      }
    }
  }
}

In OpenSearch it looks like this:

"dls": "{\"match\": {\"category\": \"${attr.internal.category}\"}}"

Please refer to Part 2 - Users which explains how to migrate the metadata associated with a user.

To adjust the mapping for X-Pack metadata variables to OpenSearch variables, use the following table:

X-Pack Security	OpenSearch Security
`_user.username`	`user.name`
`_user.full_name`	n.a.
`_user.email`	n.a.
`_user.roles`	`user.roles`
`_user.metadata.XXX`	`attr.internal.XXX`

The syntax differs also. In X-Pack it’s mustache and in OpenSearch a homegrown one originated from here.

Limitations

OpenSearch Security does not have support for except feature for FLS to exclude certain fields like X-Pack have it. With OpenSearch Security, you can exclude a field using the ~ modifier but you can not mix including and excluding yet.

On the other hand, OpenSearch Security supports Term Level Queries (TLQ) as DLS queries whereas X-Pack does not.

Next Steps

In our next article, we will cover the migration of more complex roles containing user impersonation, tenants and role mappings.