STS tokens are security credentials that have a limited validity period. This topic describes how to use a Security Token Service (STS) token of a Resource Access Management (RAM) role for authorizing a mobile app to access Alibaba Cloud resources.

Prerequisites

An Alibaba Cloud account is created. To create an Alibaba Cloud account, visit the account registration page.

Background information

An enterprise has developed a mobile app and purchased Object Storage Service (OSS). The mobile app runs on mobile devices. These mobile devices are not controlled by the enterprise. The enterprise must grant the necessary permissions to the mobile app. The mobile app can then upload data to and download data from OSS.

The enterprise has the following requirements:

  • Direct data transmission: The mobile app directly uploads data to or downloads data from OSS. The application server of the enterprise does not need to transfer data between the mobile app and OSS.
  • Security control: AccessKey pairs are not saved on mobile devices. Mobile devices are controlled by app users and cannot provide trusted operating environments.
  • Risk control: Security risks are minimized. During direct access to OSS, each app client is authorized based on the principle of least privilege and the access duration is under strict control.

Solution

Before a mobile app directly uploads data to or downloads data from OSS, the mobile app requests an STS token from the application server. After the application server receives the request, the server calls the AssumeRole STS API operation as a RAM user. If the call succeeds, the application receives an STS token and forwards the STS token to the mobile app. The mobile app can then use the STS token to access OSS.

Authorize a mobile app to access Alibaba Cloud resources
  1. The mobile app requests an STS token from the application server.
  2. The enterprise uses its Alibaba Cloud account to create a RAM role and grant the necessary permissions to the role. For more information, see Create a RAM role and grant the necessary permissions to the role.
  3. The enterprise uses its Alibaba Cloud account to create a RAM user for the application server and allows the application server to assume the RAM role. For more information, see Create a RAM user and allow the user to assume a RAM role.
  4. The application server calls the AssumeRole STS API operation to obtain an STS token of the RAM role. For more information, see Obtain an STS token of the RAM role.
  5. The application server can request an STS token whose permissions are fewer than those that are granted to the RAM role. In this way, the application server controls the access from the mobile app to OSS. For more information, see Request an STS token whose permissions are fewer than those of the RAM role.
  6. The mobile app uses the STS token to directly upload data to or download data from OSS. For more information, see Use the STS token to access OSS.

Create a RAM role and grant the necessary permissions to the role

The ID of the Alibaba Cloud account that is used by the enterprise in this section is 123456789012****.

  1. The enterprise uses its Alibaba Cloud account to create a RAM role named oss-readonly. Alibaba Cloud Account is selected as the trusted entity type.
    Note When the RAM role is created, Current Alibaba Cloud Account is selected as the trusted account. This ensures that only RAM users under the account can assume the RAM role.

    For more information, see Create a RAM role for a trusted Alibaba Cloud account.

    After the RAM role is created, the enterprise can view the information of the role on the basic information page.

    • In this example, the Alibaba Cloud Resource Name (ARN) of the RAM role is acs:ram::123456789012****:role/oss-readonly.
    • The following policy is attached to the RAM role:
      Note This policy indicates that only RAM users under the Alibaba Cloud account of the enterprise can assume the RAM role.
      {
      "Statement": [
      {
       "Action": "sts:AssumeRole",
       "Effect": "Allow",
       "Principal": {
         "RAM": [
           "acs:ram::123456789012****:root"
         ]
       }
      }
      ],
      "Version": "1"
      }
  2. The enterprise uses its Alibaba Cloud account to attach the AliyunOSSReadOnlyAccess policy (OSS read-only permission) to the RAM role oss-readonly.

    For more information, see Grant permissions to a RAM role.

Create a RAM user and allow the user to assume a RAM role

  1. The enterprise uses its Alibaba Cloud account to create a RAM user named appserver.

    For more information, see Create a RAM user.

  2. The enterprise uses its Alibaba Cloud account to attach the AliyunSTSAssumeRoleAccess policy to the RAM user. The RAM user can then assume the RAM role.

    For more information, see Grant permissions to a RAM user.

Obtain an STS token of the RAM role

  1. The application server uses the AccessKey pair of the RAM user to call the AssumeRole STS API operation.
    Note The AccessKey pair of the RAM user rather than the Alibaba Cloud account must be used.

    The following example shows how to use Alibaba Cloud CLI to call the AssumeRole operation:

    $ aliyuncli sts AssumeRole --RoleArn acs:ram::123456789012****:role/oss-readonly --RoleSessionName client-001
     {
         "AssumedRoleUser": {
             "AssumedRoleId": "391578752573****:client-001", 
             "Arn": "acs:ram::123456789012****:role/oss-readonly/client-001"
         }, 
         "Credentials": {
             "AccessKeySecret": "93ci2umK1QKNEja6WGqi1Ba7Q2Fv9PwxZqtVF2Vy****", 
             "SecurityToken": "********", 
             "Expiration": "2016-01-13T15:02:37Z", 
             "AccessKeyId": "STS.F13GjskXTjk38dBY6YxJt****"
         }, 
         "RequestId": "E1779AAB-E7AF-47D6-A9A4-53128708B6CE"
     }
    Note In this example, the returned STS token has all permissions of the RAM role oss-readonly because the Policy parameter is unspecified. The application server can also request an STS token whose permissions are fewer than those of the RAM role. For more information, see Request an STS token whose permissions are fewer than those of the RAM role.
  2. The STS service sends the STS token to the application server. The STS token contains the following elements: AccessKeyId, AccessKeySecret, and SecurityToken.
    Note The STS token (SecurityToken) is valid only for a short period of time. If the mobile app requires access to OSS for a long period of time, the application server can request a new STS token at a regular basis, for example, every 1,800 seconds.

Request an STS token whose permissions are fewer than those of the RAM role

In practice, we recommend that you specify the Policy parameter to grant the STS token fewer permissions than those that are granted to the RAM role. Ensure that the principle of least privilege is applied. The following example shows how to specify the Policy parameter.

In this example, the returned STS token has only the permissions to access objects that match the sample-bucket/2015/01/01/*.jpg pattern.

$ aliyuncli sts AssumeRole --RoleArn acs:ram::123456789012****:role/oss-readonly --RoleSessionName client-002 --Policy "{\"Version\":\"1\", \"Statement\": [{\"Effect\":\"Allow\", \"Action\":\"oss:GetObject\", \"Resource\":\"acs:oss:*:*:sample-bucket/2015/01/01/*.jpg\"}]}"
{
   "AssumedRoleUser": {
       "AssumedRoleId": "391578752573****:client-002", 
       "Arn": "acs:ram::123456789012****:role/oss-readonly/client-002"
   }, 
   "Credentials": {
       "AccessKeySecret": "28Co5Vyx2XhtTqj3RJgdud4ntyzrSNdUvNygAj7x****", 
       "SecurityToken": "********", 
       "Expiration": "2016-01-13T15:03:39Z", 
       "AccessKeyId": "STS.FJ6EMcS1JLZgAcBJSTDG1****"
   }, 
   "RequestId": "98835D9B-86E5-4BB5-A6DF-9D3156ABA567"
}
Note The default and maximum validity period of the STS token is 3,600 seconds. The enterprise can specify the DurationSeconds parameter to shorten the validity period of the STS token.

Use the STS token to access OSS

  1. The application server sends the STS token to the mobile app.
  2. The mobile app uses the STS token to access OSS.

    The following example shows how to use Alibaba Cloud CLI and the STS token to access an OSS object:

    The syntax that is used to specify the STS token: aliyuncli oss Config --host  --accessid  --accesskey  --sts_token 
    $ aliyuncli oss Config --host oss.aliyuncs.com --accessid STS.FJ6EMcS1JLZgAcBJSTDG1**** --accesskey 28Co5Vyx2XhtTqj3RJgdud4ntyzrSNdUvNygAj7x**** --sts_token CAESnQMIARKAASJgnzMzlXVyJn4KI+FsysaIpTGm8ns8Y74HVEj0pOevO8ZWXrnnkz4a4rBEPBAdFkh3197GUsprujsiU78FkszxhnQPKkQKcyvPihoXqKvuukrQ/Uoudk31KAJEz5o2EjlNUREcxWjRDRSISMzkxNTc4NzUyNTczOTcyODU0KgpjbGllbnQtMDAxMKmZxIHBKjoGUnNhTUQ1Qn8KATEaegoFQWxsb3cSJwoMQWN0aW9uRXF1YWxzEgZBY3Rpb24aDwoNb3NzOkdldE9iamVjdBJICg5SZXNvdXJjZUVxdWFscxIIUmVzb3VyY2UaLAoqYWNzOm9zczoqOio6c2FtcGxlLWJ1Y2tldC8yMDE1LzAxLzAxLyouanBnSgU0MzI3NFIFMjY4NDJaD0Fzc3VtZWRSb2xlVXNlcmAAahIzOTE1Nzg3NTI1NzM5NzI4NTRyCWVjcy1hZG1pbnjgxt7Cj/bo****
    Access OSS:
    $ aliyuncli oss Get oss://sample-bucket/2015/01/01/grass.jpg grass.jpg