Security Token Service (STS) enables more strict permission management than Resource Access Management (RAM). You can use STS to grant RAM users temporary permissions to access resources.

Background information

RAM users and the permissions that are granted to RAM users are permanently valid. You can only manually delete RAM users or revoke permissions from RAM users. If the information of a RAM user is leaked and you do not delete the RAM user or revoke permissions from the RAM user, your Alibaba Cloud resources and information are exposed to risks. Therefore, we recommend that you use STS to manage key permissions or permissions that do not require long-term validity.

Figure 1. Process for granting temporary permissions to RAM users
STS

Step 1: Create a RAM role

A RAM role is a virtual entity that represents a virtual user with a set of permissions.

  1. Log on to the RAM console by using your Alibaba Cloud account.
  2. Click Roles. On the Roles page, click Create Role to create a RAM role.
  3. In the Create Role panel, select Alibaba Cloud Account as the trusted entity. Then, click Next.
  4. Set the RAM Role Name and Note parameters, select Current Alibaba Cloud Account or Other Alibaba Cloud Account for the Select Trusted Alibaba Cloud Account parameter, and then click OK.
    Note If you select Other Alibaba Cloud Account, enter the ID of another Alibaba Cloud account.

Step 2: Create a policy

A policy defines the resource permissions that you want to grant to roles.

  1. Log on to the RAM console. In the left-side navigation pane, choose Permissions > Policies.
  2. On the Policies page, click Create Policy.
  3. On the Create Policy page, click the JSON tab.
  4. Specify the policy parameters and click Next Step.

    You can also click the JSON tab and write a policy script. For more information, see Policy structure and syntax.

    The following sample code shows a policy that has read-only permissions on the resources of IoT Platform:

    {
        "Version":"1",
        "Statement":[
            {
                "Action":[
                    "rds:DescribeDBInstances",
                    "rds:DescribeDatabases",
                    "rds:DescribeAccounts",
                    "rds:DescribeDBInstanceNetInfo"
                ],
                "Resource":"*",
                "Effect":"Allow"
            },
            {
                "Action":"ram:ListRoles",
                "Effect":"Allow",
                "Resource":"*"
            },
            {
                "Action":[
                    "mns:ListTopic"
                ],
                "Resource":"*",
                "Effect":"Allow"
            },
            {
                "Action":[
                    "dhs:ListProject",
                    "dhs:ListTopic",
                    "dhs:GetTopic"
                ],
                "Resource":"*",
                "Effect":"Allow"
            },
            {
                "Action":[
                    "ots:ListInstance",
                    "ots:ListTable",
                    "ots:DescribeTable"
                ],
                "Resource":"*",
                "Effect":"Allow"
            },
            {
                "Action":[
                    "log:ListShards",
                    "log:ListLogStores",
                    "log:ListProject"
                ],
                "Resource":"*",
                "Effect":"Allow"
            },
            {
                "Effect":"Allow",
                "Action":[
                    "iot:Query*",
                    "iot:List*",
                    "iot:Get*",
                    "iot:BatchGet*"
                ],
                "Resource":"*"
            }
        ]
    }

    The following sample code shows a policy that has read and write permissions on the resources of IoT Platform:

    {
        "Version":"1",
        "Statement":[
            {
                "Action":[
                    "rds:DescribeDBInstances",
                    "rds:DescribeDatabases",
                    "rds:DescribeAccounts",
                    "rds:DescribeDBInstanceNetInfo"
                ],
                "Resource":"*",
                "Effect":"Allow"
            },
            {
                "Action":"ram:ListRoles",
                "Effect":"Allow",
                "Resource":"*"
            },
            {
                "Action":[
                    "mns:ListTopic"
                ],
                "Resource":"*",
                "Effect":"Allow"
            },
            {
                "Action":[
                    "dhs:ListProject",
                    "dhs:ListTopic",
                    "dhs:GetTopic"
                ],
                "Resource":"*",
                "Effect":"Allow"
            },
            {
                "Action":[
                    "ots:ListInstance",
                    "ots:ListTable",
                    "ots:DescribeTable"
                ],
                "Resource":"*",
                "Effect":"Allow"
            },
            {
                "Action":[
                    "log:ListShards",
                    "log:ListLogStores",
                    "log:ListProject"
                ],
                "Resource":"*",
                "Effect":"Allow"
            },
            {
                "Effect":"Allow",
                "Action":"iot:*",
                "Resource":"*"
            }
        ]
    }
  5. Specify the Name and Note parameters, and then click OK.

After a policy is created, you can attach the policy to a RAM role. This way, the permissions that are defined in this policy are granted to the RAM role.

Step 3: Authorize a RAM role

A RAM role can access resources only after it is authorized. To authorize a single RAM role, you can click Add Permissions in the Actions column of the RAM role on the Roles page. To authorize multiple RAM roles at a time, perform the following steps:

  1. In the RAM console, choose Permissions > Grants in the left-side navigation pane.
  2. On the page that appears, click Grant Permission.
  3. On the Grant Permission page, enter the names of RAM roles in the Principal field, select policies that you want to attach to the RAM roles, and then click OK.

After you authorize RAM roles, you can grant a RAM user the permission to assume RAM roles.

Step 4: Grant a RAM user the permission to assume a RAM role

After a policy is attached to a RAM role, the RAM role obtains the permissions that are defined in the policy. However, a RAM role is only a virtual user identity. The RAM role can be used to perform the allowed operations only after a RAM role is assumed by a RAM user. If any RAM user can assume a RAM role, security risks are caused. To prevent such risks, a RAM user can assume RAM roles only after the RAM user is authorized.

To authorize a RAM user to assume a RAM role, you can create a custom policy in which the Resource parameter is set to the ID of the RAM role. Then, you can use this policy to authorize the RAM user.

  1. Log on to the RAM console. In the left-side navigation pane, choose Permissions > Policies.
  2. On the Policies page, click Create Policy.
  3. On the Create Policy page, click the JSON tab.
  4. Specify the policy parameters and click Next Step.
    Note In the policy content, set the Resource parameter to the Alibaba Cloud Resource Name (ARN) of a RAM role. To view the ARN of a RAM role, go to the Roles page and click the name of the RAM role. You can view the ARN of the RAM role in the Basic Information section.

    Example:

    {
        "Version":"1",
        "Statement":[
            {
                "Effect":"Allow",
                "Action":"iot:QueryProduct",
                "Resource":"ARN of a RAM role"
            }
        ]
    }
  5. Specify the Name and Note parameters, and then click OK.
  6. After the policy is created, return to the RAM console homepage.
  7. In the left-side navigation pane, choose Identities > Users.
  8. In the list of RAM users, select a RAM user that you want to authorize and click Add Permissions below the list of RAM users.
  9. In the Add Permissions panel, select the created policy and click OK.

After the authorization is complete, the RAM user obtains the permission to assume the specified RAM role. Then, you can use STS to obtain the temporary identity credentials that are required to access resources.

Step 5: Obtain temporary identity credentials for a RAM user

Authorized RAM users can call the STS API operations or use STS SDKs to obtain the temporary identity credentials. The temporary identity credentials include an AccessKey ID, AccessKey secret, and security token. For more information about the STS API and STS SDKs, see STS API reference and STS SDK reference in the RAM documentation.

The following parameters are required when you use the STS API or SDK to obtain temporary identity credentials:

  • RoleArn: the ARN of the RAM role that the RAM user is to assume.
  • RoleSessionName: the name of the temporary identity credentials. This is a custom parameter.
  • Policy: the policy that specifies the permissions of the RAM role to be granted to the RAM user. This parameter is used to generate a token with limited permissions of the RAM role. If you do not set this parameter, a token that has all permissions of the RAM role is returned.
  • DurationSeconds: the validity period of the temporary identity credentials. This parameter is measured in seconds. The default value is 3600 and the value ranges from 900 to 3600.
  • id and secret: the AccessKey ID and AccessKey secret of the RAM user.

The following examples show how to obtain temporary identity credentials.

API example: The RAM user calls the AssumeRole operation of STS to obtain the temporary identity credentials.

https://sts.aliyuncs.com?Action=AssumeRole
&RoleArn=acs:ram::1234567890123456:role/iotstsrole
&RoleSessionName=iotreadonlyrole
&DurationSeconds=3600
&Policy=<url_encoded_policy>
&<Common request parameters>

SDK example: The RAM user uses the Python command-line interface (CLI) for STS to obtain the temporary identity credentials.

$python ./sts.py AssumeRole RoleArn=acs:ram::1234567890123456:role/iotstsrole RoleSessionName=iotreadonlyrole Policy='{"Version":"1","Statement":[{"Effect":"Allow","Action":"iot:*","Resource":"*"}]}' DurationSeconds=3600 --id=id --secret=secret

After the request is successful, the temporary identity credentials are returned. The credentials include an AccessKey ID, AccessKey secret, and security token.

Step 6: Access resources as a RAM user

After a RAM user obtains the temporary identity credentials, the RAM user can pass in the credentials in SDK requests to assume the specified RAM role.

The following sample code shows that a RAM user uses STS SDK for Java to assume a RAM role. The RAM user passes in the AccessKey ID, AccessKey secret, and security token in the request and creates the IAcsClient object.

IClientProfile  profile = DefaultProfile.getProfile("cn-hangzhou", AccessKeyId,AccessSecret);
RpcAcsRequest request.putQueryParameter("SecurityToken", Token);
IAcsClient client = new DefaultAcsClient(profile);
AcsResponse response = client.getAcsResponse(request);