Emergency Access

If there are issues with the identity provider that Humio is configured to use, then you might not be able to log in to Humio. To mitigate this, Humio provides emergency users that can be created locally within the Humio cluster.

To enable emergency users, the environment variable EMERGENCY_USERS must be set to true. This enables the emergency API endpoint found at /api/v1/emergency. This API can be used by any user with root access on the Humio instance to create and manage emergency users.

Emergency users expire automatically after a configurable timeout.

Once an emergency user is created, the emergency user can be used to log in to Humio. To access local login, add the locallogin=true query parameter to your humio url. Eg. humio.example.com?locallogin=true.

API

The following examples assume the emergency API is accessed from the same machine running Humio and therefore uses the local admin token. An API token of a root user can also be used.

  • POST to /api/v1/emergency creates a new emergency user. The payload is a JSON object with the following fields:

    • isRoot: Whether the created user should be root. Must be true or false. Defaults to false.
    • groups: An array of the groups the user should be members of. These groups must exist when the user is created. Optional.
    • expireIn: A string containing the amount of time before the emergency user expires. The unit may be either m, h, or d for either minute, hour, or day, respectively. (For Humio up to 1.14.0 expireIn must be less than or equal to 48 hours. This limit does not apply to 1.14.1+)

    The response then returns a generated username and password of the emergency user as a JSON object.

    Example:

    curl localhost:8080/api/v1/emergency \
        -X POST \
        -H "Authorization: Bearer $(cat /data/humio-data/local-admin-token.txt)" \
        -H "Content-Type: application/json" \
        -d '{"isRoot":false, "groups":["foo","bar"], "expireIn": "48h"}'
    

    Outputs:

    {"password":"kM3mA2FW6f5CoLOL5OtpzvWs","username":"emergency-GVyrVm0oyhNqPL6XXbdvIQAq"}
    
  • GET to /api/v1/emergency lists all emergency users.

    Example:

    curl localhost:8080/api/v1/emergency \
        -X GET \
        -H "Authorization: Bearer $(cat /data/humio-data/local-admin-token.txt)"
    

    Outputs:

    {"users":[{"expires": "2020-05-08T13:22:49.269Z", "groups":["foo", "bar"], "isRoot":false,
      "username":"emergency-GVyrVm0oyhNqPL6XXbdvIQAq"}]}
    
  • DELETE to /api/v1/emergency/$USERNAME removes an emergency user.

    Example:

    curl localhost:8080/api/v1/emergency/emergency-GVyrVm0oyhNqPL6XXbdvIQAq \
        -X DELETE \
        -H "Authorization: Bearer $(cat /data/humio-data/local-admin-token.txt)"
    

Basic Authentication

An emergency user can authenticate using basic auth instead of bearer tokens. This allows adding the emergency credentials to a proxy in front of Humio.

  USERNAME=emergency-GVyrVm0oyhNqPL6XXbdvIQAq
  PASSWORD=kM3mA2FW6f5CoLOL5OtpzvWs
  curl localhost:8080/api/v1/repositories \
      -H "Authorization: basic $(printf "$USERNAME:$PASSWORD" | base64 -w0)"