Resource Access Management:Use SourceIdentity for role assumption traceability and access control

Format requirements

• The value must be 2 to 64 characters in length.

• The value can contain letters, digits, and the following special characters: =, ,, ., @, -, and _.

• The value cannot use prefixes reserved by Alibaba Cloud, such as acs:, aliyun:, or alibabacloud:.

Permission operation

Permission operation configuration example

To allow an identity, such as a RAM user or RAM role, to set SourceIdentity when calling AssumeRole, you must grant the sts:SetSourceIdentity permission in both the identity-based access policy of the principal and the role trust policy of the target role. Add sts:SetSourceIdentity to the Action block.

• Example of an identity-based access policy (granted to the principal):

  {
    "Version": "1",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "sts:AssumeRole",
          "sts:SetSourceIdentity"
        ],
        "Resource": "acs:ram::ACCOUNT_ID:role/TARGET_ROLE"
      }
    ]
  }

• Example of a role trust policy (configured for the assumed role):

  {
    "Statement": [
      {
        "Action": [
          "sts:AssumeRole",
          "sts:SetSourceIdentity"
        ],
        "Effect": "Allow",
        "Principal": {
          "RAM": [
            "acs:ram::ACCOUNT_ID:root"
          ]
        }
      }
    ],
    "Version": "1"
  }

Permission operation configuration example for a role-based SSO scenario

When you assume a role by calling the AssumeRoleWithSAML or AssumeRoleWithOIDC operation, you only need to grant the sts:SetSourceIdentity permission in the role trust policy of the target role. The following example shows a policy for SAML role-based SSO:

{
  "Statement": [
    {
      "Action": [
        "sts:AssumeRole",
        "sts:SetSourceIdentity"
      ],
      "Condition": {
        "StringEquals": {
          "saml:recipient": [
            "https://signin.aliyun.com/saml-role/sso"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "Federated": [
          "acs:ram::ACCOUNT_ID:saml-provider/PROVIDER_NAME"
        ]
      }
    }
  ],
  "Version": "1"
}

Condition keys

The difference between the sts:SourceIdentity and acs:SourceIdentity condition keys is as follows:

• sts:SourceIdentity matches the SourceIdentity attribute in the role assumption request.

• acs:SourceIdentity matches the SourceIdentity attribute that exists in the role session, including the STS token, after the role is successfully assumed.

If you are assuming a role for the first time, you must configure the sts:SourceIdentity condition key in the policy, including the identity-based access policy and the role trust policy. Because no valid role session has been generated yet, using the acs:SourceIdentity condition key will cause the role assumption to fail.

Condition control example

Using the sts:SourceIdentity condition key in the Condition block of a policy, you can require that a specific SourceIdentity value must be passed when a role is assumed. You can configure conditions in one or both of the following types of policies:

• Set conditions in an identity-based access policy: Restrict the identity to setting a specific SourceIdentity value when it assumes a specific role.

• Set conditions in a role trust policy: Restrict any identity to setting a specific SourceIdentity value when assuming the role.

Note that you must also add the sts:SetSourceIdentity permission to the Action block of the policy. Otherwise, the condition control feature will not work.

Assume there is a high-privilege RAM role for the production environment named prod-role. An administrator needs to implement the following controls:

1. Only the RAM users Alice and Bob can assume prod-role.

2. When assuming prod-role, SourceIdentity must be set, and its value must match the username of the principal. For example, when Alice assumes the role, the value can be set to alice or alice@exampledomain.com.

Step 1: Configure the role trust policy for prod-role

This policy ensures that only Alice and Bob can assume this role, and the request must contain a SourceIdentity value that starts with alice or bob.

{
  "Statement": [
    {
      "Action": [
        "sts:AssumeRole",
        "sts:SetSourceIdentity"
      ],
      "Condition": {
        "StringLike": {
          "sts:SourceIdentity": [
            "alice*",
            "bob*"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "RAM": [
          "acs:ram::ACCOUNT_ID:user/alice",
          "acs:ram::ACCOUNT_ID:user/bob"
        ]
      }
    }
  ],
  "Version": "1"
}

Step 2: Configure identity-based access policies for Alice and Bob

The following policies grant Alice and Bob the permission to assume prod-role and require them to set a SourceIdentity value that matches their respective usernames in the request.

• Alice's identity-based access policy

  {
    "Version": "1",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "sts:AssumeRole",
          "sts:SetSourceIdentity"
        ],
        "Resource": "acs:ram::ACCOUNT_ID:role/prod-role",
        "Condition": {
          "StringLike": {
            "sts:SourceIdentity": [
              "alice*"
            ]
          }
        }
      }
    ]
  }

• Bob's identity-based access policy

  {
    "Version": "1",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "sts:AssumeRole",
          "sts:SetSourceIdentity"
        ],
        "Resource": "acs:ram::ACCOUNT_ID:role/prod-role",
        "Condition": {
          "StringLike": {
            "sts:SourceIdentity": [
              "bob*"
            ]
          }
        }
      }
    ]
  }

{
  "Statement": [
    {
      "Action": [
        "sts:AssumeRole",
        "sts:SetSourceIdentity"
      ],
      "Condition": {
        "StringEquals": {
          "saml:recipient": [
            "https://signin.aliyun.com/saml-role/sso"
          ],
          "sts:SourceIdentity": [
            "employeeid-alice",
            "employeeid-bob"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "Federated": [
          "acs:ram::ACCOUNT_ID:saml-provider/PROVIDER_NAME"
        ]
      }
    }
  ],
  "Version": "1"
}

Scenario description

A Continuous Integration/Continuous Deployment (CI/CD) automation tool, such as Jenkins, runs using the RAM role automation-role. This role can be assumed by developers, such as Alice and Bob.

A developer, such as Alice, uses the tool to deploy an application to an OSS bucket in the production environment. The deployment operation requires assuming a higher-privilege role, deploy-role, which has write permissions on the OSS bucket.

Alice, Bob, and automation-role belong to Alibaba Cloud account A. deploy-role belongs to Alibaba Cloud account B.

Business requirements and workflow

automation-role can successfully assume deploy-role only when the original caller is Alice. Call requests from other users, such as Bob, should be rejected.

The workflow is as follows:

1. Alice calls the AssumeRole operation to assume automation-role and sets SourceIdentity to alice in the request.

2. After automation-role obtains an STS token, it calls the AssumeRole operation again to assume deploy-role. The SourceIdentity value is automatically passed.

3. The trust policy of deploy-role checks whether the incoming SourceIdentity is alice. If the verification is successful, the role assumption is allowed.

Policy configuration steps

Step 1: Modify the trust policy of deploy-role

This policy trusts only role assumption requests from the automation-role role in account A and requires that the SourceIdentity value must be alice.

{
  "Statement": [
    {
      "Action": [
        "sts:AssumeRole",
        "sts:SetSourceIdentity"
      ],
      "Condition": {
        "StringEquals": {
          "acs:SourceIdentity": [
            "alice"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "RAM": [
          "acs:ram::ACCOUNT_A_ID:role/automation-role"
        ]
      }
    }
  ],
  "Version": "1"
}

Step 2: Modify the access policy and trust policy of automation-role

• Access policy: Allows the automation-role role to assume the deploy-role role in account B.

  {
    "Version": "1",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "sts:AssumeRole",
          "sts:SetSourceIdentity"
        ],
        "Resource": "acs:ram::ACCOUNT_B_ID:role/deploy-role"
      }
    ]
  }

• Trust policy: Allows Alice and Bob to assume automation-role.

  {
    "Statement": [
      {
        "Action": [
          "sts:AssumeRole",
          "sts:SetSourceIdentity"
        ],
        "Effect": "Allow",
        "Principal": {
          "RAM": [
            "acs:ram::ACCOUNT_A_ID:user/alice",
            "acs:ram::ACCOUNT_A_ID:user/bob"
          ]
        }
      }
    ],
    "Version": "1"
  }

Step 3: Modify the identity-based access policies for Alice and Bob

Allow them to assume the automation-role role and require them to set a SourceIdentity value that exactly matches their username.

• Alice's identity-based access policy

  {
    "Version": "1",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "sts:AssumeRole",
          "sts:SetSourceIdentity"
        ],
        "Resource": "acs:ram::ACCOUNT_A_ID:role/automation-role",
        "Condition": {
          "StringEquals": {
            "sts:SourceIdentity": [
              "alice"
            ]
          }
        }
      }
    ]
  }

• Bob's identity-based access policy

  {
    "Version": "1",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "sts:AssumeRole",
          "sts:SetSourceIdentity"
        ],
        "Resource": "acs:ram::ACCOUNT_A_ID:role/automation-role",
        "Condition": {
          "StringEquals": {
            "sts:SourceIdentity": [
              "bob"
            ]
          }
        }
      }
    ]
  }

Scenario 1: Issues caused by an identity-based access policy

Error message:

{
  "RequestId": "AC9DDEC1-3E1F-50B8-A2D1-BAA155FD****",
  "Code": "NoPermission",
  "Message": "You are not authorized to do this action. You should be authorized by RAM.",
  "AccessDeniedDetail": {
    "PolicyType": "AccountLevelIdentityBasedPolicy",
    "AuthAction": "sts:SetSourceIdentity",
    ...
  }
}

Cause analysis:

• "PolicyType": "AccountLevelIdentityBasedPolicy" indicates that the error is caused by the caller's identity-based access policy.

• "AuthAction": "sts:SetSourceIdentity" indicates that the permission for the sts:SetSourceIdentity operation is missing.

Solution: Contact an administrator to check the caller's identity-based access policy and ensure the following:

1. The policy includes "Action": "sts:SetSourceIdentity".

2. The Resource scope of the policy includes the target role that you are trying to assume.

3. If the policy contains a Condition block, confirm that the SourceIdentity value in the request meets the conditions.

Scenario 2: Issues caused by a role trust policy

Error message:

{
  "RequestId": "ECC91EE1-0EB0-5E79-B3F5-E54FD8B9****",
  "Code": "NoPermission",
  "Message": "You are not authorized to do this action. You should be authorized by RAM.",
  "AccessDeniedDetail": {
    "PolicyType": "AssumeRolePolicy",
    "AuthAction": "sts:SetSourceIdentity",
    ...
  }
}

Cause analysis:

• "PolicyType": "AssumeRolePolicy" indicates that the error is caused by the target role's role trust policy.

• "AuthAction": "sts:SetSourceIdentity" indicates that the target role does not trust the sts:SetSourceIdentity operation.

Solution: Contact an administrator to check the target role's role trust policy and ensure the following:

1. The policy includes "Action": "sts:SetSourceIdentity".

2. If the policy contains a Condition block, confirm that the SourceIdentity value in the request meets the conditions.

General troubleshooting recommendations

1. Narrow the scope: If you encounter a permission issue when setting SourceIdentity, first try to remove the SourceIdentity parameter and assume the role again. If the operation succeeds, the issue is likely related to the permission configuration for SourceIdentity.

2. Analyze the error: Carefully read the AccessDeniedDetail section of the error message, especially the PolicyType field. This can help you quickly determine whether the issue is caused by an identity-based access policy or a role trust policy.

3. Use a diagnostic tool: If you only have the RequestId, use the OpenAPI Troubleshoot tool. Enter the RequestId, and the system returns detailed diagnostic information to help you locate the permission issue. For example:

   

4. Compare the policy and the request: After you locate the specific policy, carefully check the settings for Resource and Condition. Ensure that they match the parameters in the API request, such as the target role's ARN and the SourceIdentity value.

For more information about how to troubleshoot permission issues, see How to troubleshoot access errors due to insufficient permissions.