Access Key Authentication

Access key authentication provides an alternative to the security credentials of a node user or system user. Because an access key is restricted to its own storage (local or cloud), it allows access control and usage reporting to be segregated by storage. This offers significant benefits to multi-tenant service providers, and enterprise installations with multiple departments. Access key authentication supports Aspera client products, such as Desktop Client, Point-to-Point Client, Enterprise Server, Connect, and Drive. It also supports Faspex, Shares, and Aspera Files. For details about using access key authentication with these products, see the documentation for these products.

Node Access through SSH and HTTPS

A node (a transfer server) is accessed over SSH or HTTPS:

  • SSH services are best suited for access when all computers are part of the same administrative domain (in the same organization and with the same administrators).
  • HTTPS is best suited for services offered to arbitrary clients or the Internet at large.

Access through SSH and HTTPS use various types of authentication:

  • SSH services (ascp and async)
    • SSH user and password or user and key
    • Token - SSH authentication bypass using the Aspera web private key protected by requiring an authorization token (ATM).
    • Access key - SSH authentication bypass using the Aspera web private key protected by requiring an access key and secret.
  • HTTPS (Node API)
    • Basic authentication using a node user and password.
    • Basic authentication using an access key and secret.
Note: When using access key authentication, the following constraints apply:
  • Access keys cannot be used by users with docroots. If a docroot is configured (in aspera.conf), access key creation and use will fail.
  • A restriction is required. No restriction results in failure.
  • Although access keys can be created with no storage, using that access key with a transfer will result in failure.

Creating and Testing Access Keys

Set up a node user, associate it with a system user, and reload asperanoded by running the following commands. In the examples below, asp1 is the node user, aspera is the node user's password, and xfer is the system user. Running asnodeadmin requires root or admin permissions. 

# /opt/aspera/bin/asnodeadmin -a -u asp1 -p aspera -x xfer
# /opt/aspera/bin/asnodeadmin --reload

To create access keys, run curl commands as in the following examples. Curl is included in many Unix-based operating systems. To check if it is installed, enter curl on the command line. If it is not installed, download it from the Curl website: https://curl.haxx.se/download.html.

To create an access key with local storage, run the following: 

# curl -d @access_key-make-local.json -ki -u asp1:aspera https://localhost:9092/access_keys

where:

-d @access_key-make-local.json
Indicates the next argument is the data to send. The "@" identifies access_key-make-local.json as a file containing the data, in this case, a JSON payload file. For an example of the text to include in access_key-make-local.json and examples of access key files for other types of storage, see below.
-i
Includes the HTTP header in the output.
-k
Allows curl to perform "insecure" SSL connections and transfers.
-u 'asp1:aspera'
Specifies the user name asp1 and password aspera to use for server authentication.
https://localhost:9092/access_keys
Indicates where to store the access keys.

Similarly, to create an access key with cloud storage for Swift you specify a different JSON payload file:

# curl -d @access_key-make-swift.json -ki -u asp1:aspera https://localhost:9092/access_keys

Examples of JSON payload files for various storage types:

access_key-make-local.json
{
"secret" : "aspera",
"storage" : {
    "type" : "local",
    "path" : "/home/asp1/data"
}
}
access_key-make-aws.json
{
"secret" : "aspera",
"storage" : {
    "type" : "aws_s3",
    "path" : "/",
    "endpoint" : "s3.amazonaws.com",
    "bucket" : "aspera-demo",
    "storage_class" : "STANDARD",
    "server_side_encryption" : null,
    "credentials" : {
        "access_key_id" : "AKI...............KHQ",
        "secret_access_key" : "KScx...............................PHcm1"
    }
}
}
access_key-make-azure-sas.json
{
"secret" : "aspera",
"storage" : {
    "type" : "azure_sas",
    "path" : "/",
    "credentials" : {
        "shared_access_signature" : "https://asperadev.blob.core.windows.net/temp?sv=2014-02-14&sr=c&sig=yfew...79uXE%3D&st=2015-07-29T07%3A00%3A00Z&se=2018-08-06T07%3A00%3A00Z&sp=rwdl"
    }
}
}
access_key-make-azure.json
{
"secret" : "aspera",
"storage" : {
    "type" : "azure",
    "container": "temp",
    "path" : "/",
    "credentials" : {
        "storage_endpoint" : "blob.core.windows.net",
        "account" : "asperadev",
        "key" : "1XWGPGsn7.................................QObRmSQ=="
    }
}
}
access_key-make-swift.json
{
"secret" : "aspera",
"storage" : {
    "type" : "softlayer_swift",
    "path" : "/",
    "container" : "wallball",
    "credentials" : {
    "authentication_endpoint" : "https://sjc01.objectstorage.service.networklayer.com/auth/v1.0",
    "username" : "IBMOS303446-2:IBM303446",
    "api_key" : "e0a8987...................................2d6706"
    }
}
}

To view a list the access keys, run the following command:

# curl -ki -u asp1:aspera https://localhost:9092/access_keys

The command returns output similar to the following. In the example below, the first access key listed is one created for local storage and the second is for swift storage, with the text copied from the access key file:

HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

[
{
"id" : "diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA",
"uri" : "file:////home/asp1/data",
"file_id" : "1",
"token_verification_key" : null,
"license" : null,
"storage" : {
    "type" : "local",
    "path" : "/home/asp1/data"
}
},
{
"id" : "Yc6Q4VuvaYA9mMRf55NyNsiVGC-HHSBh0FTuqMH8aHsA",
"uri" : "swift://sjc01.objectstorage.softlayer.net/wallball",
"file_id" : "1",
"token_verification_key" : null,
"license" : null,
"storage" : {
    "type" : "softlayer_swift",
    "path" : "/",
    "container" : "wallball",
    "credentials" : {
    "authentication_endpoint" : "https://sjc01.objectstorage.softlayer.net/auth/v1.0",
    "username" : "IBMOS303446-2%3AIBM303446",
    "api_key" : "e0a8987b571cca4e475c8dd816c2d2db71b6d6e060f2a75ce23b1832c12d6706"
    }
}
}
]

To test whether you can browse the storage for each key, run the following commands. To specify the user (-u) enter the access key ID.

Testing the local storage:

# curl -ki -u diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA:aspera https://localhost:9092/files/1/files

Testing the Swift storage:

# curl -ki -u Yc6Q4VuvaYA9mMRf55NyNsiVGC-HHSBh0FTuqMH8aHsA:aspera https://localhost:9092/files/1/files

Client-Server Authentication Using Basic Authentication with Access Key

Basic authentication is used by Aspera Faspex and Aspera Shares.

  1. On the server, create a system user xfer and configure the user for token authorization, as described in Setting Up Token Authorization.
  2. Create an access key for the storage type, as described in Creating and Testing Access Keys above.
  3. Obtain the id of the access key corresponding to the storage type by running the following command, where -u asp1:aspera specifies the node username and password:
    # curl -ki -u asp1:aspera https://localhost:9092/access_keys
  4. Create a basic auth token by encoding the access_key_id:secret in base64. 
    # echo -n diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA:aspera | base64

    The basic auth token looks similar to the following:

    ZGlEZXVGTGNwRzlJWWRzdnhqMFNDcTRtT29oTkpUS3ZwNVEyblJXakRnSUE6YXNwZXJh
    If the basic auth token breaks across lines in the output, rerun the command using the -w0 option to remove the line break. For example:
    # echo -n diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA:aspera | base64 -w0
  5. Set the basic auth token as an environment variable by running the following command:
    # export ASPERA_SCP_TOKEN="Basic ZGlEZXVGTGNwRzlJWWRzdnhqMFNDcTRtT29oTkpUS3ZwNVEyblJXakRnSUE6YXNwZXJh"

To upload a file using access keys and basic auth, use the following syntax:

# ascp [--tags='{"aspera":{"node":{access_key":"access_key_id", "file_id":"value"}}}'] --mode=send --host=127.0.0.1 --user=username -i path/to/private_key_file -d filename directory

Where the path to the private key file is the following:

/opt/aspera/var/aspera_tokenauth_id_rsa

The directory can be / to indicate the top of the access key storage, or /directory to indicate a subdirectory. For example:

# ascp --tags='{"aspera":{"node":{access_key":"diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA", "file_id":"1"}}}' --mode=send --host=127.0.0.1 --user=xfer -i /opt/aspera/var/aspera_tokenauth_id_rsa -d testfile03 /tmp

The tags are optional. The tag "file_id":"1" can be used to indicate the top of the access key storage.

Client-Server Authentication Using Bearer Token and File IDs

Bearer token authentication is a requirement for Aspera Files.

Server setup:

  1. Create a private/public key pair. 
    $ openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096
$ openssl rsa -pubout -in private_key.pem -out public_key.pem

    These commands create the private key file private_key.pem and the public key file public_key.pem/

  2. Use the node user to create an access key, as described in Creating and Testing Access Keys above. This access key cannot be used by any other Aspera authentication system.
  3. Obtain the id of the access key corresponding to the storage type by running the following command:
    $ curl -ki -u asp1:aspera https://localhost:9092/access_keys
  4. Set the public key as the 'token verification key' of the access key. "JSON encode" the public key text (convert it into a single line with new lines indicated by \r\n) and use it in the following command:
    $ curl -X PUT -ki -u diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA -d '{"token_verification_key":"-----BEGIN PUBLIC KEY-----\r\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDMLkM2xiSPWjj4NxBHUa0m2ZAm\r\niog3JM3VEMW6rhE6LUtXM1KxRawih5pyD8OuGOAUTZmw7mnL3Cbebdzmc+CuqEkS\r\nkFJrYWCzNgQcRxc9v+XKk0YN8BZvMDmrSInmNQ5TPfG3sz4KJcf9QMJ\/TsR3rfns\r\nRYar\/IDoOTbgJgGQkwIDAQAB\r\n-----END PUBLIC KEY-----"}'
  5. Create a JSON file containing the bearer token payload and save it as bearer_token.json.
    {
  "user_id": "luke@aspera.us",
  "scope": "node.diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA:all",
  "expires_at": ""
  "group_ids": [],
}
    Ensure that the file does not end with a new line. If it does, truncate it to size - 1. For example, if the file is 154 lines with the new line, the command to remove the new line is as follows:
    $ truncate bearer_token.json --size 153
  6. Create a signature for the token.
    $ sudo openssl dgst -sha512 -sign private_key.pem bearer_token.json | base64 > signature
  7. Create the signed token.
    $ cat bearer_token.json > bearer_token.json.signed
$ echo "==SIGNATURE==" >> bearer_token.json.signed
$ cat signature >> bearer_token.json.signed
  8. Inspect the token:
    $ cat token-bearer-luke@aspera.us.json
{
  "user_id": "luke@aspera.us",
  "scope": "node.diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA:all",
  "expires_at": ""
  "group_ids": [],
}
==SIGNATURE==
YJixqw+5VjsGGIgOavoPdbhgr+1r9VGrKxBjAjV9mcMti0OJorbY7svIokz4
WLkszV5guz539nwcQCdiuISeGlBrJYMKfludCGP8MGxl8PaiZzJfzii6FWtm
K+4BhXlMDN4JIK+cAPL/zkdMu71mO2n8XcPOfXQv9HkUO8NXxl0ue7fDYnX6
+eB4GekGK7Latgfw2HBAyBSYKq8k7uiWOWC2/7qZDXXclei70OJR7zhe3wSR
FhR3yhfusz97XS5Zj2+nlfxE4hxw5sZrhQDqcp3vQwl26arMNI16vvuTZBY2
LUFY6f4mVmKmrz7hSGt1Gz9liO6jTImIYHmthzZ1TQ==
  9. Construct the final bearer token:
    $ cat bearer_token.json.signed | openssl zlib | base64 -w0 > bearer_token.json.sig.z.b64
  10. Create permissions for user ID (access ID) luke@aspera.us to the top level of the storage.
    $ curl -d '{"file_id":"1", "access_type":"user","access_id":"luke@aspera.us","access_level":"edit"}' \
-ki -u diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA:aspera https://localhost:9092/permissions
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

{
  "id" : "1",
  "file_id" : "1"
}

To test the access key, run the following command to browse the top directory of the access key:

# curl -i -u diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA:aspera https://localhost:9092/files/1

To test the bearer token, run the following to browse the top directory of the access key:

# curl -ki -H "Authorization: Bearer eJwVkNmuolgARd/5DF/pKhlFTG7SCMikzIOeSqXCqCBwmKdK/3t7n/faKzv7L7Ib+7T7kye7064c3+m/Yd+kXfhz7Hf/ILs+hk36SWqYpD9rUXP7baWfPbteSmDUWUwl69bVszYUhC6zjgKMt6xXF447fVtPYVl+W9Klybu0/xMOHxWB4YcfOPGDwFwMP9H4iWLBN/Ts4Nh8dvS706/fyH/I15ejSDrnerb49YXwc7G0Fg4r8lIsJEfzHfM62tKkQWhL0WHNyMoebry5tqxoRXtBaettpiRt6vVyXwX+I342cXcVqLoIkGv5CASI8no+SoILb0LBzI8COrIkvArR3nIY9NA2FdQQRn1B8Yo1l5YmUxyA7pGgMhpr5sHF01UCNeKp74irWafha14TQvSI7dWb5CXBm4xNaYZOmSkynCQj49wluJS6ZPEwzjpZrRTyZeFuRzSTcFBztdgQNroCMFpGvArg0+RcM7DuTKBig2Yaoe9gCk9ukgS3yc555uaqiuOaU1zL/PWuev1lCPDM1mkjm449Mm6kSRJnT3lgYGWuWArwgBCBuiXuWagHqn9rDtO0bG8/k/loTEOEj1JR1cCZzSkApJveBPQ+b8klTZCXPXTeSzG1IYD5mV16zBzoTaLQAtBRqep4Lsr0Pr29vWE/R4EnkgIWQJVpVz/KuIPvE/7gjG1om/QTCVuxIXR+tAgg+mm5b3LQU0s2W+/btUInqNlbqNqa2WUFcfAEJ4wyp8M+h6RxW1oUd6krLy7imWrjCqltR+Uoj0ePh/JgnZc6L807YztmeM7J9nAzrps8C6wh2w9VkK6Eqa6mv6wvA70z/QbsJDmXFtBh14A7og80JqsPGkKOOr4moX9KyoG54JTSwf3EBxw2FvtjwDTP54NvcE14VcA3o3eQLQ2RF758jGJ2jamH+PxC/gc1nBpn" -H "X-Aspera-AccessKey: diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA" https://localhost:9092/files/1

Both of these tests should return a list of files and directories in the top directory.

To do a simple upload using the bearer token, set the bearer token as an environment variable and run an ascp transfer specifying the access key:

# export ASPERA_SCP_TOKEN="Bearer eJwVkNmuolgARd/5DF/pKhlFTG7SCMikzIOeSqXCqCBwmKdK/3t7n/faKzv7L7Ib+7T7kye7064c3+m/Yd+kXfhz7Hf/ILs+hk36SWqYpD9rUXP7baWfPbteSmDUWUwl69bVszYUhC6zjgKMt6xXF447fVtPYVl+W9Klybu0/xMOHxWB4YcfOPGDwFwMP9H4iWLBN/Ts4Nh8dvS706/fyH/I15ejSDrnerb49YXwc7G0Fg4r8lIsJEfzHfM62tKkQWhL0WHNyMoebry5tqxoRXtBaettpiRt6vVyXwX+I342cXcVqLoIkGv5CASI8no+SoILb0LBzI8COrIkvArR3nIY9NA2FdQQRn1B8Yo1l5YmUxyA7pGgMhpr5sHF01UCNeKp74irWafha14TQvSI7dWb5CXBm4xNaYZOmSkynCQj49wluJS6ZPEwzjpZrRTyZeFuRzSTcFBztdgQNroCMFpGvArg0+RcM7DuTKBig2Yaoe9gCk9ukgS3yc555uaqiuOaU1zL/PWuev1lCPDM1mkjm449Mm6kSRJnT3lgYGWuWArwgBCBuiXuWagHqn9rDtO0bG8/k/loTEOEj1JR1cCZzSkApJveBPQ+b8klTZCXPXTeSzG1IYD5mV16zBzoTaLQAtBRqep4Lsr0Pr29vWE/R4EnkgIWQJVpVz/KuIPvE/7gjG1om/QTCVuxIXR+tAgg+mm5b3LQU0s2W+/btUInqNlbqNqa2WUFcfAEJ4wyp8M+h6RxW1oUd6krLy7imWrjCqltR+Uoj0ePh/JgnZc6L807YztmeM7J9nAzrps8C6wh2w9VkK6Eqa6mv6wvA70z/QbsJDmXFtBh14A7og80JqsPGkKOOr4moX9KyoG54JTSwf3EBxw2FvtjwDTP54NvcE14VcA3o3eQLQ2RF758jGJ2jamH+PxC/gc1nBpn"
# ascp --tags='{"aspera":{"node":{"access_key":"diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA","file_id":"1"}}}' -mode=send --host=hostname --user=xfer -i /opt/aspera/var/aspera_tokenauth_id_rsa -d testfile01 /