使用 IAM 访问条件分配对存储区中对象的访问权

IAM 访问策略允许将 Cloud Object Storage 存储区中的许可权授予特定对象组。此方法允许对数据访问进行细粒度访问控制，使其在需要由不同用户或应用程序访问存储区的不同部分的场景中很有用。

如果需要对整个存储区进行访问 (即，当不需要细颗粒度访问控制时)，请遵循分配对单个存储区的访问权上的信息。

存储在 Cloud Object Storage 存储区中的每个对象都具有唯一键，这些键通常遵循类似于文件系统的分层结构。

与 IAM 访问策略相关的链接

示例

具有键 "folder1/subfolder1/file.txt" 的单个对象可以模拟文件夹或目录层次结构，其中目录 “folder1” 包含名为 “sub-folder1” 的子目录，其中包含文件 "file.txt"。可以在任何文件夹级别分配访问权。
可以为所有对象创建访问策略，并且可以在名为 *“folder1”*的文件夹中创建访问策略，也可以仅为名为 *“subfolder1”*的子目录中的对象分配访问权。

策略管理员可以通过在创建 IAM 访问策略时配置条件来分配对各个对象和文件夹的访问权。下一节描述如何构造这些类型的策略。

构造细颗粒度访问控制策略

授予对存储区中各个对象的访问权的第一步是构造 IAM 策略。您可以在 Cloud Object Storage 教程限制对单个 Object Storage 存储区的访问中找到有关为 Object Storage 构造 IAM 访问策略的更多信息。有关构建 IAM 策略的更多常规信息，请转至 IBM Cloud IAM 工作方式。以下项目是为Object Storage资源构建 IAM 访问策略的关键组成部分。

主题

访问策略的主题可以是单个用户，访问组，服务标识或可信概要文件。有关可以应用于策略的主体类型的更多信息，请参阅哪些是 IAM 策略以及谁可以分配这些策略?。

服务

该服务是包含您尝试向其分配访问权的资源的 IBM Cloud 服务。要分配对个别对象的访问权，请使用 Cloud Object Storage 服务。

资源

IBM Cloud® Object Storage 支持以下资源目标:

资源组标识
服务实例
值为 "bucket" 的资源类型
资源标识 (存储区名称)

角色

IBM Cloud 访问角色是操作组。访问角色允许主体在策略中定义的目标资源的上下文中完成特定任务。 Cloud Object Storage 支持多个预定义的服务角色，这些角色使分配许可权变得更容易。 Cloud Object Storage 还允许创建定制角色。有关 Cloud Object Storage支持的角色的更多信息，请参阅 Identity and Access Management 角色。

要获取 Cloud Object Storage 角色及其与条件的交互的列表，请转至此表。

条件

标识资源时，可以使用条件来进一步限定对存储区中单个对象 (称为细颗粒度访问控制) 的对象的访问范围。

通过使用 OR 或 AND 语句来组合这些条件，单个 IAM 策略可以具有多个条件。条件语句 (包含一个或多个条件) 应该求值为 TRUE，以便允许用户请求执行操作。 IAM 策略将拒绝无法评估 TRUE 的任何操作。策略语句应包含角色所需的所有条件属性。如果策略语句未包含角色所需的所有条件属性，那么将拒绝符合省略的条件属性的操作。

使用没有条件属性的策略来授予对目标资源的完全访问权 (由角色定义)。

使用 IAM v2 策略来构造具有基于属性的条件的 IAM 策略。

在 IAM 策略中使用条件

Cloud Object Storage 支持以下属性，以指定在 Cloud Object Storage 资源上分配细颗粒度访问权的条件:

前缀和定界符

前缀和分隔符一起使用，可将所有列表权限范围扩大到水桶中的特定对象。

Prefix 条件属性定义此条件应允许列出对象或文件夹的对象键集的前缀。例如，在名为 "folder1/subfolder1/file.txt"的对象中，"folder1/" 和 “folder1/subfolder1/” 都是可能的前缀。
定界符 可帮助用户像浏览文件层次结构一样浏览存储区。指定定界符条件语句将限制用户可以在列表中生成的文件夹结构类型。在名为 *"folder1/subfolder1/file.txt"*的对象中，可以使用定界符 "/" 来模拟以 *"/"*分隔每个文件夹的文件夹层次结构。如果条件语句仅允许定界符 "/"，那么不允许具有任何其他定界符值的列表请求。

通常情况下，前缀和分隔符在条件语句中与 "AND 运算符一起使用。可以在条件语句中使用不带定界符的前缀。如果仅使用前缀而不是定界符条件语句来配置策略，那么用户可以使用任何定界符或不使用任何定界符来列出对象。

使用前缀和定界符条件语句的示例

请考虑名为 *"folder1/subfolder1/file.txt"*的对象:

"folder1/" 的前缀 AND 无定界符

通过对 folder1/ 执行列表请求并不提供定界符，可以返回以 folder1/ 开头的每个对象的列表。
如果在列表请求中使用定界符 "/"，那么将限制为只能看到 *folder1/*中的第一级对象和子文件夹。
如果用户尝试列出子文件夹 (请求列出前缀 = “folder1/subfolder1/”)，那么将拒绝访问。

"folder1/" 的前缀 AND "/" 的定界符

只能列出 folder1的第一级中的对象和子文件夹。
只能列出指定了定界符 *"/"*的请求。
如果尝试列出 subfolder1的内容，那么将拒绝访问 (用户需要具有允许前缀 = “folder1/subfolder1/" 以允许列出 subfolder1的内容的条件)。

以下 API 受前缀/定界符条件约束:

GET 存储区(列出对象)
GET 存储区对象版本 (列出对象版本)
列出多重部件上载

要查看操作的完整列表和受支持的条件属性，请参阅 Identity and Access Management 操作。

要授予细颗粒度用户访问权以在 UI 中浏览到其文件夹，用户需要具有列出存储区的根文件夹的访问权。请参阅场景 4，以了解如何构造策略以启用此功能。

路径

路径用于限定特定对象的所有读，写或管理访问权。

对于名为 *"folder1/subfolder1/file.txt"*的对象，完整对象键是路径。要将读，写或管理操作限制为此对象，请定义路径为 *"folder1/subfolder1/file.txt"*的条件。

直接对对象执行操作的所有 Cloud Object Storage API 都受路径条件限制。请参阅 Identity and Access Management 操作，以获取支持路径的 Cloud Object Storage API 操作的列表。

建议您在向同一策略中的用户授予读，写或列表操作时同时定义前缀/定界符条件和路径条件。Manager，Writer，Reader 和 Content Reader 是建议同时定义前缀/定界符和路径条件的角色示例。请参阅场景 4，以了解如何构造策略以启用此功能。在 IAM 策略语句中，指定前缀/定界符的条件和指定路径的条件应该在逻辑上为 ORed，以允许两种类型的操作 (对象或列表对象的读，写或管理)。

与条件属性配合使用的运算符

定义条件属性时可以使用多个运算符。可以在基于资源属性的条件中找到可用于前缀，定界符和路径条件属性的运算符的完整列表。

通配符的使用

当运算符为 stringMatch 或 stringMatchAnyOf 时，条件属性的值可以包含通配符。

在条件语句中使用通配符的示例:

请考虑名为 *"folder1/subfolder1/file.txt"*的对象:

“folder1/*”

您将获得对以 *“folder1/”*开头的所有对象的读，写或管理访问权 (由角色定义)。

"folder1/*" 的前缀 AND 无定界符

对于前缀设置为 “folder1/” 且没有定界符的对象列表请求，用户请求将返回以 *“folder1/”*开头的所有对象。
对于前缀设置为 “folder1/” 且定界符为 *"/"*的对象列表请求，该请求仅在 folder1的第一级返回对象和文件夹的视图。
对于前缀设置为 “folder1/subfolder1/” 且定界符为 *"/"*的对象列表请求，该请求仅在 folder1/subfolder1的第一级返回对象和文件夹的视图。

"folder1/*" 的前缀 AND "/" 的定界符

对于前缀设置为 “folder1/” 且定界符为 *"/"*的对象列表请求，该请求仅在 folder1的第一级返回对象和文件夹的视图。
对于前缀设置为 “folder1/subfolder1/” 且定界符为 *"/"*的对象列表请求，该请求将返回 folder1/subfolder1中的对象 (以及任何子文件夹)。
对于前缀设置为 “folder1/” 且没有定界符的对象列表请求，将不允许该请求，因为必须在列表请求中使用 "/" 定界符才能将此策略求值为 true。

不使用前缀/定界符或路径的操作

某些 Cloud Object Storage API 未指定路径或前缀和定界符。 Cloud Object Storage 服务角色 Manager，Writer，Reader 和 Content Reader 是包含这些操作的角色的示例。这也适用于定制角色。要在使用 Prefix/Delimiter 或 Path 条件时允许这些操作，IAM 策略中需要以下条件语句:

((path stringExists = false) AND (prefix stringExists = false) AND (delimiter stringExists= false))

请参阅 Identity and Access Management 操作表，以获取不支持 前缀/定界符 或路径条件且在使用细颗粒度访问时需要以上语句的 API 操作的完整列表。

请参阅有关如何为具有条件的用户创建新策略的部分，以在 IAM 策略中使用此子句。

将条件与 Cloud Object Storage 服务角色配合使用

使用 COS 服务角色的条件
访问角色	操作描述	受支持的条件属性
管理者	将对象设为公共对象，创建并销毁水桶和对象。	请参阅注释
写入者	创建和销毁水桶和对象	请参阅注释
读者	列出存储区，列出对象和下载对象。	请参阅注释
内容读取者	列出和下载对象。	请参阅注释
对象阅读器	下载对象。	路径
对象写程序	上载对象。	路径

注: 这些角色支持前缀/定界符和路径条件属性。这些角色还包括未指定路径或前缀和定界符的操作。在条件语句中使用 stringExists 子句以允许这些操作。

请参阅链接，以获取每个 Cloud Object Storage 服务角色的完整操作列表以及每个操作支持的条件属性列表。

为具有条件的用户创建新策略

以下示例为具有 “Writer” Cloud Object Storage 服务角色的用户提供了以下功能:

列出对名为 *"folder1/subfolder1"*的文件夹中完整对象层次结构的访问权。
对名为 *"subfolder1"*的文件夹中所有对象的读，写或删除访问权。
执行存储区配置管理，例如 HEAD Bucket 和 GET/PUT Bucket Versioning。

具有条件的 IAM 策略的 CLI

有关如何使用 CLI 的常规信息，请参阅使用 IBM Cloud® 命令行界面部分。

示例

policy.json:

{
"type": "access",
  "subject": {
    "attributes": [
      {
        "value": "IBMid-664001QJNU",
        "operator": "stringEquals",
        "key": "iam_id"
      }
    ]
  },
  "resource": {
    "attributes": [
      {
        "value": "cloud-object-storage",
        "operator": "stringEquals",
        "key": "serviceName"
      },
      {
        "value": "e6156134-5ed7-4f73-80d3-d6d1ef56f1f9",
        "operator": "stringEquals",
        "key": "serviceInstance"
      },
      {
        "value": "bucket",
        "operator": "stringEquals",
        "key": "resourceType"
      },
      {
        "value": "fgac-tf-test",
        "operator": "stringEquals",
        "key": "resource"
      }
    ]
  },
  "control": {
    "grant": {
      "roles": [
        {
          "role_id": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
        }      ]
    }
  },
  "rule": {
    "operator": "or",
    "conditions": [
      {
        "operator": "and",
        "conditions": [
          {
            "key": "{{resource.attributes.prefix}}",
            "operator": "stringMatch",
            "value": "folder1/subfolder1/*"
          },
          {
            "key": "{{resource.attributes.delimiter}}",
            "operator": "stringEqualsAnyOf",
            "value": [
              "/",
              ""
            ]
          }
        ]
      },
      {
        "key": "{{resource.attributes.path}}",
        "operator": "stringMatch",
        "value": "folder1/subfolder1/*"
      },
      {
        "operator": "and",
        "conditions": [
          {
            "key": "{{resource.attributes.delimiter}}",
            "operator": "stringExists",
            "value": false
          },
          {
            "key": "{{resource.attributes.prefix}}",
            "operator": "stringExists",
            "value": false
          },
          {
            "key": "{{resource.attributes.path}}",
            "operator": "stringExists",
            "value": false
          }
        ]
      }
    ]
  },
  "pattern": "attribute-based-condition:resource:literal-and-wildcard"
}
ibmcloud iam  user-policy-create hello@ibm.com --file policy.json --api-version v2

使用 --api-version v2 和基于资源的属性条件。

具有条件的 IAM 策略的 API

示例

请求

curl -X POST 'https://iam.cloud.ibm.com/v2/policies' \
-H 'Authorization: Bearer $TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "type": "access",
  "description": "access control for RESOURCE_NAME",
  "resource": {
    "attributes": [
      {
        "key": "serviceName",
        "operator": "stringEquals",
        "value": "cloud-object-storage"
      },
      {
        "key": "serviceInstance",
        "operator": "stringEquals",
        "value": "$SERVICE_INSTANCE"
      },
      {
        "key": "accountId",
        "operator": "stringEquals",
        "value": "$ACCOUNT_ID"
      },
      {
        "key": "resourceType",
        "operator": "stringEquals",
        "value": "bucket"
      },
      {
        "key": "resource",
        "operator": "stringEquals",
        "value": "$RESOURCE_NAME"
      }
    ]
  },
  "subject": {
    "attributes": [
      {
        "key": "iam_id",
        "operator": "stringEquals",
        "value": "IBMid-123453user"
      }
    ]
  },
  "control": {
    "grant": {
      "roles": [
        {
          "role_id": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
        }
      ]
    }
  },
  "rule": {
    "operator": "or",
    "conditions": [
      {
        "operator": "and",
        "conditions": [
          {
            "key": "{{resource.attributes.prefix}}",
            "operator": "stringMatch",
            "value": "folder1/subfolder1/*"
          },
          {
            "key": "{{resource.attributes.delimiter}}",
            "operator": "stringEqualsAnyOf",
            "value": [
              "/",
              ""
            ]
          }
        ]
      },
      {
        "key": "{{resource.attributes.path}}",
        "operator": "stringMatch",
        "value": "folder1/subfolder1/*"
      },
      {
        "operator": "and",
        "conditions": [
          {
            "key": "{{resource.attributes.delimiter}}",
            "operator": "stringExists",
            "value": false
          },
          {
            "key": "{{resource.attributes.prefix}}",
            "operator": "stringExists",
            "value": false
          },
          {
            "key": "{{resource.attributes.path}}",
            "operator": "stringExists",
            "value": false
          }
        ]
      }
    ]
  },
  "pattern": "attribute-based-condition:resource:literal-and-wildcard"
}'

响应

{
    "id": "d4078e99-d78a-4a50-95d6-b528e3c87dff",
    "description": "access control for RESOURCE_NAME",
    "type": "access",
    "subject": {
        "attributes": [
            {
                "key": "iam_id",
                "operator": "stringEquals",
                "value": "IBMid-123453user"
            }
        ]
    },
    "resource": {
        "attributes": [
            {
                "key": "serviceName",
                "operator": "stringEquals",
                "value": "cloud-object-storage"
            },
            {
                "key": "serviceInstance",
                "operator": "stringEquals",
                "value": "$SERVICE_INSTANCE"
            },
            {
                "key": "accountId",
                "operator": "stringEquals",
                "value": "$ACCOUNT_ID"
            },
            {
                "key": "resourceType",
                "operator": "stringEquals",
                "value": "bucket"
            },
            {
                "key": "resource",
                "operator": "stringEquals",
                "value": "$RESOURCE_NAME"
            }
        ]
    },
    "pattern": "attribute-based-condition:resource:literal-and-wildcard",
    "rule": {
        "operator": "or",
        "conditions": [
            {
                "operator": "and",
                "conditions": [
                    {
                        "key": "{{resource.attributes.prefix}}",
                        "operator": "stringMatch",
                        "value": "folder1/subfolder1/*"
                    },
                    {
                        "key": "{{resource.attributes.delimiter}}",
                        "operator": "stringEqualsAnyOf",
                        "value": [
                            "/",
                            ""
                        ]
                    }
                ]
            },
            {
                "key": "{{resource.attributes.path}}",
                "operator": "stringMatch",
                "value": "folder1/subfolder1/*"
            },
            {
                "operator": "and",
                "conditions": [
                    {
                        "key": "{{resource.attributes.delimiter}}",
                        "operator": "stringExists",
                        "value": false
                    },
                    {
                        "key": "{{resource.attributes.prefix}}",
                        "operator": "stringExists",
                        "value": false
                    },
                    {
                        "key": "{{resource.attributes.path}}",
                        "operator": "stringExists",
                        "value": false
                    }
                ]
            }
        ]
    },
    "control": {
        "grant": {
            "roles": [
                {
                    "role_id": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
                }
            ]
        }
    },
    "href": "https://iam.test.cloud.ibm.com/v2/policies/d4078e99-d78a-4a50-95d6-b528e3c87dff",
    "created_at": "2023-10-09T16:24:52.391Z",
    "created_by_id": " IBMid-12345user",
    "last_modified_at": "2023-10-09T16:24:52.391Z",
    "last_modified_by_id": " IBMid-12345user",
    "counts": {
        "account": {
            "current": 785,
            "limit": 4020
        },
        "subject": {
            "current": 1,
            "limit": 1000
        }
    },
    "state": "active",
    "version": "v1.0"
}

具有条件的 IAM 策略的 Terraform

示例

data "ibm_resource_group" "cos_group" {
      name = "Default"
}

resource "ibm_iam_user_policy" "example" {
 ibm_id = “user_email_id”
 roles = ["Writer"]
 resources {
  service = "cloud-object-storage"
  resource_type = "bucket"
  resource_instance_id = "cos instance guid"
  resource = "bucket-name"
}


rule_conditions {
 operator = "and"
 conditions {
  key = "{{resource.attributes.prefix}}"
  operator = "stringMatch"
  value = ["folder1/subfolder1/*"]
 }
 conditions {
  key = "{{resource.attributes.delimiter}}"
  operator = "stringEqualsAnyOf"
  value = ["/",""]
 }
 }
rule_conditions {
  key = "{{resource.attributes.path}}"
  operator = "stringMatch"
  value = ["folder1/subfolder1/*"]
 }
rule_conditions {
 operator = "and"
  conditions {
   key = "{{resource.attributes.delimiter}}"
   operator = "stringExists"
   value = ["false"]
  }
  conditions {
   key = "{{resource.attributes.prefix}}"
   operator = "stringExists"
   value = ["false"]
  }
  conditions {
   key = "{{resource.attributes.path}}"
   operator = "stringExists"
   value = ["false"]
  }
 }
rule_operator = "or"
 pattern = "attribute-based-condition:resource:literal-and-wildcard"
}

其他信息

有关如何使用 前缀/定界符或路径条件属性的示例，请参阅有关控制对存储区中各个对象的访问权的教程。