How to create and use bearer tokens

IN THIS ARTICLE:

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 called bearer_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 the bearer_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 user luke@aspera.us to 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> -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

 

Have more questions? Submit a request

1 Comments

  • Avatar
    Thomas Doerr

    This is more clear than the example on the developer site and has the benefit of actually working

Please sign in to leave a comment.
Powered by Zendesk