In the previous article of this series
, we demonstrated how to set up the OpenSearch security plugin by using the demo installer. We also looked at TLS encryption on the transport and REST-layer. Now it’s time to add our first user and assign an OpenSearch security role that governs access to indices and data.
In this article, we will implement a very straightforward use case. We will set up two indices on our cluster, named
We will then configure two users. The first user has read and write access to
my-index-a, but no access to
The second user will have read-only access to
my-index-a, and full access to
This article assumes that you went through all steps in the previous article
, so you have a running OpenSearch cluster with the security demo configuration installed.
To set up the two indices
we are going to use, execute the following curl commands:
curl -u admin:admin -k -X PUT "https://localhost:9200/my-index-a?pretty"
curl -u admin:admin -k -X PUT "https://localhost:9200/my-index-b?pretty"
Both calls should return with an output like this:
"acknowledged" : true,
"shards_acknowledged" : true,
"index" : "my-index-a"
-u switch adds HTTP Basic Authentication headers to the curl call. For simplicity, we use the
admin user, which has full access to the cluster.
We also add the
-k switch to accept our self-signed demo TLS certificates. Omitting this switch would result in an error message:
curl: (60) SSL certificate problem: Invalid certificate chain
OpenSearch Security Configuration Handling
All security configuration settings are stored in an OpenSearch index. At the time of writing, this index is called
. This system index is protected and is not accessible for regular users. To make changes, like adding users and roles, we will use the securityadmin command line tool
The tool will read and parse one or more security configuration files and upload the contents of the files to the
.opendistro_security index. Changes to the index will get propagated to each node and will take effect immediately.
Adding Security Roles
The security roles are defined in the file
<OS installation dir>/plugins/opensearch-security/securityconfig/roles.yml
For our use case, we want to add two new roles. Let’s start with the first one. This role should grant a user read- and write access to
my-index-a, but no access to
OpenSearch uses a white-list approach for defining access controls: If not explicitly granted, a user has no access to any indices or data. This makes the second part of the use case easy to implement. To deny access to
my-index-b we have to do nothing. However, we need to define a security role to grant read and write access to
A security role has a name and two main sections: Cluster-level permissions and index-level permissions. For the sake of simplicity, we will not go into the details of cluster-level permissions in this article.
Defining index-level permissions is also straightforward. We need to define one or more permissions (aka “actions”) that a user is allowed to perform, and we need to specify for which indices these permissions shall apply. For our use case, we define our first role like this:
my-role-a is the name of the security role. You can use any naming schema you like.
Then we define an index pattern to which this role should grant access. As the term “index pattern” implies, you can use concrete index names, but wildcards, regular expressions, and even date math expressions are also allowed. In our case, we just want to grant access to a single index, so we use the concrete index name.
Next, we need to define what actions a user should be allowed to perform on that index. We use one of the pre-defined action groups
OpenSearch ships with, named
. This action group grants create, read, update and delete permissions.
For our second role, we use the following definition. This time, we use two index patterns with different actions:
This role grants read access to
my-index-a and full access to
my-index-b. Note that for
my-index-b, we have simply used a wildcard in the
Now that we have defined our two new roles in
roles.yml let’s add some users. For this, we edit the file
internal_users.yml. We just need to specify the names of our new users and their password hashes.
entry is the BCrypt
hash of the password. OpenSearch ships with a
script that you can use to generate a BCrypt hash on your machine directly. The script is in the tools directory. Example:
./hash.sh -p password-a
We generate a hash for both users and add it to the entries in internal_users.yml:
Assigning Users to Roles
As the last step, we need to “connect” our newly created users with the newly created roles. In other words, we define the security roles a user should have.
For this, we edit the file
roles_mapping.yml and add two new entries:
The top-level entry defines the role name we want to add users to. The
users array contains the names of the users.
These two entries basically say: Please add
user-a to the
my-role-a security role and
user-b to the
my-role-b security role.
Uploading the Configuration Changes
We are now ready to upload the changed configuration to our OpenSearch cluster. For this, we use the
securityadmin command-line tool, also located in the
tools folder. We
cd into the
tools folder and execute:
-cd ../securityconfig/ \
-cacert ../../../config/root-ca.pem \
-cert ../../../config/kirk.pem \
The -cd (–configdir) argument tells
securityadmin where to find the configuration files.
The following three arguments are required for authentication. Since we want to make changes to the security configuration, we have to use the TLS admin certificate
. Regular users are not allowed to perform changes to the security configuration.
We define the root CA that was used to sign the admin certificate (
-cacert), the admin TLS PEM certificate (
-cert), and the admin TLS certificate private key (
If everything went well, you should see an output like this:
Will connect to localhost:9300 ... done
Connected as CN=kirk,OU=client,O=client,L=test,C=de
Will update '_doc/roles' with ../securityconfig/roles.yml
SUCC: Configuration for 'roles' created or updated
Will update '_doc/rolesmapping' with ../securityconfig/roles_mapping.yml
SUCC: Configuration for 'rolesmapping' created or updated
Will update '_doc/internalusers' with ../securityconfig/internal_users.yml
SUCC: Configuration for 'internalusers' created or updated
Done with success
Done with success! We have created two new users with restricted access to our OpenSearch cluster.
In the next part of this series, we will dig deeper into more flexible ways to assign users to roles. See you there!