[comment]: # aside:1

[comment]: # ({c9088bab-f9e8f670})
# User directory object

The following objects are directly related to the `userdirectory` API.

[comment]: # ({/c9088bab-f9e8f670})

[comment]: # ({57811c28-ad144502})
### User directory

The user directory object has the following properties.

|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|userdirectoryid|ID|ID of the user directory.<br><br>If a user directory is deleted, the value of the [User object](/manual/api/reference/user/object#user) property `userdirectoryid` is set to "0" for all users that are linked to the deleted user directory.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *read-only*<br>- *required* for update operations|
|idp_type|integer|Type of the authentication protocol used by the identity provider for the user directory.<br>Note that only one user directory of type SAML can exist.<br><br>Possible values:<br>1 - User directory of type LDAP;<br>2 - User directory of type SAML.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Example: *cn*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *required* if `provision_status` is set to "Enabled" and `saml_jit_status` of [Authentication object](/manual/api/reference/authentication/object#authentication) 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](/manual/api/reference/user/object#user) property `name` when the user is provisioned.<br><br>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](/manual/api/reference/user/object#user) property `surname` when the user is provisioned.<br><br>Examples: *sn*, *surname*, *lastName*|
|provision_status|integer|Provisioning status of the user directory.<br><br>Possible values:<br>0 - *(default)* Disabled (provisioning of users created by this user directory is disabled);<br>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](/manual/api/reference/authentication/object#authentication)) must be enabled).|
|provision_groups|array|Array of [provisioning groups mappings](object#provisioning-groups-mappings) objects for mapping LDAP/SAML user group pattern to Zabbix user group and user role.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *required* if `provision_status` is set to "Enabled"|
|provision_media|array|Array of [media type mappings](object#media-type-mappings) objects for mapping user's LDAP/SAML media attributes (e.g., email) to Zabbix user media for sending notifications.|
|**[LDAP](/manual/web_interface/frontend_sections/users/authentication/ldap)-specific properties:**|<|<|
|name|string|Unique name of the user directory.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *required* if `idp_type` is set to "User directory of type LDAP"|
|host|string|Host name, IP or URI of the LDAP server.<br>URI must contain schema (`ldap://` or `ldaps://`), host, and port (optional).<br><br>Examples:<br>*host.example.com*<br>*127.0.0.1*<br>*ldap://ldap.example.com:389*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *required* if `idp_type` is set to "User directory of type LDAP"|
|port|integer|Port of the LDAP server.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *required* if `idp_type` is set to "User directory of type LDAP"|
|base_dn|string|LDAP user directory base path to user accounts.<br><br>Examples:<br>*ou=Users,dc=example,dc=org*<br>*ou=Users,ou=system* (for OpenLDAP)<br>*DC=company,DC=com* (for Microsoft Active Directory)<br>*uid=%{user},dc=example,dc=com* (for direct user binding; placeholder "*%{user}*" is mandatory)<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Examples:<br>*uid* (for OpenLDAP)<br>*sAMAccountName* (for Microsoft Active Directory)<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>For direct user binding and anonymous binding, `bind_dn` must be empty.<br><br>Examples:<br>*uid=ldap_search,ou=system* (for OpenLDAP)<br>*CN=ldap_search,OU=user_group,DC=company,DC=com* (for Microsoft Active Directory)<br>*CN=Admin,OU=Users,OU=Zabbix,DC=zbx,DC=local*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>For direct user binding and anonymous binding, `bind_password` must be empty.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *supported* if `idp_type` is set to "User directory of type LDAP"|
|description|string|Description of the user directory.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Ignored when provisioning a user if `group_membership` is set.<br><br>Example: *ou=Groups,dc=example,dc=com*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Ignored when provisioning a user if `group_membership` is set.<br><br>Supported `group_filter` placeholders:<br>*%{attr}* - search attribute (replaced by the `search_attribute` property value);<br>*%{groupattr}* - group attribute (replaced by the `group_member` property value);<br>*%{host}* - host name, IP or URI of the LDAP server (replaced by the `host` property value);<br>*%{user}* - Zabbix user username.<br><br>Default: *(%{groupattr}=%{user})*<br><br>Examples:<br>- *(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;<br>- *(%{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.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Ignored when provisioning a user if `group_membership` is set.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Example: *memberOf*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Supported `search_filter` placeholders:<br>*%{attr}* - search attribute name (e.g., *uid*, *sAMAccountName*);<br>*%{user}* - Zabbix user username.<br><br>Default: *(%{attr}=%{user})*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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).<br><br>Note that `start_tls` must be set to "Disabled" for hosts using the `ldaps://` protocol.<br><br>Possible values:<br>0 - *(default)* Disabled;<br>1 - Enabled.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Examples: *cn*, *uid*, *member*, *uniqueMember*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *supported* if `idp_type` is set to "User directory of type LDAP"|
|**[SAML](/manual/web_interface/frontend_sections/users/authentication/saml)-specific properties:**|<|<|
|idp_entityid|string|URI that identifies the identity provider and is used to communicate with the identity provider in SAML messages.<br><br>Example: *https://idp.example.com/idp*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Examples:<br>*https://idp.example.com/sp*<br>*zabbix*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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](/manual/api/reference/user/object#user) property `username` when authenticating.<br><br>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*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Example: *http://idp.example.com/idp/sso/saml*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Example: *https://idp.example.com/idp/slo/saml*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *supported* if `idp_type` is set to "User directory of type SAML"|
|encrypt_nameid|integer|Whether the SAML name ID should be encrypted.<br><br>Possible values:<br>0 - *(default)* Do not encrypt name ID;<br>1 - Encrypt name ID.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *supported* if `idp_type` is set to "User directory of type SAML"|
|encrypt_assertions|integer|Whether the SAML assertions should be encrypted.<br><br>Possible values:<br>0 - *(default)* Do not encrypt assertions;<br>1 - Encrypt assertions.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Examples:<br>*urn:oasis:names:tc:SAML:2.0:nameid-format:persistent*<br>*urn:oasis:names:tc:SAML:2.0:nameid-format:transient*<br>*urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos*<br>*urn:oasis:names:tc:SAML:2.0:nameid-format:entity*<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *supported* if `idp_type` is set to "User directory of type SAML"|
|scim_status|integer|Whether SCIM provisioning for SAML is enabled or disabled.<br><br>Possible values:<br>0 - *(default)* SCIM provisioning is disabled;<br>1 - SCIM provisioning is enabled.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Possible values:<br>0 - *(default)* Do not sign assertions;<br>1 - Sign assertions.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Possible values:<br>0 - *(default)* Do not sign AuthN requests;<br>1 - Sign AuthN requests.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Possible values:<br>0 - *(default)* Do not sign messages;<br>1 - Sign messages.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Possible values:<br>0 - *(default)* Do not sign logout requests;<br>1 - Sign logout requests.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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.<br><br>Possible values:<br>0 - *(default)* Do not sign logout responses;<br>1 - Sign logout responses.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *supported* if `idp_type` is set to "User directory of type SAML"|

[comment]: # ({/57811c28-ad144502})

[comment]: # ({07d3d820-c2b51996})
#### Media type mappings

The media type mappings object has the following properties.

|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|----------------|
|userdirectory_mediaid|ID|Media type mapping ID.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *read-only*|
|name|string|Visible name in the list of media type mappings.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *required*|
|mediatypeid|ID|ID of the media type to be created; used as the value for the [Media object](/manual/api/reference/user/object#media) property `mediatypeid`.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *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., *user@example.com*) which is used as the value for the [Media object](/manual/api/reference/user/object#media) property `sendto`.<br><br>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.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *required*|
|active|integer|User media `active` property value when media is created for the provisioned user.<br><br>Possible values:<br>0 - *(default)* enabled;<br>1 - disabled.|
|severity|integer|User media `severity` property value when media is created for the provisioned user.<br><br>Default: 63.|
|period|string|User media `period` property value when media is created for the provisioned user.<br><br>Default: 1-7,00:00-24:00.|

[comment]: # ({/07d3d820-c2b51996})

[comment]: # ({fe544518-67bd0ce1})
#### Provisioning groups mappings

The provisioning groups mappings has the following properties.

|Property|[Type](/manual/api/reference_commentary#data-types)|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").<br>Supports the wildcard character "\*".<br>Unique across all provisioning groups mappings.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *required*|
|roleid|ID|ID of the user role to assign to the user.<br><br>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.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *required*|
|user_groups|array|Array of Zabbix user group ID objects. Each object has the following properties:<br>`usrgrpid` - `(ID)` ID of Zabbix user group to assign to the user.<br><br>If multiple provisioning groups mappings are matched, Zabbix user groups of all matched mappings is assigned to the user.<br><br>[Property behavior](/manual/api/reference_commentary#property-behavior):<br>- *required*|

[comment]: # ({/fe544518-67bd0ce1})