Authorization

This page covers Humio’s authorization model from version 1.9.0 onwards. For information about the RBAC model in prior versions, please see Role Based Authorization.

Humio’s role-based access control (RBAC) model enables authorization of users based on roles with different sets of permissions. We distinguish between authentication, which establishes the identity of the user, and authorization which decides which actions an authenticated user may perform.

Concepts

The model is centered around two important concepts: Groups and Roles. Groups contain users, while Roles contain permissions. Groups are assigned Roles in the context of a repository, giving all members of the Group in question the permissions contained in the Role. A user action on a repository is allowed, or authorized, if the user is a member of a Group that has a Role containing the needed permission.

Figure 1, Each Group Assigned a Role in a Specific Repository

If a user is member of more than one Group that has been assigned a Role in a specific repository, the user has the combined permissions from the Roles involved. So in the above diagram, Tom is both a member of Support UK and Devs DK which makes him an Admin and a Searcher in the Web Log repository.

Except for root access, all authorization in Humio is based on Group memberships. Root access is a per-user property and independent of Roles and Groups. See root access.

Group Memberships

A user may be a member of zero or more groups. Users not members of any groups can log in but can not access anything but the personal sandbox and the system repos that provide access to data on their own actions and metrics.

The group memberships usually stem from an external directory, such as your LDAP tree or an IDP (Identity Provider). It is also possible to edit the group memberships through the UI to support cases where the login mechanism only supplies the identity of the user and not the group memberships.

In order for the login mechanism to capture and sync the users groups from the authentication mechanism, set the following configuration:

ini
AUTO_UPDATE_GROUP_MEMBERSHIPS_ON_SUCCESSFUL_LOGIN=true

In order for Humio’s SAML login module to pick up the group from the SAMLResponse coming from the SAML SSO server, Humio needs to know the name of the attribute containing the roles. If this attribute is named group, you would configure it like this:

ini
SAML_GROUP_MEMBERSHIP_ATTRIBUTE=group

For LDAP, Humio needs to know the query to perform to get the user’s groups, which is defined using the following config properties (for the case of Microsoft Active Directory) [comment]: <> (what about other cases?):

ini
LDAP_GROUP_BASE_DN="OU=User administration,DC=humio,DC=com"
LDAP_GROUP_FILTER="(& (objectClass=group) (member:1.2.840.113556.1.4.1941:={0}))"

For information on syncing groups from other authentication mechanisms see their specific integration sections in our docs.

Once set up, a user can see their associated groups in the Account Settings pane.

It is also useful to set the following, which creates the user inside Humio once a successful login is established. That way, operators do not have to add individual users.

ini
AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN=true

With the auto-create user option, the user is only allowed to log in if that would result in the user having access to some data. That is, the access rights for at least one of the groups that the user has must already be set up.

From version 1.15 this is no longer the default. Users will by default have access to sandboxes and certain system repos. Switching back to the old behavior is done by setting the config:

ini
ONLY_CREATE_USER_IF_SYNCED_GROUPS_HAVE_ACCESS=true

Simple or Advanced Mode

Two permission configurations are available, simple or advanced. Simple mode provides three predefined roles—Admin, Member, and Eliminator—that closely resemble the permissions setup of earlier versions of Humio.

In simple mode, Admins of a given repository are allowed to add users to the repository in question. In advanced mode, the full flexibility of the model is in play, allowing root to create new roles and groups from Humio’s administration page or through a permissions file. In advanced mode only root access is currently allowed to give users access to repositories through group memberships.

If changing configuration from Advanced to Simple mode, you will need to delete all roles and groups (if roles or groups were modified in advanced mode). To delete all roles and groups, use the GraphQL mutation deleteAllRolesAndGroups with the argument documentationRead set to: I understand this deletes all groups and roles. This is to emphasize the consequences; all roles and groups will be deleted including user membership. After calling deleteAllRolesAndGroups users need to be added to repositories and views again.

Defining New Roles

In contrast to Group memberships, which can have an external source of truth, Roles and how they are assigned to Groups are always defined in the context of Humio. In order to create a new Role a user must have root access.

Role Permissions

Permission

Description

ChangeUserAccess (Only applicable in Simple mode)

Allow editing users of this view/repo and assign them permissions

ChangeAlertsAndNotifiers

Allow creating and updating alerts, scheduled searches and actions

ChangeDashboards

Allow creating and updating dashboards

ChangeFiles

Allow creating and updating uploaded CSV files

ChangeParsers

Allow creating and updating parsers

ChangeSavedQueries

Allow creating and updating saved queries

DeleteEvents

The ability to be able to delete events

ChangeRetention

Allow editing retention on a repository

DeleteDataSources

Allow deleting datasources

DeleteRepositoryOrView

Allow deletion of repositories and views

ChangeDataDeletionPermissions (Only applicable in Simple mode)

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

ChangeDefaultSearchSettings

Allow editing the default search query and time interval.

ChangeS3ArchivingSettings

Allow editing the configuration for S3 archiving.

ConnectView (Only applicable in Simple mode)

Allow creation of views that involve connecting to this repository.

ReadAccess

Gives access to dashboards, search, and saved queries,, as well as exporting these in packages or standalone templates.

ChangeIngestTokens

Allow creating and editing ingest tokens.

ChangeConnections

Allows changing connections for a view.

ChangePackages

Allows installing, updating, and uninstalling packages.

Assigning Roles to Groups

For a Group to have access to Humio it must be assigned a Role for a specific repository or view. This is either done through the UI or defined by a permissions file.

Configuration

You can configure the permission model mode to run in simple or advanced mode:

ini
PERMISSION_MODEL_MODE=advanced

Migrating to Groups & Roles

If Humio previously used a RBAC configuration file, this can be converted to the new RBAC model like this:

ini
PERMISSION_MODEL_MODE=advanced
READ_GROUP_PERMISSIONS_FROM_FILE=true

When starting Humio with this configuration, Groups and Roles will be converted and visible under Administration, but in read only mode, since it’s read from the RBAC configuration file.

To make the Groups and Roles configurable in the UI, make this config change (please notice it’s important to include the previous step first, otherwise the Groups and Roles will not be converted):

ini
PERMISSION_MODEL_MODE=advanced
READ_GROUP_PERMISSIONS_FROM_FILE=false

Now, when starting Humio, the Groups and Roles are now configurable and the RBAC file is no longer used.

Setting Roles from 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.