Configuring Token Authentication

  • Protect your Controller UI and API with a Root Token.
  • Create User API Keys and assign specific permissions to them for protecting the API.
This guide requires an Anka Enterprise or Enterprise Plus license.

Starting in 1.19.0 of the Anka Build Cloud, there are two options for securing the communication with the Build Cloud Controller & Registry:

  1. Setting the Root Token, protecting the Controller API and UI.

  2. Generating a user private key which is then used to request temporary session tokens by the client. These session tokens allow access to the API to perform various tasks.

However, there are several license specific differences that should be noted before you begin:

  • Enterprise: By default, any tokens you generate (root or user) always have full access to the API.
  • Enterprise Plus: By default, only the root token has full access to the API. User tokens must be created with a group attached and permissions added for the group.
We recommend disjoining all but one node. One node must stay joined to ensure the Build Cloud has the proper license attached. You can rejoin it later once you’re configured and you’ve rejoined all of your other nodes.

Protecting your cloud with RTA (Root Token Auth)

Enabling root token authentication is a simple process. The root user has what we call “superuser” (full) access to the controller, API (basic auth), etc.

How to configure RTA

MacOS Package

Edit /usr/local/bin/anka-controllerd and add:

export ANKA_ENABLE_AUTH="true"
export ANKA_ROOT_TOKEN="{min10chartoken}"
The macOS package has no way to set tokens or auth for either the controller or registry. It will be enabled for both if the ENV is set to true.
The root token must be at least 10 characters long.
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":""}

Protecting your cloud with UAK (User API Keys)

How to configure UAK

  1. Follow the same instruction from the above root token section, but also include ANKA_ENABLE_API_KEYS set to true.

  2. Use the API to generate a user key for the controller and also the registry.

  3. You can now use the key and ID to communicate with the Controller or Registry.

Joining Nodes with your UAK

❯ sudo ankacluster join http://anka.controller:8090 --groups "gitlab-test-group-env" --reserve-space 10GB --api-key-id "nathan" --api-key-string "$ANKA_API_KEY_STRING"
I0920 15:31:15.008778   77147 factory.go:75] Default http client using API Key authentication
Testing connection to the controller...: Ok
Testing connection to the registry...: Ok
Success!
I0920 15:31:37.300568   77147 factory.go:75] Default http client using API Key authentication
Anka Cloud Cluster join success
At the moment the ankacluster command does not support ENVs.
Instead of passing the private key base64 as a string (--api-key-string), you can specify the path to the key file with --api-key-file.

Controller and Registry communication with your UAK

Should the Registry be protected by authentication and User API Keys, the Controller requires its own key for registry API calls. Once generated, you need to specify the ANKA_API_KEY_ID and ANKA_API_KEY_STRING (or file) ENVs described in the Configuration Reference.


Token Authentication Protocol (TAP)

The following API is only useful if you’d like to build your own client to request and renew session tokens from UAKs.
  • Highly recommended to integrate with HTTPS
  • Base64 uses safe url encoding
  • Key length is 2048, Hashing algorithm SHA256, OAEP padding
  • Private key format is PEM PKCS#1
  • Public key format is PKIX, ASN.1 DER

This communication protocol is for user authentication using asymmetric encryption. The API is separate from the usual /api/v1/.

Authentication flow

  1. A public key is stored on the server along with some unique identifier.
  2. A client sends the first phase of the authentication: POST /tap/v1/hand -d '{"id": "<USER-ID>" }'
  3. The server generates a random string, encrypts it with the client’s public key, encodes it in base64 and passes it back to the client in the response body
  4. The client decodes and decrypts the response and sends the following the second phase of the authentication: POST /tap/v1/shake -d '{"id": "<USER-ID>", "secret": "<SECRET-STRING>" }'
  5. The server successfully authenticates the client and returns the following object (base64 encoded) in the response body: { "id": <USER-IDENTIFIER>, "data": <GENERIC-OBJECT> }
  6. The “data” field is a generic object, and can be customized for specific needs

Putting it all together

When an API Key is created, the public key and id are stored and later used in the TAP authentication protocol.

Upon a successful authentication with the TAP protocol, a session is created and the generic data object that is returned includes the following data:

{
  "userName": <USER-IDENTIFIER>
  "sessionId": <SESSION-ID>
  "token": <SESSION-TOKEN>
}

This object, encoded in JSON and base64 is what the user supplies in the HTTP Authorization header, with the Bearer prefix, for future requests.


Managing User/Group Permissions (Authorization)

Your --api-key-id is the username.
This feature requires Enterprise Plus

Permission groups are configurable from your Controller’s https://<controller address>/admin/ui page.

The permission groups here differ from the groups you assign to nodes within the Controller UI.

The Available Permissions list will display all of the permissions we can assign to the group (see below for the full list). These permissions will allow plugins/users (like Jenkins) to communicate with the Controller & Registry:

Controller

  • get_groups
  • get_registry_disk_info
  • list_images
  • list_nodes
  • list_vms
  • save_image
  • start_vm
  • terminate_vm
  • update_vm
  • view_logs

Controller Permissions

PermissionDescription
Instances
list_vmsgives the user permission to list vms
start_vmgives the user permission to start vm
terminate_vmgives the user permission to terminate vm
Registry
get_registry_filesgives the user permission to get registry files (logs)
view_logsgives the user permission to view log files in dashboard
get_registry_disk_infogives the user permission to get registry disk info
registry_listgives the user permission to list vms on registry
registry_deletegives the user permission to registry delete
Nodes
list_nodesgives the user permission to list nodes
delete_nodegives the user permission to delete node
change_node_configgives the user permission to change node configuration
Node Groups
create_groupgives the user permission to create node groups
get_groupsgives the user permission to view node groups
delete_groupgives the user permission to delete node groups
update_groupgives the user permission to update node groups
add_node_to_groupgives the user permission to add a node to a node group
remove_group_from_nodegives the user permission to remove a node from node group
Distribute VMs
registry_distributegives the user permission to distribute vms from registry
registry_distribute_statusgives the user permission to view distribution statuses
Config
change_configgives the user permission to change global configuration
get_configgives the user permission to view global configuration
Permissions and groups
view_permissionsgives the user permission to view the list of available permissions
view_prmission_groupsgives the user permission to view permission groups
update_permission_groupsgives the user permission to update permission groups
delete_permission_groupsgives the user permission to delete permission groups

Registry Permissions

PermissionDescription
Information about Registry
indexgives the user permission to view the registry index (welcome html file)
get_disk_infogives the user permission to get disk info
List VMs
list_vmsgives the user permission to list vms
Push VMs
head_push_vmgives the user permission to “negotiate” a push (understand which files exists on the server and which files need to be sent)
push_vmgives the user permission to push vm and create new vms or tags
Pull VMs
pull_vmgives the user permission to get a pull vm request (list of files needed for download and their paths)
download_vmgives the user permission to download vm files (as given by pull_vm)
Delete VMs
delete_vmgives the user permission to delete a vm
revertgives the user permission to revert vm versions
File Server
upload_filegives the user permission to upload a file
download_filegives the user permission to download a file
Log Server
get_streamergives the user permission to get an html streamer page (for logs)
stream_loggives the user permission to stream a log file (as given by get_streamer)
get_log_archivegives the user permission to download a log archive (tar.gz)
send_log_eventgives the user permission to send log events (only applies specifically to eventLog)
send_loggives the user permission to send a log file row
Permissions and groups
view_permissionsgives the user permission to view the list of available permissions
view_prmission_groupsgives the user permission to view permission groups
update_permission_groupsgives the user permission to update permission groups
delete_permission_groupsgives the user permission to delete permission groups