http://www.rlmueller.net/NameTranslateFAQ.htmFrequently Asked Questions about NameTranslate
What is NameTranslate?On What clients is NameTranslate available?What can NameTranslate do for me?Why do I need to use NameTranslate?How do I use NameTranslate?How about a quick example of the use of NameTranslate?What are the options when I initialize NameTranslate?What formats are accepted by the Set and Get methods of NameTranslate?How do I convert an NT name to a Distinguished Name?How do I convert the NetBIOS name of a computer to it's Distinguished Name?How do I convert a Distinguished Name to an NT name?How do I convert an NT Name to a Display Name?How do I convert an NT Name to a User Principal Name?How do I convert an NT Name to a GUID?Can I convert the Display Name of a user to the Distinguished Name?How do I find the NetBIOS name of the domain?How do I specify credentials with NameTranslate?Can I convert the names of more than one object at a time?What errors can occur?Where can I get more information?1.
What is NameTranslate?NameTranslate refers to the IADsNameTranslate interface, which can be used to convert the names of Active Directory objects from one format to another.
2.
On what clients is NameTranslate available?The IADsNameTranslate interface is available on any client with Windows 2000 or above, or any other 32-bit client with DSClient installed. On Windows 95, Windows 98, Windows ME, or Windows NT clients, if DSClient is not installed, the IADsNameTranslate interface is only available if ADS is installed. The object is provided by ADSI on the client, but it must connect to Active Directory. The user must either be authenticated to the domain, or must provide credentials.
3.
What can NameTranslate do for me?The IADsNameTranslate interface can translate Active Directory object names between several formats. NameTranslate can be used to convert the name of any Active Directory object from one format to another. Among the formats supported by NameTranslate are:
Distinguished Names - format as specified in RFC 1779. For example cn=TestUser,ou=Sales,dc=MyDomain,dc=com.
NT format - the name format used in Windows NT 4.0. For example MyDomain\TestUser, where MyDomain is the NetBIOS name of the domain and TestUser is the NT name of the object. The sAMAccountName attribute is the NT name (or NetBIOS Name) of the object.
Canonical Name - For example MyDomain.com/Jim Anderson, where MyDomain.com is the DNS name of the domain and "Jim Anderson" is the Relative Distinguished Name (RDN, or the "cn" attribute, or common name, for most classes of objects) of the object.
Display Name - The displayName attribute of the object, for example "Jim L. Anderson".
User Principal Name (UPN) of the object. For example
JimAnderson@MyDomain.com.
GUID - The Global Unique Identifier. For example {95ee9fff-3436-11d1-b2b0-d15ae3ac8436}.
4.
Why do I need to use NameTranslate?If you use the LDAP provider, which is more powerful and exposes more attributes than the WinNT provider, you must bind to Active Directory objects with the Distinguished Name of the object. However, most people refer to objects by their NT names. Users call this their UserName, or User ID. This single string value uniquely identifies the account in Active Directory. It is easier to remember and deal with than the lengthy Distinguished Name with its many components. In addition, the WshNetwork object can determine the NT name of the current user and the computer, but not the Distinguished Name.
5.
How do I use NameTranslate?The steps required to convert names with the IADsNameTranslate interface are:
Bind to the NameTranslate object.
Initialize the NameTranslate object by calling the Init method and specifying the type of translation.
Use the Set method of the NameTranslate object to specify the Active Directory object whose name will be converted.
Use the Get method of the NameTranslate object to retrieve the name of the Active Directory object in the desired format.
6.
How about a quick example of the use of NameTranslate?The VBScript code below converts the NT name of a user to the Distinguished Name:
' Constants for the NameTranslate object.
Const ADS_NAME_INITTYPE_GC = 3Const ADS_NAME_TYPE_NT4 = 3Const ADS_NAME_TYPE_1779 = 1' Specify the NetBIOS name of the domain and the NT name of the user.strNTName = "MyDomain\TestUser"' Use the NameTranslate object to convert the NT user name to the' Distinguished Name required for the LDAP provider.Set objTrans = CreateObject("NameTranslate")
' Initialize NameTranslate by locating the Global Catalog.objTrans.Init ADS_NAME_INITTYPE_GC, ""' Use the Set method to specify the NT format of the object name.objTrans.Set ADS_NAME_TYPE_NT4, strNTName
' Use the Get method to retrieve the RPC 1779 Distinguished Name.strUserDN = objTrans.Get(ADS_NAME_TYPE_1779)
' Escape any "/" characters with backslash escape character.
' All other characters that need to be escaped will be escaped.
strUserDN = Replace(strUserDN, "/", "\/")' Bind to the user object in Active Directory with the LDAP provider.Set objUser = GetObject("LDAP://" & strUserDN)
The following characters can appear in Distinguished Names, but must be escaped with the backslash "\" escape character:
,\/#+<>;"=
The Get method of the NameTranslate object will return the Distinguished Name with these characters properly escaped, with the exception of the forward slash character "/". If this character is found in the Distinguished Name, it should be replaced by "\/" before using the Distinguished Name in a binding string. Otherwise, an error will be raised.
7.
What are the options when I initialize NameTranslate?The Init method of the NameTranslate object accepts any of the following values:
Const ADS_NAME_INITTYPE_DOMAIN = 1
Const ADS_NAME_INITTYPE_SERVER = 2
Const ADS_NAME_INITTYPE_GC = 3
With ADS_NAME_INITTYPE_DOMAIN you specify the domain that the NameTranslate object will connect to. With ADS_NAME_INITTYPE_SERVER you specify the server (domain controller) that the NameTranslate object will connect to. With ADS_NAME_INITTYPE_GC the NameTranslate object locates a Global Catalog. Unless you are converting the name of an object in another domain, there is no need to use anything other than ADS_NAME_INITTYPE_GC. Code examples using each follow:
Const ADS_NAME_INITTYPE_DOMAIN = 1
Set objTrans = CreateObject("NameTranslate")
objTrans.Init ADS_NAME_INITTYPE_DOMAIN, "MyDomain.com"
Const ADS_NAME_INITTYPE_SERVER = 2
Set objTrans = CreateObject("NameTranslate")
objTrans.Init ADS_NAME_INITTYPE_SERVER, "MyServer"
The server name can be in the form "MyServer" or "MyServer.MyDomain.com"
Const ADS_NAME_INITTYPE_GC = 3
Set objTrans = CreateObject("NameTranslate")
objTrans.Init ADS_NAME_INIITTYPE_GC, ""
8.
What formats are accepted by the Set and Get methods of NameTranslate?The following constants define the formats used with the Set and Get methods to convert names:
Const ADS_NAME_TYPE_1779 = 1
Const ADS_NAME_TYPE_CANONICAL = 2
Const ADS_NAME_TYPE_NT4 = 3
Const ADS_NAME_TYPE_DISPLAY = 4
Const ADS_NAME_TYPE_DOMAIN_SIMPLE = 5
Const ADS_NAME_TYPE_ENTERPRISE_SIMPLE = 6
Const ADS_NAME_TYPE_GUID = 7
Const ADS_NAME_TYPE_UNKNOWN = 8
Const ADS_NAME_TYPE_USER_PRINCIPAL_NAME = 9
Const ADS_NAME_TYPE_CANONICAL_EX = 10
Const ADS_NAME_TYPE_SERVICE_PRINCIPAL_NAME = 11
Const ADS_NAME_TYPE_SID_OR_SID_HISTORY_NAME = 12
9.
How do I convert an NT name to a Distinguished Name?The VBScript example below converts the NT name of any user, in conjunction with the NetBIOS name of the domain, to the Distinguished Name of the user object:
' Constants for the NameTranslate object.
Const ADS_NAME_INITTYPE_GC = 3Const ADS_NAME_TYPE_NT4 = 3Const ADS_NAME_TYPE_1779 = 1' Specify the NetBIOS name of the domain.
strNetBIOSDomain = "MyDomain"
' Specify the NT name of the user.strNTName = "TestUser"' Use the NameTranslate object to convert the NT user name to the' Distinguished Name required for the LDAP provider.Set objTrans = CreateObject("NameTranslate")
' Initialize NameTranslate by locating the Global Catalog.objTrans.Init ADS_NAME_INITTYPE_GC, ""' Use the Set method to specify the NT format of the object name.objTrans.Set ADS_NAME_TYPE_NT4, strNetBIOSDomain & "\" & strNTName
' Use the Get method to retrieve the RPC 1779 Distinguished Name.strUserDN = objTrans.Get(ADS_NAME_TYPE_1779)
' Escape any "/" characters with backslash escape character.
' All other characters that need to be escaped will be escaped.
strUserDN = Replace(strUserDN, "/", "\/")' Bind to the user object in Active Directory with the LDAP provider.Set objUser = GetObject("LDAP://" & strUserDN)
If the object with the specified NT name does not exist, the Set method of the NameTranslate object raises an error. To programmatically determine the NetBIOS name of the domain you have authenticated to, see FAQ # 16 below.
10.
How do I convert the NetBIOS name of a computer to it's Distinguished Name?Computer accounts are just like user accounts, except that the sAMAccountName attribute of computer objects is terminated with "$". The NT name of a computer is the NetBIOS name with "$" appended on the end. The WshNetwork object returns the NetBIOS name of the computer. Before you can convert this name with NameTranslate, you must append the "$". For example:
' Constants for the NameTranslate object.
Const ADS_NAME_INITTYPE_GC = 3Const ADS_NAME_TYPE_NT4 = 3Const ADS_NAME_TYPE_1779 = 1' Specify the NetBIOS name of the domain.
strNetBIOSDomain = "MyDomain"
' Retrieve the NetBIOS name of the computer object from WshNetwork.
' Append a "$" on the end.
Set objNetwork = GetObject("Wscript.Network")
strComputer = objNetwork.ComputerName & "$"' Use the NameTranslate object to convert the NT computer name to the' Distinguished Name required for the LDAP provider.Set objTrans = CreateObject("NameTranslate")
' Initialize NameTranslate by locating the Global Catalog.objTrans.Init ADS_NAME_INITTYPE_GC, ""' Use the Set method to specify the NT format of the object name.objTrans.Set ADS_NAME_TYPE_NT4, strNetBIOSDomain & "\" & strComputer
' Use the Get method to retrieve the RPC 1779 Distinguished Name.strComputerDN = objTrans.Get(ADS_NAME_TYPE_1779)' Bind to the computer object in Active Directory with the LDAP provider.Set objComputer = GetObject("LDAP://" & strComputerDN)
This assumes that the Distinguished Name of the computer object does not contain any forward slash characters "/". If there are any forward slash characters, they must be escaped with the backslash escape character "\" to avoid an error when you bind to the object.
If you use NameTranslate to convert the Distinguished Name of a computer object to the NT from, you will need to parse the value returned by the Get method for the NetBIOS domain name and the NT name of the computer. If you want the NetBIOS name of the computer, you will need to strip off the trailing "$".
11.
How do I convert a Distinguished Name to an NT name?The VBScript example below converts the Distinguished Name of any user object to the NT form, which includes the NetBIOS name of the domain and the NT name of the user.
' Constants for the NameTranslate object.
Const ADS_NAME_INITTYPE_GC = 3Const ADS_NAME_TYPE_NT4 = 3Const ADS_NAME_TYPE_1779 = 1' Specify the Distinguished Name of the user.
strUserDN = "cn=TestUser,ou=Sales,dc=MyDomain,dc=com"
' Use the NameTranslate object to convert the Distinguished Name
' of the user to the NT Name required for the WinNT provider.Set objTrans = CreateObject("NameTranslate")
' Initialize NameTranslate by locating the Global Catalog.objTrans.Init ADS_NAME_INITTYPE_GC, ""' Use the Set method to specify the RPC 1779 format of the object name.objTrans.Set ADS_NAME_TYPE_1779, strUserDN
' Use the Get method to retrieve the NT Name.strNTName = objTrans.Get(ADS_NAME_TYPE_NT4)
' Parse for the NetBIOS name of the domain and the NT name of the user.
strNetBIOSDomain = Mid(strNTName, 1, InStr(strNTName, "\") - 1)
strUserName = Mid(strNTName, InStr(strNTName, "\") + 1)' Bind to the user object in Active Directory with the WinNT provider.Set objUser = GetObject("WinNT://" & strNetBIOSDomain & "/" & strUserName)
If the object with the specified Distinguished Name does not exist, the Set method of the NameTranslate object will raise an error.
12.
How do I convert an NT Name to a Display Name?The VBScript example below converts the NT form of any user name to the Display Name of the user object (the value of the displayName attribute):
' Constants for the NameTranslate object.
Const ADS_NAME_INITTYPE_GC = 3Const ADS_NAME_TYPE_NT4 = 3Const ADS_NAME_TYPE_DISPLAY = 4' Specify the NetBIOS name of the domain.
strNetBIOSDomain = "MyDomain"
' Specify the NT name of the user.strNTName = "TestUser"' Use the NameTranslate object to convert the NT user name to the' Distinguished Name required for the LDAP provider.Set objTrans = CreateObject("NameTranslate")
' Initialize NameTranslate by locating the Global Catalog.objTrans.Init ADS_NAME_INITTYPE_GC, ""' Use the Set method to specify the NT format of the object name.objTrans.Set ADS_NAME_TYPE_NT4, strNetBIOSDomain & "\" & strNTName
' Use the Get method to retrieve the Display Name.strDisplayName = objTrans.Get(ADS_NAME_TYPE_DISPLAY)
If the NT name of the user does not exist, the Set method of the NameTranslate object raises an error. However, if the object does not have a value assigned to the displayName attribute, the Get method of the NameTranslate object raises an error.13.
How do I convert an NT Name to a User Principal Name?The VBScript example below converts the NT form of any user name to the User Principal Name (the value of the userPrincipalName attribute):
' Constants for the NameTranslate object.
Const ADS_NAME_INITTYPE_GC = 3Const ADS_NAME_TYPE_NT4 = 3Const ADS_NAME_TYPE_USER_PRINCIPAL_NAME = 9' Specify the NetBIOS name of the domain.
strNetBIOSDomain = "MyDomain"
' Specify the NT name of the user.strNTName = "TestUser"' Use the NameTranslate object to convert the NT user name to the' Distinguished Name required for the LDAP provider.Set objTrans = CreateObject("NameTranslate")
' Initialize NameTranslate by locating the Global Catalog.objTrans.Init ADS_NAME_INITTYPE_GC, ""' Use the Set method to specify the NT format of the object name.objTrans.Set ADS_NAME_TYPE_NT4, strNetBIOSDomain & "\" & strNTName
' Use the Get method to retrieve the User Principal Name.strUserUPN = objTrans.Get(ADS_NAME_TYPE_USER_PRINCIPAL_NAME)
If the NT name of the user does not exist, the Set method of the NameTranslate object raises an error. However, if the object does not have a value assigned to the userPrincipalName attribute, the Get method of the NameTranslate object raises an error.14.
How do I convert an NT Name to a GUID?The VBScript example below converts the NT form of any user name to the GUID of the object. This is the value of the objectGUID attribute converted to a string format. It is also the value returned by the GUID property method of the object.
' Constants for the NameTranslate object.
Const ADS_NAME_INITTYPE_GC = 3Const ADS_NAME_TYPE_NT4 = 3Const ADS_NAME_TYPE_GUID = 7' Specify the NetBIOS name of the domain.
strNetBIOSDomain = "MyDomain"
' Specify the NT name of the user.strNTName = "TestUser"' Use the NameTranslate object to convert the NT user name to the' Distinguished Name required for the LDAP provider.Set objTrans = CreateObject("NameTranslate")
' Initialize NameTranslate by locating the Global Catalog.objTrans.Init ADS_NAME_INITTYPE_GC, ""' Use the Set method to specify the NT format of the object name.objTrans.Set ADS_NAME_TYPE_NT4, strNetBIOSDomain & "\" & strNTName
' Use the Get method to retrieve the GUID of the user object.strUserGuid = objTrans.Get(ADS_NAME_TYPE_GUID)
If the NT name of the user does not exist, the Set method of the NameTranslate object raises an error.
15.
Can I convert the Display Name of a user to the Distinguished Name?Yes, you can, as long as the user has a Display Name that is unique. If you specify ADS_NAME_INITTYPE_GC, the Display Name must be unique in the forest. Otherwise, it must be unique in the domain. An error will be raised by the Set method if the Display Name value you specify does not uniquely identify the object. The corresponding attribute is displayName. Of course, the value cannot be empty (null). A VBScript example follows:
' Constants for the NameTranslate object.
Const ADS_NAME_INITTYPE_GC = 3Const ADS_NAME_TYPE_1779 = 1Const ADS_NAME_TYPE_DISPLAY = 4' Specify the Display Name of the user.
strDisplay = "Test User"
' Use the NameTranslate object to convert the Display Name' of the user to the Distinguished Name.Set objTrans = CreateObject("NameTranslate")
' Initialize NameTranslate by locating the Global Catalog.objTrans.Init ADS_NAME_INITTYPE_GC, ""' Use the Set method to specify the Display Name of the object name.objTrans.Set ADS_NAME_TYPE_DISPLAY, strDisplay
' Use the Get method to retrieve the Distinguished Name of the user object.strUserDN = objTrans.Get(ADS_NAME_TYPE_1779)
If the Distinguished Name has any forward slash characters "/", they should be escaped with the backslash escape character "\" before using the Distinguished Name to bind to the corresponding object.
16.
How do I find the NetBIOS name of the domain?Most uses of the NameTranslate object require the NetBIOS name of the domain. If the client OS is NT or above, the environment variable %USERDOMAIN% is the NetBIOS name of the domain the user authenticated to. In VBScript, you can use the WshShell object to retrieve the value of this environment variable. For example:
Set objShell = CreateObject("Wscript.Shell")
strNetBIOSDomain = objShell.Environment("Process").Item("userdomain")
On any client, you can use the RootDSE object to retrieve the default naming context, which is the Distinguished Name of the domain that the user authenticated to. Then, you can use the NameTranslate object to convert this to the NetBIOS name of the domain. For example:
' Constants for the NameTranslate object.Const ADS_NAME_INITTYPE_GC = 3Const ADS_NAME_TYPE_NT4 = 3Const ADS_NAME_TYPE_1779 = 1
' Determine DNS name of domain from RootDSE.Set objRootDSE = GetObject("LDAP://RootDSE")strDNSDomain = objRootDSE.Get("defaultNamingContext")' Use the NameTranslate object to find the NetBIOS domain name from the' DNS domain name.Set objTrans = CreateObject("NameTranslate")objTrans.Init ADS_NAME_INITTYPE_GC, ""objTrans.Set ADS_NAME_TYPE_1779, strDNSDomainstrNetBIOSDomain = objTrans.Get(ADS_NAME_TYPE_NT4)' Remove trailing backslash.strNetBIOSDomain = Left(strNetBIOSDomain, Len(strNetBIOSDomain) - 1)
If the client is NT or above, you can also retrieve the NetBIOS domain name from the WshNetwork object. For example:
Set objNetwork = CreateObject("Wscript.Network")
strNetBIOSDomain = objNetwork.UserDomain
Finally, if the client is Windows 2000 or above, or NT with DSClient installed, you can use the WinNTSystemInfo object. For example:
Set objWinNTSysInfo = CreateObject("WinNTSystemInfo")
strNetBIOSDomain = objWinNTSysInfo.DomainName
You might attempt to retrieve the NetBIOS domain name from the domain object (binding with the DNS domain name retrieved from the RootDSE object). However, the nETBIOSName attribute of the domain object only has a value if the NetBIOS domain name is different from the Relative Distinguished Name of the domain (which is the top level domain component of the domain).
Note that the only method above that works on all clients (including Win9x) is the one that retrieves the DNS domain name from the RootDSE object and uses NameTranslate to convert this to the NT format.
17.
How do I specify credentials with NameTranslate?The InitEx method of the NameTranslate object is similar to the Init method, but allows you to specify a user name, domain, and password. The same connection options are supported. A VBScript example:
' Constants for the NameTranslate object.
Const ADS_NAME_INITTYPE_GC = 3Const ADS_NAME_TYPE_NT4 = 3Const ADS_NAME_TYPE_1779 = 1' Specify the NetBIOS name of the domain and the NT name of the user.strNTName = "MyDomain\TestUser"
' Specify a domain, user name, and password.
' The connection to Active Directory will be made with these credentials.
strDomain = "MyDomain"
strUser = "TestUser"
strPassword = "xyz321"
' Use the NameTranslate object to convert the NT user name to the' Distinguished Name required for the LDAP provider.Set objTrans = CreateObject("NameTranslate")
' Initialize NameTranslate by locating the Global Catalog.
' Specify credentials.objTrans.InitEx ADS_NAME_INITTYPE_GC, "", strUser, strDomain, strPassword' Use the Set method to specify the NT format of the object name.objTrans.Set ADS_NAME_TYPE_NT4, strNTName
' Use the Get method to retrieve the RPC 1779 Distinguished Name.strUserDN = objTrans.Get(ADS_NAME_TYPE_1779)
' Escape any "/" characters with backslash escape character.
' All other characters that need to be escaped will be escaped.
strUserDN = Replace(strUserDN, "/", "\/")' Bind to the user object in Active Directory with the LDAP provider.Set objUser = GetObject("LDAP://" & strUserDN)
18.
Can I convert the names of more than one object at a time?Yes, you can. The SetEx and GetEx methods of the NameTranslate object are similar to the Set and Get methods, except that they deal with arrays of names. A VBScript example:
' Constants for the NameTranslate object.
Const ADS_NAME_INITTYPE_GC = 3Const ADS_NAME_TYPE_NT4 = 3Const ADS_NAME_TYPE_1779 = 1' Specify the NT form of several user names.arrNTNames(0) = "MyDomain\TestUser"
arrNTNames(1) = "MyDomain\JoeSmith"
arrNTNames(2) = "MyDomain\MaryNelson"' Use the NameTranslate object to convert the NT user names to the' Distinguished Names required for the LDAP provider.Set objTrans = CreateObject("NameTranslate")
' Initialize NameTranslate by locating the Global Catalog.objTrans.Init ADS_NAME_INITTYPE_GC, ""' Use the SetEx method to specify the NT format of the object names.objTrans.Set ADS_NAME_TYPE_NT4, arrNTNames
' Use the GetEx method to retrieve the RPC 1779 Distinguished Names.arrUserDNs = objTrans.GetEx(ADS_NAME_TYPE_1779)
For k = 0 To UBound(arrUserDNs)
Wscript.Echo arrUserDNs(k)
Next
19.
What errors can occur?If the domain, server, or GC cannot be contacted, the Init method will raise an error. This will happen if you are not authenticated to the domain. You can use the InitEx method to specify user credentials. Of course, an error will be raised by the InitEx method if the credentials are incorrect, or if the domain, server, or GC cannot be contacted.
If the object with the name specified does not exist, the Set method will raise an error.
If the object does not have a value defined for the corresponding attribute, the Get method will raise an error. For example, if the displayName attribute has no value, the Get method will raise an error if you have specified ADS_NAME_TYPE_DISPLAY. Similarly, if userPrincipalName has no value, Get will raise an error if you have specified ADS_NAME_TYPE_USER_PRINCIPAL_NAME. Such an error will never occur if you attempt to retrieve a name in the formats ADS_NAME_TYPE_1779, ADS_NAME_TYPE_CANONICAL, ADS_NAME_TYPE_NT4, or ADS_NAME_TYPE_GUID because the corresponding attributes always have a value.
The Set method will raise an error if the value specified does not uniquely identify the object in Active Directory. For example, more than one user could have the same value assigned to the displayName attribute. If you specify the object with the Set method and ADS_TYPE_NAME_DISPLAY and specify a value that could identify more than one object, an error will be raised. Once again, note that this cannot happen with ADS_NAME_TYPE_1779, ADS_NAME_TYPE_CANONICAL, ADS_NAME_TYPE_NT4, ADS_NAME_TYPE_USER_PRINCIPAL_NAME, or ADS_NAME_TYPE_GUID, because the corresponding attribute values must be unique.
20.
Where can I get more information?For more information on NameTranslate, see the following links:
IADsNameTranslate Interface:
http://msdn2.microsoft.com/en-us/library/Aa706046.aspxADS_NAME_INITTYPE_ENUM:
http://msdn2.microsoft.com/en-us/library/Aa772266.aspxADS_NAME_TYPE_ENUM:
http://msdn2.microsoft.com/en-us/library/Aa772267.aspxInit Method:
http://msdn2.microsoft.com/en-us/library/Aa706049.aspxSet Method:
http://msdn2.microsoft.com/en-us/library/Aa706053.aspxGet Method:
http://msdn2.microsoft.com/en-us/library/Aa706047.aspxInitEx Method:
http://msdn2.microsoft.com/en-us/library/Aa706050.aspxSetEx Method:
http://msdn2.microsoft.com/en-us/library/Aa706054.aspxGetEx Method:
http://msdn2.microsoft.com/en-us/library/Aa706048.aspx
