Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Account Linking

Account linking refers to the process of associating a certificate on a user’s PIV credential with their domain account.

Comparing altSecurityIdentities and User Principal Name

There are two account linking attributes to choose from:

  • altSecurityIdentities (recommended)
  • User Principal Name (UPN)

It’s not possible to configure a domain to use both altSecurityIdentities and User Principal Name mapping. You must choose one of these options and configure its use for all domain users.

altSecurityIdentities approach

  • Each PIV credential can be associated with more than one account.
    • This flexibility allows for the association of a single PIV credential certificate to an individual’s end-user and privileged user account(s).
  • Users are presented with an additional field during network authentication to identify which account the user wants to access. This field is known as the User Name Hint.
    • The User Name Hint informs Windows which account the user is trying to log into if the mapped certificate is associated with multiple accounts.
    • Entering a User Name Hint is optional if the user’s PIV Authentication certificate UPN matches their Windows Logon name.
  • You can choose from one of six options to map a certificate to a given account.
  • There is more flexibility for accepting PIV credentials issued by other government agencies or partners, including PIV-Interoperable credentials.

User Principal Name approach

  • Each PIV credential can only be associated with one account.
  • The UPN value from the Subject Alternate Name in the PIV Authentication certificate is required.
  • There is no flexibility for associating the PIV credential to separate privileged accounts.
  • There is less flexibility for accepting PIV credentials issued by other government agencies or partners, including PIV-Interoperable credentials.

Transitioning from UPN Mapping to altSecurityIdentities Mapping

If you have a large network with many domains, you should carefully plan the migration from User Principal Name to the altSecurityIdentities account linking method.

Use of UPN by Applications

You may find that you have many applications that rely upon User Principal Name values. There is no need to remove existing or stop populating new User Principal Name values in your transition to altSecurityIdentities.

There are three steps to implement altSecurityIdentities account linking:

  1. Link the PIV Authentication Certificate
  2. Enable User Name Hints
  3. Disable User Principal Name Mapping

First, you need to link each user’s PIV Authentication certificate to their domain account(s). This is accomplished by populating data extracted from the user’s PIV Authentication certificate into their Active Directory record, specifically into the altSecurityIdentities attribute.

Adding altSecurityIdentities attributes will not break existing UPN account linking or cause smart card logon to fail. It’s possible to plan your transition carefully and to take your time populating the altSecurityIdentities attribute for domain users.

There are six mapping options to choose from, but most organizations use Issuer and Subject.

Options Tag Example Considerations
Subject X509:<S> X509:<S>C=US,O=U.S. Government,OU=Government Agency,CN=JANE DOE OID.0.9.2342.19200300.100.1.1=25001003151020 For certificates which assert the UID identifier (0.9.2342.19200300.100.1.1) or other object identifier in the common name, the identifier is prepended with the OID qualifier.
Issuer and Subject X509:<I><S> X509:<I>C=US,O=U.S. Government,OU=Certification Authorities,OU=Government Demonstration CA<S>C=US,O=U.S. Government,OU=Government Agency,CN=JANE DOE OID.0.9.2342.19200300.100.1.1=47001003151020 Note the spaces carefully when testing machine-readable formats of the certificate extensions versus the human-readable formats.
Issuer and Serial Number X509:<I><SR> X509:<I>C=US,O=U.S. Government,OU=Certification Authorities,OU=Government Demonstration CA<SR>46a65d49 Serial number is stored in a reversed byte order from the human-readable version, starting at the most significant byte.
Subject Key Identifier X509:<SKI> X509:<SKI>df2f4b04462a5aba81fec3a42e3b94beb8f2e087 Not generally recommended; may be difficult to manage.
SHA1 hash of public key X509:<SHA1-PUKEY> X509:<SHA1-PUKEY>50bf88e67522ab8ce093ce51830ab0bcf8ba7824 Not generally recommended; may be difficult to manage.
RFC822 name X509:<RFC822> Not recommended Not recommended; not commonly populated in PIV Authentication certificates.
Methods for Linking the PIV Authentication Certificate

System administrators can leverage one of the approaches below to link PIV Authentication certificates with user accounts. Run these steps from a domain controller with elevated privileges.

A. Use the Active Directory Users and Computers Graphical User Interface
The following steps are useful if you only need to update a small number of user accounts:

  • Start > Server Manager
  • Tools > Active Directory Users and Computers
  • View > Advanced Features
  • Expand your domain to reveal the Users directory
  • Right-click on the user whose certificate you’d like to map and select Name Mappings
  • Click Add and browse to a local copy of the user’s PIV Authentication certificate
  • Click Apply and then OK

B. Use Automation
If designing an automated process to transition users from Principal Name to altSecurityIdentities mapping, consider the following functionality:

  • Load and process multiple certificates at once (for example, reading a directory of user certificates)
  • Extract the UPN from each certificate and ensure a corresponding user record exists in Active Directory
  • For certificates that contain a UPN that matches a record in Active Directory:
    • Extract and format the certificate Issuer and Subject attributes in preparation for publishing to Active Directory
    • Update the user’s Active Directory record with the altSecurityIdentities attribute and corresponding Issuer and Subject data
  • For certificates that do not contain a UPN that matches a record in Active Directory:
    • Set aside for manual review (e.g., these users may be no longer affiliated with your organization)
  • Evaluate accounts in Active Directory that do not contain an altSecurityIdentities attribute after process execution for manual review and further remediation

Collaborate with us!

We're working with a small number of agencies to pilot a simple PowerShell script to help with some of the functional requirements above. Contact us at icam@gsa.gov if you'd like more information or if you'd like to collaborate with us.

2. Enable User Name Hints

You need to enable User Name Hints for your network domain. This will modify the logon prompts for Windows workstations and servers joined to the network domain. Your users will be prompted to provide both the PIV credential PIN value and a User Name Hint value.

Did you know?

If a user's PIV Authentication certificate UPN matches their Windows Logon name, the User Name Hint value may be left blank during the logon process. The UPN is found in the Subject Alternative Name extension of the PIV Authentication Certificate.

User Name Hint Setting

For Windows Server 2008 R2:

  • Computer Configuration -> Policies-> Administrative Templates -> Windows Components, and then expand Smart Card.
  • Select Allow User Name Hint

For Windows Server 2012 and later:

  • Computer Configuration -> Administrative Templates -> Windows Components, and then expand Smart Card.
  • Select Allow User Name Hint

Management of smart card settings should be deployed using a group policy object for the domain.

3. Disable User Principal Name Mapping

To transition from UPN mapping to altSecurityIdentities account linking, you will need to configure a registry setting on all domain controllers. Only configure the registry setting below once you have completed the above steps and are ready to disable UPN mapping.

Note: Organizations should carefully plan their transition to the altSecurityIdentities account linking approach and test interoperability before implementing changes in their production IT environments. The registry configuration below will cause smart card logon to fail for any user missing the altSecurityIdentities attribute.

  • Key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Kdc
  • Name: UseSubjectAltName
  • Type: DWORD
  • Data (Value): 00000000

This setting tells your network domain: I don’t always want to use the Subject Alternate Name values for my user certificates. More information on the setting is available here.

It’s possible to revert to UPN account linking by removing the registry setting above.

Use group policy objects or other centralized management options to manage registry options.