Test connection using the ldap SSO configuration saved in the account

  • Published on Oct 7, 2026
Prev Next
Post
/sys/v1/ldap/test

Test connection using the ldap SSO configuration saved in the account.

Security
HTTP
Type bearer
API Key: apiKeyAuth
Header parameter nameAuthorization

Please enter your token prefixed with 'Basic ' (e.g., 'Basic your_token_here')

Body parameters
object
ldap
object Required
name
string Required

A user-visible name to give this LDAP integration.

icon_url
string Required

The URL hosting an image to display for this LDAP integration. An empty string can also be specified (to indicate that no icon needs to be displayed).

ldap_url
string Required

The URL of the LDAP server, e.g., "ldap://example.org".

dn_resolution

Distinguished Name (DN) resolution method. Given a user's email address, a DN resolution method is used to find the user's DN in an LDAP directory.

OneOf
LdapDnResolutionVariantConstruct
object (LdapDnResolutionVariantConstruct)
method
string Required
Valid values[ "construct" ]
domain_format
object Required

For example: "example.com" => "uid=,ou=users,dc=example,dc=com".

property*
string additionalProperties
LdapDnResolutionVariantSearchByMail
object (LdapDnResolutionVariantSearchByMail)
method
string Required
Valid values[ "search-by-mail" ]
LdapDnResolutionVariantUserPrincipalName
object (LdapDnResolutionVariantUserPrincipalName)
method
string Required
Valid values[ "upn" ]
tls

TLS client settings.

OneOf
TlsConfigVariantDisabled
object (TlsConfigVariantDisabled)
mode
string Required
Valid values[ "disabled" ]
TlsConfigVariantOpportunistic
object (TlsConfigVariantOpportunistic)
mode
string Required
Valid values[ "opportunistic" ]
TlsConfigVariantRequired
object (TlsConfigVariantRequired)
mode
string Required
Valid values[ "required" ]
validate_hostname
boolean Required
ca

CA settings.

OneOf
CaConfigVariantCaSet
object (CaConfigVariantCaSet)
ca_set
string Required

Predefined CA sets.

Valid values[ "global_roots" ]
CaConfigVariantPinned
object (CaConfigVariantPinned)
pinned
Array of string Required
string (byte)
client_key
string (byte)
client_cert
string (byte)
base_dn
string | null

The subtree from which to perform LDAP searches; for example, "OU=users,DC=example,DC=org". This field is required if the DN resolution method is search-by-mail or if authorization settings are enabled for this LDAP integraton.

user_object_class
string | null

The LDAP object class (e.g., "User") to use when looking up DSM users trying to authenticate. This field is required if the DN resolution method is search-by-mail or if authorization settings are enabled for this LDAP integraton.

service_account

Details for an LDAP service account.

Note: for backward compatibility, if the JSON request contains string fields dn and password, DSM will interpret the value as an Inline LdapServiceAccount object (even if the $type field is missing or set to a string other than "inline"). This means that requests like

{
"dn": "...",
"password": "...",
"$type": "credential_ref",
"credential_id": "..."
}

would be interpreted as if the request were instead

{
"dn": "...",
"password": "...",
"$type": "inline"
}

It is RECOMMENDED to always specify the $type field, and to avoid mixing up fields between variants.

OneOf
LdapServiceAccountVariantInline
object (LdapServiceAccountVariantInline)
$type
string Required
Valid values[ "inline" ]
dn
string Required

Distinguished name of the service account.

password
string Required

The password for the service account.

LdapServiceAccountVariantCredentialRef
object (LdapServiceAccountVariantCredentialRef)
$type
string Required
Valid values[ "credential_ref" ]
credential_id
string (uuid) Required

A wrapper type to provide better clarity that the id referenced is an integration credential object.

authorization
object
valid_for
integer Required

Number of seconds after which the authorization should be checked again.

require_role
object | null

A map from account roles to distinguished names of LDAP groups. If a DN is specified for an account role, entities with that role must be a member of the specified LDAP group.

property*
string additionalProperties
user_self_provisioning
object
role_assignment

A structure indicating how self-provisioned LDAP users will be assigned account roles.

OneOf
LdapUserSelfProvisioningRoleVariantFixed
object (LdapUserSelfProvisioningRoleVariantFixed)
$type
string Required
Valid values[ "Fixed" ]
role
Array Required

User's role(s) and state in an account.

Unique itemstrue

User account flag or legacy user account role name or custom role id

OneOf
UserAccountFlag
UserAccountFlag
Valid values[ "STATEENABLED", "PENDINGINVITE" ]
LegacyUserAccountRole
LegacyUserAccountRole
Valid values[ "ACCOUNTADMINISTRATOR", "ACCOUNTMEMBER", "ACCOUNTAUDITOR" ]
string (uuid)
string
role_conflict_resolution
string

Controls how we resolve conflicting role assignments with LDAP authorization.

When users are authorized through LDAP, their DSM group memberships are determined by their LDAP groups and the external role mappings created in DSM. For example, if the user belongs to 3 LDAP groups A, B and C, and these LDAP groups are mapped to DSM groups G1 and G2 in the following way:

  • A -> G1 as "group auditor"
  • B -> G1 as "group administrator"
  • C -> G2 as "group administrator" Then which role should be assigned to this user in G1?

The answer to this question used to be simple before the introduction of custom user roles in DSM: we took the maximum of the roles. Note that the legacy roles (group admin/auditor) formed a strict "more powerful than" relation, i.e. group administrator is strictly more powerful than group auditor (and same is true for legacy account roles). However, custom user roles do not have that relationship anymore. Moreover, the legacy behavior is not quite square with the role exclusivity rules either since the legacy behavior can also be regarded as assigning multiple exclusive roles in the same group.

After the introduction of custom user roles, we allow a user to have multiple roles in one group as long as none of the roles are marked as exclusive. That rule is easily enforceable in the user Invite API. With LDAP authorization, the group memberships are computed dynamically when the Select Account API is called and it is possible that we run into conflicting role assignments due to user's LDAP group membership and current mappings between external roles (i.e. LDAP groups) and DSM groups.

Valid values[ "backcompat_legacy_roles_only", "disregard_exclusive_roles" ]
test_credentials
password
string Required
account_role

Role of a user or app in an account for the purpose of LDAP configurations.

OneOf
LegacyLdapAccountRole
LegacyLdapAccountRole
Valid values[ "ADMIN_USER", "MEMBER_USER", "AUDITOR_USER", "ADMIN_APP", "CRYPTO_APP" ]
string (uuid)
string
OneOf
LdapPrincipalUnresolved
object (LdapPrincipalUnresolved)
email
string (email) Required
LdapPrincipalResolved
object (LdapPrincipalResolved)
dn
string Required
Responses
204

Nothing is returned on success