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
CLIInstall 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.
-
Enter these commands to create the
admin
role and key, replacinghttps://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 theadmin
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.**
-
Save the key somewhere safe. That key is the only way to work with EraSearch until you create more roles and keys.
-
Export the key for the
admin
role for future use:
Follow these steps to create the first admin
role and key:
-
To define the
admin
role, write the content below to a file calledera_admin_role.json
.The file defines a role named
admin
with all database- and index-level permissions. The*
indicates all indexes — users with theadmin
role canread
,write
, anddelete
all indexes. -
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:
-
To define the key for the
admin
role, write the following content toera_admin_key.json
.The file names the key and specifies the role the key maps to. In this case, the
role
is theadmin
role. -
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
. Theapi_key
value is the key for theadmin
role. -
Save the
api_key
value somewhere safe. That key is the only way to work with EraSearch until you create more roles and keys. -
Export the key for the
admin
role for future use:
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:
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
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
:
-
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.
-
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:
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.