An Aspera on Cloud (AoC) bearer token is used to:

  • Manage AoC (including create packages, manage nodes, manage users) with the Files API
  • Transfer content to and from an AoC node with the Node API
  • Create Aspera on Cloud transfer service (AoCts) API Keys

The following instructions describe how to:

  1. Set up the user who will send requests to the Files API, ATS API, or Node API
  2. Create an API client ID and secret, which are used to authenticate the request for the bearer token
  3. Create the JWT token request
  4. Create an AoC bearer token
  5. Create a Node API bearer token

Setting up the User and Client

  1. The user who will use the AoC bearer token creates a private-public key pair by running the following commands:
    $ openssl genrsa -out private_key.pem 2048
    $ openssl rsa -in private_key.pem -pubout -out public_key.pem
  2. The organization admin adds the user’s public key to their profile. Go to Admin > Users > username, paste the user’s public key into their profile. Click Save to activate your changes. This step can also be done through the Files API if the admin already has an admin-scoped bearer token.
  3. If you are creating a bearer token to authenticate requests to the ATS API, the user must have both the Organization admin role and the ATS admin role enabled. If they do not, another ATS admin enables the ATS admin role for the user by going to Admin > Users > username and selecting ATS admin. Click Save to activate your changes. This step can also be done through the Files API if the admin already has an admin-scoped bearer token.
  4. Create a client ID and secret by registering an API client. The client must be configured to accept JWT tokens. You do not need to enter real values for Origin or Redirect URIs. For instructions, see Registering an API Client.

Constructing a JWT Token and Creating an AoC Bearer Token

  1. The JWT token header is the same for all JWT tokens: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.

    It is created by running the following command:

    $ echo -n '{"typ":"JWT","alg":"RS256"}' | base64 | tr '+' '-' | tr '/' '_' | tr -d '='
  2. Encode the JWT token payload by running the following command (with correct values):
    $ echo -n '{"iss":"client_id","sub":"user_email_address","aud":"https://api.asperafiles.com/api/v1/oauth2/token","nbf":valid_start_time,"exp":token_expiration_time}' | base64 | tr '+' '-' | tr '/' '_' | tr -d '='

    The payload has the following structure:

    {
      "iss": "client_id",
      "sub": "user_email_address"
      "aud": "https://api.ibmaspera.com/api/v1/oauth2/token",
      "nbf": valid_start_time,
      "exp": token_expiration_time
    }

    Where,

    • “iss” is the client ID that is generated when you register an API client.
    • “sub” is the email address of the user who will use the bearer token for authentication.
    • “aud” is always “https://api.ibmaspera.com/api/v1/oauth2/token”.
    • “nbf” is the Unix timestamp when the bearer token becomes valid, for example 1524616200.
    • “exp” is the Unix timestamp when the bearer token expires, for example 1525134600.

    For example,

    $ echo -n '{"iss":"test","sub":"admin@asperasoft.com","aud":"https://api.ibmaspera.com/api/v1/oauth2/token","nbf":1483984874,"exp":1516318468}' | base64 | tr '+' '-' | tr '/' '_' | tr -d '='
    eyJpc3MiOiJ0ZXN0Iiwic3ViIjoiYWRtaW5AYXNwZXJhc29mdC5jb20iLCJhdWQiOiJodHRwczovL2FwaS5hc3BlcmFmaWxlcy5jb20vYXBpL3YxL29hdXRoMi90b2tlbiIsIm5iZiI6MTQ4Mzk4NDg3NCwiZXhwIjoxNTE2MzE4NDY4fQ
  3. Sign the combined header and payload with the user’s private key and encode the signature by running the following command (in this example, private_key.pem is the user’s private key file):
    $ echo -n encoded_header.encoded_payload | openssl dgst -sha256 -sign private_key.pem | base64 | tr '+' '-' | tr '/' '_' | tr -d '='

    For example,

    $ echo -n eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ0ZXN0Iiwic3ViIjoiYWRtaW5AYXNwZXJhc29mdC5jb20iLCJhdWQiOiJodHRwczovL2FwaS5hc3BlcmFmaWxlcy5jb20vYXBpL3YxL29hdXRoMi90b2tlbiIsIm5iZiI6MTQ4Mzk4NDg3NCwiZXhwIjoxNTE2MzE4NDY4fQ | openssl dgst -sha256 -sign private_key.pem | base64 | tr '+' '-' | tr '/' '_' | tr -d '='
    io-t_tVHwA_4qGRC6uBXtjAsyxfJsBwSdAxTsocyX6oERUdRKaXFammUCdb6PmSxtaB88I912lpgIK4Wwrb55p7AFrZjKmcmBN5AZJrhPAB-J3d1M_7h8chLZUoFGS6ny5NgInRsk1I_qdTCCe9pUTNpcv7MRErvmgcNTcJqZ21nrFYlQM8DX8rezs1rwH7nDHDzA-9U5E_J9e19v-tRmTJHAxhpeeDrlvgRiS84bW3_2msF9tNSMTjcckGq4XvgLtgc4eMLN4BSLjp7Q9FKZwSxx_Ry-N_U972fo_aHXakstxGxtim8CCGWAkpu1AnoW-zrv0Kk1IXNU4qY-bwX6w
  4. Request a bearer token by sending the following request to the Files API:
    $ curl -i -u client_id:secret -H "Content-Type: application/x-www-form-urlencoded" -X POST https://api.ibmaspera.com/api/v1/oauth2/{org_name}/token -d"assertion=encoded_header.encoded_payload.encoded_signature&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&scope=scope"

    The scope can be one of the following:

    Scope Description
    user:all Allows access to AoC user features, including creating and modifying packages and files; retreiving node and organization information; and managing contacts. User-scoped tokens do not allow the user to create nodes, manage other users, or manage workspaces.
    admin:all Allows access to AoC admin features, including creating nodes, managing workspaces, and adding users to workspaces. Admin-scoped bearer tokens have shorter expirations and require re-authenticating more frequently.
    • Note: Because the scope of the token affects the function of the Files API endpoints, Aspera recommends that you use user-scoped bearer tokens for user-specific activity, and admin-scoped tokens for admin activity.

    • Transfer Service Users: If you are creating a bearer token to use to authenticate requests to the ATS API, the scope must be a type of admin as either of the following:

      • admin:all (URL-encoded as admin%3Aall) – Use if you do not already have a transfer service access key. Note: This allows the user access to the entire cloud storage.
      • node.{access_key_id}.admin:all (URL-encoded as node.{URL-encoded_access_key}%3Aadmin%3Aall) – Use if you have an access key and want to restrict access to the cloud storage to the path that is defined in the access key.

    For example,

    $ curl -i -u 61in8fhrw:zHslLvyJRxzrTrRnskTbl3JYlQAmF17lhvJbES -H "Content-Type: application/x-www-form-urlencoded" -X POST https://api.asperafiles.com/api/v1/oauth2/organization424/token -d"assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ0ZXN0Iiwic3ViIjoiYWRtaW5AYXNwZXJhc29mdC5jb20iLCJhdWQiOiJodHRwczovL2FwaS5hc3BlcmFmaWxlcy5jb20vYXBpL3YxL29hdXRo42Mi90b2tlbiIsIm5iZiI6MTQ4Mzk4NDg3NCwiZXhwIjoxNTE2MzE4NDY4fQ.io-t_tVHwA_4qGRC6uBXtjAsyxfJsBwSdAxTsocyX6oERUdRKaXFammUCdb6PmSxtaB88I912lpgIK4Wwrb55p7AFrZjKmcmBN5AZJrhPAB-J3d1M_7h8chLZUoFGS6ny5NgInRsk1I_qdTCCe9pUTNpcv7MRErvmgcNTcJqZ21nrFYlQM8DX8rezs1rwH7nDHDzA-9U5E_J9e19v-tRmTJHAxhpeeDrlvgRiS84bW3_2msF9tNSMTjcckGq4XvgLtgc4eMLN4BSLjp7Q9FKZwSxx_Ry-N_U972fo_aHXakstxGxtim8CCGWAkpu1AnoW-zrv0Kk1IXNU4qY-bwX6w&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&scope=user%3Aall"
    HTTP/1.1 201 Created
    {
        "access_token":"eJwdkNuOokAURd/5DF4dQgElFxMflIuIAtqAFzqdDpcSUcSyoFTozL8PPQ8n2VlZ2Ts5PyxtEPkuc3bCiuwftsnuGA35l06SqhoQeuOSoOY7aX8dICgcEDhBC0UwEZQJAPHgUPq/QREUkAqJzMkwyzh4gimX5ILGpZmWKTmEQMpPg12QO8XDZsNOPllhAOPhJPbrLzOdBsuFNwujD3M6ZXB109dCHirLo296RjAmqxFd1LkR39uVG5OHrZ6XzsOOjlgsna19t6o0HgeF61U94yu+BC31fUqKdiOVNJBI5p59Y7spu6KuK/jRi2htBy4Jm9IKZY1/JOpxDbGSvph3V89Sq6eWi1Rt1+4lpGnt6CiPlsg6FJ7m392NuZnLHtEF7Iid7CWxfeGNuo1C5rz33eIBQEgJwn2a2wdI67C9oWB3RbzlXC295AGYz66pEu9pYnvzC32BGswvL4b0wPRETBIM1O6lNry2Q/tqcT0fbqbTdcdTaXQ38KaR7VFYBhtdvUHB4hdPBzXMOyHRFrqJWvHSc/H01wcU87oum3KP9Og6Gq+NEGOyWs2G7/4DxMqeUg==",
        "token_type":"bearer",
        "expires_in":3599,
        "scope":"admin:all"
    }

    Record the value for “access_token”, which is the bearer token that the user can use to authenticate requests to the Files API, and note when the token expires (“expires_in” is reported in seconds).

This AoC bearer token can now be used to authenticate requests to the Files API or the ATS API. It cannot be used to authenticate requests to the Node API, including transfers with /ops/transfers; see the following instructions for requesting a Node API bearer token that can be used to authenticate Node API requests to Aspera on Cloud nodes.

Using the AoC Bearer Token to Create a Node API Bearer Token

The AoC bearer token cannot be used to authenticate requests to the Node API. Instead, you request a Node API bearer token that contains node-specific information.

  1. Retrieve the access key that is associated with the AoC bearer token and the node URL (the target of your Node API requests) by sending the following request to the Files API:
    curl -i -H "Authorization: Bearer token_string" -X GET https://api.asperafiles.com/api/v1/nodes

    For example,

    $ curl -i -H "Authorization: Bearer eyIwMTgtMDUtMjNUpbmUiLCy" -X GET https://api.asperafiles.com/api/v1/nodes
    HTTP/1.1 200 OK
     
    [{"access_key":"hMBQmvNhEILmR42hm904lR22TmdV8-1BA-aslep4L6I",
    "capabilities":[
         {"name":"sync","value":true},
         {"name":"watchfolder","value":true},
         {"name":"symbolic_links","value":false},
         {"name":"move_file","value":true},
         {"name":"move_directory","value":false},
         {"name":"filelock","value":true},
         {"name":"ssh_fingerprint","value":true}],
     "configuration_policy_id":null,
     "host":"files-qa-aejd.qa.ibmaspera.com",
    "id":"1913",
    "name":"files-qa-aejd.qa.ibmaspera.com",
    "path":"/","port":443,
    "settings":[
         {"name":"content_protection_required","value":false},
         {"name":"content_protection_strong_pass_required","value":false},
         {"name":"filelock_restriction","value":"none"},
         {"name":"ssh_fingerprint","value":"3494mgel4j634543ij"}],
    "status":"ok",
    "url":"https://files-qa-aejd.qa.ibmaspera.com:443/",
    "use_ssl":true,
    "verify_ssl_certificate":true,
    "network_policy_id":null,
    "ats_access_key":false,
    "ats_storage_type":null,
    "ssh_fingerprint":null}]

    Record the values for “access_key” and “url”.

  2. Request a Node API bearer token by sending the following request to the Files API:
    $ curl -i -u client_id:secret -H "Content-Type: application/x-www-form-urlencoded" -X POST https://api.ibmaspera.com/api/v1/oauth2/{org_name}/token -d"assertion=encoded_header.encoded_payload.encoded_signature&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&scope=scope"

    Important: For the Node API bearer token, the scope must include the access key, as node.access_key.user:all or node.access_key.admin:all.

    Scope Description
    node.url-encoded-ak:user:all Allows access to files, folders, and permissions on the node that is associated with the access key, within the tenant space that is set in the access key.
    node.url-encoded-ak:admin:all Allows administration of the access key and its storage on the node, as well as access to all content in the tenant space.

    For example,

    $ curl -i -u 61in8fhrw:zHslLvyJRxzrTrRnskTbl3JYlQAmF17lhvJbES -H "Content-Type: application/x-www-form-urlencoded" -X POST https://api.ibmaspera.com/api/v1/oauth2/organization424/token -d"assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ0ZXN0Iiwic3ViIjoiYWRtaW5AYXNwZXJhc29mdC5jb20iLCJhdWQiOiJodHRwczovL2FwaS5hc3BlcmFmaWxlcy5jb20vYXBpL3YxL29hdXRoMi90b2tlbiIsIm5iZiI6MTQ4Mzk4NDg3NCwiZXhwIjoxNTE2MzE4NDY4fQ.io-t_tVHwA_4qGRC6uBXtjAsyxfJsBwSdAxTsocyX6oERUdRKaXFammUCdb6PmSxtaB88I912lpgIK4Wwrb55p7AFrZjKmcmBN5AZJrhPAB-J3d1M_7h8chLZUoFGS6ny5NgInRsk1I_qdTCCe9pUTNpcv7MRErvmgcNTcJqZ21nrFYlQM8DX8rezs1rwH7nDHDzA-9U5E_J9e19v-tRmTJHAxhpeeDrlvgRiS84bW3_2msF9tNSMTjcckGq4XvgLtgc4eMLN4BSLjp7Q9FKZwSxx_Ry-N_U972fo_aHXakstxGxtim8CCGWAkpu1AnoW-zrv0Kk1IXNU4qY-bwX6w&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&scope=node.hMBQmvNhEILmR42hm904lR22TmdV8-1BA-aslep4L6I%3Aadmin%3Aall"
    HTTP/1.1 201 Created
    {
        "access_token":"eJwdkNuOokAURd/5DF4dQgElFxMflIuIAtqAFzqdDpcSUcSyoFTozL8PPQ8n2VlZ2Ts5PyxtEPkuc3bCiuwftsnuGA35l06SqhoQeuOSoOY7aX8dICgcEDhBC0UwEZQJAPHgUPq/QREUkAqJzMkwyzh4gimX5ILGpZmWKTmEQMpPg12QO8XDZsNOPllhAOPhJPbrLzOdBsuFNwujD3M6ZXB109dCHirLo296RjAmqxFd1LkR39uVG5OHrZ6XzsOOjlgsna19t6o0HgeF61U94yu+BC31fUqKdiOVNJBI5p59Y7spu6KuK/jRi2htBy4Jm9IKZY1/JOpxDbGSvph3V89Sq6eWi1Rt1+4lpGnt6CiPlsg6FJ7m392NuZnLHtEF7Iid7CWxfeGNuo1C5rz33eIBQEgJwn2a2wdI67C9oWB3RbzlXC295AGYz66pEu9pYnvzC32BGswvL4b0wPRETBIM1O6lNry2Q/tqcT0fbqbTdcdTaXQ38KaR7VFYBhtdvUHB4hdPBzXMOyHRFrqJWvHSc/H01wcU87oum3KP9Og6Gq+NEGOyWs2G7/4DxMqeUg==",
        "token_type":"bearer",
        "expires_in":899,
        "scope":"node.hMBQmvNhEILmR42hm904lR22TmdV8-1BA-aslep4L6I:admin:all"
    }
  3. To confirm that your Node API bearer token works, run a test Node API request:
    curl -i -H "Authorization: Bearer token_string" -H "X-Aspera-AccessKey: access_key" -X GET https://node_url:443/info

    For example,

    curl -i -H "Authorization: Bearer eJwlUNmOokAAfOczeGVZ6QNtTHxARQdhNByCsNlMWroFlGsAlXGy/75k97GOVFXqW7x3vP3ImTgXMQCaJv4Qu6Ru+IirmvGf2fvSKR/7zDDt0sUwKzUFFy6EfskCIoOlLtOu4A22p+acsjKv5rQoxhA+NHnLuw/aj0lQAURWVBkBH5A5UueIxKPnfv/XSxknyhljmSMNypgzJNPLRZHJmVwoJYTNZnB0121Kq/xF+7yu/g8GaKapo5K29b0ZqU6c/xLhFKpA/P1HWCw8c7vX/aNrLBbCDQSpwl6m8dj2dhHrN2e4ams77g/bw6WM3DVuwZqaEExyPTKqtpJo09xNwPFpEN7s6VDf0tZOk5e/+QJRi9fxEy9X/Om5J0z9Z7qZBk4qxZYF1oS16ip9v9rBbrCRYOJKjTQ37/X7KUBN2qKuPH6V0qMMO/0BNsWrVK0At6cM6Ak0QueEAJ35n3V8GAQpD44opIlxnAVkXXWvJtqOL0MpCTfkERUT4/p4HY4g9g6FxiQ0jQ0nY53EyLkTvHBV+oEjVU09YIvnVmx9nuvd9ES4ubF3albDFJmGO9G3LLF7qZvB2Mpos4zjqwDCDhn7qtdD70m2+Kk7Z/+iMe+tybw0SxzVHrJJi46RM777F7tAth4=" -H "X-Aspera-AccessKey: hMBQmvNhEILmR42hm904lR22TmdV8-1BA-aslep4L6I" -X GET https://files-test.asperafiles.com:443/info

You can now use the bearer token to authorize a Node API transfer request to an Aspera on Cloud node. For instructions, see Node API Security.