The User Principle Name and You

Originally published on May 26, 2004.

Beginning with Windows 2000, Microsoft began moving away from their proprietary WINS (Windows Internet Naming Service). WINS is responsible for name-to-IP-address mapping, and is in the process of being supplanted by DNS (Domain Name System). DNS has long been used on the Internet, and this is just another step for Microsoft to meet industry standards within its operating systems and applications.

Unfortunately, as of Windows 2003 and Exchange 2003, this movement is not yet complete (reference: KB 837391). However, we are well on our way. Windows 2000 and Windows 2003 preferentially use DNS for most, if not all, of their name to IP address mappings. Exchange 2000 and Exchange 2003 are not quite as far along the path. Outlook clients prior to Outlook 2003 still require WINS for full and proper operation.

Part of the movement involves the deprecation of NetBIOS domain names and usernames (referred to in Active Directory Users and Computers as “User logon name (pre-Windows 2000)”). These are (slowly) being replaced by what ADU&C now calls “User logon name”, in the format of an email address. These logon names are also known as User Principal Names (as that is the name given for these attributes as they are stored in Active Directory).A user principal name looks like an email address. At some companies, it is the user's email address. It has a format of: username@upn-suffix. A UPN suffix typically appears to be a DNS domain name. For example, within my company, our A/D root domain is named “brnets.local” and my username is “michael.smith”. Each domain contained within a forest is available, by default, as a UPN suffix. Therefore, since my User record is within our forest root, my default user principal name is “michael.smith@brnets.local”.The down-level domain name (that is, the NetBIOS name) of our forest root is “BRNETS”. For company employees, we have chosen that the username of the UPN will be the same as the username of the down-level logon.Therefore, my down-level username (pre-Windows 2000) is “BRNETS\michael.smith”. This is the domain\username format that NT administrators have been accustomed to seeing for many years (as well as many of our users).

The user principal name is not a required attribute (that is, Active Directory does not require it to be set). The new user wizard in ADU&C makes you set it - but you can go in and delete it from the Account Properties page later, and when you are creating users programmatically (such as via scripting), it doesn't need to be specified at all.

However, the “User logon name (pre-Windows 2000)” is a required attribute. This down-level attribute is commonly known as sAMAccountName (again, this is the attribute name for this item as it is stored in Active Directory). The sAMAccountName is unique within a domain. When combined with the domain it is defined within, it becomes unique within a forest. The sAMAccountName does not include the domain, it inherits the domain from the domain in which the user object is defined.   

When creating a user within A/D, the uniqueness of domain\sAMAccountName is enforced, regardless of where you create the user – via ADU&C, via scripting, whatever. However, while a user principal name should be unique, it is only enforced within ADU&C. You can easily create multiple user objects with the same UPN. You do not want to do this, though: if a user object is created which has a duplicate user principal name, neither user will be able to authenticate.

Yes, authenticate. Both the domain\username and the UPN may be used to authenticate to A/D with Windows 2000, Windows XP and Windows Server 2003. If you enter a UPN in the username dialog box, you'll find the domain box is grayed out, and no longer available for selection.

User principal name suffixes are stored in two different places within A/D. The “normal” place is at the forest root. This may be accessed directly using Active Directory Domains and Trusts (right click on the “top” in the left pane of the MMC and select “Properties”). This is stored at the CN=Partitions entry of the Configuration naming context within the LDAP tree (and may be viewed using tools such as LDP and other LDAP browsers). The multi-valued attribute of interest associated with that ADSPath is uPNSuffixes. For example, an LDAP URL is LDAP://CN=Partitions,CN=Configuration,DC=brnets,DC=local.

The other location is per Organizational Unit (OU). Each OU may also have a multi-valued attribute named uPNSuffixes associated with it. There is no way within the standard GUI's provided by Microsoft to set this value (however, ADSIEdit or scripting can be used). However, once it is set, ADU&C will present these uPNSuffixes as options for assigning UPNs to newly created (or modified) users who are created as objects within those OU's.

Placing the UPN suffixes in these locations seems to be only relevant to the user interface. However, that is not completely true. Scripting (and other languages) permits you to create users whose UPN suffixes are not defined in either of the above locations. This is perfectly legal, and 99% of the time causes no issues whatsoever. However, if your environment has a situation where there are non-transitive trusts involved, or cross-forests trusts (in Windows Server 2003) are present, not having the UPN suffixes defined can cause a number of authentication issues (especially in the event of UPN suffix collision).

Quoting Guido Grillenmeier of HP in Germany (a well-known Active Directory expert) from a posting on the ActiveDir mailing list:

Adding the UPN suffixes to the list of alternate UPNs will enable configuration of TLN restrictions (Top-Level Name restrictions) for forest trusts (i.e. transitive trust between two 2003 forests). The UI lists the available UPN suffixes of the trusted forest incl. the stored alternate UPNs and allows you to configure which ones you allow to be used "accross the trust" for authentication.  This is a must, if your UPN isn't a subordinate of the top level name of your root (e.g. TLN of root = "", but your alternative UPN suffix is ""). 

Alternative UPNs which are subordinates (e.g. "") can be added manually within the wizard by adding exceptions for your existing root-UPN suffix.
Soon, we'll discuss dealing with UPNs in code.
However, if you've made it this far, you are probably actually wondering: “Why do I care about UPNs?”
Thanks for asking, and I'll tell you: to allow a user to sign into Outlook, webmail (Outlook Web Access), a workstation, a server, to perform any authentication using their email address.
Let's use, as an example, “”. If we configure this as a UPN, and configure the username to be the same as the LHS (left hand side) of the user's email address, then the user can authenticate using their email address.
As a more complete example:
1) create the UPN “” in Active Directory as discussed above
2) Create a recipient policy for all users having a UPN ending in “” to receive an email address equal to “”, with an LDAP query such as:
3) Create user USER1 assigning the UPN of “”.
Now, voila', this user will be able to authenticate in Windows XP, in a properly configured OWA, etc. etc. as
This is in common usage in hosted environments -- this allows the hosting company for most purposes to hide their NetBIOS domain name.
P.S.: Extra credit for the first person to decode the LDAP query. While there are loads of LDAP references, small and easy-to-understand references are few and far between...
Published Tuesday, November 13, 2007 4:51 PM by michael
Filed under:


Tuesday, April 07, 2009 3:49 PM by Michael's meanderings...

# Handling the userPrincipalName in PowerShell

I dealt with the importance of the userPrincipalName in one of my very early blog postings, dated May