通过 API 管理访问策略
访问策略是一组用于评估后确定访问决策的规则和条件。 您可以创建定制访问策略。 所有定制访问策略在应用程序配置中显示为选项。
关于此任务
提供了一些缺省访问策略可供立即使用，但无法修改。 租户可以根据自己的需求添加定制访问策略。
- 规则以第一匹配为基础进行评估。 当规则中的所有条件的匹配求值为 true 时，将返回规则的结果作为评估决策。 未完成进一步处理。
- 可选参数
alwaysRun: true可以添加到单个规则中。 除了最优匹配的规则集以外，此参数导致此规则也将被评估。 最优匹配结果和alwaysRun参数组合在一起，限制最多的操作将作为策略结果进行应用。 多个alwaysRun规则可以添加到一个策略中。 - 如果策略需要条件的特定预订（例如设备管理），并且租户当前无权使用该预订，那么跳过该策略。 返回多因子认证 (MFA) 决策。
- 如果规则需要 MFA 的特定预订，并且租户当前无权使用该预订，那么评估的 MFA 决策更改为拒绝。 此更改保护应用程序，而不是允许无条件访问。
策略编辑器可用于创建和修改策略。 请参阅 “管理访问策略”。
无法使用策略编辑器添加某些条件。 在这些情况下，API 可用于修改现有策略或使用这些条件创建新的访问策略。
创建或更新访问策略时，将执行语法验证。
访问策略采用以下 JSON 格式：
注意：FedRAMP 不支持自适应访问。 因此， FedRAMP 用户无法使用任何 Trusteer 功能。
{
"name": "policy_name",
"description": "Description of the policy",
"schemaVersion": "urn:access:policy:4.0:schema",
"rules": [
{
"name": "allow_with_conditions",
"id": "1",
"conditions": {
"contextAttributes": {
"attributes": [
{
"name": "attrName",
"values": [
"value1",
"value2"
],
"opCode": "EQ"
}
]
},
"subjectAttributes": {
"attributes": [
{
"name": "realmName",
"values": [
"cloudIdentityRealm",
"www.ibm.com"
],
"opCode": "IN"
},
{
"name": "customAttr1",
"values": [
"val1"
],
"opCode": "NEQ"
}
]
},
"timeAttributes": {
"attributes": [
{
"name": "timezone",
"opCode": "EQ",
"values": [
"UTC Offset or GMT Offset"
]
},
{
"name": "startDate",
"opCode": "EQ",
"values": [
"YYYY-MM-DD HH:mm:ss"
]
},
{
"name": "endDate",
"opCode": "EQ",
"values": [
"YYYY-MM-DD HH:mm:ss"
]
},
{
"name": "Monday",
"opCode": "EQ",
"values": [
"hh:mm-hh:mm"
]
},
{
"name": "Tuesday",
"opCode": "EQ",
"values": [
"hh:mm-hh:mm"
]
}
]
},
"ipAddress": {
"opCode": "MATCH",
"values": [
"<ip_address>",
"<ip_address_range_start> - <ip_address_range_end>",
"<ip_address/subnet>"
]
},
"location": {
"attributes": [
{
"values": [
"3-Letter-ISO"
],
"name": "country",
"opCode": "IN"
}
]
}
"location": {
"attributes": [
{
"values": [
"<city>"
],
"name": "city",
"opCode": "IN"
}
]
}
"geoLocation": {
"enabled": "true"
},
"trusteer": {
"enabled": "true"
}
},
"result": {
"extendedAction": {
"action": "ACTION_ALLOW"
},
"authnMethods": []
}
},
{
"name": "Authentication factor validity",
"id": "2",
“alwaysRun”: true,
"conditions": {
"factorLifetimeAttributes": {
"attributes": [
{
"name": "anyFactor",
"opCode": "EQ",
"values": [
"120"
]
},
{
"name": "reauthPerDevice",
"opCode": "EQ",
"values": [
"enabled"
]
}
]
}
},
"result": {
"extendedAction": {
"action": "ACTION_MFA_OVERRIDE"
}
}
},
{
"name": "mfa_once_per_session_device_conditions",
"id": "3",
"contextAttributes": {
"attributes": [
{
"name": "devicePlatform",
"values": [
"IOS",
"ANDROID",
"OTHER_MOBILE",
"MACOS",
"WINDOWS",
"OTHER_DESKTOP"
],
"opCode": "IN"
},
{
"name": "deviceCompliance",
"values": [
"COMPLIANT",
"NONCOMPLIANT",
"UNKNOWN"
],
"opCode": "IN"
}
]
},
"result": {
"extendedAction": {
"action": "ACTION_MFA_PER_SESSION"
},
"authnMethods": [
"urn:ibm:security:authentication:asf:macotp"
]
}
},
{
"name": "deny_otherwise",
"id": "100",
"conditions": {},
"result": {
"extendedAction": {
"action": "ACTION_DENY"
},
"authnMethods": []
}
}
]
}
注： API 的绝大部分内容已在 Swagger 文档中进行了说明。 您可以通过管理员控制台 ”访问 Swagger 文档。 有关 Swagger API 的更多信息，请参阅 《验证应用程序编程接口 (API)》。
以下信息适用于 API 规则。
- 每个规则包含以下特性：
- name
- 规则的名称。
- id
- 事件数据和报告中使用的规则的唯一标识。
- conditions
- 每个规则可以存在多个条件。 规则中的所有条件必须求值为 true 以匹配规则并应用结果。 缺省规则包含空条件。
- 条件包含以下特性：
- contextAttributes
- 与运行访问策略的流上下文相关的属性。 这些属性包括设备管理属性、OpenID Connect 属性和 HTTP 请求属性。
- subjectAttributes
- 与已认证用户主题相关联的登录会话属性。
- factorLifetimeAttributes
- 使有效性与特定认证因子或方法关联。
- timeAttributes
- 启用基于时间的访问控制的时间属性。
- ipAddress
- 启用个人、范围或基于子网的允许或阻止列表的 IP 地址条件。
- location
- 从用户的 IP 地址解析的国家或地区或者城市。 根据以下 ISO 标准，国家或地区必须包含国家或地区名称或者三字母国家或地区代码的逗号分隔列表。 单个国家或地区或者三字母国家或地区代码是允许的。
城市必须包含城市名称的逗号分隔列表。 单个城市是允许的。
- geoLocation
- 验证访问决策的位置。 缺省设置适用于前 5 个已验证的位置。 condition 属性取值为 (true) 或
disabledenabled(false)。 - trusteer
- IBM Security Trusteer 检测到用户首次访问新设备。
- 这些属性包含以下特性：
- name
- 属性的名称。
- values
- 属性的值。
- opCode
- 运算符。
- 用于评估属性值的运算符：
- EQ
- 所有值都存在。
- NEQ
- 所有值都不存在。
- IN
- 一个或多个值存在。
- MATCH
- 用于匹配 IP 地址、范围或子网的 ipAddress 条件 opCode。
- NOMATCH
- 用于不匹配 IP 地址、范围或子网的 ipAddress 条件 opCode。
- 结果包含以下特性：
- Action
- 指定满足条件时要触发的操作。 有效值为：
- ACTION_ALLOW
- ACTION_MFA_ALWAYS - MFA 在访问策略评估期间规则每次都匹配。
- ACTION_MFA_PER_SESSION - MFA 每个已认证会话执行一次并在已完成时允许。
- ACTION_DENY。
- authnMethods
- 当执行多因素认证 (MFA) 操作时，请指定允许的认证机制。urn:ibm:security:authentication:asf:macotp - 允许用户选择可以完成的任何机制，或以下一个或多个因素：
emailotp- 电子邮件一次性密码smsotp- SMS 一次性密码totp- 基于时间的一次性密码（认证器应用程序）signatures- IBM® Verify 应用推送通知passkey- 密钥验证器voiceotp- 发送到用户的注册电话号码的口头一次性密码。anyFactor– 是urn:ibm:security:authentication:asf:macotp的别名。 此机制常用于factorLifetime条件，表示由用户完成的任何有效认证机制。
因子生命周期
此条件使有效性与特定认证因子或方法关联。 有效性可以与用户概要文件关联，或与用户设备关联。
此功能可用于实现业务逻辑，例如：
- 对于希望每个日历天对用户仅执行一次 MFA 的组织，您可以配置 18 小时周期的重新认证。
- 对于希望每个业务周对用户执行一次 MFA 的组织，您可以每 6 天配置一次策略。注意： 当此
reauthPerDevice选项启用时，系统会提示用户对“未知”设备进行多因素身份验证。 例如，用户从其他浏览器（是 Chrome，而不是 Edge），或者从其他物理设备进行认证。使用专用浏览方式后，在每个新会话中为第一次访问生成 MFA 质询。
注意： 包含此条件的规则必须是 “alwaysRun” 规则，且该规则中不得定义其他条件。
factorLifeTimeAttributes 包含以下必需属性：- name
- 有效的
authnMethods或anyFactor属性的列表。 - values
authnMethod的有效性时间间隔（以秒计）。- opCode
- EQ。
如果值为“已启用”，以下属性使 MFA 有效性与用户设备关联，如果值为“已禁用”，则与用户概要文件关联。
- name
reauthPerDevice.- values
- 已启用或已禁用。
- opCode
- EQ。
上下文属性
上下文属性可以包括设备管理属性、OpenID Connect 属性和 HTTP 请求属性。
- 设备管理上下文属性
- 设备管理属性 devicePlatform 和 deviceplince 是在 contextAttributes 条件下定义的。
- OpenID Connect 上下文属性
- 以下可用于 OpenID Connect 应用程序的大多数上下文属性为 OIDC 请求参数。 对于那些与请求参数名称不是一对一匹配的属性，提供了解释。 如需了解更多信息，请访问 https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest 和 https://tools.ietf.org/html/rfc7636#section-4.3。
- scope
- 此令牌接收的作用域的任意空格分隔的列表。 众所周知的作用域的示例为
emailaddressprofileopenid。 - response_type
- 以下一个或多个：
codetokenid_token。 有关支持的值，请参阅 https://oidc-dev-test.ite1.idng.ibmcloudsecurity.com/developer/explorer/#!/OpenID_Connect/handleAuthorizeGet。 - acr_values
- 将特定
ARC连接到特征认证。 - method
urn:ibm:security:policy:id:<policy-id>一个字符串列表，其中包含已执行的策略，格式为.- claims
- 复杂 JSON。
- response_mode
- 字符串，
query fragment form_post之一。 - response_method
- 指定从请求返回到 URI 的方法。
- code_challenge_exist
- PKCE 流中的布尔值选项，其指定是否在请求中设置
code_challenge。 - redirect_uri_scheme
- 重定向 URI 的方案组件，用于检测非浏览器用户代理程序和响应。
- client_type
- 指定客户机是
public还是confidential客户机。 机密客户机具有客户机密钥。 - request_type
client_registrationrevokeuser_infointrospectaccess_tokenauthorizationuser_authorizedevice_authorize标识请求来源的端点，包括、、、、、、、、、或。
- HTTP 请求上下文属性
- 可以在访问策略中评估 HTTP 请求头。 使用 HTTP 请求头名称作为 contextAttributes 中属性的名称，以及与入站头的值相对应的值。 当前不支持转换值，并且只能使用上下文属性的标准 opCodes。 例如，
"conditions": { "contextAttributes": { "attributes": [{ "name": "referer", "values": [ "https://<isv_tenant>/usc/", "https://<some_other_known_referrer>" ], "opCode": "IN" }, { "name": "user-agent", "values": [ "<specific_user_agent>" ], "opCode": "EQ" }, { "name": "x-forwarded-for", "values": [ "<x_forwarded_for_ip_address>" ], "opCode": "EQ" } ] } }
Cloud Directory 主题属性
以下主题属性可用于来自 Cloud Directory 身份源的用户。
- displayName
- 所显示的用户的名字。
- name
- 名字后跟姓氏。
- family_name
- 用户的姓氏。
- given_name
- 用户的名字。
- 用户的电子邮件。
- emailAddress
- 用户的电子邮件。
- groupIds
- 组标识。
- preferred_username
- 可更改的用户名。
- uuid
- 用户的唯一标识。
- uniqueSecurityName
- 用户的唯一标识。
- realmName
- 对于非联合 Cloud Directory 用户，此值始终为
cloudIdentityRealm。 - userType
- 对于非联合 Cloud Directory 用户，此值始终为
regular。
timeAttributes
时间属性。
- 这些属性包含以下特性：
- name
- 属性的名称。 name 是一周的某一天，也可以选择 timeZone、startDate 和 endDate。 它可以具有以下值：
- 周一
- 周二
- 周三
- 周四
- 星期五
- 星期六
- 周日
星期几时间范围由其
{ ... "values": [ "hh:mm-hh:mm" ]}中的范围启用，（可选）可以使用 startDate 和 endDate 登台。 - timeZone
- 与区域相关联的时区。 缺省值为全球标准时间 (UTC)。 值可以是以下任何格式。
UTC<+/-><offset>- 例如，UTC+10GMT<+/-><offset>- 例如，GMT-5- 时区数据库名称 - 例如，
Australia/Brisbane
- startDate
- 条件处于活动状态时的开始日期和时间。 可以单独使用它来创建使用星期几属性登台的块时间匹配。 startDate 优先于星期几。
YYYY-MM-DD HH:mm:ss数值采用. 格式。 对于一周中的某些天，值的格式为hh:mm-hh:mm。 - endDate
- 条件不再活动时的可选结束日期和时间。 可以单独使用它来创建与 startDate 匹配的块时间，或使用星期几属性登台。 在没有 endDate 的情况下，如果存在 startDate 或星期几，那么条件将无限匹配。 值的格式为
YYYY-MM-DD HH:mm:ss。
ipAddress
支持 IPv4 和 IPv6 的基于 IP 地址的条件。
- 条件包含以下特性：
- values
- 条件的值。 有效值为 IP 地址范围，以逗号分隔的 IP 地址列表或 CIDR IP 地址。
- opCode
- 运算符。 ipAddress 条件需要特定的 opCodes。可用的运算符：
- MATCH
- 所有值都存在。
- NOMATCH
- 所有值都不存在。
location
从用户的 IP 地址解析的国家或地区或者城市。 根据以下 ISO 标准，国家或地区必须包含国家或地区名称或者三字母国家或地区代码的逗号分隔列表。 参见 ISO 3166-1 alpha-3。 单个国家或地区或者三字母国家或地区代码是允许的。 城市必须包含城市名称的逗号分隔列表。 单个城市是允许的。
- 条件包含以下特性：
- 已启用
- 条件是启用 (true) 还是禁用 (false)。
- opCode
- 运算符。 location 条件需要特定的 opCodes。可用的运算符：
- IN
- 一个或多个值存在。
- NOT IN
- 所有值都不存在。
geoLocation
验证访问决策的位置。 缺省设置适用于前 5 个已验证的位置。
- 条件包含以下特性：
- 已启用
- 条件是启用 (true) 还是禁用 (false)。
trusteer
IBM Security Trusteer 检测到用户首次访问新设备。
- 条件包含以下特性：
- 已启用
- 条件是启用 (true) 还是禁用 (false)。