Enabling Emergency Access

If there are issues with the identity provider that LogScale is configured to use, then you might not be able to log in to LogScale. To mitigate this, LogScale provides emergency users that can be created locally within the LogScale 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 LogScale 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 LogScale. To access local login, add the locallogin=true query parameter to your LogScale url. For example, humio.example.com?locallogin=true.

Emergency Access API

The following examples assume the emergency API is accessed from the same machine running LogScale 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 LogScale 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. Below is an example:

shell
$ 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"}'

This returns the following:

json
{
  "password": "kM3mA2FW6f5CoLOL5OtpzvWs",
  "username": "emergency-GVyrVm0oyhNqPL6XXbdvIQAq"
}

GET to /api/v1/emergency lists all emergency users. Below is an example:

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

It returns the following:

json
{
  "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. Here's an example:

shell
$ 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 LogScale.

shell
$ USERNAME=emergency-GVyrVm0oyhNqPL6XXbdvIQAq
$ PASSWORD=kM3mA2FW6f5CoLOL5OtpzvWs

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