You are viewing documentation for the development version, it may be incomplete.
Join our translation project and help translate Zabbix documentation into your native language.

User directory object

The following objects are directly related to the userdirectory API.

User directory

The user directory object has the following properties.

Property Type Description
userdirectoryid ID ID 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_type integer Type 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_name string LDAP/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_username string LDAP/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_lastname string LDAP/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_status integer Provisioning 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_groups array Array 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_media array Array 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:
name string Unique name of the user directory.

Property behavior:
- required if idp_type is set to "User directory of type LDAP"
host string Host 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"
port integer Port of the LDAP server.

Property behavior:
- required if idp_type is set to "User directory of type LDAP"
base_dn string LDAP 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_attribute string LDAP 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_dn string LDAP 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_password string LDAP 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"
description string Description of the user directory.

Property behavior:
- supported if idp_type is set to "User directory of type LDAP"
group_basedn string LDAP 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_filter string Filter 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_member string LDAP 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_membership string LDAP 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_filter string Custom 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_tls integer LDAP 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_attr string LDAP 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_entityid string URI 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_entityid string URL 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_attribute string SAML 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_url string URL 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_url string URL 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_nameid integer Whether 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_assertions integer Whether 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_format string Name 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_status integer Whether 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_assertions integer Whether 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_requests integer Whether 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_messages integer Whether 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_requests integer Whether 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_responses integer Whether 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.

Property Type Description
userdirectory_mediaid ID Media type mapping ID.

Property behavior:
- read-only
name string Visible name in the list of media type mappings.

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

Property behavior:
- required
attribute string LDAP/SAML user directory attribute (also SCIM attribute if scim_status is set to "SCIM provisioning is enabled") that contains the user's media (e.g., [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
active integer User media active property value when media is created for the provisioned user.

Possible values:
0 - (default) enabled;
1 - disabled.
severity integer User media severity property value when media is created for the provisioned user.

Default: 63.
period string User media period property value when media is created for the provisioned user.

Default: 1-7,00:00-24:00.

Provisioning groups mappings

The provisioning groups mappings has the following properties.

Property Type Description
name string Full 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
roleid ID ID 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_groups array Array of Zabbix user group ID objects. Each object has the following properties:
usrgrpid - (ID) 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