This topic describes how to set up a direct data transfer service for a mobile app in less than 30 minutes by using the Security Token Service (STS) policy. Direct data transfer allows a mobile app to directly connect to Object Storage Service (OSS) for data uploads and downloads, while only control flow is sent to the application server.

Prerequisites

Background information

In the mobile Internet era, increasing amounts of data are uploaded by using mobile apps. Developers can leave their data storage concerns to OSS and concentrate on app development.

OSS-based direct data transfer for mobile apps has the following benefits:
  • Data security: OSS allows mobile apps to upload and download data based on flexible authorization and authentication methods, which ensures better security.
  • Cost-effectiveness: Fewer app servers are required, which minimizes costs. The mobile app is directly connected to OSS for data uploads and downloads, while only the control flow is sent to the app server.
  • High concurrency: OSS supports concurrent access from a large number of users.
  • Elastic scalability: OSS provides storage space that can be scaled.
  • Data processing: OSS provides Image Processing (IMG) and ApsaraVideo Media Processing to facilitate flexible data processing.

Process

The following figure shows the development process of the direct data transfer service for mobile apps.chart
Role description:
  • Android or iOS app: an app on a mobile device that applies for and uses an STS credential from the app server.
  • OSS: processes data requests from the mobile app.
  • Resource Access Management (RAM)/STS: generates a temporary upload credential, which is a token.
  • App server: the backend service developed for the Android or iOS app. The app server is used to manage the tokens used for data uploads and downloads by using the app and the metadata of the app-uploaded data.

Procedure:

  1. The mobile app applies for a temporary upload credential from the app server.
    AccessKey pairs cannot be stored in Android and iOS apps due to security concerns. Therefore, the app must apply for a token from the app server. The token is valid only for a specified period of time. If the app server developer sets the validity period of the token to 30 minutes, the Android or iOS app can use this token to upload data to or download data from OSS within 30 minutes after the token is issued. After 30 minutes, the app must request a new token to upload or download data.
  2. The app server checks the validity of the request and then returns a token to the app.
  3. The Android or iOS app uses this token to upload data to or download data from OSS.

The following section describes how the app server generates a token and how to use the Android or iOS app to obtain a token.

Step 1: Activate STS

  1. Log on to the OSS console.
  2. In the left-side navigation pane, click Overview.
  3. In the Common Features section, choose Security Token (Authorization for RAM User) > RAM Console.
  4. Click Start, and complete authorization.
    After the authorization is complete, save the AccessKey ID, AccessKey secret, and RoleArn parameters of the RAM user.

Step 2: Configure the app server

  1. Download the app server code.
  2. Modify the configuration file.
    The following sample code is written in PHP. Each downloaded package for a specific programming language contains a config.json configuration file, which contains the following information: 
    {
"AccessKeyID" : "",
"AccessKeySecret" : "",
"RoleArn" : "",
"TokenExpireTime" : "900",
"PolicyFile": "policy/bucket_write_policy.txt"
}
    Parameter description:
    • AccessKeyID: Enter the obtained AccessKey ID.
    • AccessKeySecret: Enter the obtained AccessKey secret.
    • RoleArn: Enter the obtained RoleArn.
    • TokenExpireTime: specifies the validity period of the token obtained by using the Android or iOS app. The default value is the minimum value, which is 900 seconds.
    • PolicyFile: specifies the file that lists the permissions that the token grants. The default value can be retained.
    This topic describes two policy files that define the most common permissions. The files are stored in the policy directory. To use the policy file, replace $BUCKET_NAME and $OBJECT_PREFIX with specified values.
    • bucket_read_policy.txt: specifies that the token grants permissions to read data from the specified bucket and objects whose names contain the specified prefix for the account.
    • bucket_write_policy.txt: specifies that the token grants permissions to write data to the specified bucket and objects whose names contain the specified prefix for the account.

    For more information about permissions, see examples and implementation of policies in Overview. Follow the principle of least privilege (PoLP) based on business requirements. If you specify all resources (resource:*) or all actions (action:*), security risks such as data leaks may arise because of excess permissions.

    Warning The sample code is only for reference. The online system must implement permission isolation for different users or devices. This way, tokens that grant different permissions are generated.
  3. Run the sample code.
    Run the sample code by using the following methods:
    • Run the sample code in PHP: After the package is downloaded and decompressed, modify the config.json file. Run the php sts.php command to generate a token. Deploy the program to the app server address.
    • Run the sample code that depends on JDK 1.7 in Java: After the package is downloaded and decompressed, modify the config.json file. Reopen the package and run the java -jar app-token-server.jar (port) command. If you do not specify a port, the program starts listening on port 7080 by default. You can specify the port used for listening, but you cannot specify a port that already exists.

      You must run the java -jar app-token-server.jar command to start the services of the app server and call AssumeRole to obtain the response.

    Sample responses: 
    // Sample success responses.
{
    "StatusCode":200,
    "AccessKeyId":"STS.3p***dgagdasdg",
    "AccessKeySecret":"rpnwO9***tGdrddgsR2YrTtI",
   "SecurityToken":"CAES+wMIARKAAZhjH0EUOIhJMQBMjRywXq7MQ/cjLYg80Aho1ek0Jm63XMhr9Oc5s˙∂˙∂3qaPer8p1YaX1NTDiCFZWFkvlHf1pQhuxfKBc+mRR9KAbHUefqH+rdjZqjTF7p2m1wJXP8S6k+G2MpHrUe6TYBkJ43GhhTVFMuM3BZajY3VjZWOXBIODRIR1FKZjIiEjMzMzE0MjY0NzM5MTE4NjkxMSoLY2xpZGSSDgSDGAGESGTETqOio6c2RrLWRlbW8vKgoUYWNzOm9zczoqOio6c2RrLWRlbW9KEDExNDg5MzAxMDcyNDY4MThSBTI2ODQyWg9Bc3N1bWVkUm9sZVVzZXJgAGoSMzMzMTQyNjQ3MzkxMTg2OTExcglzZGstZGVtbzI=",
   "Expiration":"2017-12-12T07:49:09Z"
}
// Sample error responses.
{
    "StatusCode":500,
    "ErrorCode":"InvalidAccessKeyId.NotFound",
    "ErrorMessage":"Specified access key is not found."
}
    A token in a sample success response consists of the following variables:
    • StatusCode: the status of the operation to obtain the token. If the token is obtained, 200 is returned.
    • AccessKeyId: the AccessKey ID obtained when the Android or iOS app initializes OSSClient.
    • AccessKeySecret: the AccessKey secret obtained when the Android or iOS app initializes OSSClient.
    • SecurityToken: the token obtained when the Android or iOS app initializes OSSClient.
    • Expiration: the time when the token expires. OSS SDK for Android determines whether the token is valid. If the token becomes invalid, another token is automatically obtained.
    Error code description:
    • StatusCode: indicates the status of the operation to obtain the token. If the operation fails, 500 is returned.
    • ErrorCode: indicates the cause of the error.
    • ErrorMessage: indicates the error message.

Step 3: Download and install the mobile app

  1. Download the app source code.
    Download link:

    You can use the mobile app on devices that run Android or iOS to upload images to OSS. Simple upload and resumable upload are supported. If the network quality is poor, we recommend that you use resumable upload. You can also use IMG to resize an image to obtain a thumbnail and add watermarks to the image.

  2. Open the mobile app and configure the app parameters.
    • App server: the app server address specified in Step 2: Configure the app server.
    • Destination bucket: the bucket to which the data is uploaded from a mobile app.
    • Region: the region in which the destination bucket is located.
    • OSS object name: The name must contain the prefix specified in the policy configuration file of the app server.
  3. Click Configure.

Step 4: Implement direct data transfer for mobile apps

  1. Open the mobile app.
  2. Click Select Image. Select the image to upload and specify the object name.
  3. After the object is uploaded, check the upload result in the console.

Core code analysis

The following code provides examples on how to use OSS SDK for Android and OSS SDK for iOS to initialize OSSClient instances.

  • For Android apps: 
    // We recommend that you use OSSAuthCredentialsProvider. The token is automatically updated after it expires. 
String stsServer = "App server address such as https://example.com:8080"
OSSCredentialProvider credentialProvider = new OSSAuthCredentialsProvider(stsServer);
// Configure the following parameters. 
ClientConfiguration conf = new ClientConfiguration();
conf.setConnectionTimeout(15 * 1000); // The connection timeout period in seconds. Default value: 15. 
conf.setSocketTimeout(15 * 1000); // The socket timeout period in seconds. Default value: 15. 
conf.setMaxConcurrentRequest(5); // The maximum number of concurrent requests. Default value: 5. 
conf.setMaxErrorRetry(2); // The maximum number of retry attempts. Default value: 2. 
OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider, conf);
  • For iOS apps: 
    OSSClient * client;
...
// We recommend that you use OSSAuthCredentialProvider. The token is automatically updated after it expires. 
id<OSSCredentialProvider> credential = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:@"App server address such as https://example.com:8080"];
client = [[OSSClient alloc] initWithEndpoint:endPoint credentialProvider:credential];