Root Token Authentication

How to protect your Controller UI, API, and Registry API with a Root Token.

Enabling root token authentication is a simple process. The root user has full permissions to the Controller UI and APIs for both the Controller and Registry. It is however not used for Node communication.

Important
  • Enabling the Root Token is required in all of our Auth features to function.
  • The root token must be at least 10 characters long.
  • The root token set for both the Registry and Controller must match.
  • Keep this token safe. We don’t recommend trying to use the root token for API calls in scripts due to security risk.
  • Enabling RTA will block any access for Anka Nodes joined to the primary interface/port for the controller. You will need to set up one of the other Authentication methods supported by the ankacluster join command. You can expose a queue only interface instead which can be used to join your nodes ONLY if you cannot use credentials.

How to configure RTA

Linux/Docker Package

With our docker package, each service is split up into its own container. You can enable a root token for either the controller, registry, or both.

Edit the docker-compose.yml and add both ANKA_ENABLE_AUTH and ANKA_ROOT_TOKEN environment variables:

. . .

anka-controller:
   build:
      context: .
      dockerfile: anka-controller.docker
   ports:
      - "80:80"
   volumes:
     # Path to ssl certificates directory
     - /home/ubuntu:/mnt/cert
   depends_on:
      - etcd
   restart: always
   environment:
     ANKA_ENABLE_AUTH: "true"
     ANKA_ROOT_TOKEN: "1111111111"
     # ANKA_ENABLE_API_KEYS="true"

anka-registry:
   build:
      context: .
      dockerfile: anka-registry.docker
   ports:
      - "8089:8089"
   . . .
   environment:
     ANKA_ENABLE_AUTH: "true"
     ANKA_ROOT_TOKEN: "1111111111"
     # ANKA_ENABLE_API_KEYS="true"
. . .

Testing RTA

If everything is configured correctly, you can visit your Controller Dashboard and a login box should appear.

root token login

Enter the token you specified and ensure that it logs you in.

Finally, you can test the API using:

❯ curl -H "Authorization: Basic $(echo -ne "root:1111111111" | base64)" http://anka.registry:8089/registry/status
{"status":"OK","body":{"status":"Running","version":"1.19.0-309d8150"},"message":""}