Authentication

The Aspera Mobile SDK supports several methods of account authentication as well as an additional transfer authentication mechanism (via tokens).

Account authentication is required in order to establish a connection with the remote server, that is to say it is a mandatory process carried out at the very beginning of any FASP transfer - if it fails, the transfer fails. Supported methods include password authentication and public-key authentication.

Token authentication is an additional (optional) transfer authentication mechanism. It is usually leveraged to implement a virtual user base on top of regular transfer accounts (which are system accounts), and can in general be used to exercise finer control on a per-transfer basis. Tokens are verified by the server only after account authentication has succeeded, so tokens come into play at a later stage of the transfer process.

Together these mechanisms provide a flexible platform for deciding which transfers to authorize. The basic uses of each are described below.

Account Authentication

Each FASP session must at the very beginning authenticate using a system account on the remote server. The ASFaspSessionParameters instance used to construct an ASFaspSession instance determines the authentication method and parameters. Two authentication methods are possible: password authentication and public-key authentication.

In order to use password authentication set the password attribute on the ASFaspSessionParameters instance and avoid setting the privateKeyFilename attribute. The following sample code creates an ASFaspSessionParameters instance describing a download that will use password authentication against a server at the address example.com for the user usr1 with password testpw:

Objective-C     Swift
    ASFaspSessionParameters *parameters;
    parameters = [ASFaspSessionParameters uploadSessionWithHost:@"example.com" user:@"usr1"];
    parameters.password = @"testpw";

    let parameters = ASFaspSessionParameters.uploadSessionWithHost("example.com", user:"usr1");
    parameters.password = "testpw";

If a session is then constructed using these parameters it will use password authentication for the transfer.

Alternatively in order to use public key authentication set the privateKeyFilename attribute on the FaspSessionParamerters and avoid setting the password attribute. For instance, a transfer to the same server using a private key:

Objective-C     Swift
    ASFaspSessionParameters *parameters;
    parameters = [ASFaspSessionParameters uploadSessionWithHost:@"example.com" user:@"usr1"];
    parameters.privateKeyFilename = @"/path/to/key";

    let parameters = ASFaspSessionParameters uploadSessionWithHost("example.com", user:"usr1")
    parameters.privateKeyFilename = "/path/to/key";

If the key requires a passphrase use privateKeyPassphrase to set one. Keys should be in the OpenSSH/OpenSSL format. The default private key used by connect is provided in the SDK via ASConnectPrivateKey. First it must be written to disk:

Objective-C     Swift
    NSError *err = nil;
    ASConnectPrivateKey *connectKey = [ASConnectPrivateKey sharedKey];
    BOOL success = [connectKey writeToDisk:@"/tmp/key.p12" error:&err];

    do {
        try ASConnectPrivateKey.sharedKey().writeToDisk("/tmp/key.p12")
    }
    catch {
        print("Error writing key to disk: (error)")
    }

Then it can be used in session parameters:

Objective-C     Swift
    parameters.privateKeyFilename = [[ASConnectPrivateKey sharedKey] path];
    parameters.privateKeyPassphrase = [[ASConnectPrivateKey sharedKey] passphrase];

    parameters.privateKeyFilename = ASConnectPrivateKey.sharedKey().path!
    parameters.privateKeyPassphrase = ASConnectPrivateKey.sharedKey().passphrase!

Token Authentication

Token authentication provides an additional transfer-specific authentication mechanism for FASP transfers. A server system account that is configured to require tokens will only allow transfers that contain a valid transfer token (see the token attribute on ASFaspSessionParameters). A common use case is to have one dedicated system account over which all transfers occur and to use tokens as the ultimate factor in determining which transfers to allow. In particular, tokens may be provided by the server based on external factors, for instance an external authentication process carried out via REST APIs that is part of a virtual user model. It is the embedding application’s responsibility to obtain a transfer token for each session. If an attempt is made to transfer using a system account that requires token authentication but no token is set in the transfer session then the transfer will fail.

In its simplest form all that is necessary in order to use token authentication for a given session is to set a token on a FaspSessionParameters instance and then build a session with it. Once set in this way the token will be used for token authentication by the server.

In general, token authentication is separate from account authentication and tokens may be used in conjunction with any form of account authentication. In practice when token authentication is used account authentication is often made of secondary importance by using the same account for all transfers and relying on token authentication as the primary transfer authorization mechanism (for instance one may embed a private key into the application and use this key for all sessions).