Contents:

Overview of Authentication Methods

The Node API is an authenticated API that supports:

  • HTTP Basic authentication (as access keys or Node API credentials)
  • OAuth2 authentication (as bearer tokens)

These different types of authentication are related to each other, as shown in the following diagram, and support for authentication methods depends on the type of node.
In the diagram:

  • Blue arrows and text show the configuration changes that create one authentication type from another. Each arrow has a number that corresponds to a creation path described following the diagram.
  • Only authentication methods in solid blue boxes can be used for Node API requests.
  • For self-managed nodes, such as High-Speed Transfer Server (HST Server), High-Speed Transfer Endpoint (HST Endpoint), and Aspera on Demand (AOD), authentication begins with an operating system user who is configured for Aspera transfers (an Aspera Transfer User). This user can authenticate FASP transfers but not Node API requests (yellow box).
  • For Aspera on Cloud transfer service (AoCts) nodes and Aspera on Cloud (AoC), users start by using the ATS API or Files API (green boxes) to create Node API authentication credentials.

Node API authentication creation paths:

  1. Node API Credentials (1a and 1b): Node API credentials are an HTTP Basic method of authenticating Node API requests. They consist of a username and password that are created in the Aspera NodeD Service database by using an Aspera command line tool, asnodeadmin.

    Node API credentials are associated with a transfer user (a system user that can authenticate and authorize FASP transfers) and inherit any file system access restrictions that are configured for the transfer user. Transfer users can have their access to the node’s file system restricted by configuring:

    • file restrictions (1a) – A set of file matching filters that use “*” as a wildcard and “!” to indicate “exclude”, such as file:////docs/*.
    • a docroot (1b) – An absolute pathname or URI to which the user is allowed access, such as /docs.

    For example, if a transfer user has the file restriction /users/xfer/docs/*, the associated Node API credentials allow access only to /users/xfer/docs.

    Node API credentials are only available to customers in self-managed nodes, such as High-Speed Transfer Server. In Aspera’s SaaS offerings, the Node API credentials are “under the hood” and customers use access keys or bearer tokens provided through the product’s API.

  2. Access Keys (2): Access keys are another HTTP Basic method of authenticating Node API requests. Access keys are created and managed by using the API corresponding to the Aspera product (2). For Aspera on Cloud transfer service, they are created with the ATS API.

    An access key encodes authorization to a specific path in the file system.

  3. Bearer Tokens (3): Bearer tokens are a type of OAuth2 authentication that encode an access key, an SSL key pair, a scope role, and a user or group ID.

    For on-premises or self-managed nodes, bearer tokens can be created using the asnodeadmin command line tool. For Aspera on Cloud, they are created with the Files API. For other cloud-based nodes, you must manually assemble the bearer token.

    Node API requests that are authenticated with bearer tokens are restricted to the same part of the node’s file system as the access key; additionally, the user or group ID must have permissions on the content. Permissions are managed through the Node API /permissions endpoint.

HTTP Basic Authentication in an Authorization Header: If needed, HTTP Basic authentication credentials, either Node API credentials or access keys, can be provided in an HTTP request header. To do so, base64-encode the credentials (as id:secret). For instructions and a usage example, see HTTP Basic Authentication Header.

Security by Node Type

Supported Node API authentication methods vary by node type. Click the links in the following table for more information about Node API security for each node type.

HTTP Basic Authentication OAuth2 Authentication
Node Type Access Keys Node API Credentials Bearer Token
Aspera on Cloud (AoC) no no yes
Aspera on Cloud transfer service (AoCts) yes no yes
Aspera Transfer Cluster Manager (ATCM) yes no yes
High-Speed Transfer Server (HST Server) and Endpoint (HST Endpoint) yes yes yes
Aspera on Demand (AOD) yes yes yes

Aspera on Cloud

Supported Authentication

HTTP Basic OAuth2
none Bearer token

Aspera on Cloud is a multi-tenant SaaS product that enables high-speed file transfers to and from Aspera-managed IBM Cloud Object Storage. To ensure complete separation and security between tenants, Node API requests to Aspera on Cloud require bearer token authorization.

Creating a Bearer Token

The bearer token is created by using the Files API; see Creating an Aspera on Cloud API Bearer Token for details.

Note: The bearer token that is created for use with the Files API (that has a scope of user:all or admin:all) cannot be used to authenticate Node API requests. You must use the Files API bearer token to create a token with a scope that includes the access key, as described in the link.

Example

Authenticate a Node API request with a bearer token by providing the bearer token and the access key associated with it. For example:

curl -i -H "Authorization: Bearer jg3904ts48thj348thll4tj4l8h" -H "X-Aspera-AccessKey: eirn23rual3u3824ul283rj3rnawlrh" -X GET https://files-prod-es-tor03.asperafiles.com/info

Aspera on Cloud Transfer Service

Supported Authentication

HTTP Basic OAuth2
Access key Bearer token

The Aspera on Cloud transfer service is a feature of Aspera on Cloud that allows you to use Aspera technology to run high-speed transfers to and from your cloud storage (in supported platforms and regions).

Creating an Access Key

You can create an access key through the Aspera on Cloud UI or the ATS API.

Creating a Bearer Token

Bearer tokens for Aspera on Cloud transfer service must be manually constructed from an access key and SSL key pair. In the access key, set the public key as the value for “token_verification_key”, then build the bearer token as described in https://support.asperasoft.com/hc/en-us/articles/216131418-How-to-create-and-use-bearer-tokens.

Examples

  • To authenticate your request with an access key:
    curl -i -u access-key-id:access-key-secret -X GET https://ats-aws-us-west-2.aspera.io:443/info
  • To authenticate your request with a bearer token:
    curl -i -H "Authorization: Bearer jg3904ts48thj348thll4tj4l8h" -H "X-Aspera-AccessKey: eirn23rual3u3824ul283rj3rnawlrh" -X GET https://ats-aws-us-west-2.aspera.io:443/files/1/files

Aspera Transfer Cluster Manager (ATCM)

Supported Authentication

HTTP Basic OAuth2
Access key Bearer token

The Aspera Transfer Cluster Manager is a self-managed, cloud-based cluster of High-Speed Transfer Servers. Node API requests to ATC nodes require access key authentication and can use bearer token authentication.

Creating an Access Key

For instructions about how to create an access key for ATCM, see the IBM Aspera Transfer Cluster Manager Admin Guide.

Creating a Bearer Token

Bearer tokens for Aspera Transfer Cluster Manager nodes must be manually constructed from an access key and SSL key pair. In the access key, set the public key as the value for “token_verification_key”, then build the bearer token as described in https://support.asperasoft.com/hc/en-us/articles/216131418-How-to-create-and-use-bearer-tokens.

Examples

Authenticate Node API requests as described in the section for the Aspera on Cloud transfer service, using the ATCM hostname in the target URL.

High-Speed Transfer Server and Aspera on Demand

Supported Authentication

HTTP Basic OAuth2
Node API credentials

Access key

Bearer token

The Aspera High-Speed Transfer Server (HST Server) is a FASP-powered transfer server that can be deployed on-premises or on a VM image in cloud storage. Aspera on Demand (AOD) is an Aspera-provided VM image with HST Server pre-installed and configured for the cloud platform. You must have HST Server version 3.6.0 or higher to use the Node API.

Selecting a Security Method

Node API requests to on-premises HST Servers, cloud-based HST Servers, or AOD can use HTTP Basic authentication (as an access key or Node API credentials) or bearer tokens, depending on your security needs.

  • For single-tenant nodes, Aspera recommends that you manage security with access keys. If all users share the same storage, Node API credentials can be used; however, /files/{id} does not support Node API credential authentication and a different set of files management endpoints must be used instead.
  • For multi-tenant nodes, if your application serves as a broker between front-end clients and the node, then you should manage security with access keys. If your application allows clients to interact directly with the node, then bearer tokens offers a more secure authentication method.

Creating Node API Credentials

Node API credentials are created and associated with a transfer user (a system user that is configured on the Aspera node). When you use Node API is controlled by the restriction or docroot that is configured for the associated transfer user. The node user is allowed the same access to storage as the associated transfer user; when multiple clients share the same node user, they have the same access to the storage.

Node API credentials are created and managed on the node by using the asnodeadmin command line tool, which requires administrator or root privileges. The system user who is running asnodeadmin does not need to be the same user who is associated with the Node API credentials.

For instructions on configuring your server and creating a Node API credentials, see “Node API Setup” in the IBM Aspera High-speed Transfer Server Admin Guide.

Creating an Access Key

For instructions on creating access keys for HST Server and AOD, see “Access Keys” in the “Authentication and Authorization” section of the IBM Aspera High-Speed Transfer Server Admin Guide or the Node API endpoint reference in API Explorer.

Creating a Bearer Token

If your HST Server is multi-tenant, you may want to use bearer token authentication instead of access keys. Bearer tokens are created from an access key ID and secret, and an SSL private-public key pair.

Note: This bearer token is different from the kind that are used to authenticate Node API requests to Aspera on Cloud nodes. See the Files API documentation for more information.

For instructions on creating bearer tokens for HST Server and AOD, see “Bearer Tokens” in the “Authentication and Authorization” section of the IBM Aspera High-Speed Transfer Server Admin Guide.

Examples

  • To authenticate your request with Node API credentials:
    curl -i -u node_username:node_password -X GET https://10.0.0.1:9092/info
  • To authenticate your request with an access key:
    curl -i -u access_key_id:access_key_secret -X GET https://10.0.0.1:9092/info
  • To authenticate your request with a bearer token:
    curl -i -H "Authorization: Bearer jg3904ts48thj348thll4tj4l8h" -H "X-Aspera-AccessKey: eirn23rual3u3824ul283rj3rnawlrh" -X GET https://10.0.0.1/files/1/files

HTTP Basic Authentication Header

HTTP Basic Authentication credentials can be provided in an Authorization header as part of the HTTP request. For example,

curl -i -H "Authorization: Basic jg3904ts48thj348thll4tj4l8h" -X GET https://10.0.0.1:9092/info

The basic auth string is created by base64-encoding Node API credentials or an access key ID and secret.

To create a basic auth string:

Linux, macOS, and other Unix-like operating systems

  • Access key ID and secret
    $ echo -n access_key_id:access_key_secret | base64
  • Node API credentials
    $ echo -n node_username:node_password | base64

If the string 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

    or for Node API credentials

    node_username:node_password
  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.