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.


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 in to 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 (PIV-I) 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-I 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 on 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.
Gathering PIV Authentication Certificates for Mapping into AD

Identity certificates used for Windows logon can generally be found:

  • On the smart card itself.
  • By requesting the certificates directly from the smart card issuer.
  • By exporting the certificates from a third party application in which the certificates are already registered, such as a FIPS 201-compliant Physical Access Control System (PACS).

Each of these options is discussed below.

Gather Certificate from Smart Card
To gather the certificate from the smart card using a Windows workstation, have the cardholder do the following:

  1. Open the Start Menu, located in the bottom left corner of the screen.
  2. Type command prompt.
  3. In the prompt, type certutil -scinfo.
    A screenshot of a command prompt with certutil information.
  4. Press Enter.
  5. The cardholder will be prompted several times for a PIN, but a PIN is not required for this operation. Have the cardholder press cancel each time they are prompted for a PIN until they see the Certificate List.
    A screenshot of a Windows Security Certificate List window.
  6. Have the cardholder click Click here to view certificate properties. The appropriate certificate will list “Smart Card Logon” in the intended purposes on the General tab. If the certificate has this purpose listed, have the cardholder proceed to Step 7. Otherwise, have the cardholder close the certificate, click more choices on the Certificate List, click another certificate in the list, and click Click here to view certificate properties until the correct certificate has been identified.
    A screenshot of a Certificate Details window.
  7. Have the cardholder select the Details tab and then proceed with the steps below.
  8. Click copy to file to start the certificate export wizard.
  9. Click Next.
  10. Click Next again to indicate that the cardholder does not wish to export the private key.
  11. Click Next again to use the default DER encoding.
  12. Click Browse to select where to save the certificate. Have the cardholder select a location that he or she has permission to save to, such as Desktop or Documents.
  13. Enter a meaningful name for the certificate (such as the cardholder’s name or employee ID).
  14. Click Save.
  15. Click Next.
  16. Click OK.
  17. Click OK to close the Certificate Details window.
  18. Click OK to close the Certificate List.
  19. Close the command prompt.
    A screenshot of a Save As window with the This PC option highlighted.
    A screenshot showing several windows with the Certificate Export Wizard window on top.
  20. Have the cardholder send the exported .cer file to your organization’s Network Administrator in a way that aligns with the organization’s security policies.

Request Certificates from the Smart Card Issuer
Your organization’s credential issuer may have a copy of certificates issued to current users. You will need to specifically request from the issuer the most recent valid identity certificates suitable for smart card logon. The issuer will produce these certificates in a variety of ways, based on the certification authority or the Card Management System in use.

Export Certificates from a Third Party System
Your organization may have already collected the relevant certificates as part of the enrollment process for a third party application, such as a FIPS 201-compliant PACS system. Depending on the system and configuration in use, you may be able to export your cardholders’ certificates from the database where they are enrolled. Speak with your PACS integrator to understand what options are available to you. A screenshot of a Card Operations window that shows several rows of card IDs and other information.

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 you are 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. Check out the script in our public scripts repository or contact ICAM at GSA.Gov for more information.

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.

An official website of the General Services Administration

Looking for U.S. government information and services?
Visit Edit this page