Access Key Authentication

Access key authentication provides an alternative to entering the security credentials of a Node API 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 Support:

Access key authentication can by used by Aspera client products such as IBM Aspera Desktop Client, HST Server, HST Endpoint, and IBM Aspera Drive. It can also be used by IBM Aspera Faspex, IBM Aspera Shares, and AIBM Aspera on Cloud transfer service. For details about using access key authentication with these products, see their documentation.

Access Key Restrictions:
  • The transfer user must have a file restriction configured in aspera.conf, rather than a docroot. If a docroot is configured, access key creation and use fails.
  • Access keys must specify the storage path. Although they can be created with no storage specified, transfers using these keys fail.

Access Key Creation:

  1. Configure the system user with a restriction and ensure that no docroot is configured: 
    # asconfigurator -x "set_user_data;user_name,username;absolute,AS_NULL;file_restriction,|restriction"

    The format of the restriction depends on the storage type (these examples allow access to the entire storage):

    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://*
    Alibaba Cloud oss://*
    Google Cloud gs://*
    HDFS hdfs://*

    For example, to configure the system user xfer with a restriction that allows full access to local storage:

    # asconfigurator -x "set_user_data;user_name,xfer;absolute,AS_NULL;file_restriction,|file:////*"
  2. Assign a Node API username and password to the system user. This command requires admin permissions. 
    # /opt/aspera/bin/asnodeadmin -au node_username -p node_password -x system_user

    For example, to assign the Node API username nodeuser to the system user xfer:

    # /opt/aspera/bin/asnodeadmin -au nodeuser -p asperaissofast -x xfer

    This command automatically reloads the node configuration.

  3. To create access keys, send a request to the Node API /access_keys endpoint by using curl command.

    Curl is included in many Unix-based operating systems. To determine if it is installed, run 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, run the following command on the server: 

    # curl -ki -u node_username:node_password -X POST https://localhost:9092/access_keys -d @access_key_config.json

    where access_key_config.json is the access key configuration file.

    For example,

    # curl -ki -u nodeadmin:superP@55wOrD -X POST https://localhost:9092/access_keys -d @/nodeadmin/ak_client1.json

    Access Key Configuration

    The access key configuration is specified in JSON. Only the "storage" object is required; the Node API creates an access key ID and secret if they are not provided.

    Note: If your access key configuration is simple, you can specify it on the command line, replacing -d @ access_key_config.json with an argument like -d'{"storage":{"type":"local","path":"/projects/project1"}}'.
    {
    "id" : "access_key_id",
    "secret" : "access_key_secret",
    "token_verification_key" : "token_key",
    "storage" : {
         storage_configuration
         },
    "license" : {
        "customer_id" : "customer_id",
        "entitlement_id" : "entitlement_id"
    },
    "configuration" : {
        "transfer" : {
            "cipher" : "cipher",
            "policy" : "policy",
            "target_rate_kbps" : target_rate,
            "target_rate_cap_kbps" : target_rate_cap,
            "content_protection_secret" : "secret",
            "preserve_timestamps" : true|false,
            "aggressiveness" : "aggressiveness",
        },
        "server" : {
            "activity_event_logging" : true|false,
            "recursive_counts" : true|false,
        }
    },
    "files_filelock_enabled" : true|false,
    "files_filelock_restriction" : "restriction"
    }
    Element Required Type Description
    id Optional String ID of the access key. Returns 209 (conflict) if it already exists. If it is not provided, the Node API creates an ID and returns the value in the response.
    secret Optional String Access key secret. If it is not provided, the Node API creates a secret and returns the value in the response.
    token_verification_key Optional String Required when the access key is used to create a bearer token, the public key corresponding to the private key that is used to create the bearer token.
    storage Required JSON Storage specification object. See examples following this table.
    license Optional JSON object Entitlement information, similar to regular Aspera on Demand. This is needed when the access key logs against SafeNet.
    customer_id Optional String Customer ID
    entitlement_id Optional String ID of the entitlement
    configuration Optional JSON object The transfer and server configuration object.
    transfer Optional JSON object The transfer configuration object. Available as of 3.8.0.
    cipher Optional String The encryption mode and minimum cipher key length allowed by the server for transfers that are authorized by this access key. Default is unset, such that the transfer authorized by the access key must respect the server configuration.

    Aspera supports three sizes of AES cipher keys (128, 192, and 256 bits) and supports two encryption modes, cipher feedback mode (CFB) and Galois/counter mode (GCM). The GCM mode encrypts data faster and increases transfer speeds compared to the CFB mode, but the server must support and permit it.

    Note: To ensure client compatibility when requiring encryption, use a cipher with the form aes-XXX, which is supported by all clients and servers. Requiring GCM causes the server to reject transfers from clients that are running a version of Ascp 3.8.1 or older. When a client requests a shorter cipher key than is configured on the server (or in an access key that authorizes the transfer), the transfer is automatically upgraded to the server setting. For more information about how the server and client negotiate the transfer cipher, see the description of -c in the Ascp Command Reference.

    Cipher values

    • none - require unencrypted transfers (not recommended).
    • aes-128, aes-192, or aes-256 - allow transfers that use an encryption cipher key that is as long or longer than the setting. These settings use the CFB or GCM mode depending on the client version and cipher requested. Supports all client versions.
    • aes-128-cfb, aes-192-cfb, or aes-256-cfb - require that transfers use the CFB encryption mode and a cipher key that is as long or longer than the setting. Supports all client versions.
    • aes-128-gcm, aes-192-gcm, or aes-256-gcm - require that transfers use the GCM encryption mode introduced in version 3.9.0 and a cipher that is as long or longer than the setting.

    For more information about server cipher configuration, see aspera.conf - Authorization Configuration.

    policy Optional String The policy allowed for transfers that are authorized by this access key. Value can be high, regular, fair, low, trickle, or fixed. Aspera recommends against setting the policy to fixed, which can result in the transfer rate exceeding network or storage capacity if the client also requests a high minimum transfer rate that is not capped by the server. This can decrease transfer performance and cause problems on the target storage. To avoid these problems, set the allowed policy to fair. Available as of 3.8.0.
    target_rate_kbps Optional Integer The default initial rate for transfers that are authorized by this access key, in kilobits per second. Available as of 3.8.0.
    target_rate_cap_kbps Optional Integer The maximum target rate for transfers that are authorized by this access key, in kilobits per second. Available as of 3.8.0.
    content_protection_secret Optional String Provide a password to require that content be encrypted by the client (enforce client-side encryption-at-rest) for transfers that are authorized by this access key. Available as of 3.8.0.
    preserve_timestamps Optional Boolean Set to true to preserve file access and modification timestamps for transfers that are authorized by this access key. The server configuration overrides the access key configuration. Timestamp support in object storage varies by provider; consult your object storage documentation to determine which settings are supported. Default is unset, such that the access key inherits the server configuration. Available as of 3.8.0.
    aggressiveness Optional Float The aggressiveness of transfers that are authorized by this access key in claiming available bandwidth. Value can be 0.00-1.00. Available as of 3.8.0.
    server Optional JSON object The server configuration object. Available as of 3.8.0.
    activity_event_logging Optional Boolean Set to true to allow the Node API to query transfers that are associated with this access key through the /events endpoint. The access key configuration overrides the server configuration. This option must be enabled for event reporting to IBM Aspera on Cloud. Default is unset, such that the access key inherits the server configuration. Available as of 3.8.0.
    recursive_counts Optional Boolean Set to true to enable recursive counts. The access key configuration overrides the server configuration. This option must be enabled for event reporting to IBM Aspera on Cloud. Default is unset, such that the access key inherits the server configuration. Available as of 3.8.0.
    files_filelock_enabled Optional Boolean Set to true to allow the access key user to create filelocks. Filelocks cannot be set if filelocks are disabled on the server (files_filelock_enabled is set to false in aspera.conf). Available as of 3.8.0.
    files_filelock_restriction Optional String Set to none to allow the access key user to write, delete, or rename files if they are not locked or if the filelock was applied by the user. Set to write to allow the access key user to write, delete, or rename files only if the filelock was applied by the user. Available as of 3.8.0.

    Minimum Access Key Configuration - The Storage Object

    The "storage" section requires different values, depending on the storage type. The following examples contain the minimum information required to create an access key, and can be cut and pasted into a text file for editing.

    Local storage
    {"storage" : {
    "type" : "local",
    "path" : "path"
}}

    Because local storage objects are simple, you can create your access key by specifying the storage in the command line:

    # curl -ki -u nodeadmin:superP@55wOrD -X POST https://localhost:9092/access_keys -d'{"storage":{"type":"local","path":"/projects/project1"}}
    Amazon S3
    {"storage" : {
    "type" : "aws_s3",
    "endpoint" : "s3.amazonaws.com",
    "bucket": "bucket",
    "path" : "/path",
    "storage_class" : "STANDARD|REDUCED_REDUNDANCY|INFREQUENT_ACCESS",
    "server_side_encryption" : "AES256|AWS_KMS",
    "server_side_encryption_aws_kms_key_id" = "arn_encryption_key",
    "credentials" : {
        "type" : "key|iam-role|assume-role",
        "access_key_id" : "aws_access_key",
        "secret_access_key" : "secret_access_key",
        "iam_role_name" : "iam_role",
        "assume_role_arn": "arn:aws:iam::your_aws_account_id:role/role_name",
        "assume_role_external_id" : "external_id",
        "assume_role_session_name" : "session_name"
    }
}}

    Where:

    • If server side encryption is set to "AWS_KMS", then "server_side_encryption_aws_kms_key_id" is required and is set to the ARN of the encryption key (for example, "arn:aws:kms:us-east-1:648543846928:key/er23525-8754-84g4-8sf7-4834ngigfre45").
    • Values for credentials depend on the type of authentication you use. To authenticate with your storage access key ID and secret, only specify "access_key_id" and "secret_access_key". To authenticate with an IAM role, only specify "iam_role_name". To authenticate with an assumed IAM role, only specify "assume_role_arn", "assume_role_external_id", and "assume_role_session_name".
    Azure (Block and Page Storage)
    {"storage" : {
    "type" : "azure",
    "api" : "PAGE | BLOCK",
    "container" : "container",
    "path" : "path",
    "credentials" : {
        "storage_endpoint" : "blob.core.windows.net",
        "type": "key",
        "account" : "account_name",
        "key" : "storage_access_key"
    }
}}
    Azure Data Lake Storage
    "storage" : {
    "type" : "azure-datalake",
    "path" : "container/path",
    "storage_endpoint" : "data_lake_store_name.azuredatalakestore.net",
    "credentials" : {
        "type" : "ClientCredential", 
        "client_id" : "client_application_id",
        "refresh_url" : "https://login.windows.net/directory_id/oauth2/token",
        "client_secret" : "secret"
    }
}
    Azure SAS
    {"storage" : {
    "type" : "azure_sas",
    "container" : "container",
    "path" : "path",
    "api": "BLOCK|PAGE"
    "credentials" : {
        "shared_access_signature" : "shared_url"
    }
}}

    Where the "shared_access_signature" is the shared URL, such as https://company.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.

    Azure Files
    {"storage" : {
    "type" : "azure-files",
    "path" : "share/path",
    "credentials" : {
        "file_service_endpoint" : "https://account.file.core.windows.net/",
        "password" : "password"
    }
}}
    Google Cloud Storage
    Authenticated by a service account with a private key:
    {"storage": {
    "type" : "google-gcs",
    "storage_endpoint" : "storage.googleapis.com",
    "bucket" : "bucket",
    "path" : "/path",
    "max_segments_per_compose" : 10000,
    "credentials": {
      "type": "service_account",
      "project_id": "project_id", 
      "private_key_id": "key_id",
      "private_key": "-----BEGIN PRIVATE KEY-----key_string-----END PRIVATE KEY-----\n",
      "client_email": "client_id@developer.gserviceaccount.com",
    }
}}

    Authenticated by an OAuth token:

    {"storage" : {
    "type" : "google-gcs",
    "storage_endpoint" : "storage.googleapis.com",
    "bucket" : "bucket",
    "path" : "/path",
    "max_segments_per_compose" : 1024,
    "credentials" : {
      "type" : "oauth",
      "client_id" : "client_id",
      "client_secret" : "secret"
      "project_id" : "project_id",
      "access_token" : "access_token",
      "refresh_token" : "refresh_token",
      "token_expiration" : "token_lifetime_seconds"
      "auth_uri" : "https://accounts.google.com/o/oauth2/auth", 
      "token_uri" : "https://accounts.google.com/o/oauth2/token",
      "auth_provider_x509_cert_url" : "https://www.googleapis.com/oauth2/v1/certs",
      "client_x509_cert_url" : "https://www.googleapis.com/robot/v1/metadata/x509/client_id%40developer.gserviceaccount.com"
    }
}}
    IBM Cloud Object Storage (COS) - S3
    {"storage" : {
  "type" : "ibm-s3",
  "bucket" : "bucket",
  "path" : "/path",
  "endpoint" : "s3-api.us-geo.objectstorage.service.networklayer.com",
  "credentials" : {
	"type" : "key",
	"access_key_id" : "key_id",
	"secret_access_key" : "key_secret"
  }
}}
  4. Confirm that your access key was created and retrieve its ID by running the following command: 
    # curl -ki -u node_username:node_password -X GET https://localhost:9092/access_keys

    The output includes the ID and configuration of all access keys. For example, the following output lists an access key is for local storage:

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

[
{
    "id" : "ak_1234",
    "secret" : "j3489tht42o8y32unifhkfw38ty238h3rih",
    "token_verification_key" : "9mgr3wtl4utmf394ur2ur52jgj934864ginsrh",
    "storage" : {
        "type" : "local",
        "path" : "/"
    },
    "license" : {
        "customer_id" : "customer1",
        "entitlement_id" : "43gsdi459-23r3r-w38ron-23523ro-sr82h3r8h3r"
    },
    "configuration" : {
        "transfer" : {
            "cipher" : "aes-128",
            "policy" : "fair",
            "target_rate_kbps" : 10000,
            "target_rate_cap_kbps" : 20000,
            "content_protection_secret" : "secretsecret",
            "preserve_timestamps" : false,
            "aggressiveness" : "0.00",
        },
        "server" : {
            "activity_event_logging" : true,
            "recursive_counts" : true,
        }
    },
    "files_filelock_enabled" : true,
    "files_filelock_restriction" : "none"
}
]
  5. Test the access key.
    If your access key is configured correctly, the following command returns the files in the path that was specified in the access key configuration:
    # curl -ki -u access_key_id:access_key_secret https://localhost:9092/files/1/files