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 have long-term validity. 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 RAM Roles. On the RAM Roles page, click Create RAM Role to create a RAM role.
  3. In the Create RAM Role panel, select Alibaba Cloud Account for the Trusted entity type parameter. 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, you must enter the ID of an 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. Enter a policy name, select a configuration mode, configure the policy content, and then click OK.

    If you select Script for the Configuration Mode parameter, you must compile a script to configure the policy content. For more information about how to compile a script for a policy, see Policy structure and syntax.

    The following sample code configures 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 configures 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":"*"
            }
        ]
    }

After a policy is created, you can attach the policy to a RAM role to grant the permissions that are defined in this policy 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 RAM 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 Grants page, click Grant Permission.
  3. In the Add Permissions panel, 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. After a RAM role is assumed by a RAM user, the RAM role can be used to perform the operations that are allowed by the permissions. If all RAM users are allowed to play 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. In the RAM console, choose Permissions > Policies in the left-side navigation pane.
  2. On the Policies page, click Create Policy.
  3. On the Create Custom Policy page, enter a policy name, select Script as the configuration mode, configure the policy content, and then click OK.
    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 RAM Roles page and click the name of the RAM role. You can view the ARN of the RAM role in the Basic Information section.

    The following sample code shows a policy for role authorization:

    {
        "Version":"1",
        "Statement":[
            {
                "Effect":"Allow",
                "Action":"iot:QueryProduct",
                "Resource":"ARN of a RAM role"
            }
        ]
    }
  4. After a policy created, go to the homepage of the RAM console.
  5. In the left-side navigation pane, choose Identities > Users.
  6. 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.
  7. In the Add Permissions panel, select the created role authorization 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 for resource access.

Step 5: Obtain temporary identity credentials as a RAM user

Authorized RAM users can call the STS API operations or use STS SDKs to obtain the temporary identity credentials that are required to assume RAM roles. 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 generates 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 you how to obtain temporary identity credentials.

API example: The RAM user calls the AssumeRole operation of STS to obtain the temporary identity credentials that are required to assume RAM roles.

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 that are required to assume RAM roles.

$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 that are required to assume RAM roles 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 that are required to assume RAM roles, 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);