You can use Security Token Service (STS) to generate a temporary credential to allow a user to access your Object Storage Service (OSS) resources within the specified period. This way, you do not need to share your AccessKey pair or risk the security of your OSS resources.

Scenarios

A mobile app developer plans to store the user data of an app in Alibaba Cloud OSS. The data of each user must be isolated to prevent one user from obtaining the data of another user. In this case, you can use STS to authorize users to access their own OSS resources.

The following figure shows the process of how to use STS to authorize a user to access OSS.

sts
  1. The app user logs on to the app server. An app user uses their username and password to log on to the app server without using the AccessKey pair of the Alibaba Cloud account used to access OSS. The app server must be capable of defining the minimum access permissions for each valid app user.
  2. The app server sends a request to STS to obtain a security token. Before the app server sends the request to STS, the app server must determine the minimum permissions required by the app user to access OSS and the validity period of the credential. The minimum permissions are customized by using a Resource Access Management (RAM) policy. Then, the app server calls AssumeRole to obtain a security token that indicates a role from STS.
  3. STS returns a temporary access credential to the app server. The credential consists of a security token and a temporary AccessKey pair that can be used to access OSS within a validity period. A temporary AccessKey pair consists of an AccessKey ID and an AccessKey secret.
  4. The app server returns the temporary access credential to the app client. The app client can cache the credential. After the credential expires, the app client must apply for a new temporary access credential from the app server. For example, if the temporary access credential is valid for one hour, the app client can send a request to the app server to update the credential every 30 minutes.
  5. The app client uses the locally cached temporary access credential to initiate a request to call OSS API operations. After OSS receives the request, OSS uses STS to verify the access credential in the request and responds to the request.

Step 1: Create a RAM user

  1. Log on to the RAM console.
  2. In the left-side navigation pane, choose Users > Identities.
  3. On the Users page, click Create User.
  4. On the Create User page, set Logon Name and Display Name.
  5. In the Access Mode section, select Programmatic Access, and click OK.
  6. Click Copy in the Actions column that corresponds to the created RAM user to save the AccessKey pair of the RAM user.

Step 2: Grant the RAM user the AssumeRole permission

  1. On the Users page, click Add Permissions in the Actions column that corresponds to the created RAM user.
  2. In the Add Permissions panel, select the AliyunSTSAssumeRoleAccess policy from the policy list for System Policy. policy
  3. Click OK.

Step 3: Create a role used to obtain a temporary access credential from STS

  1. In the left-side navigation pane, click RAM Roles.
  2. Click Create RAM Role, select Alibaba Cloud Account for Trusted entity type, and then click Next.
  3. In the Create RAM Role panel, enter RamOssTest in the RAM Role Name field, and then select Current Alibaba Cloud Account in the Select Trusted Alibaba Cloud Account section.
  4. Click OK. After the role is created, click Close.
  5. On the RAM Roles page, enter RamOssTest in the search box to search for the created role.
  6. Click Copy to save the Alibaba Cloud Resource Name (ARN) of the role. arn

Step 4: Grant the role permissions to upload objects to OSS

  1. In the left-side navigation pane, click Policies under Permissions.
  2. On the Policies page, click Create Policy.
  3. On the Create Custom Policy page, enter a policy name in the Policy Name field, select Script for Configuration Mode, set the Policy Document field, and then edit the script in the Policy Document editor to grant the role permissions to upload objects to a directory named exampledir in the bucket named examplebucket.
    Warning The following script is for reference only. You must configure fine-grained RAM policies based on your requirements to avoid granting excessive permissions to users. For more information about how to configure fine-grained RAM policies, see Common examples of RAM policies.
    {
        "Version": "1",
        "Statement": [
         {
               "Effect": "Allow",
               "Action": [
                 "oss:PutObject"
               ],
               "Resource": [
                 "acs:oss:*:*:examplebucket/exampledir",
                 "acs:oss:*:*:examplebucket/exampledir/*"
               ]
         }
        ]
    }
  4. Click OK.

Step 5: Obtain a temporary access credential

You can call the AssumeRole operation or use STS SDKs for various programming languages to obtain a temporary access credential from STS.

The following code provides an example on how to use STS SDK for Java to obtain a temporary access credential:
package com.aliyun.sts.sample;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.http.MethodType;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.profile.IClientProfile;
import com.aliyuncs.sts.model.v20150401.AssumeRoleRequest;
import com.aliyuncs.sts.model.v20150401.AssumeRoleResponse;
public class StsServiceSample {
    public static void main(String[] args) { 
        // Specify the endpoint of STS. Example: sts.cn-hangzhou.aliyuncs.com.        
        String endpoint = "<sts-endpoint>";
        // Specify the AccessKey pair generated in Step 1. 
        String AccessKeyId = "<yourAccessKeyId>"";
        String accessKeySecret = "<yourAccessKeySecret>";
        // Specify the role ARN created in Step 3. 
        String roleArn = "<yourRoleArn>";
        // Specify a custom role session name to distinguish different tokens. Example: SessionTest.         
        String roleSessionName = "<yourRoleSessionName>";
        // The following policy allows users to use only a temporary access credential to upload objects to the bucket named examplebucket. 
        // The permission of the temporary access credential is the intersection of the role permission configured in Step 4 and the permission specified by the RAM policy. Users can use the temporary access credential to upload objects only to the exampledir directory in the examplebucket bucket. 
        String policy = "{\n" +
                "    \"Version\": \"1\", \n" +
                "    \"Statement\": [\n" +
                "        {\n" +
                "            \"Action\": [\n" +
                "                \"oss:PutObject\"\n" +
                "            ], \n" +
                "            \"Resource\": [\n" +
                "                \"acs:oss:*:*:examplebucket/*\" \n" +
                "            ], \n" +
                "            \"Effect\": \"Allow\"\n" +
                "        }\n" +
                "    ]\n" +
                "}";
        try {
            // Add the endpoint. 
            DefaultProfile.addEndpoint("", "", "Sts", endpoint);
            // Create a default profile. 
            IClientProfile profile = DefaultProfile.getProfile("", AccessKeyId, accessKeySecret);
            // Use the profile to create 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 not specified, the user obtains all permissions of the role. 
            request.setDurationSeconds(3600L); // Set the validity period of the temporary access credential to 3,600 seconds. 
            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());
        }
    }
}
Note
  • The minimum validity period of a temporary access credential is 900 seconds. The maximum validity period of a temporary access credential is the maximum session duration specified by the current role. For more information, see Specify the maximum session duration for a RAM role.
  • For naming conventions for roleSessionName role session names, see AssumeRole.

Step 6: Use the temporary access credential to upload objects to OSS

The following code provides an example on how to use OSS SDK for Java to upload a file named exampletest.txt from a local path D:\\localpath to a directory named exampledir in a bucket named examplebucket:

import com.aliyun.oss.OSSClient;
import com.aliyun.oss.model.PutObjectRequest;

import java.io.File;

public class upload {
    public static void main(String[] args) {

// Specify the temporary AccessKey pair included in the access credential obtained from STS in Step 5. 
String AccessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";
// Specify the security token included in the temporary access credential obtained from STS in Step 5. 
String securityToken = "<yourSecurityToken>";

// Create an OSSClient instance. 
OSSClient ossClient = new OSSClient(endpoint, AccessKeyId, accessKeySecret, securityToken);
// Upload a local file named example.txt to the directory named exampledir in the bucket named examplebucket. 
PutObjectRequest putObjectRequest = new PutObjectRequest("examplebucket", "exampledir/exampletest.txt", new File("D:\\localpath\\exampletest.txt"));

// The following code provides an example on how to specify the storage class and the access control list (ACL) of the object to upload. 
// ObjectMetadata metadata = new ObjectMetadata();
// metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard.toString());
// metadata.setObjectAcl(CannedAccessControlList.Private);
// putObjectRequest.setMetadata(metadata);

// Upload the object. 
ossClient.putObject(putObjectRequest);

// Shut down the OSSClient instance. 
ossClient.shutdown();
   }
}                    
For more information about the examples on OSS SDKs for other programming languages, see the following topics:

For more information about how to obtain the URL after the object is uploaded, see How do I obtain the URL of an uploaded object?.

FAQ

  • What do I do if the The security token you provided is invalid. error message is returned?

    Make sure that you specify the complete security token obtained in Step 5.

  • What do I do if the The OSS Access Key Id you provided does not exist in our records. error message is returned?

    Use the temporary AccessKey pair to apply for a new temporary access credential from the app server because the current temporary access credential expired. For more information, see Step 5.

  • What do I do if the NoSuchBucket error message is returned when I obtain an access credential from STS?

    Enter a valid STS endpoint based on your region. The error message is returned because the specified STS endpoint is invalid. For more information about the endpoints used to access STS in different regions, see Endpoints.