User Permissions

Figure 1, Roles

In Humio, a user is allowed to do specific actions if one or more needed permissions are assigned them. Permissions can be assigned either directly to the user or via a group of which they are a member. Permissions are always assigned in sets called, Roles. If you’re the one setting up Humio—either because you’ve created a new organization on Humio Cloud and you’re the owner, or you’re a root user of an on-premise installation—you will by default have the needed permissions to assign roles to users.

The Roles page can be found if you click your profile avatar in the upper right corner and then select Organization Settings.

For each role, the permissions granted via the role is displayed in the User Interface. While Humio comes with a predefined set of roles (i.e., Admin, Member and Eliminator), they may be customized to your specific needs. Keep in mind that it’s generally a good idea to grant as few permissions as possible and to add more as needed.

Creating a User

Figure 2, Users

If you want to give a user access to a repository, but not through a group membership, you will need to make sure that the user exists in the system. Assuming you’re using the Humio Cloud, click on your profile avatar in the upper right corner and select Organization Settings and then Users on the left:

Click on the + Add User button and then provide an email address of the user to add. This will start an invite process for the user. After the user first logs in successfully, they’ll be visible in the Users list.

If you’re not on Cloud, adding a user here will create the user immediately and without an email invitation.

Another typical configuration for on-premise installs of Humio is to set the configuration option AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN to true. This will automatically create the user in Humio after a successful login.

Assigning Permissions

Figure 3, Select Users and Groups

Before assigning permissions to a user you need to decide a repository or view that the user need access to. If you just need to give a specific user access to a repository or view go to the front page of Humio and click on it.

Navigate to Settings/Permissions:

Click the + Add button to see a list of available users or groups:

Select one or more that need access to your repository. You can search if the ones you are looking for are not immediately visible in the list.

Next up you need to select a role for each. The predefined Member Role is a good choice for regular users that need to search, setup dashboards and configure alerts. While leaving the responsibility of configuring ingest, user access, integrations and data retention to others.

Figure 4, Select Roles

After selecting a Role for each you click Finish and you are done. You’re freshly added users are now visible in the list with the selected Role and the permissions for the Role:

Besides organization owners and root users any user with the Change user access permission in a repository or view can add new users to it. The Admin role from the set of predefined roles have this permission:

Figure 5, Change User Access

Groups

Figure 6, Users in a Group

Assigning permissions to individual users in larger organizations can be a cumbersome task. Humio allows you to create groups and either manage user memberships directly in Humio or by synchronizing with an external system. Either way you need to create groups in Humio first. You need to be an organization owner on Cloud or a root user on-premise. Configure groups by clicking your profile in the upper right corner and select Organizations Settings and lastly Groups on the left:

Create a new group by clicking +Add. Enter a name e.g. SysAdmins and click Add.

You now have an empty group with no users and no permissions assigned.

You can assign users to the Group by going to the Users tab for a specific Group. Click the + Add button and select a user from the dropdown. Afterwards your user will be in the Users list:

Group Synchronization

Alternatively you can rely on a one-way synchronizing of group memberships upon user login. In order to map a group name from an external system such as LDAP to a Humio group you can specify a Mapping name:

Figure 7, Group Mapping

When a user who is a member of the above LDAP group logs in to Humio he will be a member of the Humio group that defines the mapping. In the current version of Humio a user will remain a member of the Humio groups from the last login until he logs in again with a new set of groups.

For specific instructions on how to setup group synchronization for the different authentication mechanisms go to the Security overview page and select a relevant entry.

Assigning Permissions to Groups

Assuming your new Humio Group has members it’s time to assign permissions. As with users its possible to assign permissions directly on the Permissions page of a repository or view:

Figure 8, Add Group to Repository or View

As discussed earlier this is possibly for any user who is assigned the Change user access permission. Groups can also be assigned permissions from the Groups page by an organization owner or root.

Figure 9, Add Group to Repository or View from Groups Settings

As before it involves selecting a repository and a role.

Note that if you intend on administering access to repositories and views centrally by an organization owner or root only be sure not to give out the Change user access permission to anyone. In practice this means removing the permission from all Roles thus not allowing any users to go to a repository or view and add another user or group directly.

If you aren’t keen on administering groups and roles as new repositories are created you have the chance of defining Default permissions for a group here as well. Enabling default permissions will assign the permissions selected to all repositories and views except for Humio system repositories if you are using our Cloud. Also new ones that happen to be created after the fact.

Figure 10, Default Group Permissions

Exceptions to the rule can be specified as well if you have a few repositories that need to be treated differently. Click the + Add an exception button and select a repository and role. For this specific repository the selected Role will be applied and not the default one.

Figure 11, Exceptions

For groups it’s also possible to define a query prefix which is effectively a search filter applied to any search:

Figure 12, Query Prefix

As illustrated by the red line in the above the query prefix for the group is host=web*. This is a Humio query that acts as a filter when any member of the group searches the repository developer. In effect a user of the group is only allowed to see log lines that has a host field that starts with web. E.g. web-server01, web-server02 and so on. This allows partitioning of data at search time. It’s also possible to define a default query prefix if a default role has been selected. Meaning the default query prefix will be applied to all searches in all repositories unless an exception is defined.

Roles

Customizing roles is done via the Roles settings page as mentioned in above.

Clicking + Add will prompt for a name for your new Role:

Figure 13, Add Role

In this case our intention is to create a strictly read-only Role. So we click Data Access and nothing else and hit Save.

Figure 14, Select Permissions for Role

The new Role can now be assigned to users or groups. Note that if a user is assigned more than one Role in a repository or view by way of being a member of more than one group or by being a member of one group and having a role assigned directly, the permissions assigned is the combination of all roles involved.

Role Permissions

The permissions available for a Role can be seen here. Note the shorthand is used if you choose to setup a permissions file which is described in the next section.

Search Permissions

Description

Shorthand

Change connections for a view

Allows changing connections for a view.

ChangeConnections

Change dashboards

Allow creating and updating dashboards.

ChangeDashboards

Change default search settings

Allow editing the default search query and time interval.

ChangeDefaultSearchSettings

Change files

Allow creating and updating uploaded CSV files.

ChangeFiles

Change saved queries

Allow creating and updating saved queries.

ChangeSavedQueries

Change view or repository description

Allow changing description.

ChangeViewOrRepositoryDescription

Connect a view

Allow creation of views that involve connecting to this repository.

ConnectView

Triggers and Actions

Description

Shorthand

Change triggers and actions

Allow configuration of alerts.

ChangeAlertsAndNotifiers

Data

Description

Shorthand

Change data retention

Allow changing retention on a repository.

ChangeRetention

Delete data sources

Allow deleting individual data sources in a repository.

DeleteDataSources

Delete events

The ability to be able to delete events.

DeleteEvents

Delete repository or view

Allow deletion of repositories and views.

DeleteRepositoryOrView

Ingest

Description

Shorthand

Change Ingest tokens

Allow creating and editing ingest tokens.

ChangeIngestTokens

Change parsers

Allow creating and updating parsers.

ChangeParsers

Integrations

Description

Shorthand

Change S3 archiving settings

Allow editing the configuration for S3 archiving.

ChangeS3ArchivingSettings

Change event forwarding

Allow setting up event forwarding.

EventForwarding

Change packages

Allow installing packages etc.

ChangePackages

Users

Description

Shorthand

Change data deletion permissions

Special permission needed to be able to assign the permissions (DeleteEvents, DeleteDataSources, DeleteRepositoryOrView and ChangeRetention).

ChangeDataDeletionPermissions

Change user access

Allow adding or removing existing users or groups to this view/repo.

ChangeUserAccess

Setting up Roles in a File

It’s possible to define Roles and how they are assigned to individual Groups in the context of a repository or view through a permissions file. The file must be named role-permissions.json and located in humio-data/. The file is re-read every 30 seconds. We recommend putting it on only one of the servers.

The following JSON is an example permissions file

javascript
{
  "roles": {
    "Admin": {
      "permissions": [
        "ChangeUserAccess",
        "ChangeDashboards",
        "ChangeFiles",
        "ChangeParsers",
        "ChangeSavedQueries",
        "ChangeDataDeletionPermissions",
        "ChangeDefaultSearchSettings",
        "ChangeS3ArchivingSettings",
        "ConnectView",
        "ReadAccess",
        "ChangeIngestTokens",
        "EventForwarding"
      ]
    },
    "Searcher": {
      "permissions": [
        "ChangeAlertsAndNotifiers",
        "ChangeFiles",
        "ChangeDashboards",
        "ChangeSavedQueries",
        "ReadAccess"
      ]
    }
  },
  "views": {
    "Audit Log": {
      "Devs DK": {
        "role": "Searcher",
        "queryPrefix": "secret=false"
      },
      "Support UK": {
        "role": "Admin",
        "queryPrefix": "*"
      }
    },
    "Web Log": {
      "Devs DK": {
        "role": "Admin",
        "queryPrefix": "*"
      },
      "Support UK": {
        "role": "Searcher",
        "queryPrefix": "*"
      }
    }
  }
}

In it we have defined two Roles: Admin and Searcher. The views section defines which groups, in our case Devs DK and Support UK, have access to which repositories with the permissions dictated by the Role assigned. In the example above Support UK has access to Web Log as a Searcher and Audit Log as an Admin.

It’s possible to define defaults for a Group

javascript
{
  "roles": {
      "Admin": {
        "permissions": [
          "ChangeUserAccess",
          "ChangeDashboards",
          "ChangeFiles",
          "ChangeParsers",
          "ChangeSavedQueries",
          "ChangeDataDeletionPermissions",
          "ChangeDefaultSearchSettings",
          "ChangeS3ArchivingSettings",
          "ConnectView",
          "ReadAccess",
          "ChangeIngestTokens",
         "EventForwarding"
        ]
      },
      "Searcher": {
        "permissions": [
          "ChangeAlertsAndNotifiers",
          "ChangeFiles",
          "ChangeDashboards",
          "ChangeSavedQueries",
          "ReadAccess"
        ]
      }
    },
  "defaults": {
    "Support UK": {
      "role": "Searcher",
      "queryPrefix": "*"
    }
  },
  "views": {
    "Audit Log": {
      "Devs DK": {
        "role": "Searcher",
        "queryPrefix": "secret=false"
      },
      "Support UK": {
        "role": "Admin",
        "queryPrefix": "*"
      }
    },
    "Web Log": {
      "Devs DK": {
        "role": "Admin",
        "queryPrefix": "*"
      }
    }
  }
}

A default section dictates the role and queryPrefix for a group, when a view is not specifically mentioned in the views section.

Coming from an earlier version

If you come from an earlier version of Humio you might experience having groups that are named e.g. myRepository.admins, myRepository.eliminators or myRepository.members. You can use the groups as is or instead add users directly to the repository in question.