FASP Transfer Authentication and Authorization

Starting a transfer through the Node API (by sending POST requests to /ops/transfers) involves two sets of credentials, one to authenticate to the "local" node endpoint and authorize access to the local storage (described in Node API Authentication and Authorization), and another to authenticate to the "remote" node (the other side of the FASP transfer) and authorize access to the remote storage (described in this article). The authentication and authorization method that is used to access the Node API endpoint does not need to be the same as the method used to access the remote node, depending on your tenancy requirements.

When transferring content between computers using FASP, the client FASP process connects to the server by using SSH to start the server-side FASP process. Thus, SSH connections and authentication to the server are always used for FASP transfers. The transfer user (a system user who is configured for Aspera on the server) is used to authenticate the connection with a system password or SSH key.

HTTPS (Node API) authentication was introduced to support browsing and transfers that are initiated through Aspera web applications (Faspex, Shares, and Files), and uses a token-based authorization security layer in addition to SSH. For node-to-node transfers that are started through the Node API, the client must provide a token to to the server in order to authorize the transfer.

Node-to-node transfers that are started by POST requests to /ops/transfers can use basic tokens or bearer tokens to authorize the transfer. ascp can also use transfer tokens, but these are deprecated for Node API transfers and information is provided for legacy customers who are using the deprecated /transfers endpoint.

Basic Tokens

Basic tokens are created from an access key ID and secret. They authorize transfers with the storage specified in the access key from which they are created and are used for single-tenancy applications.

  • Creating Basic Tokens
    Basic tokens are created by base64-encoding the access key ID and secret into a token string.

    $ echo -n access_key_id:access_key_secret | base64
    For example:
    $ 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 access_key_id:access_key_secret | base64 -w0

    For instructions on creating basic tokens for other OS, see "Basic Tokens" in the IBM Aspera Enterprise Server Admin Guide for your OS.

  • Using Basic Tokens in a Transfer Request
    The following is an example showing the minimum information required for the request body when you use basic token authentication:
    {
        "direction": "send",                              <!-- required -->
        "remote_host": "domain",                          <!-- required -->
        "remote_user" : "transfer_user",                  <!-- required if not using "xfer" -->
        "remote_password" : "password",                   <!-- required to use either password or private key, Aspera recommends key -->
        "ssh_private_key": "key_string",
        "ssh_private_key_passphrase" : "passphrase",      <!-- might be required to use key -->
        "token" : "Basic token_string"                    <!-- required -->
        "paths": [
            {
                "source": "file_name",
                "destination": "destination_file_name"    <!-- optional if transferring to access key root storage -->
            },
            {
                "source": "source_folder",
                "destination": "destination_folder_name"
            }
        ]
    }

Bearer Tokens

A bearer token is created from an access key ID, access key secret, and an SSL private-public key pair. They authorize transfers with the storage as restricted by the access key from which they are created, the bearer token configuration, and permissions on the content. They are used for multitenancy applications.

  • Creating Bearer Tokens
    Bearer tokens are created from an SSL key pair and an access key ID and secret. For instructions on generating bearer tokens, see Authentication and Authorization.
  • Using Bearer Tokens in a Transfer Request
    The following is an example showing the minimum information required for the request body when you use bearer token authentication:
    {
        "direction": "send",                               <!-- required -->
        "remote_host": "domain",                           <!-- required -->
        "remote_user" : "transfer_user",                   <!-- required if not using "xfer" -->
        "remote_access_key": "remote_access_key_id",       <!-- the same access key that was used to create the remote bearer token -->
        "token" : "Bearer remote_bearer_token_string",     <!-- required -->
        "source_root_id" : "1",                            <!-- required if using bearer token auth on local node -->
        "destination_root_id" : "1",                            <!-- required --> 
        "paths": [
            {
                "source": "file_name",
                "destination": "destination_file_name"     <!-- optional if transferring to bearer token root storage -->
            },
            {
                "source": "source_folder",
                "destination": "destination_folder_name"
            }
        ]
    }

Transfer Tokens

A transfer token authorizes specific content uploads to a destination or content downloads from a remote source. Transfer-token-based authorization is generally used for FASP transfers initiated through Aspera web applications, such as IBM Aspera Shares, Faspex, and Sharepoint, but can be used in place of SSH authentication for other types of Aspera products.Transfer tokens authorize an upload or download of a specific file or directory from the source. These tokens can also specify the allowed destination and transfer parameters.
  • Required User and Server Configuration
    Transfer token authorization requires configuration of the server. For instructions, see "Setting Up Transfer Token Authorization" in the IBM Aspera Enterprise 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.

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.

The following table describes token behavior for different transfer scenarios for which a token is generated:

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.
Video player

Video

×