FreeIPA trust controllers and agents

Where FreeIPA trust controllers and trust agents fit before you connect Active Directory

If your IdM team must connect Linux identity to an Active Directory forest, the first decision is which servers will carry the trust roles. Trust controllers and trust agents are a placement decision made on top of your existing replication layout, not a separate install step. The connection itself is a cross-forest trust that FreeIPA establishes through Samba components, and the IPA domain must use a DNS domain that does not overlap with any domain in the AD forest, according to the FreeIPA Trusts page. Settle that naming question before you touch either side, because it is hard to unwind once users and hosts depend on it.

Plan trust roles before the first trust, when you add a data center, or when you replace an older synchronization method. A new site changes which servers can answer Kerberos and AD referrals for local clients, so the placement you chose for one site may no longer make sense once a second one exists. Replacing an older sync method has the same effect: the roles you assign will determine how cutover traffic reaches the servers that remain. Review the current replica list, the servers that run DNS or the certificate authority, and the sites they serve, then map each planned trust role onto that list.

Before you assign roles, confirm three things with your AD team and your own records: the forest and domain functional levels in use, the domain controller versions, and which of your IdM servers have spare capacity and are dedicated to identity services. Ask the vendor documentation and your Windows team to confirm supported combinations for your versions rather than assuming them. Record the reasoning for each placement, because the count and location of roles will be questioned during the first audit of the trust and during any later data center change.

What a trust controller does and what a trust agent does

A FreeIPA trust with Active Directory depends on two roles that are easy to confuse: the trust controller that holds the cross-forest relationship, and the trust agents that serve Kerberos referrals and ID lookups to Linux hosts. Placing them well determines whether Linux logins keep working when a site or link fails, so each card below covers one part of that design.

Trust controller role

The trust controller is the IdM server that establishes and maintains the cross-forest trust with the AD forest, using Samba components to talk to AD domain controllers. It handles the trust relationship and cross-realm Kerberos referrals, so it must be able to reach AD over the network at all times. Confirm the controller behavior for your release in the FreeIPA trust documentation before you decide how many controllers to run and where they sit.

Trust agent role

A trust agent is an IdM server that can answer identity lookups for AD users on behalf of the controllers without holding the trust itself. Agents let Linux clients resolve AD users and groups in a site that has no direct path to AD domain controllers. Ask your team to confirm which Kerberos functions an agent can and cannot perform in the release you deploy, because that boundary decides whether AD users can authenticate there at all.

Samba components in each role

Trust handling relies on Samba components on the IdM servers that take part in the trust, including the tooling that joins the IPA domain to the AD forest and the services that answer AD-side queries. Controllers and agents do not run the same Samba set, so package and service checks must be done per host. Record which Samba packages and services are present on each server as part of your build sign-off.

Kerberos ticket path from AD users

An AD user requests a service ticket through the cross-realm trust, and the Kerberos referral path decides which KDC the request reaches and whether it can be answered locally. Map this path for each site before go-live, including which IdM hosts receive the referral and which clients use them. Tracing one test login end to end, with a named AD user and a named Linux host, is the fastest way to confirm the path works as designed.

Effect of placement during a site outage

If a site loses its link to AD or to the controllers, Linux hosts there can only authenticate AD users through what is already reachable locally. Placement therefore decides whether AD logins continue during an outage, and whether cached credentials and SSSD offline behavior cover the gap. Test this by isolating a site in a lab or maintenance window and confirming which logins succeed and which fail, then document the result for the operations team.

Packages each role requires

Controllers and agents each need a specific set of IdM and Samba packages, and the exact list changes between FreeIPA releases and between RHEL-based platforms. Installing the same package set on every server is not a safe shortcut, because a controller may need trust components that an agent does not. Obtain the package list for your release from the trust documentation, then compare it against each host with your package manager before enabling the trust.

Which trust role fits each site in a FreeIPA deployment

This table compares four site situations and the trust role that suits each one, with the dependencies and questions to settle with the AD team. Read each row as a starting placement to check against your own network, AD site layout and recovery requirements. The main takeaway is that trust role placement follows where AD domain controllers are reachable and how much Linux login must survive a WAN outage.

Situation	Role placed	Why it fits	Depends on and confirm with the AD team
Single data center	Trust controller on two or three IdM replicas	Keeps trust handling on servers close to the AD domain controllers and the clients they serve	Local DNS for the AD domain; confirm which AD domain controllers the controllers will contact
Multiple data centers with local AD domain controllers	Trust controller in each data center that has a local AD domain controller	Trust traffic stays local, so each site does not depend on a remote link to reach AD	AD site and subnet design; confirm which AD sites map to which data center and that DNS SRV records resolve per site
Site with no local AD domain controller	Trust agent on local IdM servers, with trust controllers elsewhere	Local Linux hosts can still resolve trusted users without running trust handling locally	Reachable controllers over the WAN; confirm the trust agent limits for Kerberos in the FreeIPA trust documentation before relying on them
Site that must keep Linux login working when the WAN link fails	Local IdM replicas with cached identity data, plus a local trust agent if AD users must log in	Local KDC and LDAP service keep working without a remote path, and SSSD caches identities for offline use	Test offline logins after a simulated WAN cut; confirm with the AD team which AD users and groups must work during an outage

How many trust controllers and agents to place per data center

The count question starts with the replica plan, not with trust. The FreeIPA deployment recommendations advise at least two to three replicas in each datacenter. Trust roles should be placed on servers that already belong to that layout, so the number you choose for trust has to fit inside the servers you already need for authentication, replication and failover. Do not add trust roles to a site as an afterthought. The supplied recommendations do not set a trust-specific count, so confirm the trust-capable count per data center against the current trust guidance and your own topology plan before you fix a number.

Three limits in the recommendations shape how many trust-capable servers a site can carry. The first is no more than four replication agreements per replica. Every additional replica adds agreements, and cross-site links draw from the same budget, so a busy site can exhaust a replica's agreements quickly. The second is that servers should be dedicated, without other applications, so a trust-capable server cannot double as a general application host to save hardware. The third is the PKI and DNS rule: where those services are used, at least one replica per datacenter must run them. If a site runs a certificate authority or DNS, that replica is already committed, so plan trust roles around that commitment and do not assume they are free.

Work through each site in order. List its replicas, count the replication agreements each one already holds, mark which replicas run PKI or DNS, and see how many dedicated servers remain for trust roles. If a site cannot meet the limits with the trust roles you need, change the topology before any trust is configured. Ask your partner or the FreeIPA project which current guidance sets the trust-capable count, and record the answer for each data center. Also check naming early, because the trust documentation requires that the IPA DNS domain not overlap any domain in the AD forest.

How to lay out trust roles before you run the trust setup

This sequence checks naming, replica layout, host packages, replication and DNS so that trust controllers and agents are placed correctly before any trust is created.

Confirm IPA and AD DNS naming
Before choosing any server, the IPA team and the AD team confirm the IPA DNS domain and Kerberos realm names and the AD forest and domain names. The IPA domain must use a DNS domain that does not overlap with any domain in the AD forest, so this is the first gate. Write the names into a shared record and have both teams sign off. The step is done when each side can state, from its own documentation, the same list of domains and realms with no overlap.
Map existing replicas for each site
Inventory every FreeIPA server, its site or data center, its installed roles (DNS, CA, NTP) and its current replication agreements. Use the replication topology commands available on your IPA version to export the list, and confirm it against your own change records. Note which sites have fewer than the two to three replicas that the FreeIPA deployment recommendations advise. The step is done when you have one table covering every server and site with no unknown entries.
Decide which servers take trust roles
Choose which replicas act as trust controllers and which act as trust agents, and in which sites. A trust controller runs the Samba components that talk to AD for the trust, and a trust agent serves Kerberos and LDAP lookups for clients in its site. Keep trust roles on dedicated servers where possible, since the deployment recommendations advise against running other applications on IPA servers. Ask your IPA specialist to confirm the role count for each site against the current trust documentation. The step is done when each server has one recorded role and an owner.
Confirm package availability on each chosen host
On every server selected in the previous step, confirm that the packages needed for trust operation are installed or installable from your configured repositories. Check the exact package set in the FreeIPA trust documentation for your release and your operating system, and compare it with rpm -q output on each host. Also confirm that the Samba and Kerberos versions on the host match what the trust documentation expects. The step is done when every host reports the required packages and no host depends on an unsupported repository.
Set up replication agreements within the limit
Add or adjust replication agreements so that no replica has more than four agreements, as the deployment recommendations advise. Build the topology so every site has at least one replica that runs the certificate authority or DNS if those services are used. Confirm that the planned trust controllers can reach their peers over the required ports. Run the replication status check on each server and record the result. The step is done when the replication status shows no errors and no replica exceeds four agreements.
Verify DNS from both sides
Test name resolution from the IPA side and from the AD side. Confirm that each IPA server and each client resolves the IPA domain, the SRV records for the Kerberos realm and the LDAP service, and the AD domain names through the forward zones you planned. Confirm that each client's resolver lists at least two DNS servers, as the deployment recommendations advise. The AD team should run the matching checks against their domain controllers. The step is done when both teams have saved the query output and every lookup returns the expected address.
Test login from a client in each site
Before any trust is used for production users, enroll or pick one test client in each site that has a trust role and run a login with a local IPA test account. Then confirm that name resolution, Kerberos ticket issuance and SSSD lookups succeed on each client. A failed test in one site often points to a missing agent or a DNS gap in that site. Record the login result and the SSSD log output for each site. The step is done when every site passes the test login and the results are filed with the change record. The trust setup itself is covered on a separate page, so run this sequence first and then follow that page.

Security and operational risks for trust-role servers

Trust controllers and trust agents sit inside the same replication and authentication path as the rest of your IdM topology, so a mistake on one of them can affect logins across the domain. The cards below cover the risks that most often surprise teams, and what to confirm on your own hosts before and after deployment.

Outdated backup restores break replication

Restoring an older backup into a live replica topology can break replication between servers that already hold newer data. Before any restore, confirm which server holds the newest state, plan whether the restore should be run on a fresh or isolated host, and document the recovery order for trust-role servers alongside the controllers. Rehearse this on a non-production copy so the steps are known before an incident.

First server owns certificate renewal

By default, the first server in a FreeIPA deployment handles certificate renewal and CRL publication. If that server is also hosting trust-role services, an outage or rebuild there can stall renewals and revocation updates for the whole deployment. Check which server is first in your topology, confirm where renewal and CRL duties run, and make sure a documented path exists to move those duties if the host is lost.

Keep trust-role hosts dedicated

Trust-role servers should run only the FreeIPA components they need, not unrelated applications that bring their own packages, users and attack surface. Shared hosts complicate patching windows and make it harder to tell whether a problem comes from FreeIPA or from another workload. Confirm that each trust controller and agent has a single purpose in your inventory and that its patch schedule is tracked separately.

Apply the 4.13.4 security fixes

FreeIPA 4.13.4 fixed two CVEs, including LDAP access control flaws that could let unauthenticated clients obtain credentials, and it hardened authentication checks across the API. Any trust-role server running an earlier 4.x release should be scheduled for this update, with the upgrade tested on a copy first. Verify the installed version on every server with the package manager and record the result against your change ticket.

Limit who holds the admin role

Anyone with the IdM admin role on a trust-role host can change identity data, policies and trust configuration that affect AD users across the deployment. Keep the admin role to a named, small group, separate day-to-day administration from break-glass access, and log every use of privileged accounts. Review membership on a schedule and confirm that AD administrators do not gain FreeIPA admin rights by default.

Kerberos limits on trust agents and what to test

Kerberos decides what a trust agent can actually serve, so this is the part of the design to settle before any hosts are pointed at it. An agent does not hold its own authority over AD accounts. Ticket requests from AD users travel along a trust path that runs from the client to the agent's IPA domain and then across the trust to the AD domain controllers, and each hop has to issue, forward and accept tickets correctly. The trust direction and whether Kerberos FAST (Flexible Authentication Secure Tunneling) is enforced both change that path. The sibling topic on one-way versus two-way trust covers those trade-offs, so use its conclusions as the starting point here and confirm which direction your design needs before you test Kerberos behavior.

The exact Kerberos limits on agents depend on the FreeIPA release and the trust documentation for that release, and they must be confirmed there rather than assumed from older deployments. Check the release notes for the version in use, the Trusts page and the deployment recommendations on the FreeIPA site, and ask your Red Hat or distribution support contact for any platform-specific constraints. Record, per agent, which AD domains it can serve, which ticket types it handles and whether FAST is required by the AD side, so the test results can be compared with a written design rather than memory.

Build the test plan around three checks that run from a client enrolled in IPA and from a host that depends on the agent. First, log in as an AD user with a password and confirm that a ticket is issued through the expected path, using klist on the client and the agent's logs for the request. Second, let the ticket age past its renewal point and confirm that kinit -R or the SSSD renewal behavior succeeds, then repeat after restarting the agent. Third, where two-factor authentication applies, test an AD user whose policy requires a second factor and confirm the result for each trust direction and FAST setting you plan to use. Record every failure with the agent, domain, ticket type and client version, because those four details are what the vendor or support team will ask for first.

Limits to confirm in your environment before you commit to a layout

A trust controller and trust agent layout depends on facts that sit outside the FreeIPA topology diagram: the release in use, the AD forest it must reach, the packages on your OS and the DNS names already in place. Confirm these items with the teams that own them before you fix server counts or placement.

FreeIPA release and trust role behavior

Confirm which FreeIPA 4.x release your servers run and whether its trust controller and trust agent roles behave as your design assumes. Release behavior changes between versions, and a security release such as 4.13.4 can change authentication checks on the API. Ask your platform vendor or your IdM team which release is in production and which one you will install. Record the version in the design document so later upgrades are checked against the same role model.

AD forest and domain functional levels

Confirm the forest and domain functional levels and the domain controller versions in every AD forest that the trust must reach. Those levels decide which trust features and encryption settings are available, and they limit which Windows Server versions can join the trust. Ask the AD team for the exact levels, not the levels the team remembers. Also ask whether any domain controller runs a version your RHEL release does not support for trusts.

Package set for the chosen OS

Confirm the package set for your operating system before you assign trust controller or trust agent roles to particular hosts. Trust support depends on Samba components, and package names and versions differ between distributions. Ask the platform team to build a test host from the planned image and list every installed package, including the Samba and IdM trust packages. Check that the same set is available in each data center, since a missing package on one site can leave that site without a trust path.

DNS overlap with AD domains

Confirm that the IPA DNS domain does not overlap with any domain in the AD forest. The FreeIPA trust documentation requires non-overlapping DNS domains, and an overlap blocks the trust before any server role matters. Ask the AD team for the full list of forest domain names, including child and tree domains, and ask the IdM team to confirm the planned IPA domain. Check the result from both sides of the trust before you order hardware.

Replication agreement limits in the actual topology

Confirm that the planned replica count per data center keeps each replica within the recommended limit of no more than four replication agreements. Trust controllers and agents add servers to the topology, so the count can exceed the limit once you combine them with existing replicas. Ask the IdM team for the current agreement list, then map the proposed roles onto it. The recommendation also asks for two to three replicas per data center, so confirm that the new roles do not push any site outside that range.

Existing WinSync or other sync setup

Confirm whether a WinSync user synchronization or another directory sync job already feeds FreeIPA from AD. Running a trust alongside WinSync can create duplicate users and conflicting UIDs, and a sync job may need to stop before the trust takes over Linux access. Ask the IdM team to list every sync job and the accounts it touches, and ask the AD team who owns the sync account. Decide with both teams whether the sync retires before, during or after the trust cutover.

What buyers ask about trust controllers and trust agents

How many trust controllers does each site need?

The count follows from your topology, so confirm it against the FreeIPA trust documentation for your version before fixing a number. The general deployment guidance advises at least two to three replicas in each datacenter and no more than four replication agreements per replica, according to the FreeIPA deployment recommendations. Trust roles sit on top of that layout, so a site with two data centers and a planned AD trust needs its controller placement decided together with its replicas. Ask the partner to show the count per site, the hosts that hold each role, and how a failed controller is replaced.

Can trust agents replace trust controllers in a site?

Treat agents and controllers as separate roles and confirm in the trust documentation which Kerberos and trust operations an agent-only site can perform for your Windows and Linux users. Agents may be suitable for some sites, but the answer depends on the Kerberos behavior you need and the FreeIPA version you run. Ask for a written list of each operation your users depend on, and a test showing which hosts handle it. Do not accept a design that removes controllers from a site until that list has been checked against your version.

What drives the effort for a trust layout?

Effort rises with the number of pieces that must agree before any user can log in across the trust. The main drivers are:

The number of AD forests and domains in scope, and whether they use one-way or two-way trust.
The number of data centers and how many controllers and agents each one needs.
DNS separation: the FreeIPA trust page requires that the IPA DNS domain not overlap with any AD forest domain, so naming problems can force rework.
ID range design for AD users, which is hard to change once users exist.
Replication, backup and test coverage on both sides of the trust.

Each driver adds review and testing time, so ask which of these the quote covers.

How long does a trust project take, and what sets that time?

Duration depends on the layout, the number of sites, and how quickly approvals and changes move on the AD and network sides, so no fixed duration applies to every environment. Most of the time is usually spent on decisions and coordination rather than on installation. The biggest timing factors are the number of data centers, DNS fixes, change windows, and the test cycles that prove each side works. Ask for a timeline tied to written milestones, with each dependency on your teams named. Because most engagements are fixed-scope, the timeline should be agreed in writing before work starts.

What does a trust project need from our AD and network teams?

The AD team must confirm forest and domain details, DNS forward zones for the AD domain, and the trust setup steps they will own, so FreeIPA administrators do not need domain admin credentials. The network team must confirm that the firewall paths between IdM servers, agents and AD domain controllers are open for the chosen design. Both teams should agree on change windows, backup points and a rollback plan. A FreeIPA backup restored into an active replica topology can break replication, so backups must be taken and labeled before any change, according to the FreeIPA backup documentation. Ask the quote to name each request and its owner.

Can our own staff set up and run the trust layout?

Your staff can run it if they already know FreeIPA replication, Kerberos, DNS and the AD side of the trust, and if someone owns the runbooks and tests. The practical gap is usually not installation but knowing which change is safe in a live topology. Ask yourself who will handle controller failure, certificate renewal on the first server, and backup restores. A partner can design and build the layout, hand over documentation, and train your team, while your team keeps ownership of daily operations. Put the handover items into the written scope so they can be checked at closeout.

What should a fixed-scope quote for a trust layout list?

A useful quote lists the work in terms you can check against the final design. Ask for:

The AD forests and domains in scope, and the trust direction for each.
Every data center, with the controllers and agents planned for it and the hosts that hold them.
DNS changes on both sides, including the naming rules applied.
ID range and mapping decisions, and who signs them off.
The test plan for both sides, with acceptance criteria written down.
Backup and rollback steps before each change.
Handover documents, training and what your teams must provide.
Exclusions, such as work on AD domain controllers or client enrollment.

DeployOpen agrees scope, deliverables and timelines in writing before work starts, so compare quotes on this list rather than on the total alone.

How DeployOpen scopes and delivers trust layout work for FreeIPA

DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including FreeIPA. For trust controllers and trust agents, we start from your data center map, your AD forest layout and your replication topology, then agree the placement in writing before any server is changed.

How we scope

Inventory of data centers, AD domains, existing FreeIPA replicas and the Linux hosts that need AD user access
Written decision record for controller and agent counts per data center, agreed before installation starts
Fixed-scope deliverables and timelines confirmed in writing, with the trust-related components listed explicitly

How we build

Install and configure trust controllers and agents on dedicated servers in your environment, with the required packages verified per host
Test Kerberos ticket handling and agent reachability from each site, including failure of a single controller
Validate DNS and SRV resolution from both the FreeIPA and AD sides before any trust-dependent access is enabled

How we hand over

Topology diagram showing each controller, agent, replica and its data center, kept current with your change process
Runbook covering package versions, placement rules, replication agreement limits and failover steps for your team
Walkthrough with your identity, network and Windows teams so each role has a named owner after handover

How we support

Ongoing support, upgrades and continuous testing are available as a retainer, scoped to your FreeIPA and trust layout
Review of placement when you add a data center, a domain controller or a new Linux host group
Re-test of trust paths after FreeIPA security releases and before upgrading servers in the topology