Node API Authentication and Authorization

Documentation deprecated: This documentation is no longer being updated as of 3.8.0. For up-to-date information, see the guide information in the IBM Developer Community and the endpoint reference in IBM API Explorer.

To authenticate and authorize requests to the Aspera Node API endpoints you can use:

  • HTTP Basic Auth - Provide either Node API credentials (a node username and password) or an access key ID and secret.
  • Bearer token - Provide in the API request header. Supported for most endpoints.

The method you use for your application depends on how your application interacts with Aspera nodes and the number of tenants that share the storage.

Choosing an Authorization Method

  1. How many tenants will access your Aspera node?
    • One (Single-tenant, like Shares or Faspex): go to question 2
    • Many (Multi-tenant, like ATS or Files): go to question 3

  2. Do your users require separate spaces in the storage on the node (by user or group), or can they share the same storage?
  3. How is the Node API accessed by your application? Does your application serve as a broker between front-end clients and the node (like ATS), or does it allow clients to interact directly with the node (like Files)?

Node API Credentials

Node API credentials are created and associated with a transfer user (a system user that is configured on the Aspera server).

When using Node API credentials to authorize a Node API request, the request is authenticated by the node username and password, and access 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 users can authorize access to their storage, or a path within their storage, for other node users by creating access keys.

Creating Node API Credentials:

Node API credentials are created and managed on the server 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 will be associated with the Node API credentials.

  1. Select or create a system user on the server.
    Note: If this user will be associated with a node user that will be used to create access keys or bearer tokens, Aspera recommends that you set up SSH private-public key authentication for the user.
  2. Restrict the user's access to the file system.

    If you need to support access key or bearer token authorization, then configure a restriction for the user . Otherwise, configure a docroot.

    • Configure a restriction:
      Run the following command:
      # asconfigurator -x "set_user_data;user_name,username;file_restriction,|restriction"

      Where username is the system username, | is a delimiter (to configure multiple restrictions, separate them with "|"), and restriction is specific to the storage type and path, or stream source:

      Storage Type Format Example
      local storage For Unix-like OS:
      • specific folder: file:////folder/*
      • drive root: file:////*
      For Windows OS:
      • specific folder: file:///c%3A/folder/*
      • drive root: file:///c*
      Amazon S3 and IBM Cloud Object Storage - S3 s3://*
      Azure azu://*
      Azure Files azure-files://*
      Azure Data Lake Storage adl://*
      Swift swift://*
      Alibaba Cloud oss://*
      Google Cloud gs://*
      HDFS hdfs://*

      For FASPStream transfers that are managed with the Node API, the restriction can be set to allow all access (*) or limited by protocol, hostname or path:

      Restriction Format Example
      By protocol udp://*
      tcp://*
      By protocol and hostname udp://hostname*
      By protocol, hostname, and port udp://hostname:5000*
    • Configure a docroot:
      Run the following command:
      # asconfigurator -x "set_user_data;user_name,username;absolute,docroot"

      Where username is the system username and docroot is the area of the storage to which the user has access. For local storage, the docroot is the absolute path. For docroots in object storage, see "Setting Docroots for Object Storage and HDFS" in the IBM Aspera Enterprise Server Admin Guide for Linux or Windows.

    Once the system user is configured with a docroot or restriction, they are a transfer user who can run Aspera transfers (if allowed by the server).

  3. Set the user's login shell to aspshell by running the following command:
    # sudo usermod -s /bin/aspshell username
  4. To enable node-to-node transfers, set the Aspera Connect public SSH key as an authorized key for the transfer user, and ensure that they own the file, by running the following commands:
    $ mkdir /home/username/.ssh
    $ cp /opt/aspera/var/aspera_tokenauth_id_rsa.pub /home/username/.ssh/authorized_keys
    $ chmod 700 /home/username/.ssh
    $ chmod 600 /home/username/.ssh/authorized_keys
    $ chown -R username:username /home/username/.ssh
  5. Associate a node username and password with the transfer user by running the following command:
    # /opt/aspera/bin/asnodeadmin -a -u node_username -p node_user_password -x transfer_username

    A transfer user can be associated with multiple sets of Node API credentials, so you do not need to create a new system user for each node user.

  6. Confirm that the node user credentials were successfully added to the node database by running the following command:
    # /opt/aspera/bin/asnodeadmin -l

    The output lists any node users in the node database, the transfer user with which they are associated, and their ACLs. For example, if node user node_admin is associated with the system user root and has admin ACLs, the output is the following:

    # /opt/aspera/bin/asnodeadmin -l
    List of node user(s):
              user          system/transfer user                    acls
     =============      ========================     ===================
            aspera                          root                 [admin]
  7. Test the node user credentials by running the following command:
    $ curl -u node_username:node_user_password -ki https://localhost:9092/info

    If successful, the output is a JSON object that lists information about the node.

Authorizing a Node API Request with Node API Credentials:
Enter the credentials as the value for the -u option. For example:
# curl -i -u node_username:node_user_password -X POST https://localhost:9092/access_keys -d @payload.json

Managing Node Users:
The asnodeadmin tool can also be used to manage node users. You must have admin/root privileges to run asnodeadmin.
  • Change Password
    # /opt/aspera/bin/asnodeadmin -m -u node_username -x transfer_username -p new_password
  • Delete Node User
    # /opt/aspera/bin/asnodeadmin -d -u node_username

For more information about asnodeadmin options, run asnodeadmin -h.

Access Key Authorization

An access key ID and secret allows access to the storage, or a path within the storage, of the node user who created the access key. Access keys follow the same model as node user authorization, in that the request is authenticated by the access key ID and secret, and access is controlled by the path that is configured for the access key. Access key users can authorize restricted access to their storage for other node users by creating sub-access keys or bearer tokens.

Creating an Access Key:
Access keys are created on the server by sending a POST request to the /access_keys endpoint, which requires node credentials to authenticate the request. To use access key authentication and authorization:
  1. Create node credentials.
  2. Use the node credentials to create access keys.
Authorizing a Node API Request with Access Key Credentials:
Enter the access key ID and secret as the value for the -u option. For example:
# curl -i -u access_key_id:access_key_secret -X GET https://{domain}:9092/events?after_time=2018-01-18T05:20:00Z&count=50

Bearer Tokens

A bearer token grants restricted access and restricted permissions to the storage authorized by the access key. When using bearer token authorization, the request is authenticated by the access key. Access is controlled by the path specified in the access key, the user ID, and the group ID specified in the bearer token, and the permissions that are set on the file.

Creating a Bearer Token:

Bearer tokens are created from an access key ID and secret, and an SSL private-public key pair. With Enterprise Server version 3.8.0 or later, they can also be created by using the asnodeadmin tool, which automatically generates an SSL private-public key pair and builds the bearer token. They can be also created by programatically building the token from an SSL key pair and an access key.

  • Using asnodeadmin
    To create a bearer token with asnodeadmin, run the following command. If you do not specify an SSL key file or directory, you are asked if you want to create one and the filename for the private key. The bearer token is returned to standard out.
    # /opt/aspera/bin/asnodeadmin -u node_username -p node_user_password \
        --bearer-create \
        --access-key access_key_id \
        --user-id user_id \
        --expires-at UTC_date \ 
        --group-ids id1,id2,… \
        --key-file-dir dir \
        --key-file-path filepath \
        --scope-role {user|admin} \
        --token-key-length  length
    Option Required Value Type Value Description
    -u, --user Required String The node username.
    -p, --pwd, --password Required String The node user's password.
    --bearer-create Required N/A N/A
    --access-key Required String The ID of the access key that is used to create the bearer token
    --user-id Required String The ID of the user who is granted permissions to content in the storage by /permissions.
    --group-ids Optional String The ID of the group that is granted permissions to content in the storage by /permissions.
    --expires-at Optional UTC time The expiration date of the bearer token in UTC format. For example, 2016-06-23T13:21:58.453Z. Default expiration is 1 hour after token creation time.
    --key-file-dir Optional String If you have an SSL private-public key pair to use for the bearer token, specify the path to their directory.
    --key-file-path Optional String If you have an SSL private-public key pair to use for the bearer token, specify the pathname for the private key file.
    --scope-role Optional String The access level of the bearer token. Value can be admin (default) or user. admin can change the access key configuration, user cannot.
    --token-key-length Optional Integer The length of the RSA key. Must be a power of 2 between 1024 bits (128 bytes) and 16384 bits (2048 bytes). Default key length is 4096 bits.
  • Manual build
    For instructions on manually building a bearer token, see "Bearer Tokens" in the IBM Aspera Enterprise Server Admin Guide.
Authorizing a Node API Request with a Bearer Token:
Enter the token string as the value for the authorization header and the access key as the value for the access key header. For example:
# curl -i -X POST https://{domain}:9092/ops/transfers \
     -H "Authorization: Bearer bearer_token_string" \
     -H "X-Aspera-AccessKey: access_key_id" \
     -d @transfer_spec.json

Setting Permissions on Files:
For instructions on creating permissions with the Node API, see Permissions.
Video player

Video

×