> User directory object

The following objects are directly related to the userdirectory API.

User directory

The user directory object has the following properties.

PropertyTypeDescription
userdirectoryidstringID of the user directory.

If a user directory is deleted, the value of the User object property userdirectoryid is set to “0” for all users that are linked to the deleted user directory.

Property behavior:
- read-only
- required for update operations
idp_typeintegerType of the authentication protocol used by the identity provider for the user directory.
Note that only one user directory of type SAML can exist.

Possible values:
1 - User directory of type LDAP;
2 - User directory of type SAML.

Property behavior:
- required for create operations
group_namestringLDAP/SAML user directory attribute that contains the group name used to map groups between the LDAP/SAML user directory and Zabbix.

Example: cn

Property behavior:
- required if provision_status is set to “Enabled” and saml_jit_status of Authentication object is set to “Enabled for configured SAML IdPs”
user_usernamestringLDAP/SAML user directory attribute (also SCIM attribute if scim_status is set to “SCIM provisioning is enabled”) that contains the user’s name which is used as the value for the User object property name when the user is provisioned.

Examples: cn, commonName, displayName, name
user_lastnamestringLDAP/SAML user directory attribute (also SCIM attribute if scim_status is set to “SCIM provisioning is enabled”) that contains the user’s last name which is used as the value for the User object property surname when the user is provisioned.

Examples: sn, surname, lastName
provision_statusintegerProvisioning status of the user directory.

Possible values:
0 - (default) Disabled (provisioning of users created by this user directory is disabled);
1 - Enabled (provisioning of users created by this user directory is enabled; additionally, the status of LDAP or SAML provisioning (ldap_jit_status or saml_jit_status of Authentication object) must be enabled).
provision_groupsarrayArray of provisioning groups mappings objects for mapping LDAP/SAML user group pattern to Zabbix user group and user role.

Property behavior:
- required if provision_status is set to “Enabled”
provision_mediaarrayArray of media type mappings objects for mapping user’s LDAP/SAML media attributes (e.g., email) to Zabbix user media for sending notifications.
LDAP-specific properties:
namestringUnique name of the user directory.

Property behavior:
- required if idp_type is set to “User directory of type LDAP”
hoststringHost name, IP or URI of the LDAP server.
URI must contain schema (ldap:// or ldaps://), host, and port (optional).

Examples:
host.example.com
127.0.0.1
ldap://ldap.example.com:389

Property behavior:
- required if idp_type is set to “User directory of type LDAP”
portintegerPort of the LDAP server.

Property behavior:
- required if idp_type is set to “User directory of type LDAP”
base_dnstringLDAP user directory base path to user accounts.

Examples:
ou=Users,dc=example,dc=org
ou=Users,ou=system (for OpenLDAP)
DC=company,DC=com (for Microsoft Active Directory)
uid=%{user},dc=example,dc=com (for direct user binding; placeholder “%{user}“ is mandatory)

Property behavior:
- required if idp_type is set to “User directory of type LDAP”
search_attributestringLDAP user directory attribute by which to identify the user account from the information provided in the login request.

Examples:
uid (for OpenLDAP)
sAMAccountName (for Microsoft Active Directory)

Property behavior:
- required if idp_type is set to “User directory of type LDAP”
bind_dnstringLDAP server account for binding and searching over the LDAP server.

For direct user binding and anonymous binding, bind_dn must be empty.

Examples:
uid=ldap_search,ou=system (for OpenLDAP)
CN=ldap_search,OU=user_group,DC=company,DC=com (for Microsoft Active Directory)
CN=Admin,OU=Users,OU=Zabbix,DC=zbx,DC=local

Property behavior:
- supported if idp_type is set to “User directory of type LDAP”
bind_passwordstringLDAP password of the account for binding and searching over the LDAP server.

For direct user binding and anonymous binding, bind_password must be empty.

Property behavior:
- supported if idp_type is set to “User directory of type LDAP”
descriptionstringDescription of the user directory.

Property behavior:
- supported if idp_type is set to “User directory of type LDAP”
group_basednstringLDAP user directory base path to groups; used to configure a user membership check in the LDAP user directory.

Ignored when provisioning a user if group_membership is set.

Example: ou=Groups,dc=example,dc=com

Property behavior:
- supported if idp_type is set to “User directory of type LDAP”
group_filterstringFilter string for retrieving LDAP user directory groups that the user is a member of; used to configure a user membership check in the LDAP user directory.

Ignored when provisioning a user if group_membership is set.

Supported group_filter placeholders:
%{attr} - search attribute (replaced by the search_attribute property value);
%{groupattr} - group attribute (replaced by the group_member property value);
%{host} - host name, IP or URI of the LDAP server (replaced by the host property value);
%{user} - Zabbix user username.

Default: (%{groupattr}=%{user})

Examples:
- (member=uid=%{ref},ou=Users,dc=example,dc=com) will match “User1” if an LDAP group object contains the “member“ attribute with the value “uid=User1,ou=Users,dc=example,dc=com“, and will return the group that “User1” is a member of;
- (%{groupattr}=cn=%{ref},ou=Users,ou=Zabbix,DC=example,DC=com) will match “User1” if an LDAP group object contains the attribute specified in the group_member property with the value “cn=User1,ou=Users,ou=Zabbix,DC=example,DC=com“, and will return the group that “User1” is a member of.

Property behavior:
- supported if idp_type is set to “User directory of type LDAP”
group_memberstringLDAP user directory attribute that contains information about the group members; used to configure a user membership check in the LDAP user directory.

Ignored when provisioning a user if group_membership is set.

Property behavior:
- supported if idp_type is set to “User directory of type LDAP”
group_membershipstringLDAP user directory attribute that contains information about the groups that a user belongs to.

Example: memberOf

Property behavior:
- supported if idp_type is set to “User directory of type LDAP”
search_filterstringCustom filter string used to locate and authenticate a user in an LDAP user directory based on the information provided in the login request.

Supported search_filter placeholders:
%{attr} - search attribute name (e.g., uid, sAMAccountName);
%{user} - Zabbix user username.

Default: (%{attr}=%{user})

Property behavior:
- supported if idp_type is set to “User directory of type LDAP”
start_tlsintegerLDAP server configuration option that allows the communication with the LDAP server to be secured using Transport Layer Security (TLS).

Note that start_tls must be set to “Disabled” for hosts using the ldaps:// protocol.

Possible values:
0 - (default) Disabled;
1 - Enabled.

Property behavior:
- supported if idp_type is set to “User directory of type LDAP”
user_ref_attrstringLDAP user directory attribute used to reference a user object. The value of user_ref_attr is used to get values from the specified attribute in the user directory and place them instead of the %{ref} placeholder in the group_filter string.

Examples: cn, uid, member, uniqueMember

Property behavior:
- supported if idp_type is set to “User directory of type LDAP”
SAML-specific properties:
idp_entityidstringURI that identifies the identity provider and is used to communicate with the identity provider in SAML messages.

Example: https://idp.example.com/idp

Property behavior:
- required if idp_type is set to “User directory of type SAML”
sp_entityidstringURL or any string that identifies the identity provider’s service provider.

Examples:
https://idp.example.com/sp
zabbix

Property behavior:
- required if idp_type is set to “User directory of type SAML”
username_attributestringSAML user directory attribute (also SCIM attribute if scim_status is set to “SCIM provisioning is enabled”) that contains the user’s username which is compared with the value of the User object property username when authenticating.

Examples: 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

Property behavior:
- required if idp_type is set to “User directory of type SAML”
sso_urlstringURL of the identity provider’s SAML single sign-on service, to which Zabbix will send the SAML authentication requests.

Example: http://idp.example.com/idp/sso/saml

Property behavior:
- required if idp_type is set to “User directory of type SAML”
slo_urlstringURL of the identity provider’s SAML single log-out service, to which Zabbix will send the SAML logout requests.

Example: https://idp.example.com/idp/slo/saml

Property behavior:
- supported if idp_type is set to “User directory of type SAML”
encrypt_nameidintegerWhether the SAML name ID should be encrypted.

Possible values:
0 - (default) Do not encrypt name ID;
1 - Encrypt name ID.

Property behavior:
- supported if idp_type is set to “User directory of type SAML”
encrypt_assertionsintegerWhether the SAML assertions should be encrypted.

Possible values:
0 - (default) Do not encrypt assertions;
1 - Encrypt assertions.

Property behavior:
- supported if idp_type is set to “User directory of type SAML”
nameid_formatstringName ID format of the SAML identity provider’s service provider.

Examples:
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

Property behavior:
- supported if idp_type is set to “User directory of type SAML”
scim_statusintegerWhether SCIM provisioning for SAML is enabled or disabled.

Possible values:
0 - (default) SCIM provisioning is disabled;
1 - SCIM provisioning is enabled.

Property behavior:
- supported if idp_type is set to “User directory of type SAML”
sign_assertionsintegerWhether the SAML assertions should be signed with a SAML signature.

Possible values:
0 - (default) Do not sign assertions;
1 - Sign assertions.

Property behavior:
- supported if idp_type is set to “User directory of type SAML”
sign_authn_requestsintegerWhether the SAML AuthN requests should be signed with a SAML signature.

Possible values:
0 - (default) Do not sign AuthN requests;
1 - Sign AuthN requests.

Property behavior:
- supported if idp_type is set to “User directory of type SAML”
sign_messagesintegerWhether the SAML messages should be signed with a SAML signature.

Possible values:
0 - (default) Do not sign messages;
1 - Sign messages.

Property behavior:
- supported if idp_type is set to “User directory of type SAML”
sign_logout_requestsintegerWhether the SAML logout requests should be signed with a SAML signature.

Possible values:
0 - (default) Do not sign logout requests;
1 - Sign logout requests.

Property behavior:
- supported if idp_type is set to “User directory of type SAML”
sign_logout_responsesintegerWhether the SAML logout responses should be signed with a SAML signature.

Possible values:
0 - (default) Do not sign logout responses;
1 - Sign logout responses.

Property behavior:
- supported if idp_type is set to “User directory of type SAML”

Media type mappings

The media type mappings object has the following properties.

PropertyTypeDescription
namestringVisible name in the list of media type mappings.

Property behavior:
- required
mediatypeidstringID of the media type to be created; used as the value for the Media object property mediatypeid.

Property behavior:
- required
attributestringLDAP/SAML user directory attribute (also SCIM attribute if scimstatus is set to “SCIM provisioning is enabled”) that contains the user’s media (e.g., <a href=”https://www.zabbix.com/cdn-cgi/l/email-protection“ class=”_cf_email“ data-cfemail=”b0c5c3d5c2f0d5c8d1ddc0dcd59ed3dfdd”>[email protected]) which is used as the value for the Media object property sendto.

If present in data received from the LDAP/SAML identity provider, and the value is not empty, this will trigger media creation for the provisioned user.

Property behavior:
- required

Provisioning groups mappings

The provisioning groups mappings has the following properties.

PropertyTypeDescription
namestringFull name of a group (e.g., Zabbix administrators) in LDAP/SAML user directory (also SCIM if scim_status is set to “SCIM provisioning is enabled”).
Supports the wildcard character “*”.
Unique across all provisioning groups mappings.

Property behavior:
- required
roleidstringID of the user role to assign to the user.

If multiple provisioning groups mappings are matched, the role of the highest user type (User, Admin, or Super admin) is assigned to the user. If there are multiple roles with the same user type, the first role (sorted in alphabetical order) is assigned to the user.

Property behavior:
- required
user_groupsarrayArray of Zabbix user group ID objects. Each object has the following properties:
usrgrpid - (integer) ID of Zabbix user group to assign to the user.

If multiple provisioning groups mappings are matched, Zabbix user groups of all matched mappings is assigned to the user.

Property behavior:
- required