Skip to content

Setting up RBAC

Estimated time to read: 5 minutes

Acquisition notice

In October 2022, ServiceNow acquired Era Software. The documentation on this site is no longer maintained and is intended for existing Era Software users only.

To get the latest information about ServiceNow's observability solutions, visit their website and documentation.

EraSearch's role-based access control (RBAC) lets 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.

Note

If you're using EraSearch on EraCloud, visit RBAC in EraCloud to see EraCloud's RBAC features and how to use them.

Before you begin

This guide assumes you're familiar with EraSearch's RBAC terms and concepts. It also assumes you've installed the following:

  • jq
  • [Optional] eractl CLI

    Install EraSearch's experimental eractl CLI to set up RBAC with fewer commands. The steps below also show how to set up RBAC with the existing EraSearch API.

Permission needs

To complete the steps below, you need administrative access to EraSearch's deployment environment. You also need permissions to do the following:

  • Set new environment variables in the EraSearch runtime.
  • Access EraSearch's API Service directly.

    For Kubernetes users, that means you need kubectl access to the EraSearch namespace and permission to forward ports locally.

Step 1: Enable RBAC

In the EraSearch API Service environment, enter the commands below to enable RBAC, replacing:

  • RANDOM_STRING with any string value. That value is the RBAC bootstrap key you'll use to create the first administrator key and role.
  • JWT_AUDIENCE with the intended audience for JWT validation.
$ export QUARRY_RBAC=1
$ export QUARRY_BOOTSTRAP_KEY="RANDOM_STRING"
$ export QUARRY_JWT_AUDIENCE="JWT_AUDIENCE"

Step 2: Create the first admin role and key

Follow these steps to create the first admin role and key. The admin role has all database- and index-level permissions in EraSearch. And you use the key to interact with EraSearch endpoints.

  1. Enter these commands to create the admin role and key, replacing https://erasearch.example.com with the IP or hostname for the EraSearch API endpoint:

    $ export ERACTL_URL="https://erasearch.example.com"
    $ export ERACTL_API_KEY="${QUARRY_BOOTSTRAP_KEY}" 
    $ eractl rbac create-admin
    

    eractl returns this output, including the key for the admin role (era_XXXXXXXXXXXXX) and the file storing the key (era-admin-key.<timestamp>.json).

    2022-06-28T20:55:34.132924Z [info     ] Successfully connected to Era  commit=XXX es_version=7.10.2 url=https://erasearch.example.com
    2022-06-28T20:55:34.132964Z [info     ] New role created: {"name": "admin", "database": ["manage_security", "monitor"], "indexes": [{"names": ["*"], "permissions": ["write", "read", "delete"]}]}
    2022-06-28T20:55:34.393994Z [info     ] Key backed up to local file: era-admin-key.2022-06-28T20:55:34.133298+00:00.json
    2022-06-28T20:55:34.394213Z [info     ] API key created: era_XXXXXXXXXXXXX
    2022-06-28T20:55:34.394269Z [info     ] **Be sure to put this in a safe place.**
    
  2. Save the key somewhere safe. That key is the only way to work with EraSearch until you create more roles and keys.

  3. Export the key for the admin role for future use:

    $ export ERACTL_API_KEY="era_XXXXXXXXXXXXX"
    

Follow these steps to create the first admin role and key:

  1. To define the admin role, write the content below to a file called era_admin_role.json.

    The file defines a role named admin with all database- and index-level permissions. The * indicates all indexes — users with the admin role can read, write, and delete all indexes.

    {
      "name": "admin",
      "database": ["manage_security","monitor"],
      "indexes": [
        {
          "names": ["*"],
          "permissions": ["read", "write", "delete"]
        }
      ]
    }
    
  2. Enter this command to create the admin role in EraSearch:

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

    EraSearch returns this output with details about the role:

    {
      "id": 1,
      "name": "admin",
      "database": ["manage_security","monitor"],
      "indexes": [{ "names": ["*"], "permissions": ["read", "write", "delete"] }]
    }
    
  3. To define the key for the admin role, write the following content to era_admin_key.json.

    The file names the key and specifies the role the key maps to. In this case, the role is the admin role.

    {
    "name": "initial key",
    "role": "admin"
    }
    
  4. Enter this command to generate the key:

    $ 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
    

    The command writes the content below to key.json. The api_key value is the key for the admin role.

    {
      "id": 1,
      "name": "initial key",
      "api_key": "era_XXXXXXXXXXXXX",
      "role": "admin"
    }
    
  5. Save the api_key value somewhere safe. That key is the only way to work with EraSearch until you create more roles and keys.

  6. Export the key for the admin role for future use:

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

Step 3: Discard the bootstrap key

The ${QUARRY_BOOTSTRAP_KEY} variable you created in step 1 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

Discard the ${QUARRY_BOOTSTRAP_KEY} environment variable with this command:

$ unset QUARRY_BOOTSTRAP_KEY

Step 4: Create the first role mapping

Role mapping lets you map one or more roles to another role. You can use that feature to map an external IdP role (for example, a role in Azure AD) to one or more EraSearch roles.

Enter the command below to map the EraSearch admin role to a role called erasearch_admin:

$ eractl rbac create-role-mapping erasearch_admin admin

eractl returns information about the role mapping:

2022-09-27T14:32:06.946734Z [info     ] Successfully connected to Era  commit=XXXX es_version=7.10.2 url=https://api.erasearch.example.com
2022-09-27T14:32:07.193074Z [info     ] New role mapping 'erasearch_admin' created: {"id": 1, "name": "erasearch_admin", "roles": ["admin"], "created_at": "2022-09-27T14:32:07.199422115Z"}

You can now map external IdP role values to roles defined in EraSearch.

Follow these steps to map the EraSearch admin role to a role called erasearch_admin:

  1. To define the role mapping, write the content below to era_admin_role_map.json, where:

    • name is the name of the role used by the external IdP.
    • roles is a list of the relevant EraSearch role names.
    {
      "name": "erasearch_admin",
      "roles": ["admin"]
    }
    
  2. Create the role mapping with this command:

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

    The command returns the following:

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

You can now map external IdP role values to roles defined in EraSearch.

You're all set. You've enabled RBAC, created an admin role and key, and done your first role mapping.

Next steps

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


Last update: August 7, 2023