Chapter 51. Enabling authentication using AD User Principal Names in IdM

download PDF

51.1. User principal names in an AD forest trusted by IdM

As an Identity Management (IdM) administrator, you can allow AD users to use alternative User Principal Names (UPNs) to access resources in the IdM domain. A UPN is an alternative user login that AD users authenticate with in the format of user_name@KERBEROS-REALM. As an AD administrator, you can set alternative values for both user_name and KERBEROS-REALM, since you can configure both additional Kerberos aliases and UPN suffixes in an AD forest.

For example, if a company uses the Kerberos realm AD.EXAMPLE.COM, the default UPN for a user is To allow your users to log in using their email addresses, for example, 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.

51.2. Ensuring that AD UPNs are up-to-date in IdM

After you add or remove a User Principal Name (UPN) suffix in a trusted Active Directory (AD) forest, refresh the information for the trusted forest on an IdM server.


  • IdM administrator credentials.


  • Enter the ipa trust-fetch-domains command. Note that a seemingly empty output is expected:

    [root@ipaserver ~]# ipa trust-fetch-domains
    No new trust domains were found
    Number of entries returned 0

Verification steps

  • Enter the ipa trust-show command to verify that the server has fetched the new UPN. Specify the name of the AD realm when prompted:

    [root@ipaserver ~]# ipa trust-show
      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:

The output shows that the UPN suffix is now part of the realm entry.

51.3. Gathering troubleshooting data for AD UPN authentication issues

Follow this procedure to gather troubleshooting data about the User Principal Name (UPN) configuration from your Active Directory (AD) environment and your IdM environment. If your AD users are unable to log in using alternate UPNs, you can use this information to narrow your troubleshooting efforts.


  • You must be logged in to an IdM Trust Controller or Trust Agent to retrieve information from an AD domain controller.
  • You need root permissions to modify the following configuration files, and to restart IdM services.


  1. Open the /usr/share/ipa/smb.conf.empty configuration file in a text editor.
  2. Add the following contents to the file.

    log level = 10
  3. Save and close the /usr/share/ipa/smb.conf.empty file.
  4. Open the /etc/ipa/server.conf configuration file in a text editor. If you do not have that file, create one.
  5. Add the following contents to the file.

    debug = True
  6. Save and close the /etc/ipa/server.conf file.
  7. Restart the Apache webserver service to apply the configuration changes:

    [root@server ~]# systemctl restart httpd
  8. Retrieve trust information from your AD domain:

    [root@server ~]# ipa trust-fetch-domains <>
  9. Review the debugging output and troubleshooting information in the following log files:

    • /var/log/httpd/error_log
    • /var/log/samba/log.*
Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.