All Products
Document Center

STS authorization

Last Updated: Mar 18, 2019

Basic concepts

Basic concepts are explained as follows:

  • RAM user

    A RAM user is created based on an Alibaba Cloud primary account. Once created, the RAM user has its own AccessKey and can perform authorized operations in the same way as the primary account. Generally, RAM users can be considered as users with certain permissions or users who are authorized to perform the specified operations.

  • Role

    A role is a virtual concept for certain operation permissions, but it does not have its own logon password or AccessKey. A RAM user can assume a role, in which case the permissions of the RAM user are those of the role.

  • Policy

    Policies are rules that are used to define permissions, for example, rules that allow users to upload or play media files.

The relationship between a RAM user and a role is equivalent to that between a person and his/her identity. For example, the person is an employee at work, and a father at home. The person is the same person although he/she assumes different roles in different scenarios. When assuming different roles, the person has permissions that have been granted to the roles. “Employee” or “father” cannot act as an entity that performs operations unless such roles are assumed by users. This also indicates that a role may be assumed by multiple users at the same time. The user who assumes a role is automatically granted all permissions of the role.


In the previous sections, we used only the RAM user function. RAM users are for long-term normal use. This poses a serious risk if the RAM user permissions cannot be promptly revoked in the case of information disclosure.
To reslove this issue, you can deploy a server to generate an STS temporary AccessKey. You can customize the validity period of the AccessKey and specify complex policies to provide only minimum permissions to different RAM users.

Create a RAM user

  1. Log on to the Alibaba Cloud console, and select Resource Access Management.

    If you have not used the Alibaba Cloud console before, activate this service first.

  2. Go to the Users page.RAMGuide2

  3. No user is displayed on the page. Click Create User in the upper-right corner to create a RAM user with the same VOD access permissions as the primary account. Remember to select the Automatically Generate an AccessKey for This User.RAMGuide3

  4. The AccessKey for this RAM user is generated. You must save this AccessKey for future use in this step.RAMGuide4

  5. Return to the “Users” page, where the created RAM user named live_ram_test is displayed. The created RAM user does not have any permissions yet. Click Authorize on the right side and grant the AliyunSTSAssumeRoleAccess permissions to this RAM user.VODAuth

Create a role

  1. Log on to the RAM console, and choose Roles > Create Role.Create a role (1)

  2. Select the role type. In this example, select User Role.Create a role (2)

  3. Enter the role type information. Use the default settings.Create a role (3)

  4. Configure the basic information about the role.Create a role (4)

  5. Choose Roles,and grant the AliyunVODFullAccess permission to this role.Grant permissions to the role

Java example

Everything is now ready for you to use STS to grant access permissions.

The following provides a simple STS Java example. The calling method is as follows. For more information about the parameters, see STS introduction.

  1. package pop;
  2. import com.aliyuncs.DefaultAcsClient;
  3. import com.aliyuncs.exceptions.ClientException;
  4. import com.aliyuncs.http.MethodType;
  5. import com.aliyuncs.http.ProtocolType;
  6. import com.aliyuncs.profile.DefaultProfile;
  7. import com.aliyuncs.profile.IClientProfile;
  8. import com.aliyuncs.sts.model.v20150401.AssumeRoleRequest;
  9. import com.aliyuncs.sts.model.v20150401.AssumeRoleResponse;
  10. import com.aliyuncs.vod.model.v20170321.CreateUploadVideoRequest;
  11. import com.aliyuncs.vod.model.v20170321.CreateUploadVideoResponse;
  12. /**
  13. * Created by liulietao on 2017/7/4.
  14. */
  15. public class TestStsService {
  16. // Currently, only the "cn-hangzhou" region is available. Do not enter another region value.
  17. public static final String REGION_CN_HANGZHOU = "cn-hangzhou";
  18. // Current STS API version
  19. public static final String STS_API_VERSION = "2015-04-01";
  20. static AssumeRoleResponse assumeRole(String accessKeyId, String accessKeySecret,
  21. String roleArn, String roleSessionName, String policy,
  22. ProtocolType protocolType) throws ClientException {
  23. try {
  24. // Create an Alibaba Cloud ACS client for initiating an OpenAPI request.
  25. IClientProfile profile = DefaultProfile.getProfile(REGION_CN_HANGZHOU, accessKeyId, accessKeySecret);
  26. DefaultAcsClient client = new DefaultAcsClient(profile);
  27. // Create an AssumeRoleRequest and set the request parameters.
  28. final AssumeRoleRequest request = new AssumeRoleRequest();
  29. request.setVersion(STS_API_VERSION);
  30. request.setMethod(MethodType.POST);
  31. request.setProtocol(protocolType);
  32. request.setRoleArn(roleArn);
  33. request.setRoleSessionName(roleSessionName);
  34. request.setPolicy(policy);
  35. // Initiate a request and obtain the response.
  36. final AssumeRoleResponse response = client.getAcsResponse(request);
  37. return response;
  38. } catch (ClientException e) {
  39. throw e;
  40. }
  41. }
  42. public static void main(String[] args) {
  43. // Only an RAM user can call the AssumeRole operation.
  44. // The AccessKeys of an Alibaba Cloud primary account cannot be used to initiate an AssumeRole request.
  45. // Create an RAM user in the RAM console, and create an AccessKey for the user.
  46. String accessKeyId = Env.AK;
  47. String accessKeySecret = Env.AS;
  48. // AssumeRole API request parameters include RoleArn, RoleSessionName, Policy, and DurationSeconds.
  49. // You need to obtain the RoleArn in the RAM console.
  50. String roleArn = "acs:ram::example:role/ramtestupload";
  51. // RoleSessionName is the session name of a temporary Token. You must specify the parameter to identify your account. This parameter is used for audit or for distinguishing the account to which the Token is issued.
  52. // Pay attention to the length and rule of RoleSessionName. RoleSessionName can contain only hyphens (-), underscores (_), letters, and numbers, and it cannot contain any spaces.
  53. // For more information about rules, see the format requirements in the API documentation.
  54. String roleSessionName = "RamTestUpload";
  55. // Method for customizing your policy
  56. String policy = "{\n" +
  57. " \"Version\": \"1\",\n" +
  58. " \"Statement\": [\n" +
  59. " {\n" +
  60. " \"Action\": \"vod:CreateUploadVideo\",\n" +
  61. " \"Resource\": \"*\",\n" +
  62. " \"Effect\": \"Allow\"\n" +
  63. " }\n" +
  64. " ]\n" +
  65. "}";
  66. // You must enter HTTPS here.
  67. ProtocolType protocolType = ProtocolType.HTTPS;
  68. try {
  69. final AssumeRoleResponse response = assumeRole(accessKeyId, accessKeySecret,
  70. roleArn, roleSessionName, policy, protocolType);
  71. System.out.println("Expiration: " + response.getCredentials().getExpiration());
  72. System.out.println("Access Key Id: " + response.getCredentials().getAccessKeyId());
  73. System.out.println("Access Key Secret: " + response.getCredentials().getAccessKeySecret());
  74. System.out.println("Security Token: " + response.getCredentials().getSecurityToken());
  75. createUploadVideo(response.getCredentials().getAccessKeyId(),
  76. response.getCredentials().getAccessKeySecret(),
  77. response.getCredentials().getSecurityToken());
  78. } catch (ClientException e) {
  79. System.out.println("Failed to get a token.");
  80. System.out.println("Error code: " + e.getErrCode());
  81. System.out.println("Error message: " + e.getErrMsg());
  82. }
  83. }
  84. static void createUploadVideo(String accessKeyId, String accessKeySecret, String token) {
  85. String regionId = "cn-shanghai"; // Region of the VOD service. Enter "cn-shanghai" for any region in China.
  86. IClientProfile profile = DefaultProfile.getProfile(regionId, accessKeyId, accessKeySecret);
  87. DefaultAcsClient client = new DefaultAcsClient(profile);
  88. CreateUploadVideoRequest request = new CreateUploadVideoRequest();
  89. request.setSecurityToken(token);
  90. request.setTitle("t1");
  91. request.setFileName("file1.mp4");
  92. request.setFileSize(10240L);
  93. try {
  94. CreateUploadVideoResponse response = client.getAcsResponse(request);
  95. System.out.println("CreateUploadVideoRequest, " + request.getUrl());
  96. System.out.println("CreateUploadVideoRequest, requestId:" + response.getRequestId());
  97. System.out.println("UploadAddress, " + response.getUploadAddress());
  98. System.out.println("UploadAuth, " + response.getUploadAuth());
  99. System.out.println("VideoId, " + response.getVideoId());
  100. } catch (ClientException e) {
  101. System.out.println("action, error:" + e);
  102. e.printStackTrace();
  103. }
  104. }
  105. }
  • RoleArn indicates the ID of a role to be assumed. You can select Roles > Role Details to find the role ID.

  • RoleSessionName indicates the name of a temporary credential. Generally, we recommend that you use different application users to distinguish the RoleSessionNames.

  • Policy indicates that a permission restriction is added when the role is assumed.


    • The policy that is passed in is used to restrict the permissions of the temporary credential after a role is assumed. Ultimately the permissions obtained through the temporary credential are the intersection of permissions of the role and the policy that has been passed in.
    • When a role is being assumed, the policy is passed in to improve flexibility. For example, the CreateUploadVideo operation can only be used currently.
  • DurationSeconds indicates the validity period in seconds of the temporary credential. The value ranges from 900 to 3600.

  • id and secret indicate the AccessKey of the RAM user to assume a role.