Resource Access Management:Tracing and access control with SourceIdentity

Format requirements

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

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

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

Actions

Example of action configuration

To allow an identity (a RAM user or role) to set SourceIdentity when calling AssumeRole, you must grant the sts:SetSourceIdentity permission in both the identity-based policy of the principal and the trust policy of the target role. This is done by adding sts:SetSourceIdentity to the Action block.

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

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

• Example of a trust policy (configured on the role to be assumed):

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

Role SSO action configuration

When you assume a role by calling the AssumeRoleWithSAML or AssumeRoleWithOIDC operations, grant the sts:SetSourceIdentity permission only in the target role's trust policy. The following policy is an example 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 a successful role assumption.

For the initial role assumption, you must use the sts:SourceIdentity condition key in your policies, including identity-based policies and trust policies. At this stage, no valid role session exists, so using the acs:SourceIdentity condition key at this stage will cause the assumption to fail.

Example of condition control

By using the sts:SourceIdentity condition key in a policy's Condition block, you can require a specific SourceIdentity value to be passed when a role is assumed. You can configure conditions in either or both of the following policy types:

• Set a condition in an identity-based policy: Restricts the identity to setting a specific SourceIdentity value when assuming a particular role.

• Set a condition in a trust policy: Restricts any identity to setting a specific SourceIdentity value when assuming this role.

The sts:SetSourceIdentity action must also be included in the policy's Action block for the condition to take effect.

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

1. Only 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 user assuming the role. For example, when Alice assumes the role, she can set the value to alice or alice@exampledomain.com.

Step 1: Configure the trust policy for prod-role

This policy ensures that only Alice and Bob can assume this role, and the request must include a SourceIdentity value that begins 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 policies for users Alice and Bob

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

• Identity-based policy for Alice

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

• Identity-based policy for Bob

  {
    "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

A CI/CD automation tool such as Jenkins runs with a RAM role named 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 action requires assuming a more privileged role, deploy-role, which has write permissions to the OSS Bucket.

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

Business requirement and workflow

The goal is to allow automation-role to assume deploy-role only when Alice is the original caller. Any request from another user, such as Bob, must be denied.

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 along.

3. The trust policy of deploy-role checks if the incoming SourceIdentity is alice. If the validation passes, the role assumption is allowed.

Policy configuration steps

Step 1: Modify the trust policy of deploy-role

This policy allows assumption requests only from automation-role in account A, and only if the SourceIdentity value is 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 permission and trust policies of automation-role

• Identity-based 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 policies for Alice and Bob

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

• Identity-based policy for Alice

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

• Identity-based policy for Bob

  {
    "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: Identity-based policy issue

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:

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

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

Solution: Ask your administrator to check the caller's identity-based policy and ensure the following:

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

2. The policy's Resource scope includes the target role you are trying to assume.

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

Scenario 2: Trust policy issue

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:

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

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

Solution: Ask your administrator to check the target role's trust policy and ensure the following:

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

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

General troubleshooting advice

1. Narrow down the scope: If you encounter a permission issue when setting SourceIdentity, try removing the SourceIdentity parameter and assuming the role again. If the action succeeds, the problem is likely with the permission settings related to SourceIdentity.

2. Analyze the error message: Read the AccessDeniedDetail section of the error message, especially the PolicyType field. It can help you quickly determine whether the issue is with an identity-based policy or a trust policy.

3. Use diagnostic tools: If you only have the RequestId, you can use the OpenAPI Explorer tool. Enter the RequestId, and the system will return detailed diagnostic information to help you pinpoint the permission issue. For example:

   A diagnostic result shows an ErrorCode of NoPermission and an ErrorMessage of You are not authorized to do this action. You should be authorized by RAM.. The permission check conclusion is Not authorized by identity-based policy (account-level) for the action sts:SetSourceIdentity. The solution suggests granting the RAM user the system policy AliyunSTSAssumeRoleAccess, which is associated with sts:SetSourceIdentity, or creating a custom policy.

4. Compare the policy and the request: After locating the policy, check that its Resource and Condition settings match your API request parameters, such as the target role ARN and the SourceIdentity value.

For more information about troubleshooting permission issues, see How to troubleshoot access denied errors.