生效条件

简介

生效条件是访问策略语言中的一部分，一个完整的生效条件包括如下元素：

• 条件键：表示生效条件的具体类型，例如用户访问来源 IP、授权时间等。
• 条件操作符：表示生效条件的判断方法。
• 条件值：指条件键的值。

详情可参见 访问管理 CAM 生效条件。

说明：

• 当您使用条件键编写策略时，请务必遵循最小权限原则，仅为适用请求（action）添加相应的条件键，避免在指定操作（action）时使用通配符“*”，导致请求失败。
• 当您使用访问管理 CAM 控制台创建策略时，请注意语法格式，version、principal、statement、effect、action、resource、condition 语法元素需保持首字母大写或者全小写。

生效条件示例

以下存储桶策略示例中的生效条件（condition）表示用户必须在 10.217.182.3/24 或者 111.21.33.72/24 网段才能完成授权 cos:PutObject 操作。其中，

• 条件键为 qcs:ip，表示生效条件的类型是 IP。
• 条件操作符为 ip_equal，表示生效条件的判断方法是判断 IP 地址是否相等。
• 条件值为数组 ["10.217.182.3/24","111.21.33.72/24"]，表示生效条件判断的规定值。若用户处于数组中任意一个 IP 所在的网段，条件判断都为 true。

{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:PutObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "ip_equal":{
                    "qcs:ip":[
                        "10.217.182.3/24",
                        "111.21.33.72/24"
                    ]
                }
            }
        }
    ]
}

COS 支持的条件键

说明：

条件键 tls-version 当前仅支持北京地域，其他地域将陆续支持。

对象存储（Cloud Object Storage，COS）支持的条件键包括两类，一类是所有请求都适用的，包括 IP、VPC 和 HTTPS；一类是来自请求头部和请求参数的条件键，一般只适用于需要携带该请求头部或者请求参数的请求。关于这些条件键的说明和使用实例可参见 条件键说明及使用示例 文档。

说明：

生效条件、条件键等概念都是针对用户请求的访问管理进行的。由于生命周期、存储桶复制规则生效时的删除、复制等动作是由 COS 发起，不是用户发起的请求，条件键对生命周期、存储桶复制规则发起的动作无效。

适用于所有请求的条件键

第一类，所有请求都适用的条件键。包括 qcs:ip、qcs:vpc 和 cos:secure-transport，分别表示请求来源的 IP 网段、VPC ID 以及是否使用了 HTTPS 协议，所有请求都可以使用。

来自请求头部和请求参数的条件键

第二类，来自请求头部（Header）和请求参数（Param）的条件键。由于不同的请求具有不同的请求头部和请求参数，因此这些条件键一般只适合在包含这类头部或请求参数的请求中使用。

例如，条件键 cos:content-type 适用于需要使用请求头部 Content-Type 的上传类请求（PutObject 等），条件键 cos:response-content-type 适用于只适用于 GetObject 请求，因为只有该请求支持请求参数 response-content-type。

下表列出了 COS 目前支持的来自请求头部和请求参数的条件键和这些条件键适用的请求。

条件操作符

COS 的条件键支持以下条件操作符，适用于字符串（String）、数值型（Numeric）、布尔型（Boolean）和 IP 等不同类型的条件键。

_if_exist 的含义

以上所有条件操作符都支持在后面添加 _if_exist 成为一个条件操作符。例如 string_equal_if_exist。条件操作符是否包含 _if_exist 的区别在于请求不带条件键对应的请求头或请求参数时如何处理。

• 条件操作符不含有 _if_exist，例如 string_equal，当请求不带对应的请求头/请求参数时，默认不命中条件，即为 False。
• 条件操作符含有 _if_exist，例如 string_equal_if_exist，当请求不带对应的请求头/请求参数时，默认命中条件，即为 True。

示例

示例1：允许下载指定的对象版本

例如，对于下面这个存储桶策略，效力为 allow，表示允许请求参数 versionid 为 “MTg0NDUxNTc1NjIzMTQ1MDAwODg“ 的 GetObject 请求通过。如果命中了条件（True），根据 allow 的授权策略，请求会通过；如果没有命中条件（False），根据 allow 的授权策略，请求未获得授权，请求会失败。

{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:GetObject"
            ],
            "condition":{
                "string_equal":{
                    "cos:versionid":"MTg0NDUxNTc1NjIzMTQ1MDAwODg"
                }
            },
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ]
        }
    ]
}

当条件操作符是 string_equal 或 string_equal_if_exist，condition 命中情况和请求是否通过如下表所示。

示例2：拒绝下载指定的对象版本

以下存储桶策略示例，效力为 deny，表示拒绝请求参数 versionid为 “MTg0NDUxNTc1NjIzMTQ1MDAwODg” 的 GetObject 请求。如果命中了条件（True），根据 deny 的授权策略，请求会失败；如果没有命中条件（False），根据 deny 的授权策略，请求不会被拒绝。

{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"deny",
            "action":[
                "name/cos:GetObject"
            ],
            "condition":{
                "string_equal":{
                    "cos:versionid":"MTg0NDUxNTc1NjIzMTQ1MDAwODg"
                }
            },
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ]
        }
    ]
}

当条件操作符是 string_equal 或 string_equal_if_exist，condition 命中情况和请求是否被拒绝如下表所示。

相关说明

特殊字符需经过 urlencode

请求参数中的特殊字符都需要经过 urlencode，因此您在存储桶策略中使用来自请求参数的条件键时，需要先经过 urlencode。例如，您在使用 cos:response-content-type 条件键时，条件值 "image/jpeg" 必须经过 urlencode 转换为 "image%2Fjpeg"，再填入存储桶策略中。

遵循最小权限原则，避免使用*号

使用条件键时，请遵循最小权限原则，只添加您需要设置权限的 action，避免使用通配符“*”。滥用通配符“*”，可能导致部分请求失败。例如下面这个例子，GetObject 之外的其他请求均不支持使用请求参数 response-content-type。

deny + string_equal_if_exist 条件操作符在请求中缺失这一条件键时，默认按照 true 处理。因此，当您发起 PutObject、PutBucket 等请求时会命中这个 deny statement，请求被拒绝。

allow + string_equal 在请求中缺失这一条件键时，默认按照 false 处理。因此，当您发起 PutObject、PutBucket 等请求时无法命中 allow statement 时，请求不被允许。

{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"allow",
            "action":[
                "*"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_equal":{
                    "cos:response-content-type":"image%2Fjpeg"
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"deny",
            "action":[
                "*"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_not_equal_if_exist":{
                    "cos:response-content-type":"image%2Fjpeg"
                }
            }
        }
    ]
}

另一种方案，使用 allow+string_equal_if_exist 和 deny + string_not_equal，允许不带 response-content-type 请求参数的请求。

deny + string_equal 条件操作符在请求中缺失这一条件键时，默认按照 false 处理。因此，当您发起 PutObject、PutBucket 等请求时不会命中这个 deny statement，请求不被拒绝。

allow + string_equal_if_exist 在请求中缺失这一条件键时，默认按照 true 处理。因此，当您发起 PutObject、PutBucket 等请求时可以命中 allow statement，请求获得授权。

但这样使用条件操作符号，您将无法对 GetObject 是否携带 response-content-type 进行限制。当 GetObject 不携带 response-content-type 请求参数时，它和其他请求一样，将被默认允许通过。只有当 GetObject 携带了 response-content-type 请求参数时，您才可以按照自己规定的条件，检查请求参数的内容是否与您预期的一致，从而实现有条件的授权。

{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"allow",
            "action":[
                "*"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_equal_if_exist":{
                    "cos:response-content-type":"image%2Fjpeg"
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"deny",
            "action":[
                "*"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_not_equal":{
                    "cos:response-content-type":"image%2Fjpeg"
                }
            }
        }
    ]
}

因此，更加安全的方法是，遵循最小权限原则，不使用通配符“*”，将 action 限定在 GetObject。

如下面这个例子，策略生效条件被严格限定为：GetObject 请求必须携带 response-content-type，且请求参数的值必须为 "image%2Fjpeg"，才能获得授权。

对于其他请求，不受下面例子中策略的影响，您可以遵循最小权限原则，额外单独授权。

{
    "version":"2.0",
    "statement":[
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"allow",
            "action":[
                "name/cos:GetObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_equal":{
                    "cos:response-content-type":"image%2Fjpeg"
                }
            }
        },
        {
            "principal":{
                "qcs":[
                    "qcs::cam::uin/1250000000:uin/1250000001"
                ]
            },
            "effect":"deny",
            "action":[
                "name/cos:GetObject"
            ],
            "resource":[
                "qcs::cos:ap-guangzhou:uid/1250000000:examplebucket-1250000000/*"
            ],
            "condition":{
                "string_not_equal_if_exist":{
                    "cos:response-content-type":"image%2Fjpeg"
                }
            }
        }
    ]
}