This topic describes how to use a RAM role token to control temporary authorization for mobile apps in a specific scenario.

Scenario description

Assume that enterprise A has developed a mobile app and has purchased an OSS package for it. The mobile app must upload and download data to and from OSS because the mobile app runs on user devices, which are out of A's control.

  • Enterprise A does not want the app to use AppServer to transmit data. Instead, enterprise A wants the app to directly upload and download data to and from OSS.
  • For security reasons, enterprise A cannot save the AccessKey (AK) in the app.
  • Enterprise A also wants to minimize its security risks by, for example, using an access token with the minimum permissions that the app needs to connect to OSS and restricting the access duration to a specified period of time (for example, 30 minutes).

Requirement analysis

The analysis of the preceding scenario is as follows:

  • The mobile app needs to directly transmit data to OSS without a data proxy.
  • Enterprise A cannot give its AK to the mobile app because mobile devices are under users' control. The best practice is to use an access token with a specific expiration date.
  • The access permission of the mobile app must be controlled. The minimum control granularity can be OSS.


To meet the requirements, a RAM role token can be used to authorize users to temporarily access OSS.

  • Account A creates a role and grants appropriate permissions to the role, and allows AppServer (runs as the RAM user) to use this role. For more information, see Create roles, users, and grant permissions to them.
  • When the app needs to upload or download data to or from OSS through direct connection, AppServer can assume a role (by calling STS AssumeRole) to obtain a temporary security token (STS-Token) of the role and transfer the token to the app. Then, the app can use the token to directly access OSS APIs. For more information, see Obtain and transfer role tokens and access resources.
  • AppServer can further limit the resource operation permissions of the temporary security token while using the role to control the permissions of the app in greater detail. For more information, see Restrict STS-Token permissions.

Create roles, users, and grant permissions to them

Assume that the ID of account A is 11223344. The process for creating roles, users, and granting permissions for AppServer is as follows:

  1. Account A creates a user role (for example, a role named oss-readonly) and selects the Current Alibaba Cloud Account as the trusted account. That is, only the RAM users under account A are allowed to assume this role. For more information, see Role.

    You can view basic information about the role on the role details page.

    • In this example, the RoleARN is:
    • The role's policy (only the RAM users under account A can assume this role) is as follows:
      "Statement": [
       "Action": "sts:AssumeRole",
       "Effect": "Allow",
       "Principal": {
         "RAM": [
           "acs:ram::11223344:root"//when the role is a user role, it is permanently set to root
      "Version": "1"
  2. Account A adds the policy AliyunOSSReadOnlyAccess to the role oss-readonly.
  3. Account A creates a RAM user for AppServer (for example, a user named appserver), and then:
    • Creates an AK for the RAM user. That is, the RAM user (appserver) is allowed to call APIs.
    • Grants the permission to call the AliyunSTSAssumeRoleAccess API. That is, the RAM user (appserver) is allowed to assume roles.

Obtain and transfer role tokens and access resources

The procedure for AppClient to obtain and use a role token to call OSS APIs is as follows:

Figure 1. Procedure

The procedure is as follows:

  1. AppServer uses the AK of the RAM user (appserver) to call STS AssumeRole. The following is an example of the command for aliyuncli to call AssumeRole:
    Note The AK of AppServer must be configured, which cannot be the AK of account A.
    $ aliyuncli sts AssumeRole --RoleArn acs:ram::11223344:role/oss-readonly --RoleSessionName client-001
         "AssumedRoleUser": {
             "AssumedRoleId": "391578752573972854:client-001", 
             "Arn": "acs:ram::11223344:role/oss-readonly/client-001"
         "Credentials": {
             "AccessKeySecret": "93ci2umK1QKNEja6WGqi1Ba7Q2Fv9PwxZqtVF2VynUvz", 
             "SecurityToken": "CAES6AIIARKAAUiwSHpkD3GXRMQk9stDr3YSVbyGqanqkS+fPlEEkjZ+dlgFnGdCI2PV93jksole8ijH8dHJrHRA5JA1YCGsfX5hrzcNM37Vr4eVdWFVQhoCw0DXBpHv//ZcITp+ELRr4MHsnyGiErnDsXLkI7q/sbuWg6PACZ/jzQfEWQb/f7Y1Gh1TVFMuRjEzR2pza1hUamszOGRCWTZZeEp0WEFaayISMzkxNTc4NzUyNTczOTcyODU0KgpjbGllbnQtMDAxMKT+lIHBKjoGUnNhTUQ1QkoKATEaRQoFQWxsb3cSGwoMQWN0aW9uRXF1YWxzEgZBY3Rpb24aAwoBKhIfCg5SZXNvdXJjZUVxdWFscxIIUmVzb3VyY2UaAwoBKkoFNDMyNzRSBTI2ODQyWg9Bc3N1bWVkUm9sZVVzZXJgAGoSMzkxNTc4NzUyNTczOTcyODU0cgllY3MtYWRtaW544Mbewo/26AE=", 
             "Expiration": "2016-01-13T15:02:37Z", 
             "AccessKeyId": "STS.F13GjskXTjk38dBY6YxJtXAZk"
         "RequestId": "E1779AAB-E7AF-47D6-A9A4-53128708B6CE"
    Restrict STS-Token permissions
    • The Policy parameter is not specified when AssumeRole is called, which indicates that the token has all permissions for oss-readonly.
    • If you need to further restrict the token permissions, for example, allowing only access to sample-bucket/2015/01/01/*.jpg, you can restrict the token permissions in greater detail by setting the Policy parameter. The following is a command example:
      $ aliyuncli sts AssumeRole --RoleArn acs:ram::11223344: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": "391578752573972854:client-002", 
             "Arn": "acs:ram::11223344:role/oss-readonly/client-002"
         "Credentials": {
             "AccessKeySecret": "28Co5Vyx2XhtTqj3RJgdud4ntyzrSNdUvNygAj7xEMow", 
             "SecurityToken": "CAESnQMIARKAASJgnzMzlXVyJn4KI+FsysaIpTGm8ns8Y74HVEj0pOevO8ZWXrnnkz4a4rBEPBAdFkh3197GUsprujsiU78FkszxhnQPKkQKcyvPihoXqKvuukrQ/Uoudk31KAJEz5o2EjlNUREcxWjRDRSISMzkxNTc4NzUyNTczOTcyODU0KgpjbGllbnQtMDAxMKmZxIHBKjoGUnNhTUQ1Qn8KATEaegoFQWxsb3cSJwoMQWN0aW9uRXF1YWxzEgZBY3Rpb24aDwoNb3NzOkdldE9iamVjdBJICg5SZXNvdXJjZUVxdWFscxIIUmVzb3VyY2UaLAoqYWNzOm9zczoqOio6c2FtcGxlLWJ1Y2tldC8yMDE1LzAxLzAxLyouanBnSgU0MzI3NFIFMjY4NDJaD0Fzc3VtZWRSb2xlVXNlcmAAahIzOTE1Nzg3NTI1NzM5NzI4NTRyCWVjcy1hZG1pbnjgxt7Cj/boAQ==", 
             "Expiration": "2016-01-13T15:03:39Z", 
             "AccessKeyId": "STS.FJ6EMcS1JLZgAcBJSTDG1Z4CE"
         "RequestId": "98835D9B-86E5-4BB5-A6DF-9D3156ABA567"

    Additionally, The default validity period of the token is 3,600 seconds. You can use the DurationSeconds parameter to restrict the token expiration time (within 3,600 seconds).

  2. AppServer obtains and parses credentials.
    • AppServer obtains the AccessKeyId, AccessKeySecret and SecurityToken from the credentials returned by AssumeRole.
    • Because the token validity period is relatively short, if the app requires a longer validity period, AppServer must re-issue a new token (for example, AppServe issues tokens every 1,800 seconds).
  3. AppServer securely transmits the token to AppClient.
  4. AppClient uses the token to directly access cloud service APIs (such as OSS APIs). The following is an example of the command for aliyuncli to use the token (issued to client-002) to access OSS objects:
    Configure STS-Token syntax: aliyuncli oss Config --host --accessid --accesskey --sts_token 
    $ aliyuncli oss Config --host --accessid STS.FJ6EMcS1JLZgAcBJSTDG1Z4CE --accesskey 28Co5Vyx2XhtTqj3RJgdud4ntyzrSNdUvNygAj7xEMow --sts_token CAESnQMIARKAASJgnzMzlXVyJn4KI+FsysaIpTGm8ns8Y74HVEj0pOevO8ZWXrnnkz4a4rBEPBAdFkh3197GUsprujsiU78FkszxhnQPKkQKcyvPihoXqKvuukrQ/Uoudk31KAJEz5o2EjlNUREcxWjRDRSISMzkxNTc4NzUyNTczOTcyODU0KgpjbGllbnQtMDAxMKmZxIHBKjoGUnNhTUQ1Qn8KATEaegoFQWxsb3cSJwoMQWN0aW9uRXF1YWxzEgZBY3Rpb24aDwoNb3NzOkdldE9iamVjdBJICg5SZXNvdXJjZUVxdWFscxIIUmVzb3VyY2UaLAoqYWNzOm9zczoqOio6c2FtcGxlLWJ1Y2tldC8yMDE1LzAxLzAxLyouanBnSgU0MzI3NFIFMjY4NDJaD0Fzc3VtZWRSb2xlVXNlcmAAahIzOTE1Nzg3NTI1NzM5NzI4NTRyCWVjcy1hZG1pbnjgxt7Cj/boAQ==
    Access OSS objects
    $ aliyuncli oss Get oss://sample-bucket/2015/01/01/grass.jpg grass.jpg


For more information about direct connection in mobile application, see: