UAK / TAP Authentication

How to protect your Controller UI, API, and Registry API with a Root Token and/or User API keys.
Important
  • This feature requires either Enterprise or Enterprise Plus. There are several license specific differences that should be noted before you begin:
    • Enterprise: By default, any secrets you generate and use (root or user) always have full access to the API.
    • Enterprise Plus: By default, only the root token (RTA) has full access to the API. User tokens must be created with a group attached and permissions added for the group.
  • Your Nodes will lose connection until you join them using the new credential.

Starting in 1.19.0 of the Anka Build Cloud, you can generate a UAK which is then used to request a temporary auth session and token for a client. These session tokens allow access to the API to perform various tasks.

How to configure

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

  2. Use the Controller’s User API Keys UI panel or API to generate a user key for the controller and also the registry. KEEP THESE SECRET.

management ui for uak

  1. You can now use the key and ID to communicate with the Controller and/or Registry through the ankacluster join command, anka registry (only Anka version 3.1 or higher), or in your client (through a TAP session/token) to the APIs.
Each UAK can have one or more TAP generated sessions. This means you can generate a single UAK for a single piece of software which is deployed multiple times, and each software instance will get its own TAP generated session, independent from the others, but using the same key. An example of this is having a single UAK for all of your Anka Nodes to use when joining.

Joining Nodes

Once you have the UAK key generated from Step 2 (above), you can use it to join the Anka Node.

❯ 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 as a string (--api-key-string), you can specify the path to the key file with --api-key-file.

Controller and Registry Communication

There are several important points to know about Controller -> Registry communication when using UAKs.

  • The Controller UI will use the same credentials that you use when logged into the UI to make Registry calls for Templates, Logs, and status.
  • However, starting VM instances does not use your UI session. You need to give a credential to the Controller to use.

Token Authentication Protocol (TAP)

This communication protocol is for user authentication using asymmetric encryption. You’ll use this if you plan on making calls using an Authorization: bearer header to the API. The API is separate from the usual /api/v1/.

  • OpenSSL >= 3.x is required (macOS defaults to 2.x). The example below will install openssl 3 with brew and set it in the PATH ENV.
  • We highly recommended enabling 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.

How it works

  1. You’ve generated a UAK and it’s stored on the Controller and/or Registry with some unique identifier.
  2. Your client sends the first phase of the authentication: POST /tap/v1/hand -d '{"id": "<API-KEY-USER-ID>" }' (doesn’t need auth to communicate with).
  3. The server generates a random string, encrypts it with the client’s public key that is has stored, encodes it in base64, and passes it back to the requesting client in the response body.
  4. Your client then decodes and decrypts the response using the UAK private key it has available locally, and then sends the second phase of the authentication with the decoded string as SECRET-STRING: POST /tap/v1/shake -d '{"id": "<API-KEY-USER-ID>", "secret": "<SECRET-STRING>" }'
By default, the secret is valid for 3 minutes. Also, you can only call /tap/v1/shake once for a secret after which it will become invalid.

  1. The server then successfully authenticates the client and returns the following object (base64 encoded) in the response body: { "id": <API-KEY-USER-ID>, "data": <GENERIC-OBJECT> }

  2. You then take the contents of data in the response, base64 it, and use it in your Authorization: Bearer header for API calls.

The data object should look like

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

An example of the entire flow using BASH and CURL:

❯ brew install openssl
❯ export PATH="/usr/local/opt/openssl@3/bin:$PATH"

❯ ls nathan-*pem
nathan-key.pem nathan-pub.pem

❯ echo -n $(curl -s http://anka.controller:8090/tap/v1/hand -d '{"id": "nathan"}') | base64 -d > to_decrypt

# You have 10 seconds after obtaining the /hand token to shake. Otherwise, you will see an error thrown due to expiration.

❯ openssl pkeyutl -decrypt -inkey nathan-key.pem -in to_decrypt -out decrypted -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256

❯ cat decrypted
59A8Zb8XxtsBNpJ-1KYFKOzQfv8

❯ curl -s http://anka.controller:8090/tap/v1/shake -d "{\"id\": \"nathan\", \"secret\": \"$(cat decrypted)\" }"
{"id":"nathan","data":{"userName":"nathan","token":"XtACTPdOC_vF03s75EWSGunMGCDiU2aBIe97Pai0ruRDjhNpPZqg2w","sessionId":"34c06a2b-141a-434a-5313-a06788f20957"}}

❯ echo '{"id":"nathan","data":{"userName":"nathan","token":"6Z8JVhdo8MNUUHmFVy0bgjoSuiVJAsNYsqTdpqklqYv7j7xlJo6c2w","sessionId":"6dc7bd5e-a4b4-4c99-4b2e-c299fc101dc0"}}' | jq -r '.data' | base64
ewogICJ1c2VyTmFtZSI6ICJuYXRoYW4iLAogICJ0b2tlbiI6ICI2WjhKVmhkbzhNTlVVSG1GVnkwYmdqb1N1aVZKQXNOWXNxVGRwcWtscVl2N2o3eGxKbzZjMnciLAogICJzZXNzaW9uSWQiOiAiNmRjN2JkNWUtYTRiNC00Yzk5LTRiMmUtYzI5OWZjMTAxZGMwIgp9Cg==

❯ curl -s http://anka.controller:8090/api/v1/status
{"status":"FAIL","message":"Authentication Required"}

❯ curl -sH "Authorization: Bearer ewogICJ1c2VyTmFtZSI6ICJuYXRoYW4iLAogICJ0b2tlbiI6ICI2WjhKVmhkbzhNTlVVSG1GVnkwYmdqb1N1aVZKQXNOWXNxVGRwcWtscVl2N2o3eGxKbzZjMnciLAogICJzZXNzaW9uSWQiOiAiNmRjN2JkNWUtYTRiNC00Yzk5LTRiMmUtYzI5OWZjMTAxZGMwIgp9Cg==" http://anka.controller:8090/api/v1/status
{"status":"OK","message":"","body":{"status":"Running","version":"1.25.0-b2a027a4","registry_address":"http://anka.registry:8089","registry_status":"Running","license":"enterprise plus"}}
You have 10 seconds after obtaining the /hand token to shake. Otherwise, you will see an error thrown due to expiration.
By default, the TTL for keys is 5 minutes. You can modify this with the ANKA_API_KEYS_SESSION_TTL, set in the Controller and Registry configs. The TTL however will not cause long running requests, like downloads, to be interrupted.

Managing User/Group Permissions (Authorization)

Important
  • You can set groups for each api key or use the API Key ID as the “username” and create individual permissions for them.
  • Note for Enterprise Plus customers using OpenID and UAK: Typically, Authorization is enabled with the ANKA_ENABLE_CONTROLLER_AUTHORIZATION and other similar ENVs. However, when using your Ent+ license with OpenID and UAK, you will always need to add permissions for the groups claim you set in your OpenID configuration. Otherwise, you’ll see a blank Controller UI and API requests will fail.

By default, Authentication methods (enabled with ANKA_ENABLE_AUTH) will not use Authorization/permissions and allow any credential to connect to all API endpoints or pages in the UI. In order to enable Authorization, you will need to include specific ENVs in your config:

  • ANKA_ENABLE_CONTROLLER_AUTHORIZATION works for both combined and standalone (docker) packages.
  • ANKA_ENABLE_AUTHORIZATION is only for the standalone (native or docker) registry packages.
  • ANKA_ENABLE_REGISTRY_AUTHORIZATION is for the combined (controller + registry in one binary) package only.
This feature requires Enterprise Plus. The regular enterprise license automatically adds all permissions to each certificate or token that is used and gives no control over them.
This also requires that you’ve enabled Root Token Authentication, giving you super user access to the controller UI and permissions.
Do not confuse Node Groups with Permission Groups.

Permission Groups

Permission groups are configurable from your Controller’s https://<controller address>/#/permission-groups page. You can target and add permissions for either the group name or the username (which is different between the various Advanced Security Features we offer).