SourceIdentity通過在角色扮演時設定源身份標識，實現複雜情境下的身份溯源與精微調權限控制。 - Resource Access Management

本文將詳細介紹SourceIdentity的核心概念、配置方法、存取控制策略、典型應用情境及故障排除方法。

什麼是SourceIdentity

SourceIdentity是您在通過調用OpenAPI扮演RAM角色以擷取臨時安全性權杖（STS Token）時，為當前會話設定的源身份標識。

使用SourceIdentity的意義主要在於：

在角色鏈等複雜情境下進行身份溯源
角色鏈指 RAM 身份（或角色SSO）通過角色扮演獲得了角色會話後又再次通過 API 扮演其他角色的情境（例如：使用者A → 角色B → 角色C）。角色鏈中的RAM角色可以屬於同一個阿里雲帳號，也可以屬於不同帳號（跨帳號）。
在角色扮演情境下，可以設定 RoleSessionName 用於審計源身份。然而，在角色鏈情境下RoleSessionName 可能在多次角色扮演過程中被修改，導致無法準確擷取到最初操作發起者的身份資訊。
SourceIdentity一旦在角色鏈的起點設定，該值將在角色會話中持續存在且不可更改。這確保了即使經過多次角色扮演，最初發起操作的身份依然可以被日誌所追溯。
您可在角色鏈樣本中瞭解SourceIdentity在角色鏈中的具體應用情境。
對高許可權角色進行精微調權限控制
管理員可以通過 SourceIdentity 的值或存在性配置精細授權，特別是當使用共用角色（同一角色被多個身份共同使用）執行操作時。
例如，管理員通過在權限原則中使用條件控制關鍵字的方式，來強制要求源身份在扮演角色時必須設定符合要求的SourceIdentity值，以此限制只有特定的源身份才能扮演某個高許可權角色，或者訪問某些核心資源。

設定SourceIdentity的方法

您可以通過以下三種API介面，在調用STS進行角色扮演時設定SourceIdentity。

使用AssumeRole介面

在調用AssumeRole API時，通過SourceIdentity參數直接指定源身份資訊。例如，設定為Alice。適用於常規角色扮演情境，即一個RAM使用者或RAM角色扮演另一個角色。

調用成功後，SourceIdentity會作為獨立一級欄位在響應中返回。樣本如下：

{
  "RequestId": "6894B13B-6D71-4EF5-88FA-F3278173****",
  "AssumedRoleUser": {
    "AssumedRoleId": "34458433936495****:alice",
    "Arn": "acs:ram::123456789012****:role/alice"
  },
  "Credentials": {
    "SecurityToken": "********",
    "Expiration": "2015-04-09T11:52:19Z",
    "AccessKeySecret": "wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****",
    "AccessKeyId": "STS.L4aBSCSJVMuKg5U1****"
  },
  "SourceIdentity": "Alice"
}

具體調用方法，請參見AssumeRole - 擷取扮演角色的臨時身份憑證。

使用AssumeRoleWithSAML介面

用於SAML角色SSO情境中，SourceIdentity的值由身份供應商（IdP）在SAML斷言（SAML Assertion）中提供。

您需要在IdP中配置一個SAML屬性，並將其映射到使用者的身份標識（如使用者名稱）。該屬性的名稱必須為 https://www.aliyun.com/SAML-Role/Attributes/SourceIdentity。

配置完成後，在由IdP所頒發的SAML響應中會包含如下SAML斷言（假設將使用者的UPN首碼映射為SourceIdentity值）：

<Attribute Name="https://www.aliyun.com/SAML-Role/Attributes/SourceIdentity">      
  <AttributeValue>upn_prefix</AttributeValue>
</Attribute>

調用成功後的返回結果同使用AssumeRole介面的情境。具體調用方法，請參見AssumeRoleWithSAML - SAML角色SSO時擷取扮演角色的臨時身份憑證。

使用AssumeRoleWithOIDC介面

在OIDC角色SSO情境中，SourceIdentity的值由IdP在ID token（又稱OIDC令牌）中作為claim提供。

您需要在IdP中配置一個自訂ID token claim，並將其映射到使用者的身份標識（如使用者名稱）。該claim的名稱必須為https://www.aliyun.com/source_identity。例如：

配置完成後，在由IdP所頒發的ID token中會包含如下claim（假設將使用者的UPN首碼映射為SourceIdentity值）：

{
  "https://www.aliyun.com/source_identity": "upn_prefix"
}

調用成功後的返回結果同使用AssumeRole介面的情境。具體調用方法，請參見AssumeRoleWithOIDC - OIDC角色SSO時擷取扮演角色的臨時身份憑證。

格式要求

長度為2～64個字元。
可包含英文字母、數字以及特殊字元：=、,、.、@、-、_。
不能使用阿里雲保留的首碼，如acs:、aliyun:、alibabacloud:。

使用權限設定與條件控制

您可以結合使用身份權限原則和角色信任策略，對SourceIdentity的使用進行精確控制。

許可權操作

名稱	類型	使用範圍	功能
`sts:SetSourceIdentity`	許可權操作	身份權限原則角色信任策略	授予在扮演角色時設定`SourceIdentity`的許可權。

許可權操作配置樣本

要允許一個身份（RAM使用者或角色）在調用AssumeRole時設定SourceIdentity，您必須同時在扮演者的身份權限原則和目標角色的角色信任策略中授予sts:SetSourceIdentity操作許可權，也即在Action塊中增加sts:SetSourceIdentity。

身份權限原則樣本（授予扮演者）：

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

角色信任策略樣本（配置於被扮演的角色）：

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

角色SSO情境下的許可權操作配置樣本

在通過調用AssumeRoleWithSAML和AssumeRoleWithOIDC介面進行角色扮演的情境下，您僅需在目標角色的角色信任策略中授予sts:SetSourceIdentity操作許可權。例如（以SAML角色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"
}

重要

如果您在IdP中配置了SourceIdentity屬性，則所有與該IdP關聯的角色，其信任策略中都必須包含sts:SetSourceIdentity操作。否則，使用者通過SSO登入時會因缺少許可權而失敗。

條件關鍵字

名稱	類型	使用範圍	功能
`sts:SourceIdentity`	條件關鍵字	身份權限原則角色信任策略	關聯一個或多個`SourceIdentity`值。用於匹配角色扮演請求中的`SourceIdentity`值，以此判斷是否允許要求者設定某個`SourceIdentity`值。
`acs:SourceIdentity`	條件關鍵字（全域）	身份權限原則	關聯一個或多個`SourceIdentity`值。用於匹配角色會話中已存在的`SourceIdentity`值，以此判斷在訪問雲資源/雲端服務時，當前會話是否包含特定的`SourceIdentity`值。

說明

當前，acs:SourceIdentity條件關鍵字僅在STS服務的策略評估中生效。

sts:SourceIdentity與acs:SourceIdentity條件關鍵字的區別是：

sts:SourceIdentity匹配的是角色扮演請求中的SourceIdentity屬性。
acs:SourceIdentity匹配的是在角色扮演成功後，存在於角色會話（包括STS token）中的SourceIdentity屬性。

如果是首次進行角色扮演，應在策略（包括身份權限原則和角色信任策略）中配置sts:SourceIdentity條件關鍵字。由於此時還沒有產生有效角色會話，因此使用acs:SourceIdentity條件關鍵字將導致角色扮演失敗。

條件控制樣本

通過在策略的Condition塊中使用sts:SourceIdentity條件關鍵字，您可以強制要求扮演角色時必須傳入符合特定要求的SourceIdentity值。可以在以下兩類策略（任一或全部）中配置條件：

在身份權限原則中設定條件：限制該身份在扮演特定角色時，必須設定符合規定的SourceIdentity值。
在角色信任策略中設定條件：限制任何身份在扮演該角色時，都必須設定符合規定的SourceIdentity值。

請注意，在策略的Action塊中也必須添加sts:SetSourceIdentity操作許可權，否則將無法實現條件控制功能。

說明

RAM使用者登入控制台後，不支援通過切換身份功能扮演強制要求設定SourceIdentity的角色，因為控制台不支援輸入該參數。

假設有一個名為prod-role的生產環境高許可權RAM角色。管理員需要實現以下控制：

只有RAM使用者Alice和Bob可以扮演prod-role。
扮演prod-role時，必須設定SourceIdentity，且值必須與扮演者使用者名稱匹配（例如，Alice扮演時可以設定值為alice或alice@exampledomain.com）。

步驟1：配置prod-role的角色信任策略

該策略確保只有Alice和Bob可以扮演此角色，並且請求中必須包含值為alice或bob的SourceIdentity。

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

步驟2：為使用者Alice和Bob配置身份權限原則

以下策略分別授予Alice和Bob扮演prod-role的許可權，並強制他們在請求中設定與各自使用者名稱匹配的SourceIdentity。

Alice的身份權限原則

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

Bob的身份權限原則

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

角色SSO情境下的條件控制樣本

假設dev-role角色只允許通過SAML角色SSO方式扮演，並且僅限於員工號為employeeid-alice和employeeid-bob的使用者。IdP會將使用者的員工號作為SourceIdentity的值加入SAML斷言。

dev-role的信任策略配置如下：

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

條件控制使用建議

先測試，後生產：請勿直接在生產環境中啟用SourceIdentity的強制策略（包括配置了sts:SourceIdentity條件關鍵字的身份權限原則和角色信任策略）。建議先使用測試角色和策略進行充分驗證，確認無誤後，再逐步應用於生產環境。
提前溝通：在啟用強制策略前，請務必提前告知相關使用者SourceIdentity的使用方法和允許設定的值，以避免影響正常業務。

角色鏈樣本

情境描述

一個CI/CD自動化工具（如Jenkins）使用RAM角色automation-role運行。該角色允許被開發人員（如Alice和Bob）扮演。

開發人員（如Alice）通過該工具將某應用部署到生產環境的OSS Bucket。部署操作需要扮演一個更高許可權的角色deploy-role，該角色擁有OSS Bucket的寫入許可權。

Alice、Bob以及automation-role屬於阿里雲帳號A，deploy-role屬於阿里雲帳號B。

業務需求與工作流程

只允許當原始調用者是Alice時，automation-role才能成功扮演deploy-role。來自其他使用者（如Bob）的調用請求應該被拒絕。

工作流程如下：

Alice調用AssumeRole介面扮演automation-role，並在請求中設定SourceIdentity為alice。
automation-role獲得臨時安全性權杖（STS token）後，再調用AssumeRole介面扮演deploy-role。此時，SourceIdentity的值會被自動傳遞。
deploy-role的信任策略會檢查傳入的SourceIdentity是否為alice，如驗證通過則允許扮演。

策略配置步驟

步驟1: 修改deploy-role的信任策略

只信任來自帳號A下的角色automation-role的扮演請求，並且要求SourceIdentity的值必須是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"
}

說明

在上述角色信任策略中，使用的是條件關鍵字acs:SourceIdentity而非sts:SourceIdentity。這確保deploy-role角色只接受來自automation-role角色，且角色會話中SourceIdentity已被設定為alice的訪問請求。

步驟2: 修改automation-role的許可權與信任策略

身份權限原則：允許角色automation-role扮演帳號B下的角色deploy-role。

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

信任策略：允許Alice和Bob扮演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"
}

步驟3：修改Alice和Bob的身份權限原則

允許他們扮演角色automation-role，並強制設定與使用者名稱完全符合的SourceIdentity值。

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"
          ]
        }
      }
    }
  ]
}

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"
          ]
        }
      }
    }
  ]
}

在Action Trail中查看SourceIdentity

您可以在Action Trail（ActionTrail）的審計日誌中找到SourceIdentity欄位，用於身份溯源。

在AssumeRole*事件記錄中： SourceIdentity出現在responseElements及requestParameters欄位下。

{
  "eventId": "9BCD28D0-7FDB-5BF2-9302-CDA6CCC5****",
  "eventVersion": 1,
  "responseElements": {
    "SourceIdentity": "alice",
    "RequestId": "9BCD28D0-7FDB-5BF2-9302-CDA6CCC5****",
    ...
  },
  ...
  "requestParameters": {
    "SourceIdentity": "alice",
    "X-Acs-Request-Id": "9BCD28D0-7FDB-5BF2-9302-CDA6CCC5****",
    ...
  },
  "serviceName": "Sts",
  "eventName": "AssumeRole",
  ...
}

在訪問雲資源的事件記錄中： SourceIdentity出現在userIdentity.sessionContext欄位下。

{
  "eventId": "46B5B0A1-19F7-5A56-BE2C-0BCFE5F8****",
  "userIdentity": {
    "sessionContext": {
      "sourceIdentity": "alice",
      ...
    },
    "type": "assumed-role",
    ...
  },
  "serviceName": "Ecs",
  "eventName": "DescribeInstances",
  ...
}

常見故障排除

配置SourceIdentity時最常見的問題是許可權不足。以下是兩種典型的錯誤情境及其排查方法。

情境一：身份權限原則導致的問題

報錯資訊：

{
  "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",
    ...
  }
}

原因分析：

"PolicyType": "AccountLevelIdentityBasedPolicy" 表明錯誤源於調用者的身份權限原則。
"AuthAction": "sts:SetSourceIdentity" 表明缺少sts:SetSourceIdentity操作的許可權。

解決方案：聯絡管理員檢查調用者的身份權限原則，確保：

策略中包含了"Action": "sts:SetSourceIdentity"。
策略的Resource範圍包含了您嘗試扮演的目標角色。
如果策略中包含Condition，請確認請求中的SourceIdentity值符合條件。

情境二：角色信任策略導致的問題

報錯資訊：

{
  "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",
    ...
  }
}

原因分析：

"PolicyType": "AssumeRolePolicy" 表明錯誤源於目標角色的角色信任策略。
"AuthAction": "sts:SetSourceIdentity" 表明目標角色不信任sts:SetSourceIdentity這個操作。

解決方案：聯絡管理員檢查目標角色的角色信任策略，確保：

策略中包含了"Action": "sts:SetSourceIdentity"。
如果策略中包含Condition，請確認請求中的SourceIdentity值符合條件。

一般排查建議

縮小範圍：如果在設定SourceIdentity時遇到許可權問題，可先嘗試移除SourceIdentity參數並再次扮演角色。如果此時操作成功，則問題基本可以定位在SourceIdentity相關的許可權配置上。
分析報錯：仔細閱讀報錯資訊中的AccessDeniedDetail部分，尤其是PolicyType欄位，它可以協助您快速定位問題源於身份權限原則還是角色信任策略。
使用診斷工具：如果您只有RequestId，可以使用OpenAPI問題診斷工具。輸入RequestId後，系統會返回詳細的診斷資訊，協助您定位許可權問題。例如：
對比策略與請求：定位到具體策略後，請仔細核對策略中的Resource和Condition等設定，確保其與API請求中的目標角色ARN、SourceIdentity值等參數匹配。

更多許可權問題排錯方法，請參見：如何排查無許可權的訪問錯誤。