You can temporarily access OSS by using Security Token Service (STS) provided by Alibaba Cloud. Alibaba Cloud STS is a Web service that provides users with temporary access tokens. Using STS, you can grant an access credential with customized permissions and valid periods to third-party applications and federated users whose IDs are managed by you.

Scenarios

Users managed by your local identity system are referred to as federated users, for example, the users of your applications, local accounts owned by your enterprises, and third-party applications. Federated users may need to access your OSS resources directly. In addition, federated users can also include the users that are created by you and have access to your applications and resources in Alibaba Cloud.

For these users, you can use STS to manage the temporary access tokens for their Alibaba Cloud accounts (or RAM users). You can create temporary access credentials for federated users to grant OSS access permissions to them without providing your long term keys (such as logon password and AccessKeys) of your Alibaba Cloud accounts or RAM users to the federated users. The permissions and valid period of the credential can be customized. You do not need to revoke the permissions of the credential because it automatically becomes invalid after it expires.

Credentials generated by STS include security tokens (SecurityToken) and temporary access keys (AccessKeyId and AccessKeySecret). You can use a temporary access key in the same way as you use the AccessKey of an Alibaba Cloud account or a RAM user to send a request. Each request sent to OSS must carry a security token.

Implementation

A mobile application is used as an example. Assume that you are a mobile application developer and try to use Alibaba Cloud OSS to store end user data for your app. You must keep the data of each application user isolated to prevent the data of an application user from being obtained by other application users. You can use STS to authorize users so that they can directly access your OSS resources.

The following figure describes the process of using STS to grant OSS access to users.



  1. An application user logs on to the application server. An application user is an end user of the application and has no relationship to an Alibaba Cloud account. The application server can be logged on by an application user. The application server must define the minimum access permission for each valid application user.
  2. The application server request a security token from STS. Before calling STS, the application server must determine the minimum access permission for each application user (described in policy syntax) and the expiration time of the authorization. Then, the application server uses AssumeRole to obtain a security token which indicates a role.
  3. STS returns a valid access credential to the application server. The credential includes a security token, a temporary access key (AccessKeyId and AccessKeySecret), and the expiration time.
  4. The application server returns the access credential to the application user (ClientApp). The credential can be cached by the ClientApp. When the credential becomes invalid, the ClientApp must request a new valid access credential from the application server. For example, if the valid period of the returned access credential is an hour, the ClientApp can request the application server to update the access token every 30 minutes.
  5. The ClientApp use the access credential in the local cache to request Alibaba Cloud service APIs. ECS perceives the STS access credential and uses STS to verify the credential so that it can correctly respond user's requests.

For more information about STS security tokens, role management, and role usage, see Understand RAM roles. You can call the AssumeRole interface to obtain a valid access credential.

Procedure

Assume that a bucket named ram-test is used to store user data and it is required that STS should be used to grant permissions to a RAM user so that the user can access OSS buckets.

You can use OSS SDK and STS SDK together to access an OSS instance with a temporary access token provided by STS.

  1. Create a RAM user.
    1. Log on to the RAM console.
    2. In the RAM page, click Users.
    3. In the Users page, click Create User.
    4. In the Create User page, enter Logon Name and Display Name in the User Account Information area, select Programmatic Access for Access Mode, and then click OK.

    5. Select Permissions > Add Permissions.

    6. In the Add Permissions page, add the AliyunSTSAssumeRoleAccess permission for the created RAM user.

      Note Do not grant other permissions to the RAM user because it automatically obtains all permissions of a role when it acts as the role.
  2. Create a permission policy.
    1. Log on to the RAM console.
    2. In the RAM page, click Policies.
    3. Click Create Policy.
    4. In the Create Custom Policy page, enter the Policy Name and Note, and select Visualized or Script for Configure Mode.
      For example, if you select Script and want to grant read only permissions, such as ListObjects and GetObject, to a RAM user named ram-test, add the following script in the Policy Document.
      {
      	"Version": "1",
      	"Statement": [
       	{
         		"Effect": "Allow",
         		"Action": [
           		"oss:ListObjects",
           		"oss:GetObject"
         		],
         		"Resource": [
           		"acs:oss:*:*:ram-test",
           		"acs:oss:*:*:ram-test/*"
         		]
       	}
      	]
      }


  3. Create a role.
    1. Log on to the RAM console.
    2. In the RAM page, click RAM Roles.
    3. In the RAM Roles page, click Create RAM Role.
    4. In the Create RAM Role page, enter the RAM Role Name (RamOssTest in this example), select the type of trusted entities and keep the default selection for Select Trusted Alibaba Cloud Account.

    5. Click Add Permissions on the right of the created role RamOssTest.
    6. In the Add Permissions page, select Custom Policy and add the policy Ramtest that you created in step 2.
      After the policy is added, the page is shown as follows.

      Note ARN indicates the ID of the role that the RAM user acts.
  4. Obtain an STS AK and security token through STS APIs

    You can request STS through STS SDKs to obtain a security token. For more information about the installation and usage of STS SDKs, see Installation.

    The following code is described as an example to obtain a security token through STS Java SDK.
    public class StsServiceSample {
        public static void main(String[] args) {
            String endpoint = "sts.aliyuncs.com";
            String accessKeyId = "<access-key-id>";
            String accessKeySecret = "<access-key-secret>";
            String roleArn = "<role-arn>";
            String roleSessionName = "session-name";
            String policy = "{\n" +
                    "    \"Version\": \"1\", \n" +
                    "    \"Statement\": [\n" +
                    "        {\n" +
                    "            \"Action\": [\n" +
                    "                \"oss:*\"\n" +
                    "            ], \n" +
                    "            \"Resource\": [\n" +
                    "                \"acs:oss:*:*:*\" \n" +
                    "            ], \n" +
                    "            \"Effect\": \"Allow\"\n" +
                    "        }\n" +
                    "    ]\n" +
                    "}";
            try {
                // Adds an endpoint. (The STS endpoint is directly used. The first two parameters are left blank, indicating that the region ID is not required.)
                DefaultProfile.addEndpoint("", "", "Sts", endpoint);
                // Constructs a default profile. (The parameter is left blank, indicating that the region ID is not required.)
                IClientProfile profile = DefaultProfile.getProfile("", accessKeyId, accessKeySecret);
                // Uses the constructed profile to construct a client.
                DefaultAcsClient client = new DefaultAcsClient(profile);
                final AssumeRoleRequest request = new AssumeRoleRequest();
                request.setMethod(MethodType.POST);
                request.setRoleArn(roleArn);
                request.setRoleSessionName(roleSessionName);
                Request. setpolicy (policy); // If the policy is empty, the user obtains all permissions of the role.
                Request. setdurationseconds (1000l); // Sets the valid period of a credential.
                final AssumeRoleResponse response = client.getAcsResponse(request);
                System.out.println("Expiration: " + response.getCredentials().getExpiration());
                System.out.println("Access Key Id: " + response.getCredentials().getAccessKeyId());
                System.out.println("Access Key Secret: " + response.getCredentials().getAccessKeySecret());
                System.out.println("Security Token: " + response.getCredentials().getSecurityToken());
                System.out.println("RequestId: " + response.getRequestId());
            } catch (ClientException e) {
                System.out.println("Failed:");
                System.out.println("Error code: " + e.getErrCode());
                System.out.println("Error message: " + e.getErrMsg());
                System.out.println("RequestId: " + e.getRequestId());
            }
        }
    }
    The parameters are described as follows:
    • AccessKeyId and AccessKey Secret: Indicates the AK information about the RAM user.
    • RoleArn: Indicates the ID of the role that the user acts.
    • RoleSessionName: Indicates the name used to identify a temporary credential. We recommend you use different application user names to identify different credentials.
    • Policy: Indicates the permission limits added to a user when the user acts as a role.
      Note Policies are used to control the permissions of a temporary credential after the user acts as a role. The permission of a temporary credential is the intersection of the role permissions and the policies. Policies are passed in to adjust the permissions more flexibly. For example, you can use policies to set different limits on the path where a file is upload for different users.
    • DurationSeconds: Indicates the valid period (in seconds) of a temporary credential. The value of the parameter ranges from 900 to 3,600.
  5. Access OSS using the STS AK and security token.

    After obtaining the STS AK and security token, you can use the STS credential to construct a signed request.

    // This example uses the endpoint China East 1 (Hangzhou). Specify the actual endpoint based on your requirements.
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // It is highly risky to log on with the AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String securityToken = "<yourSecurityToken>";
    
    // After a user obtains a temporary STS credential, the OSSClient is generated with the security token and temporary access key (AccessKeyId and AccessKeySecret) in the credential.
    // Creates an OSSClient instance. Note that the STS credential generated in the preceding step is used.
    OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, securityToken);
    
    // Performs OSS operations.
    
    // Closes your OSSClient instance
    ossClient.shutdown();