Red Hat SummitChapter 48. Enabling authentication using AD User Principal Names in IdM
Enable Active Directory (AD) users to authenticate to Identity Management (IdM) using their User Principal Names (UPNs). This simplifies authentication in trusted AD forest environments by supporting UPN-based login.
48.1. User principal names in an AD forest trusted by IdM
Active Directory (AD) users in an Identity Management (IdM) trust can use alternative User Principal Names (UPNs) to authenticate — for example, their email address instead of the default Kerberos realm login — by configuring additional UPN suffixes in the AD forest root.
For example, if a company uses the Kerberos realm AD.EXAMPLE.COM, the default UPN for a user is user@ad.example.com. To allow your users to log in using their email addresses, for example user@example.com, you can configure EXAMPLE.COM as an alternative UPN in AD. Alternative UPNs (also known as enterprise UPNs) are especially convenient if your company has recently experienced a merge and you want to provide your users with a unified logon namespace.
UPN suffixes are only visible for IdM when defined in the AD forest root. As an AD administrator, you can define UPNs with the Active Directory Domain and Trust utility or the PowerShell command line tool.
To configure UPN suffixes for users, Red Hat recommends to use tools that perform error validation, such as the Active Directory Domain and Trust utility.
Red Hat recommends against configuring UPNs through low-level modifications, such as using ldapmodify commands to set the userPrincipalName attribute for users, because Active Directory does not validate those operations.
After you define a new UPN on the AD side, run the ipa trust-fetch-domains command on an IdM server to retrieve the updated UPNs. See Ensuring that AD UPNs are up-to-date in IdM.
IdM stores the UPN suffixes for a domain in the multi-value attribute ipaNTAdditionalSuffixes of the subtree cn=trusted_domain_name,cn=ad,cn=trusts,dc=idm,dc=example,dc=com.
48.2. Ensuring that AD UPNs are up-to-date in IdM
Refresh trusted Active Directory forest information in Identity Management (IdM) after modifying User Principal Name (UPN) suffixes to ensure IdM recognizes updated authentication credentials. This keeps your trust configuration synchronized with Active Directory changes.
Prerequisites
- IdM administrator credentials.
Procedure
Enter the
ipa trust-fetch-domainscommand. Note that a seemingly empty output is expected:[root@ipaserver ~]# ipa trust-fetch-domains Realm-Name: ad.example.com ------------------------------- No new trust domains were found ------------------------------- ---------------------------- Number of entries returned 0 ----------------------------
Verification
Enter the
ipa trust-showcommand to verify that the server has fetched the new UPN. Specify the name of the AD realm when prompted:[root@ipaserver ~]# ipa trust-show Realm-Name: ad.example.com Realm-Name: ad.example.com Domain NetBIOS name: AD Domain Security Identifier: S-1-5-21-796215754-1239681026-23416912 Trust direction: One-way trust Trust type: Active Directory domain UPN suffixes: example.comThe output shows that the
example.comUPN suffix is now part of thead.example.comrealm entry.
48.3. Gathering troubleshooting data for AD UPN authentication issues
Collect detailed User Principal Name (UPN) configuration logs from Active Directory (AD) and Identity Management (IdM) environments to diagnose authentication failures with alternate UPNs. This data helps identify misconfigurations in trust relationships.
Prerequisites
- You must be logged in to an IdM Trust Controller or Trust Agent to retrieve information from an AD domain controller.
-
You need
rootpermissions to modify the following configuration files, and to restart IdM services.
Procedure
-
Open the
/usr/share/ipa/smb.conf.emptyconfiguration file in a text editor. Add the following contents to the file.
[global] log level = 10-
Save and close the
/usr/share/ipa/smb.conf.emptyfile. -
Open the
/etc/ipa/server.confconfiguration file in a text editor. If you do not have that file, create one. Add the following contents to the file.
[global] debug = True-
Save and close the
/etc/ipa/server.conffile. Restart the Apache webserver service to apply the configuration changes:
[root@server ~]# systemctl restart httpdRetrieve trust information from your AD domain:
[root@server ~]# ipa trust-fetch-domains <ad.example.com>Review the debugging output and troubleshooting information in the following log files:
-
/var/log/httpd/error_log -
/var/log/samba/log.*
-
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}