Answer

Summary

As of the 3.6 release Aspera Node API now support the use of Access Keys and Bearer tokens. This KB provides a simple example of how to create and use bearer tokens for file system operations (list create delete) permissions granting and file transfers.

Use cases details

1. File system operations: List files delete files create folders delete folders
2. Folder permissions: Set permissions on a folder for a given id
3. Transferring: Transfer to the server using an Access Key and Bearer token

Pre-requisite

1. You have an Aspera server or Aspera Transfer Cluster (e.g. ATC) available
2. The server is configured with an Access Key that contains a verification token
3. You have the corresponding private key (e.g. private_key.pem)

Example - Creating bearer token

1. Create a JSON file containing the bearer token payload. (e.g. bearer_token.json)

Syntax:

{
 "user_id": "<YOUR_ID>"
 "group_ids": ["<GROUP1>" "<GROUP2>"]
 "scope": "node.<ACCESS_KEY>:user:all"
 "expires_at": "DATE_STAMP"
}

Example:

{
 "user_id": "luke@aspera.us"
 "group_ids": ["engineering" "emeryville"]
 "scope": "node.yl-g88EfwFmBj0KOXwU0QVPloe1IHg6QtlFbD5wCRH0A:user:all"
 "expires_at": "2020-01-01T13:20:00.000Z"
}

2. Eliminate the newline from the end JSON file. This can easily be done with perl. Assuming the payload is in a file calledbearer_token.json issue this command:

# perl -pi -e 'chomp if eof' bearer_token.json

3. Create the signature and add it to a new file bearer_token.sig and sign the existing payload and append it to thebearer_token.sig file:

# echo '==SIGNATURE==' > bearer_token.sig
# sudo openssl dgst -sha512 -sign private_key.pem bearer_token.json | base64 >> bearer_token.sig

4. Create the signed token: Append the bearer_token.sig to a new token file and then use openSSL to zlib it and base64 to encode it.

# cat bearer_token.json > bearer_token.signed
# cat bearer_token.sig >> bearer_token.signed
# cat bearer_token.signed | openssl zlib | base64 -w0 > bearer_token

The final file should look like this. NOTE: You have to re-introduce the end of line after the bearer token payload section (e.g. before the ==SIGNATURE==).

{
 "user_id": "luke@aspera.us"
 "group_ids": ["engineering" "emeryville"]
 "scope": "node.-v1Uxr3NVcvVC1O9oNg3:user:all"
 "expires_at": "2020-01-01T13:20:00.000Z"
}
==SIGNATURE==
TqhhIICJCKesUUdOYNnOyb9LoQtnb+B9d/tdeuVhMa7+hj983d2cOdFo6s2bbIegNqh6v67M9Pec
817E5SNG/SklMRFb0dyGkm9TnBlYP5NuWU9YX0PGgUeA2BlRLoLNv+vr1CKFsDiCdnyYBZtTMJui
3OhkgZEc9Yesvtp8Wq23KeWbHz+jQcXvE9oaeCOEXgvRr23nckuNyGNQr/tFv3ybFthrn0NBxB80
g0SESQhOKy385jQbQ5jO0vUcZ+9hsVQ5vZry1gtWSsjA1ytzFblBXX7Xta0/ZEhwndV72YqD3qQ1
HaWE5yi6wp9K95hLOYGekNvpyzv/JiKziIcKaWKN/zY7AF0N2h4gKOt9xrJbO0Hzcdi2O99KjwLA
j3sFFlJ9tQ6X18Cs40texxohIAb2SCG19Ir2DX9LMz24fUR97O5B89EuHnqlbspTlclzpCP//w/C
/ZVrKOr/Z3YX/RQIOqtI16zqeBUxAWppJZuhxIIep4lI6BkZzLMRwwRx+dbu7W/qBHZ7VeixFU43
PVSniQMxjNIgQ1AMz+IHGlBBbq8OH46PPvmuEz7opaWajFOk5t61N7n5ijzydvoH3+zZaiBAOUv
XAa2aOnrPw4srOzQoGF3iJvUAsV+zGkGbkOo5j1uxfNwhpcVjBOtlU8+pOu26i2+hH8IXgv7onk=

Example - Using Bearer token

1. Confirm that you can browse the server with your access keys

Syntax:

# curl -i -u <ACCESS_KEY>:<SECRET> https://<SERVER>/files/1/files

Example:

# curl -i -u yl-g88EfwFmBj0KOXwU0QVPloe1IHg6QtlFbD5wCRH0A:aspera https://myaspera.asperademo.com/files/1/files

2. Assign permissions to a folder on your server

In this example we give permission to userluke@aspera.usto the top level of the storage (this is just an example you can give permissions to any users to any subtree of the access key's storage)

Syntax:

# curl -i -u <ACCESS_KEY>:<SECRET> https://<SERVER>/permissions -d '{"file_id":"1" "access_id":"<ACCESS_ID>" "access_level":"<ACCESS_LEVEL>"access_type:"user"}'

Example:

# curl -i -u yl-g88EfwFmBj0KOXwU0QVPloe1IHg6QtlFbD5wCRH0A:aspera https://myaspera.asperademo.com/permissions -d '{"file_id":"1" "access_id":"luke@aspera.us" "access_level":"view"access_type:"user"}'

3. Test retrieval of folder contents using the bearer token

Syntax:

# curl -ki -H "Authorization: Bearer <BEARER_TOKEN>" -H "X-Aspera-AccessKey: <ACCESS_KEY>" https://<SERVER>:<NODE_PORT>/files/1/files

Example:

# curl -ki -H "Authorization: Bearer eJwdjdmOqlgARd/5ioqv3iqZRDCp5IJMMngQAZFO54bhMMkkh0Hs9L+31W87e6+s/c/Hx2pEsP9TJKv9x+qdorD5HaIO9uHXiFa/3nvWt2P3BtCb+GsFm+zdrmAN+2Uqqgqu/v6BUNx28EfRtAn8WqrPjGWldJZrocR14M8ufvasqoXEUc2Y81DJkbidD7aK8/uf/31YVf+fwWdX9BD9CYcfGYkTzCfOfJKUQ1B7kthv2S96SwWrf7Hv78tROfGOa0vf31ifOye4I5NjP42tBQS6bF5gKayT7Af5djaHwxyZJ2GOPZDqRQHGoZeKeo1CAwAX593GFCuPvHVdWRJYvGuIEFxZA0Hi0cRiC1PaNcpCL5OmzzuLEULqUG2doCVVAqnEAHVBqVKQMYs63dq4oVkoaDoTHNwYC87RLU9tp0bO1M1G8PQTSWWMTK9senDu5iDSqXhShEN6PsiBgJZh7TnkkVJMp456me1NaTBs62hfdhdsSuYFiM/ryxfmic05TpRpcB+kbT8vShNw8otFNFyfogJc+OKxS31qg7SbTpJXy7vMsbWpOK+oOorZmdj9OdJdls8atG2NlEqrPh6rc0jfT75rUa/FuKKbWmhopwRIDdpSdfuy4Q7+pONPShbqwBhAydHdcWEnjGPKCyVP7uA1NShBCtjwJoTpdIsI2yqVa5Hj64AV1/qwrSkwkKz9oALZoqx6TocdoFrBmYDmx+NzJjCb22VlZMa+Tb+0B//UHwO/ucuF9pjBtamcBGoFl6cLi0+PeiSUzfRi5DrKq6uZC2vTeQU6LxFo6iswYhPI0UWHPMMEitdAHd/knEO1YcgdaxWWenhhbtpVT/S7MgrZshhw90yBLLJ5H3iGQVZrzaM6xN8TV8XctlAvg4QnVyY9LD4M26cwjMuITq8cZH6Duno+r4VDzUldseGbW2SIWsx6cFxkaXCyLemkVG9szLv7jWH/Abp+JT4=" -H "X-Aspera-AccessKey: yl-g88EfwFmBj0KOXwU0QVPloe1IHg6QtlFbD5wCRH0A" https://10.0.109.1:9092/files/1/files