Skip to content

Using RBAC with Grafana and Azure AD

Estimated time to read: 7 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.

With EraSearch RBAC, you can map EraSearch roles to roles in external identity providers. This feature lets you integrate EraSearch into your existing authentication setup.

This guide shows how to manage EraSearch access in Grafana via Azure Active Directory (Azure AD). In the guide, you'll:

  • Create an application role (app role) and assign users to it in your Azure AD Grafana application.
  • Create an EraSearch role for reading specific indexes.
  • Map the roles together, letting only some users read EraSearch data in Grafana.

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

This document is for self-hosted EraSearch users only. If you're using EraSearch on EraCloud, visit RBAC in EraCloud to see what EraCloud offers now and how to use it.

Before you begin

This guide assumes you've installed and are using Azure AD, Grafana, and self-hosted EraSearch. Before you start:

Permission needs

You need these permissions to complete the steps below:

  • In EraSearch, you need the manage_security permission.
  • In Azure AD, you need permission to add app roles to the Grafana application.

Step 1: Add scopes to your Azure AD Grafana application

Follow these steps to let Azure AD include app roles in the JSON web tokens it sends to EraSearch:

  1. In the Azure Portal, click the hamburger menu > Azure Active Directory.
  2. Click App registrations and then your existing Grafana application.
  3. To add a scope, click Expose an API > Add a scope.
  4. In the Add a scope modal:
    • Set Scope name to EraRoleAccess. You'll use this name when configuring Grafana below.
    • Set Who can consent? to Admins and users.
    • Set Admin consent display name and User consent display name to Allow EraSearch to access app roles. You can customize those fields.
    • Set Admin consent description and User consent description to Allow EraSearch to access app roles in the access token. You can customize those fields.
    • Under State, click Enabled.
    • Click Add scope to save your changes and go back to the Expose an API page.
  5. Click Add a client application.
  6. In the Add a client application modal:
    • Set Client ID to your Azure AD Grafana application's client ID. You can find the client ID on the application's overview page.
    • Under Authorized scopes, check the box for the scope you created above.
    • Click Add application to save your changes and go back to the Expose an API page.

Note

To prevent refresh token errors, Era Software recommends adding the offline_access scope to your Azure AD Grafana application.

To complete the setup, update your Grafana configuration (grafana.ini) with the new scope created above:

[auth.azuread]
name = Azure AD
[...]
client_id = <CLIENT_ID>
client_secret = <CLIENT_SECRET>
scopes = openid email profile offline_access <CLIENT_ID>/EraRoleAccess
auth_url = https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/authorize
token_url = https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token

Step 2: Create an app role in your Azure AD Grafana application

Follow these steps to create an app role in your Azure AD Grafana application:

  1. In the Azure Portal, click the hamburger menu > Azure Active Directory.
  2. Click App registrations and then your existing Grafana application.
  3. To set up a new role, click App roles > + Create app role.
  4. Fill out the form:
    • For Display name, enter a name for the app role. Example: EraSearch - Read Logstash logs.
    • For Allowed member types, check Users/Groups.
    • For Value, enter the value you'll use to map this app role to the EraSearch role. Example: erasearch_read_logstash.
    • For Description, describe the role. Example: Read Logstash logs.
    • Check Do you want to enable this app role?
  5. Click Apply to create the app role and return to the App roles page.

Step 3: Add users to the app role

Add users to your app role by following steps 1-11 in Azure's Assign users and groups to roles.

Step 4: Enable forward OAuth identity in Grafana

Follow these steps to enable forward OAuth identity in your EraSearch data sources:

  1. In Grafana, click Configuration > Data sources.
  2. Click any relevant EraSearch data source.
  3. Under Auth, activate the Forward OAuth Identity option.
  4. Click Save & Test to save your changes.

Step 5: Create a read-only role in EraSearch

Follow the steps below to create an EraSearch role for reading indexes starting with logstash-. While the example references Logstash, you can customize the values for your own setup.

  1. In your terminal, export these environment variables, replacing:

    • YOUR_KEY with the key you generated in Setting up RBAC.
    • 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="YOUR_KEY"
    
  2. Create the read_logstash_logs role with this command:

    $ eractl rbac create-read -r read_logstash_logs -i "logstash-*" --no-key
    

    The command returns information about the new role:

    2022-09-27T14:39:43.116424Z [info     ] Successfully connected to Era  commit=XXXX es_version=7.10.2 url=https://api.erasearch.example.com
    2022-09-27T14:39:43.570141Z [info     ] New role created: {"name": "read_logstash_logs", "indexes": [{"names": ["logstash-*"], "permissions": ["read"]}]}
    

Follow the steps below to create an EraSearch role for reading indexes starting with logstash-. While the example references Logstash, you can customize the values for your own setup.

  1. In your terminal, export these environment variables, replacing YOUR_KEY with the key you generated in Setting up RBAC:
    $ export ADMIN_API_KEY="YOUR_KEY"
    $ export ERA_URL="localhost:9200"
    
  2. Define the EraSearch role by writing this content to logstash_readonly_role.json:
    {
      "name": "read_logstash_logs",
      "database": [],
      "indexes": [
        {
          "names": [
            "logstash-*"
          ],
          "permissions": [
            "read"
          ]
        }
      ]
    }
    
  3. Create the role by entering the command below. EraSearch responds with details about the role, including its id, name, and permissions.
    $ curl -H "Content-Type: application/json" -H "Authorization: Bearer ${ADMIN_API_KEY}" --data-binary @logstash_readonly_role.json ${ERA_URL}/v1/roles
    

Step 6: Map the app role to the EraSearch role

Enter this command to connect the Azure AD app role (erasearch_read_logstash) to the EraSearch role (read_logstash_logs):

$ eractl rbac create-role-mapping erasearch_read_logstash read_logstash_logs

eractl returns information about the role mapping:

2022-09-27T14:40:34.230310Z [info     ] Successfully connected to Era  commit=XXXX es_version=7.10.2 url=https://api.erasearch.example.com
2022-09-27T14:40:34.467174Z [info     ] New role mapping 'erasearch_read_logstash' created: {"id": 2, "name": "erasearch_read_logstash", "roles": ["read_logstash_logs"], "created_at": "2022-09-27T14:40:34.480707927Z"}

The Azure AD app role now maps to EraSearch's read-only role. When you assign users to the Azure AD app role, they get the permissions defined in the EraSearch role.

Connect the Azure AD app role (erasearch_read_logstash) to the EraSearch role (read_logstash_logs):

  1. Define the mapping by writing the content below to logstash_role_mapping.json. Note that name matches the app role value in Azure AD, and roles matches the EraSearch role name.

    {
      "name": "erasearch_read_logstash",
      "roles": [
        "read_logstash_logs"
      ]
    }
    

  2. Create the role mapping by entering the command below in your terminal. EraSearch responds with details about the role mapping, including its id, name, and roles.

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

The Azure AD app role now maps to EraSearch's read-only role. When you assign users to the Azure AD app role, they get the permissions defined in the EraSearch role.

Step 7: Verify your role mapping

To verify your setup:

  1. Log into Grafana as a user assigned to the erasearch_read_logstash app role.
  2. Query data from any index starting with logstash-.

You're all set!

Next steps

Visit User and role management and Giving RBAC write permissions to tools for more about EraSearch RBAC and the permissions you can work with.


Last update: August 7, 2023