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.

graph LR; subgraph Repositories R1["Audit Log"] R2["Web Log"] end subgraph Groups G1["Devs DK
Jeffrey
Tom
"] --- |Admin| R2 G2["Support UK
Dianne
Tom"] --- |Admin| R1 G2 --- |Searcher| R2 end
Each Group is 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:

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

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)

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 mechanims 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.

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 behaviour is done by setting the config:

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 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
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
ChangeIngestTokens Allow creating and editing ingest tokens
ChangeConnections Allows changing connections for a view

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

properties
# Make Humio run with Simple RBAC:
PERMISSION_MODEL_MODE=simple
properties
# Make Humio run with Advanced RBAC:
PERMISSION_MODEL_MODE=advanced

Migrating to Groups and Roles from file-based RBAC

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

# Make Humio run with Advanced RBAC:
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)

# Make Humio run with Advanced RBAC:
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 up 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

{
  "roles": {
    "Admin": {
      "permissions": [
        "ChangeUserAccess",
        "ChangeDashboards",
        "ChangeFiles",
        "ChangeParsers",
        "ChangeSavedQueries",
        "ChangeDataDeletionPermissions",
        "ChangeDefaultSearchSettings",
        "ChangeS3ArchivingSettings",
        "ConnectView",
        "ReadAccess",
        "ChangeIngestTokens"
      ]
    },
    "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

{
  "roles": {
      "Admin": {
        "permissions": [
          "ChangeUserAccess",
          "ChangeDashboards",
          "ChangeFiles",
          "ChangeParsers",
          "ChangeSavedQueries",
          "ChangeDataDeletionPermissions",
          "ChangeDefaultSearchSettings",
          "ChangeS3ArchivingSettings",
          "ConnectView",
          "ReadAccess",
          "ChangeIngestTokens"
        ]
      },
      "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.