[comment]: # aside: 1
[comment]: # ({c9088bab-f9e8f670})
# 用户目录对象
以下对象与`userdirectory` API直接相关。
[comment]: # ({/c9088bab-f9e8f670})
[comment]: # ({726c81ec-ad144502})
### 用户目录
用户目录对象具有以下属性。
|属性|[类型](/manual/api/reference_commentary#data-types)|描述|
|--|--|------|
|userdirectoryid|ID|用户目录的 ID。
如果某个用户目录被删除，则所有关联到该已删除用户目录的用户，其 [User object](/manual/api/reference/user/object#user) 属性 `userdirectoryid` 的值都会被设置为 "0"。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- *只读*
- *更新操作时* *必需*|
|idp_type|integer|用户目录的身份提供商所使用的认证协议类型。
请注意，只能存在一个 SAML 类型的用户目录。
可能的值：
1 - LDAP 类型的用户目录；
2 - SAML 类型的用户目录。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- *创建操作时* *必需*|
|group_name|string|LDAP/SAML 用户目录属性，包含组名称，用于在 LDAP/SAML 用户目录与 Zabbix 之间映射组。
示例：*cn*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 如果 `provision_status` 设置为“已启用”，且 [Authentication object](/manual/api/reference/authentication/object#authentication) 的 `saml_jit_status` 设置为“为已配置的 SAML IdP 启用”，则该属性 *必需*|
|user_username|string|LDAP/SAML 用户目录属性（如果 `scim_status` 设置为“已启用 SCIM 配置”，则也可为 SCIM 属性），包含用户名称；在配置用户时，该值将用作 [User object](/manual/api/reference/user/object#user) 属性 `name` 的值。
示例：*cn*、*commonName*、*displayName*、*name*|
|user_lastname|string|LDAP/SAML 用户目录属性（如果 `scim_status` 设置为“已启用 SCIM 配置”，则也可为 SCIM 属性），包含用户姓氏；在配置用户时，该值将用作 [User object](/manual/api/reference/user/object#user) 属性 `surname` 的值。
示例：*sn*、*surname*、*lastName*|
|provision_status|integer|用户目录的配置状态。
可能的值：
0 - *(默认)* 已禁用（禁用由该用户目录创建的用户的配置）；
1 - 已启用（启用由该用户目录创建的用户的配置；此外，还必须启用 LDAP 或 SAML 配置状态（即 [Authentication object](/manual/api/reference/authentication/object#authentication) 的 `ldap_jit_status` 或 `saml_jit_status`））。|
|provision_groups|array|用于将 LDAP/SAML 用户组模式映射到 Zabbix 用户组和用户角色的 [配置组映射](object#provisioning-groups-mappings) 对象数组。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 如果 `provision_status` 设置为“已启用”，则该属性 *必需*|
|provision_media|array|用于将用户的 LDAP/SAML 媒介属性（例如电子邮件）映射到 Zabbix 用户媒介以发送通知的 [媒介类型映射](object#media-type-mappings) 对象数组。|
|**[LDAP](/manual/web_interface/frontend_sections/users/authentication/ldap)-特定属性：**|<|<|
|name|string|用户目录的唯一名称。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 如果 `idp_type` 设置为“LDAP 类型的用户目录”，则该属性 *必需*|
|host|string|LDAP 服务器的主机名、IP 或 URI。
URI 必须包含 schema（`ldap://` 或 `ldaps://`）、主机和端口（可选）。
示例：
*host.example.com*
*127.0.0.1*
*ldap://ldap.example.com:389*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 如果 `idp_type` 设置为“LDAP 类型的用户目录”，则该属性 *必需*|
|port|integer|LDAP 服务器的端口。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 如果 `idp_type` 设置为“LDAP 类型的用户目录”，则该属性 *必需*|
|base_dn|string|LDAP 用户目录中用户账户的基础路径。
示例：
*ou=Users,dc=example,dc=org*
*ou=Users,ou=system*（用于 OpenLDAP）
*DC=company,DC=com*（用于 Microsoft Active Directory）
*uid=%{user},dc=example,dc=com*（用于直接用户绑定；占位符 "*%{user}*" 为必填）
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 如果 `idp_type` 设置为“LDAP 类型的用户目录”，则该属性 *必需*|
|search_attribute|string|LDAP 用户目录属性，用于根据登录请求中提供的信息识别用户账户。
示例：
*uid*（用于 OpenLDAP）
*sAMAccountName*（用于 Microsoft Active Directory）
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 如果 `idp_type` 设置为“LDAP 类型的用户目录”，则该属性 *必需*|
|bind_dn|string|用于绑定并在 LDAP 服务器上执行搜索的 LDAP 服务器账户。
对于直接用户绑定和匿名绑定，`bind_dn` 必须为空。
示例：
*uid=ldap_search,ou=system*（用于 OpenLDAP）
*CN=ldap_search,OU=user_group,DC=company,DC=com*（用于 Microsoft Active Directory）
*CN=Admin,OU=Users,OU=Zabbix,DC=zbx,DC=local*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“LDAP 类型的用户目录”时，该属性 *受支持*|
|bind_password|string|用于绑定并在 LDAP 服务器上执行搜索的账户的 LDAP 密码。
对于直接用户绑定和匿名绑定，`bind_password` 必须为空。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“LDAP 类型的用户目录”时，该属性 *受支持*|
|description|string|用户目录的描述。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“LDAP 类型的用户目录”时，该属性 *受支持*|
|group_basedn|string|LDAP 用户目录中组的基础路径；用于在 LDAP 用户目录中配置用户成员资格检查。
如果设置了 `group_membership`，则在配置用户时会忽略该属性。
示例：*ou=Groups,dc=example,dc=com*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“LDAP 类型的用户目录”时，该属性 *受支持*|
|group_filter|string|用于检索用户所属 LDAP 用户目录组的过滤字符串；用于在 LDAP 用户目录中配置用户成员资格检查。
如果设置了 `group_membership`，则在配置用户时会忽略该属性。
支持的 `group_filter` 占位符：
*%{attr}* - 搜索属性（替换为 `search_attribute` 属性值）；
*%{groupattr}* - 组属性（替换为 `group_member` 属性值）；
*%{host}* - LDAP 服务器的主机名、IP 或 URI（替换为 `host` 属性值）；
*%{user}* - Zabbix 用户名。
默认值：*(%{groupattr}=%{user})*
示例：
- *(member=uid=%{ref},ou=Users,dc=example,dc=com)*：如果某个 LDAP 组对象包含值为 "*uid=User1,ou=Users,dc=example,dc=com*" 的 "*member*" 属性，则将匹配 "User1"，并返回 "User1" 所属的组；
- *(%{groupattr}=cn=%{ref},ou=Users,ou=Zabbix,DC=example,DC=com)*：如果某个 LDAP 组对象包含由 `group_member` 属性指定、值为 "*cn=User1,ou=Users,ou=Zabbix,DC=example,DC=com*" 的属性，则将匹配 "User1"，并返回 "User1" 所属的组。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“LDAP 类型的用户目录”时，该属性 *受支持*|
|group_member|string|LDAP 用户目录属性，包含有关组成员的信息；用于在 LDAP 用户目录中配置用户成员资格检查。
如果设置了 `group_membership`，则在配置用户时会忽略该属性。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“LDAP 类型的用户目录”时，该属性 *受支持*|
|group_membership|string|LDAP 用户目录属性，包含用户所属组的信息。
示例：*memberOf*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“LDAP 类型的用户目录”时，该属性 *受支持*|
|search_filter|string|自定义过滤字符串，用于根据登录请求中提供的信息在 LDAP 用户目录中定位并认证用户。
支持的 `search_filter` 占位符：
*%{attr}* - 搜索属性名称（例如 *uid*、*sAMAccountName*）；
*%{user}* - Zabbix 用户名。
默认值：*(%{attr}=%{user})*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“LDAP 类型的用户目录”时，该属性 *受支持*|
|start_tls|integer|LDAP 服务器配置选项，允许使用传输层安全性（TLS）来保护与 LDAP 服务器的通信。
请注意，对于使用 `ldaps://` 协议的主机，`start_tls` 必须设置为“已禁用”。
可能的值：
0 - *(默认)* 已禁用；
1 - 已启用。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“LDAP 类型的用户目录”时，该属性 *受支持*|
|user_ref_attr|string|用于引用用户对象的 LDAP 用户目录属性。`user_ref_attr` 的值用于从用户目录中的指定属性获取值，并将其替换到 `group_filter` 字符串中的 *%{ref}* 占位符位置。
示例：*cn*、*uid*、*member*、*uniqueMember*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“LDAP 类型的用户目录”时，该属性 *受支持*|
|**[SAML](/manual/web_interface/frontend_sections/users/authentication/saml)-特定属性：**|<|<|
|idp_entityid|string|用于标识身份提供商并在 SAML 消息中与身份提供商通信的 URI。
示例：*https://idp.example.com/idp*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 如果 `idp_type` 设置为“SAML 类型的用户目录”，则该属性 *必需*|
|sp_entityid|string|用于标识身份提供商服务提供者的 URL 或任意字符串。
示例：
*https://idp.example.com/sp*
*zabbix*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 如果 `idp_type` 设置为“SAML 类型的用户目录”，则该属性 *必需*|
|username_attribute|string|SAML 用户目录属性（如果 `scim_status` 设置为“已启用 SCIM 配置”，则也可为 SCIM 属性），包含用户的用户名；认证时会将其与 [User object](/manual/api/reference/user/object#user) 属性 `username` 的值进行比较。
示例：*uid*、*userprincipalname*、*samaccountname*、*username*、*userusername*、*urn:oid:0.9.2342.19200300.100.1.1*、*urn:oid:1.3.6.1.4.1.5923.1.1.1.13*、*urn:oid:0.9.2342.19200300.100.1.44*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 如果 `idp_type` 设置为“SAML 类型的用户目录”，则该属性 *必需*|
|sso_url|string|身份提供商的 SAML 单点登录服务 URL，Zabbix 会将 SAML 认证请求发送到该地址。
示例：*http://idp.example.com/idp/sso/saml*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 如果 `idp_type` 设置为“SAML 类型的用户目录”，则该属性 *必需*|
|slo_url|string|身份提供商的 SAML 单点注销服务 URL，Zabbix 会将 SAML 注销请求发送到该地址。
示例：*https://idp.example.com/idp/slo/saml*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”时，该属性 *受支持*|
|encrypt_nameid|integer|是否应加密 SAML name ID。
可能的值：
0 - *(默认)* 不加密 name ID；
1 - 加密 name ID。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”时，该属性 *受支持*|
|encrypt_assertions|integer|是否应加密 SAML 断言。
可能的值：
0 - *(默认)* 不加密断言；
1 - 加密断言。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”时，该属性 *受支持*|
|nameid_format|string|SAML 身份提供商服务提供者的 Name ID 格式。
示例：
*urn:oasis:names:tc:SAML:2.0:nameid-format:persistent*
*urn:oasis:names:tc:SAML:2.0:nameid-format:transient*
*urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos*
*urn:oasis:names:tc:SAML:2.0:nameid-format:entity*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”时，该属性 *受支持*|
|scim_status|integer|是否启用或禁用 SAML 的 SCIM 配置。
可能的值：
0 - *(默认)* SCIM 配置已禁用；
1 - 已启用 SCIM 配置。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”时，该属性 *受支持*|
|sign_assertions|integer|是否应使用 SAML 签名对 SAML 断言进行签名。
可能的值：
0 - *(默认)* 不对断言签名；
1 - 对断言签名。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”时，该属性 *受支持*|
|sign_authn_requests|integer|是否应使用 SAML 签名对 SAML AuthN 请求进行签名。
可能的值：
0 - *(默认)* 不对 AuthN 请求签名；
1 - 对 AuthN 请求签名。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”时，该属性 *受支持*|
|sign_messages|integer|是否应使用 SAML 签名对 SAML 消息进行签名。
可能的值：
0 - *(默认)* 不对消息签名；
1 - 对消息签名。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”时，该属性 *受支持*|
|sign_logout_requests|integer|是否应使用 SAML 签名对 SAML 注销请求进行签名。
可能的值：
0 - *(默认)* 不对注销请求签名；
1 - 对注销请求签名。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”时，该属性 *受支持*|
|sign_logout_responses|integer|是否应使用 SAML 签名对 SAML 注销响应进行签名。
可能的值：
0 - *(默认)* 不对注销响应签名；
1 - 对注销响应签名。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”时，该属性 *受支持*|
|idp_certificate|string|用于设置 SAML 单点登录（SSO）服务的服务提供者（SP）证书内容。
示例：
*-----BEGIN CERTIFICATE-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7...
...more encoded data...
-----END CERTIFICATE-----*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”且在 zabbix.conf.php 中将 `$SSO['CERT_STORAGE']` 设置为 `database` 时，该属性 *受支持*
- *只写*|
|sp_private_key|string|用于设置 SAML 单点登录（SSO）服务的服务提供者（SP）私钥内容。
用于与身份提供商（IdP）进行安全认证和数据交换。
示例：
*-----BEGIN CERTIFICATE-----
MIIEvQIBADANBgkqhkiG9w0BA...
...more encoded data...
-----END CERTIFICATE-----*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”且在 zabbix.conf.php 中将 `$SSO['CERT_STORAGE']` 设置为 `database` 时，该属性 *受支持*
- *只写*|
|sp_certificate|string|用于设置 SAML 单点登录（SSO）服务的服务提供者（SP）证书内容。
示例：
*-----BEGIN CERTIFICATE-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7...
...more encoded data...
-----END CERTIFICATE-----*
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”且在 zabbix.conf.php 中将 `$SSO['CERT_STORAGE']` 设置为 `database` 时，该属性 *受支持*
- *只写*|
|idp_certificate_hash|string|idp_certificate 值的 md5 哈希。对于空的 idp_certificate，将返回空字符串。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”且在 zabbix.conf.php 中将 `$SSO['CERT_STORAGE']` 设置为 `database` 时，该属性 *受支持*
- *只读*|
|sp_private_key_hash|string|sp_private_key 值的 md5 哈希。对于空的 sp_private_key，将返回空字符串。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”且在 zabbix.conf.php 中将 `$SSO['CERT_STORAGE']` 设置为 `database` 时，该属性 *受支持*
- *只读*|
|sp_certificate_hash|string|sp_certificate 值的 md5 哈希。对于空的 sp_certificate，将返回空字符串。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- 当 `idp_type` 设置为“SAML 类型的用户目录”且在 zabbix.conf.php 中将 `$SSO['CERT_STORAGE']` 设置为 `database` 时，该属性 *受支持*
- *只读*|
[comment]: # ({/726c81ec-ad144502})
[comment]: # ({07d3d820-c2b51996})
#### 媒介类型映射
媒介类型映射对象具有以下属性。
|属性|[类型](/manual/api/reference_commentary#data-types)|描述|
|--|--|----------------|
|userdirectory_mediaid|ID|媒介类型映射 ID。
[属性行为](/manual/api/reference_commentary#property-behavior):
- *只读*|
|name|string|在媒介类型映射列表中显示的名称。
[属性行为](/manual/api/reference_commentary#property-behavior):
- *必填*|
|mediatypeid|ID|要创建的媒介类型 ID；用作 [Media object](/manual/api/reference/user/object#media) 属性 `mediatypeid` 的值。
[属性行为](/manual/api/reference_commentary#property-behavior):
- *必填*|
|attribute|string|包含用户媒介的 LDAP/SAML 用户目录属性（如果 `scim_status` 设置为“已启用 SCIM 配置”，也可以是 SCIM 属性，例如 *user@example.com*），该值将用作 [Media object](/manual/api/reference/user/object#media) 属性 `sendto` 的值。
如果该属性存在于从 LDAP/SAML 身份提供方接收的数据中，且其值非空，则会为已配置的用户触发媒介创建。
[属性行为](/manual/api/reference_commentary#property-behavior):
- *必填*|
|active|integer|为已配置的用户创建媒介时，用户媒介 `active` 属性的值。
可能的值：
0 - *(默认)* 已启用；
1 - 已禁用。|
|severity|integer|为已配置的用户创建媒介时，用户媒介 `severity` 属性的值。
默认值：63。|
|period|string|为已配置的用户创建媒介时，用户媒介 `period` 属性的值。
默认值：1-7,00:00-24:00。|
[comment]: # ({/07d3d820-c2b51996})
[comment]: # ({fe544518-67bd0ce1})
#### Provisioning 组映射
Provisioning 组映射具有以下属性。
|属性|[类型](/manual/api/reference_commentary#data-types)|描述|
|--|--|----------------|
|name|string|LDAP/SAML 用户目录中的组全名（例如 *Zabbix administrators*）（如果 `scim_status` 设置为“已启用 SCIM provisioning”，也包括 SCIM）。
支持通配符字符“\*”。
在所有 provisioning 组映射中必须唯一。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- *必填*|
|roleid|ID|要分配给用户的用户角色 ID。
如果匹配到多个 provisioning 组映射，则将最高用户类型（*User*、*Admin* 或 *Super admin*）的角色分配给该用户。如果存在多个具有相同用户类型的角色，则将第一个角色（按字母顺序排序）分配给该用户。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- *必填*|
|user_groups|array|Zabbix 用户组 ID 对象数组。每个对象具有以下属性：
`usrgrpid` - `(ID)` 要分配给用户的 Zabbix 用户组 ID。
如果匹配到多个 provisioning 组映射，则会将所有匹配映射中的 Zabbix 用户组分配给该用户。
[属性行为](/manual/api/reference_commentary#property-behavior)：
- *必填*|
[comment]: # ({/fe544518-67bd0ce1})