Use the principal_to_dn command to search Active Directory for the specified user principal name (UPN) of a security principal (user, machine, or group). If a security principal is found for the specified UPN, the command returns the distinguished name (DN) of the principal.

Zone type

Not applicable


principal_to_dn principal_upn




This command takes no options.


This command takes the following argument:

Argument Type Description



Required. Specifies the user principal name (UPN) of a security principal.

Return value

This command returns a distinguished name. If the command doesn’t find the specified security principal in Active Directory, it presents a message that it didn’t find the principal.



This example returns the distinguished name for the specified UPN:

cn=brenda butler,cn=users,dc=acme,dc=com

Related commands

The following commands perform actions related to this command:

  • dn_from_domain converts a domain’s dotted name to a distinguished name.
  • get_parent_dn returns the parent of an LDAP path as a distinguished name.
  • get_rdn returns the relative distinguished name of an LDAP path.
  • dn_to_principal searches Active Directory for a distinguished name, and, if found, returns the corresponding user principal name (UPN).
  • principal_from_sid searches Active Directory for a security identifier and returns the security principal associated with the security identifier.