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

  • Published on Jul 22, 2025
  • 2 minute(s) read
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
Body parameters
object
ldap
object Required
name
string Required
icon_url
string Required
ldap_url
string Required
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
object
object
method
string Required
Valid values[ "construct" ]
domain_format
object Required

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

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

TLS client settings.

OneOf
object
object
mode
string Required
Valid values[ "disabled" ]
object
object
mode
string Required
Valid values[ "opportunistic" ]
object
object
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
user_object_class
string | null
service_account
object
dn
string Required
password
string Required
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
object
object
$type
string Required
Valid values[ "Fixed" ]
role
Array Required

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

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

OneOf
string
string
Valid values[ "STATEENABLED", "PENDINGINVITE" ]
string
string
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
string
string
Valid values[ "ADMIN_USER", "MEMBER_USER", "AUDITOR_USER", "ADMIN_APP", "CRYPTO_APP" ]
string (uuid)
string
OneOf
object
object
email
string (email) Required
object
object
dn
string Required
Responses
204

Nothing is returned on success