Node-to-node FASP transfers with the Node API use three sets of security credentials:

  1. Authenticate the HTTP REST API request to the local node
  2. Authenticate the SSH connection from the local node to the remote node
  3. Authorize access to the storage on the remote node

Note: This example shows one possible node arrangement, with the local Aspera node in the cloud and the remote Aspera node on-premises; cloud-to-cloud and on-premises to on-premises are also supported.

The Node API request is authenticated with an access key, bearer token, or Node API credentials, as described in Node API Security.

This article describes:

  • What authentication credentials are required in the request body by node type.
  • How to generate the different kinds of authorization tokens.
  • Examples of transfer requests between different kinds of Aspera nodes.

Remote Node Authentication and Authorization Methods

Remote Node Type SSH Authentication to Remote Node Token Authorization to Remote Node

Aspera on Cloud (AoC)

Implicit SSH authentication (the /ops/transfers request body does not require SSH credentials)

  • Bearer token

    AoC supports only bearer token authorization, the /ops/transfers request body must include:

    "token": "Bearer token_string"
    "remote_access_key": "access_key"

    Note: The bearer token must have a scope of node.access_key_id.user:all.

Aspera on Cloud transfer service (AoCts)

Aspera Transfer Cluster Manager (ATCM)

Implicit SSH authentication (the /ops/transfers request body does not require SSH credentials)

AoCts and ATCM support bearer, basic, and transfer tokens. The /ops/transfers request body must include one of the following:

  • Bearer token
    "token": "Bearer token_string"
    "remote_access_key": "access_key"
  • Basic token
    "token": "Basic token_string"
  • Transfer token
    "token": "token_string"

High-Speed Transfer Server (HSTS)

High-Speed Transfer Endpoint (HSTE)

Aspera on Demand (AOD)

Explicit SSH authentication (the /ops/transfers request body must include SSH credentials)

  • Set the transfer user, when not the default value “xfer”
    "remote_user": "username"
  • Set the password or SSH private key (the transfer user’s public key must be configured on the server)
    "remote_password" : "password"

    or

    "ssh_private_key" : "private_key"
  • If required (when private key is password-protected), set the private key passphrase
    "ssh_private_key_passphrase" : "passphrase"

HSTS, HSTE, and AOD support bearer, basic, and transfer tokens. The /ops/transfers request body must include one of the following:

  • Bearer token – requires
    "token": "Bearer token_string"
    "remote_access_key": "access_key"
  • Basic token – requires
    "token": "Basic token_string"
  • Transfer token – requires
    "token": "token_string"

Token Types

The authorization token can be a bearer token, basic token, or an Aspera transfer token. All token types are supported by Aspera nodes, except for Aspera on Cloud, which only accepts bearer tokens.

Bearer Token

Bearer tokens are created from an access key and an SSL private-public key pair that are configured on the remote node. They authorize transfers with the remote storage as restricted by the access key from which they are created, the bearer token configuration, and permissions on the content. They are most often used for multitenancy applications when the node storage must be securely partitioned between tenants.

Basic Token

Basic tokens are created by base64-encoding an access key ID and secret. They authorize transfers with the storage specified in the access key from which they are created.

To create a basic token:

  • Linux, macOS, and other Unix-like operating systems
    $ echo -n access_key_id:access_key_secret | base64

    If the token breaks across lines in the output, rerun the command with the -w0 argument (this is not supported on macOs).

  • Windows

    Windows does not have a native base64 encoder. The following instructions use base64.exe, a free Windows utility.

    1. Create a text file that contains the following:
      access_key_id:access_key_secret
    2. Run the following command, where infile.txt is the file from step 1:
      > base64.exe infile.txt outfile.txt
    3. Open outfile.txt and delete any line breaks.

Transfer Token

A transfer token authorizes specific content uploads to a destination or content downloads from a remote source. These tokens can also specify the allowed destination and transfer parameters.

  • Required Configuration for HSTS, HSTE, and AOD
    Transfer token authorization requires configuration of the server. For instructions, see “Setting Up Transfer Token Authorization” in the IBM Aspera High-Speed Transfer Server Admin Guide for your OS.
  • Creating Transfer Tokens
    Transfer tokens can be created by using POST requests to /files/download_setup (for authorizing downloads from the server) or /files/upload_setup (for authorizing uploads to the server).

Caution: Before generating and using transfer tokens, review the following guidelines to avoid serious errors with high-volume transfer implementations.

Transfer Scenario Token Behavior
Upload one or more files to a destination path Allows uploads of any number of files and directories to this destination path; the source files and directories are not limited in any way. This is logically equivalent to generating the token for an upload to a destination without specifying the source files and directories.
Download one or more files or directories Authorizes a download of the specified source files and directories to any destination location on the client, in the same order that is defined in the creation of the token. This is logically equivalent to generating the token for a download of the source files and directories without specifying the destination.
Upload one or more files as source/destination pairs Authorizes only an upload of the files and directories specified as sources and destinations, in the same order as defined in the creation of the token. The source paths may be changed for the transfer since the names of the sources are not enforced. But this can cause undefined failures in transfers of large number of files – due to the chunking mechanism which accounts for the length of source file names. We therefore strongly advise to use same source destination pairs for both token generation and transfer submission.
Download one or more files as source/destination pairs Authorizes only a download of the files and directories specified as sources to the client, in the same order as defined in the creation of the token. The destination paths may be changed for the transfer since the names of the destinations are not enforced. But this can cause undefined failures in transfers of large number of files – due to the chunking mechanism which accounts for the length of destination file names. We therefore strongly advise to use same source destination pairs for both token generation and transfer submission.

For transfers that use source-destination pairs in the transfer token, Aspera strongly recommends that you use the same source-destination pairs for the transfer as those you used to generate the token, in the same order. Not doing so may cause undefined failures when transferring large numbers of files. These failures are caused by the chunking mechanism which accounts for the length of source-destination file names.

Creating the Transfer Request

When you send a POST request to /ops/transfers, the request body contains the transfer specification. The transfer specification can include key-value pairs that provide most of the functionality of command line ascp transfers. For a complete description, see the /ops/transfers documentation.

Only a subset of values are actually required for the transfer. For example, if the transfer user is “xfer”, the token is a basic token, and the destination is the root directory of the access key, then the request body requires only the following:

{
    "direction": "send",                               
    "remote_host": "domain",                                
    "token" : "Basic remote_token_string",                           
    "paths": [
        {
            "source" : "file_name"
        }
    ]
}

Note: The remote server might be configured to require certain other key-value pairs in the transfer specification, such as client-side encryption-at-rest (also called content protection) or a minimum encryption cipher. The response body of a request to GET /info contains information about some of these settings.

Example Minimum Transfer Requests

AoCts (local node) to AoCts (remote node)

In this example:

  • The Node API request to the local node is authenticated with the access key ID “YmVhcmVyX2FjY2Vzc19rZXk6YmVhcmVyX3NlY3JldAo=” and secret “323592y3582353”
  • Access to the storage on the remote node is authorized with the basic token “Basic cmVtb3RlX2FjY2Vzc19rZXk6cmVtb3RlX3NlY3JldAo=”
curl -i -u YmVhcmVyX2FjY2Vzc19rZXk6YmVhcmVyX3NlY3JldAo=:323592y3582353 -X POST https://ats-aws-us-west-2.dev.aspera.io:443/ops/transfers -d '{"direction": "send", "remote_host": "ats-sl-sjc.dev.aspera.io", "token": "Basic cmVtb3RlX2FjY2Vzc19rZXk6cmVtb3RlX3NlY3JldAo=","paths": [{"source" : "/sample.txt"}]}'

AoCts (local node) to AoC (remote node)

In this example:

  • The Node API request to the local node is authenticated with the access key ID “YmVhcmVyX2FjY2Vzc19rZXk6YmVhcmVyX3NlY3JldAo=” and secret “323592y3582353”
  • Access to the storage on the remote AoC node is authorized with the bearer token “Bearer eyJ0eXAiOiJKV1QiLCJhbGcAifQ.eyJ14cc3V25OV6ZgzcK7NmzSsNC_B6-U8ZkKrYlxaa_-eSp48TWUqvq8DbG284Yv-k06Qrg_rB7UDSS3rbIyALS0ad5sFFcT-ESW_S50PKx3QasTfwbBxA”

    Note: the bearer token must have a scope of node.-CIjOber23Nier239nfe-_RNW89.user:all.

  • The bearer token was created with the access key “-CIjOber23Nier239nfe-_RNW89”
  • Because this request authenticates to the remote node with a bearer token, and the remote node is the destination, a value for destination_root_id (the file ID of the root directory of the bearer token) is required.
curl -i -u YmVhcmVyX2FjY2Vzc19rZXk6YmVhcmVyX3NlY3JldAo=:323592y3582353 -X POST https://ats-aws-us-west-2.dev.aspera.io:443/ops/transfers -d '{"direction": "send", "remote_host": "files-prod-es-tor03.asperafiles.com", "remote_access_key": "-CIjOber23Nier239nfe-_RNW89", "token": "Bearer eyJ0eXAiOiJKV1QiLCJhbGcAifQ.eyJ14cc3V25OV6ZgzcK7NmzSsNC_B6-U8ZkKrYlxaa_-eSp48TWUqvq8DbG284Yv-k06Qrg_rB7UDSS3rbIyALS0ad5sFFcT-ESW_S50PKx3QasTfwbBxA","destination_root_id": "1", "paths": [{"source" : "/sample.txt"}]}'

HSTS (local node) to AoCts (remote node)

In this example:

  • The Node API request to the local node is authenticated with the access key ID “YmVhcmVyX2FjY2Vzc19rZXk6YmVhcmVyX3NlY3JldAo=” and secret “323592y3582353”
  • Access to the storage on the remote node is authorized with the basic token “Basic cmVtb3RlX2FjY2Vzc19rZXk6cmVtb3RlX3NlY3JldAo=”
curl -i -u YmVhcmVyX2FjY2Vzc19rZXk6YmVhcmVyX3NlY3JldAo=:323592y3582353 -X POST https://10.0.0.1:9092/ops/transfers -d'{"direction":"send","remote_host":"ats-azure-westus.aspera.io","token":"Basic cmVtb3RlX2FjY2Vzc19rZXk6cmVtb3RlX3NlY3JldAo=","paths":[{"source":"/Documents/sample.txt", "destination":"/test/sample2.txt"}]}'

HSTS (local node) to HSTS (remote node)

In this example:

  • The Node API request to the local node is authenticated with the Node API username “nodeuser” and the password “nodepassword”.
  • Access to the storage on the remote node is authorized with the transfer token “ATB2_ACsjPbserJSER32u-FHp6BsERNE3834UgE_2BTA”
  • Note: In this example, the SSH user is xfer so it does not need to be specified because “xfer” is the default value.
curl -i -u nodeuser:nodepassword -X POST https://10.0.0.1:9092/ops/transfers -d'{"direction":"send","remote_host":"10.0.0.2","token":"ATB2_ACsjPbserJSER32u-FHp6BsERNE3834UgE_2BTA","paths":[{"source":"/Documents/sample.txt", "destination":"/test/sample.txt"}]}'