Account linking refers to the process of associating a certificate on a user’s PIV credential with their domain account.
See This Alert First
Please hold off on implementing the guidance on this page until it is updated. Microsoft HIGHLY recommends that all customers who use PIV, smart card, or certificate-based authentication with AltSecID to IMMEDIATELY change the registry key on domain controllers prior to installing the KB5014754 May 2022 updates. See KB5014754—Certificate-based authentication changes on Windows domain controllers for additional information. Wait for further guidance from CISA or contact CyberLiasion at CISA dot gov.
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.
- 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
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.
|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:
- Open the Start Menu, located in the bottom left corner of the screen.
- Type command prompt.
- In the prompt, type certutil -scinfo.
- Press Enter.
- 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.
- 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.
- Have the cardholder select the Details tab and then proceed with the steps below.
- Click copy to file to start the certificate export wizard.
- Click Next.
- Click Next again to indicate that the cardholder does not wish to export the private key.
- Click Next again to use the default DER encoding.
- 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.
- Enter a meaningful name for the certificate (such as the cardholder’s name or employee ID).
- Click Save.
- Click Next.
- Click OK.
- Click OK to close the Certificate Details window.
- Click OK to close the Certificate List.
- Close the command prompt.
- 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.
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.