EraSearch has role-based access control (RBAC) to let you manage users, roles, and permissions. This document outlines how to enable and set up RBAC in EraSearch. By the end of this guide, you'll have your first role, key, and role mapping.

The content below is intended for existing self-hosted EraSearch users. Reach out to us at Era Software if you're interested in getting started with self-hosted EraSearch.

Before you begin

Copy

Copied!

This guide assumes you have administrative access to the environment where EraSearch is deployed. Throughout this guide you'll need to:

• Set new environment variables in the EraSearch run-time.
• Access EraSearch's Quarry API directly for configuring the initial RBAC settings. For Kubernetes users, this usually means having kubectl access to the EraSearch namespace and the ability to forward ports locally.

This guide also assumes you're familiar with EraSearch's RBAC terms and concepts, and you have jq installed.

Step 1: Enable RBAC

Copy

Copied!

To enable RBAC, add the following environment variables to the EraSearch Quarry API environment:

• QUARRY_RBAC - Set to 1 for Azure AD OAuth access token validation.

• QUARRY_BOOTSTRAP_KEY - Set to any string value, preferably something random. You'll use this value as the RBAC bootstrap key.

  Note: This key is only used for creating the first RBAC administrator key and role. Once you create the first admin role and key, this environment variable will be invalidated and ignored.

If you're running in Azure and want to use the Azure Active Directory OAuth integration, also include:

• QUARRY_JWT_AUDIENCE - Set to the intended audience for JWT validation with the Azure AD OAuth provider above. This option is only used if QUARRY_RBAC=1.

Now that you've set the above variables within the environment, you can create your first role, key, and role mapping.

Step 2: Create the first role

Copy

Copied!

Follow the steps below to create the first admin role in the system. The admin role has all EraSearch permissions.

1. Write the following contents to an era_admin_role.json file:

   Copy

   Copied!

   {
     "name": "admin",
     "database": ["read", "write", "delete"],
     "indexes": [
       {
         "names": ["*"],
         "permissions": ["read", "write", "delete"]
       }
     ]
   }
   

2. Create the role definition in EraSearch with the command:

   Copy

   Copied!

   $ curl -H "Content-Type: application/json" -H "Authorization: Bearer ${QUARRY_BOOTSTRAP_KEY}" --data-binary @era_admin_role.json localhost:9200/v1/roles
   

   When successful, the response resembles the output below, where:

   • id is the internal ID of this role.
   • name is the role name.
   • database contains the permissions this role can perform on the EraSearch database directly.
   • indexes is the list of indexes this role can interact with, where:
     • names is the names or templates for any indexes. In this case, * denotes all indexes.
     • permissions contains the permissions this role can perform on the provided indexes.
   Copy

   Copied!

   {
     "id": 1,
     "name": "admin",
     "database": ["manage_security","monitor"],
     "indexes": [{ "names": ["*"], "permissions": ["read", "write", "delete"] }]
   }
   

3. To verify the role exists, enter this command to list all RBAC roles in EraSearch:

   Copy

   Copied!

   $ curl -H "Content-Type: application/json" -H "Authorization: Bearer ${QUARRY_BOOTSTRAP_KEY}" localhost:9200/v1/roles | jq .
   

Step 3: Create the first key

Copy

Copied!

Follow these steps to create a key:

1. Write the following to era_admin_key.json, where:

   • name is a name to use for this key -- you can set name to any string value, though we recommend being as descriptive as possible
   • role is the role name that this key is applied to
   Copy

   Copied!

   {
     "name": "initial key",
     "role": "admin"
   }
   

2. Generate a new key with this command:

   Copy

   Copied!

   $ curl -H "Content-Type: application/json" -H "Authorization: Bearer ${QUARRY_BOOTSTRAP_KEY}" --data-binary @era_admin_key.json  localhost:9200/v1/api_keys > key.json
   

   When successful, the command writes the following JSON contents to the key.json file, where: - id is the internal ID of this key - name is the user-assigned name for the key - api_key is the API key value itself, which you need for communicating with the RBAC endpoints from now on - role is the RBAC role that this key belongs to

   Copy

   Copied!

   {
     "id": 1,
     "name": "initial key",
     "api_key": "era_1zZgTqKhh9E3TgpwbD9NZK0PQyk9ZdPMlpHtE3VmygJf4Mbu9F",
     "role": "admin"
   }
   

Warning: Save the key.json file (or api_key value) somewhere safe. The key is now the only admin key available on the system until you create more.

Step 4: Discard the bootstrap key

Copy

Copied!

Now that you've created the first admin key and role, the ${QUARRY_BOOTSTRAP_KEY} variable is no longer valid. If you use it again, you'll get an HTTP 403 error, for example:

$ curl -I -H "Content-Type: application/json" -H "Authorization: Bearer ${QUARRY_BOOTSTRAP_KEY}" localhost:9200/v1/roles
HTTP/1.1 403 Forbidden

You can now discard the ${QUARRY_BOOTSTRAP_KEY} environment variable. For the rest of this guide, you'll use the api_key value from the key.json file you created above. If you have jq installed, you can set this in your shell environment with this command:

$ export ADMIN_API_KEY=$(cat key.json | jq .api_key | xargs)

Step 5: Create the first role mapping

Copy

Copied!

You can now create a role mapping for mapping roles from an external IdP (for example, Azure AD) to EraSearch roles. To create a role mapping:

1. Write the following to era_admin_role_map.json, where:

   • name is the name of the role as it will be referenced by the external IdP
   • roles is a list of role names to apply to this role mapping
   Copy

   Copied!

   {
     "name": "erasearch_admin",
     "roles": ["admin"]
   }
   

2. Create the role mapping with the command below, where:

   • ${ADMIN_API_KEY} is the admin key you generated in the previous step
   Copy

   Copied!

   $ curl -H "Content-Type: application/json" -H "Authorization: Bearer ${ADMIN_API_KEY}" --data-binary @era_admin_role_map.json  localhost:9200/v1/role_mappings
   

   When successful, the command outputs the following JSON, where:

   • id is the internal ID of this role mapping
   • name is the user-assigned name for the role mapping
   • roles is the list of roles in this role mapping
   Copy

   Copied!

   { "id": 1, "name": "erasearch_admin", "roles": ["admin"] }
   

With the role mapping created, you can now map role values provided by an external IdP to roles defined within EraSearch.

Next steps

Copy

Copied!

To extend your RBAC setup, visit Using RBAC with Grafana and Azure AD and Giving RBAC write permissions to tools.