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.

Note

For more information on the role-based model, see new permissions model.

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.

Authorization Concepts

Figure 173. Authorization Concepts


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.

Roles

Figure 174. 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

Creating a User

Figure 175. Creating a User


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

Assigning Permissions

Figure 176. Assigning Permissions


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.

Select Users and Groups

Figure 177. Select Users and Groups


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:

User Access

Figure 178. User Access


Groups

Groups

Figure 179. Groups


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:

Group Synchronization

Figure 180. Group Synchronization


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:

Assigning Permissions to Groups

Figure 181. Assigning Permissions to Groups


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.

Assigning Permissions to Groups

Figure 182. Assigning Permissions to Groups


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.

Assigning Permissions to Groups

Figure 183. Assigning Permissions to Groups


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.

Assigning Permissions to Groups

Figure 184. Assigning Permissions to Groups


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

Assigning Permissions to Groups

Figure 185. Assigning Permissions to Groups


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:

Roles

Figure 186. Roles


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

Roles

Figure 187. Roles


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.

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",
        "ChangeFdrFeeds"
      ]
    },
    "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",
          "ChangeFdrFeeds"
        ]
      },
      "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.

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 files
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 files
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).

ini files
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.

ini files
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:

ini files
ONLY_CREATE_USER_IF_SYNCED_GROUPS_HAVE_ACCESS=true