IAM-policies

iam-policies

NPM code style: prettier Build Status NPM downloads Coverage Status deno doc semantic-release

介绍

自定义 IAM 政策来提供对资源访问的控制,并且可以设置可选的上下文几条件

拒绝政策高于认许政策

基于 @ddt/iamAWS Reference Policies .

安装

npm install --save iam-policies

或者

yarn add iam-policies

功能

提供以下功能:

使用

例子

首先需要得到政策类:

const { IdentityBasedPolicy, ResourceBasedPolicy } = require("iam-policies")

设置允许属性

const allowExample = new IdentityBasedPolicy([
  {
    effect: "allow", // 可选的, 默认值'allow'
    resource: ["secrets:${user.id}:*"], // 嵌入值
    action: ["read", "write"]
  },
  {
    resource: ["bd:company:*"],
    action: "create"
  }
])

const contextForAllowExample = { user: { id: 456 } }

allowExample.evaluate({
  action: "read",
  resource: "secrets:456:ultraSecret",
  context: contextForAllowExample
}) // true
allowExample.evaluate({
  action: "create",
  resource: "secrets:456:ultraSecret",
  context: contextForAllowExample
}) // false
allowExample.evaluate({
  action: "create",
  resource: "bd:company:account",
  context: contextForAllowExample
}) // true
allowExample.evaluate({
  action: "read",
  resource: "bd:company:account",
  context: contextForAllowExample
}) // false

设置拒绝属性

const denyExample = new IdentityBasedPolicy([
  {
    resource: ["secrets:${user.bestFriends}:*"],
    action: "read"
  },
  {
    effect: "deny",
    resource: "secrets:123:*",
    action: "read"
  }
])

const contextForDenyExample = { user: { bestFriends: [123, 563, 1211] } }

denyExample.evaluate({
  action: "read",
  resource: "secrets:563:super-secret",
  context: contextForDenyExample
}) // true
denyExample.evaluate({
  action: "read",
  resource: "secrets:123:super-secret",
  context: contextForDenyExample
}) // false

排除的行为属性

const notActionExample = new IdentityBasedPolicy([
  {
    resource: "bd:company:*",
    notAction: "update"
  }
])

notActionExample.evaluate({
  action: "delete",
  resource: "bd:company:account"
}) // true
notActionExample.evaluate({
  action: "update",
  resource: "bd:company:account"
}) // false

排除的资源属性

const notResourceExample = new IdentityBasedPolicy([
  {
    notResource: ["bd:roles:*"],
    action: "update"
  }
])

notResourceExample.evaluate({
  action: "update",
  resource: "photos"
}) // true
notResourceExample.evaluate({
  action: "update",
  resource: "bd:roles:admin"
}) // false

允许一切

const adminExample = new IdentityBasedPolicy([
  {
    resource: "*",
    action: "*"
  }
])

adminExample.evaluate({
  action: "read",
  resource: "someResource"
}) // true
adminExample.evaluate({
  action: "write",
  resource: "otherResource"
}) // true

条件属性

const conditions = {
  greaterThan: function (data, expected) {
    return data > expected
  }
}

const conditionExample = new IdentityBasedPolicy(
  [
    {
      resource: "secrets:*",
      action: ["read", "write"],
      condition: {
        greaterThan: {
          "user.age": 18
        }
      }
    }
  ],
  conditions
)

conditionExample.evaluate({
  action: "read",
  resource: "secrets:code",
  context: { user: { age: 19 } }
}) // true
conditionExample.evaluate({
  action: "read",
  resource: "secrets:admin:super-secret",
  context: {
    user: { age: 18 }
  }
}) // false

主要的属性

const principalExample = new ResourceBasedPolicy([
  {
    principal: "1",
    effect: "allow",
    resource: ["secrets:user:*"],
    action: ["read", "write"]
  },
  {
    principal: { id: "2" },
    resource: "bd:company:*",
    notAction: "update"
  }
])

principalExample.evaluate({
  principal: "1",
  action: "read",
  resource: "secrets:user:name"
}) // true
principalExample.evaluate({
  principal: "2",
  action: "read",
  resource: "secrets:user:super-secret"
}) // false
principalExample.evaluate({
  principal: "2",
  action: "read",
  resource: "bd:company:name",
  principalType: "id"
}) // true
principalExample.evaluate({
  principal: "2",
  action: "update",
  resource: "bd:company:name",
  principalType: "id"
}) // false

非主要属性

const notPrincipalExample = new ResourceBasedPolicy([
  {
    notPrincipal: ["1", "2"],
    resource: ["secrets:bd:*"],
    action: "read"
  },
  {
    notPrincipal: { id: "3" },
    resource: "secrets:admin:*",
    action: "read"
  }
])

notPrincipalExample.evaluate({
  principal: "3",
  action: "read",
  resource: "secrets:bd:tables"
}) // true
notPrincipalExample.evaluate({
  principal: "1",
  action: "read",
  resource: "secrets:bd:tables"
}) // false
notPrincipalExample.evaluate({
  principal: "1",
  action: "read",
  resource: "secrets:admin:friends",
  principalType: "id"
}) // true
notPrincipalExample.evaluate({
  principal: "3",
  action: "read",
  resource: "secrets:admin:friends",
  principalType: "id"
}) // false

使用 cancannot

const canAndCannotStatements = [
  {
    effect: "allow", // 可选的, 默认值'allow
    resource: ["website:${division.companyId}:${division.countryId}:*/*"],
    action: ["create", "update", "delete"]
  },
  {
    effect: "deny",
    resource: ["website:${division.companyId}:${division.countryId}:city/lima"],
    action: "delete"
  }
]

const inclusivePolicy = new IdentityBasedPolicy(canAndCannotStatements)

const contextCanAndCannot = {
  division: {
    companyId: 123,
    countryId: 456
  }
}

const canAndCannotDeniedArgument = {
  action: "delete",
  resource: "website:123:456:city/lima",
  context: contextCanAndCannot
}

inclusivePolicy.evaluate(canAndCannotDeniedArgument) // false
// 到这里, 我们还不确定参数是被拒绝还是不存在

inclusivePolicy.can(canAndCannotDeniedArgument) // true
// 是一个存在的允许政策, 所以应该是被拒绝了, 是吧?

inclusivePolicy.cannot(canAndCannotDeniedArgument) // true
// 事实证明, 我是对的。

const canAndCannotNotPresentArgument = {
  action: "read",
  resource: "website:123:456:}city/lima",
  context: contextCanAndCannot
}

inclusivePolicy.evaluate(canAndCannotNotPresentArgument) // false
// 在这里用户没有访问权限, 但是为什么呐, 我们看看

inclusivePolicy.can(canAndCannotNotPresentArgument) // false
// 这不是一个存在的允许政策, 但是是被拒绝了吗?

inclusivePolicy.cannot(canAndCannotNotPresentArgument) // false
// 不是的, 它不在那。

IdentityBasedPolicy 类

附加托管和内联政策到个体资源(用户,群, 或者规则)。 基于个体的政策授予权限给个体。

const { IdentityBasedPolicy } = require("iam-policies")

const identityBasedPolicy = new IdentityBasedPolicy(
  Statement,
  conditionResolver
)

Properties

名字 类型 默认值 必须的 描述
Statement object[] undefined true Statement 是政策对象中主要的元素,Statement 元素可以包含单个 statement 或者是包含一组 statement.
Statement[].effect string allow false effect 元素指明是被允许还是拒绝。 有效的值是 allowdeny.
Statement[].action string or string[] undefined false action元素描述行为, Statements 中必须包含action 或者 notAction 元素.
Statement[].notAction string or string[] undefined false notAction 元素是一个高级的政策元素, 它使得 statement 取匹配所有除了列出的所有行为。Statements 必须包含action 或者 notAction 元素. 通过使用 notAction,可以只列出少量的需要匹配的行为, 而不需要列出一个超长的列表。 当使用 notAction 的时候, 你需要注意,如果指明允许, 那么所有行为没有在这个元素中列出的将被允许,如果指明拒绝,那么所有不在这个属性里的行为将被拒绝。
Statement[].resource string or string[] undefined true resource 元素指明 statement 包含的对象。Statements 必须包含 resource 或者 notResource 元素.
Statement[].notResource string or string[] undefined true notResource 元素是一个高级政策元素, 它将匹配除了列表指定的所有的资源。Statements 必须包含 resourcenotResource 元素。 通过使用 notResource 你可以制定相对短的不匹配资源列表。
Statement[].condition object undefined false condition 元素 (或者条件块) 可以让你指定当政策生效时候的条件。 在condition 元素里边, 你可以通过条件运算符来创建表达式(equal, less than...) 来匹配在政策中的 keys,values 和在请求中的 keys, values.
Statement[].condition["conditionType"] object undefined false 对于特定条件的 conditionResolver 元素, conditionType 应该被替换成一个自定义的字符串
Statement[].condition["conditionType"]["conditionKey"] (string or number or boolean) or (string or number or boolean)[] undefined false 对于自定义的 context,conditionKey 应该是一个自定义的字符串路径。 备注: 属性必须以.分隔。

方法

identityBasedPolicy.evaluate({action, resource, context})

public: 验证针对特定资源的行为是被允许 (true) 还是拒绝 (false).

Params
名字 类型 默认值 必须的 描述
action string undefined true 描述行为。
resource string undefined true 描述资源。
context object undefined false 描述资源中嵌入的属性。

identityBasedPolicy.can({action, resource, context})

public: 验证针对特定资源的行为是被允许 (true) 还是拒绝 (false).

Params
名字 类型 默认值 必须的 描述
action string undefined true 描述行为。
resource string undefined true 描述资源。
context object undefined false 描述资源中嵌入的属性。

identityBasedPolicy.cannot({action, resource, context})

public: 验证针对特定资源的行为是被拒绝 (true) 还是不存在 (false)。

参数
名字 类型 默认值 必须的 描述
action string undefined true 描述行为。
resource string undefined true 描述资源。
context object undefined false 描述资源中嵌入的属性。

ResourceBasedPolicy 类

附加内联政策到个体资源。 Resource-based 政策授权给 principal.

const { ResourceBasedPolicy } = require("iam-policies")

const resourceBasedPolicy = new ResourceBasedPolicy(
  Statement,
  conditionResolver
)

属性

名字 类型 默认值 必须的 描述
Statement object[] undefined true Statement 是政策对象中主要的元素,Statement 元素可以包含单个 statement 或者是包含一组 statement.
Statement[].effect string allow false effect 元素指明是被允许还是拒绝。 有效的值是 allowdeny.
Statement[].principal string or string[] undefined false principal元素描述针对资源是允许或是拒绝行为, Statements 中必须包含principal 或者 notPrincipal 元素.
Statement[].notPrincipal string or string[] undefined false notPrincipal 元素指定 principal 不被允许或拒绝访问. notPrincipal 元素可以让你指定例外。使用这个元素, 可以拒绝所有 principal, 除了指定在notPrincipal 元素里边的.
Statement[].action string or string[] undefined false action元素描述行为, Statements 中必须包含action 或者 notAction 元素.
Statement[].notAction string or string[] undefined false notAction 元素是一个高级的政策元素, 它使得 statement 取匹配所有除了列出的所有行为。Statements 必须包含action 或者 notAction 元素. 通过使用 notAction,可以只列出少量的需要匹配的行为, 而不需要列出一个超长的列表。 当使用 notAction 的时候, 你需要注意,如果指明允许, 那么所有行为没有在这个元素中列出的将被允许,如果指明拒绝,那么所有不在这个属性里的行为将被拒绝。
Statement[].resource string or string[] undefined true resource 元素指明 statement 包含的对象。Statements 必须包含 resource 或者 notResource 元素.
Statement[].notResource string or string[] undefined true notResource 元素是一个高级政策元素, 它将匹配除了列表指定的所有的资源。Statements 必须包含 resourcenotResource 元素。 通过使用 notResource 你可以制定相对短的不匹配资源列表。
Statement[].condition object undefined false condition 元素 (或者条件块) 可以让你指定当政策生效时候的条件。 在condition 元素里边, 你可以通过条件运算符来创建表达式(equal, less than...) 来匹配在政策中的 keys,values 和在请求中的 keys, values.
Statement[].condition["conditionType"] object undefined false 对于特定条件的 conditionResolver 元素, conditionType 应该被替换成一个自定义的字符串
Statement[].condition["conditionType"]["conditionKey"] (string or number or boolean) or (string or number or boolean)[] undefined false 对于自定义的 context,conditionKey 应该是一个自定义的字符串路径。 备注: 属性必须以.分隔。

方法

resourceBasedPolicy.evaluate({principal, action, resource, context, principalType})

public: 验证针对特定资源的行为是被允许 (true) 还是拒绝 (false).

参数
名字 类型 默认值 必须的 描述
principal string undefined true 描述 principal。
action string undefined true 描述行为。
resource string undefined true 描述资源。
context object undefined false 描述资源中嵌入的属性。
principalType string undefined true 描述 principal 类型 (principal 的属性, 如果 statement 包含 principal 对象)。

resourceBasedPolicy.can({principal, action, resource, context, principalType})

public: 验证针对特定资源的行为是被允许 (true) 还是不存在 (false)。

参数
名字 类型 默认值 必须的 描述
principal string undefined true 描述 principal。
action string undefined true 描述行为。
resource string undefined true 描述资源。
context object undefined false 描述资源中嵌入的属性。
principalType string undefined true 描述 principal 类型 (principal 的属性, 如果 statement 包含 principal 对象)。

resourceBasedPolicy.cannot({principal, action, resource, context, principalType})

public: 验证针对特定资源的行为是被拒绝 (true) 还是不存在 (false)。

参数
名字 类型 默认值 必须的 描述
principal string undefined true 描述 principal。
action string undefined true 描述行为。
resource string undefined true 描述资源。
context object undefined false 描述资源中嵌入的属性。
principalType string undefined true 描述 principal 类型 (principal 的属性, 如果 statement 包含 principal 对象)。

getValueFromPath(data, path) Function

通过路径获取对象。

const { getValueFromPath } = require("iam-policies")

const value = getValueFromPath(data, path)

参数

名字 类型 默认值 必须的 描述
data object undefined true 上下文。
path string undefined true 数据中的路径。属性名通过.分隔。

applyContext(str, context) Function

获取嵌入到上下文的字符串

const { applyContext } = require("iam-policies")

const embeddedStr = applyContext(str, context)

参数

名字 类型 默认值 必须的 描述
str string undefined true 它可能包含嵌入的路径, 通过使用 (${}).
context object undefined false 指定上下文, 它应该被嵌入到 str 里边.

License

MIT © roggervalf