FreeIPA trust with a shared secret: AD setup

How a FreeIPA trust with a shared secret keeps AD admin credentials out of FreeIPA

The Linux identity team needs AD users to reach FreeIPA resources, but the AD team will not hand out domain admin credentials. A shared-secret trust addresses that constraint: the trust is created from the FreeIPA side with a shared secret, and the AD side carries out its own half under the control of its own administrators. According to the FreeIPA Trusts page, FreeIPA establishes a cross-forest trust with Active Directory through Samba components, and the IPA domain must use a DNS domain that does not overlap with any domain in the AD forest. That non-overlap rule is the first decision to settle, because a clash found after the trust is built is expensive to undo. Confirm the IPA domain name and the AD forest's domain list with the AD team before anyone runs a command.

A one-way trust fits when AD users need to reach FreeIPA resources but FreeIPA users do not need to authenticate against AD. In that case, the FreeIPA side trusts AD identities, and the AD side does not need to trust FreeIPA. Be clear with both teams about which direction is required, since the answer changes what each side configures and what Kerberos features can be used. The trade-offs of direction, including effects on Kerberos FAST and two-factor authentication, are covered in the sibling topic on trust direction, so settle that question first.

The exact commands, options and any prerequisite packages depend on the FreeIPA release, the RHEL or other platform version and the Samba components in use. Do not copy steps from older guides or forum posts. Check the current FreeIPA Trusts documentation and your platform's own documentation for the versions you run, and record which steps each team owns, who holds the shared secret, and how it is stored and rotated. Plan a validation pass from both sides before declaring the trust complete, and treat any step you cannot confirm against current documentation as an open item for the change review.

Trust options and when each fits

This table compares a two-way trust, a one-way trust created with an AD admin credential, and a one-way trust set up with a shared secret. Read each row as a question to settle with your AD team before setup starts. For the direction decision in depth, see the sibling page on one-way versus two-way trusts. The main takeaway: the shared secret option keeps AD admin credentials away from FreeIPA staff, but it still requires close coordination with the AD team.

Criterion	Two-way trust	One-way with admin credential	One-way with shared secret
Who must hold AD admin rights	AD team creates the trust with domain-level rights on both sides	AD domain admin credentials are given to the FreeIPA admin for setup	AD team creates the trust and issues the secret; no AD admin credentials go to FreeIPA staff
FreeIPA admin rights needed	Full FreeIPA admin rights on the IPA domain	Full FreeIPA admin rights on the IPA domain	Full FreeIPA admin rights, plus the secret received from the AD team
Direction users can reach	AD users reach IPA resources and IPA users reach AD resources	Set at creation; usually AD users reach IPA hosts and IPA users do not reach AD	Same as one-way; agree the direction with the AD team before the secret is issued
Kerberos FAST or two-factor needs	Can satisfy these needs; confirm the requirement on the trust direction page	May force a switch to two-way; confirm before choosing	Same limits as one-way; confirm before choosing
Credential exposure on the AD side	AD admin rights and trust secret both in use during setup	Highest: AD domain admin password is shared with FreeIPA staff	Limited to the trust secret, handled under your secret policy
Coordination with the AD team	High: joint change window and AD sign-off	Medium: one AD admin session with a credential handover	Medium: agree direction, secret handling and validation window in writing
Change effort later	Direction change or rebuild usually means reworking the trust with the AD team	Each change repeats the admin credential handover	Changes need a new secret from the AD team; confirm the procedure before go-live

What the AD team and the FreeIPA team each configure

The AD team owns the Active Directory half of the trust. Before any trust object is created, they confirm that AD DNS can resolve the IPA domain's records as described in the DNS setup page, and that the forward zones and SRV records they control are in place. They then create a one-way trust from AD toward the IPA domain, which generates a shared secret that will be used on the FreeIPA side.

DNS prerequisites: Forward zones and SRV records for the IPA domain exist in AD DNS and resolve from the IPA servers. Confirm the design on the DNS setup for a FreeIPA and AD trust page first.
Trust object and secret: Create the one-way trust in AD and generate the trust password. Record the trust name exactly as it will be entered on the FreeIPA side.
Scope of the change: The change is limited to one trust object and its DNS records. Nothing on domain controllers, GPOs, user accounts or group memberships changes.
Secure handover: Send the secret through an approved channel with a named recipient, and record when it was sent.
Never hand over: Domain administrator credentials, service account passwords, or access to domain controllers. The secret is the only credential the FreeIPA team needs.

Before closing the change, the AD team should confirm the trust state from their side and keep the ticket open until the FreeIPA team reports a successful validation.

The FreeIPA team owns the IPA half of the trust. They register the AD domain on the IPA servers using the shared secret, with no AD administrator password involved. The ID range that maps AD users to UIDs and GIDs must be chosen before this step, because the choice is difficult to change later, so the team should review the ID range page first.

Trust command with the secret: Run ipa trust-add with --type=ad and the AD domain name, and supply the secret when prompted. Confirm the exact flags against the FreeIPA version on your servers.
ID range: Decide the mapping method (SID-based or POSIX-based) and create the range on the ID range for AD users page's terms, then confirm it with ipa idrange-find.
Domain naming check: The IPA domain must use a DNS domain that does not overlap any AD forest domain, as described on the Trusts page.
Validation steps: Run ipa trust-fetch-domains to confirm the AD domains are visible, then resolve a test AD user with id on an enrolled host.
Records: Save the command output, the trust name and the range details in the change record for the AD team and the auditors.

The FreeIPA team should report the validation results to the AD team in writing, including any failed lookups, before the change is marked complete.

Step-by-step setup sequence with checks after each stage

This sequence takes a FreeIPA and Active Directory trust from separated DNS and agreed names to a working one-way trust that both teams have validated. Each stage ends with a check, so a failure is found before the next stage depends on it.

Confirm DNS separation and forward zones
Before any trust work, confirm that the IPA domain uses a DNS domain that does not overlap with any domain in the AD forest, as the FreeIPA Trusts page requires. The AD team and the FreeIPA team each confirm the forward zones needed to resolve the other side's domain controllers and SRV records. Check by resolving the AD domain controller SRV records from an IPA server and resolving the IPA domain's records from a Windows client. The step is done when both lookups return the expected addresses from every server involved.
Agree realm and NetBIOS naming
Both teams agree on the Kerberos realm name for the IPA side, the NetBIOS name of the AD domain and the NetBIOS name the trust will use, and record them in a shared change document. Naming mistakes are hard to fix after the trust exists, so the record should be signed off by both the FreeIPA and AD owners. The output is a written naming decision that every later command will reference. Confirm the spelling of each name against the Trusts page for the installed FreeIPA version before any command runs.
Prepare the AD side and generate the secret
An AD administrator prepares the AD domain for the trust and generates the shared secret on the AD side, without sharing domain admin credentials with the FreeIPA team. The FreeIPA team does not need AD domain admin rights at any point in this sequence. Ask the AD team to confirm, in writing, which account and which tool they used and that the secret was stored only where the procedure directs. Exact command syntax and options must come from the Trusts page for the installed version, not from memory or from this page.
Transfer the secret through an approved channel
Move the shared secret from the AD team to the FreeIPA administrator through a channel your security policy approves, such as an encrypted vault or a supervised handover, and avoid email, chat and ticket comments. Record who sent it, who received it and when, and remove any copies after the trust is created. The check is that the FreeIPA administrator can confirm receipt without the secret appearing in logs or shared documents. Your security team should review the transfer record before the next stage.
Create the IPA-side trust
The FreeIPA administrator creates the one-way trust on the IPA side using the shared secret and the agreed names, following the Trusts page for the installed FreeIPA version. Only the IPA side is configured here, so the AD side does not need to be changed again. Check that the trust command completes without errors and that the trust object appears in the IPA trust listing with the expected name and direction. Keep the command output with the change record, after removing any secret values from it.
Confirm the ID range
Confirm the ID range that FreeIPA assigns to AD users, including whether the range is built from SIDs or from AD POSIX attributes, since that choice is hard to change later. Verify that the range does not overlap any existing POSIX range in FreeIPA and that the chosen mapping matches the decision recorded earlier. The check is a trust-related ID lookup for a known AD user, which should return a UID and GID inside the expected range. If the range is wrong, stop here and resolve it before validation.
Validate from IPA and from an AD test user
The FreeIPA team checks the trust status and resolves a known AD user and group from an IPA server, then the AD team provides a dedicated test account for a login test on an enrolled Linux host. Run the login and a basic group lookup, and confirm that access matches the one-way direction of the trust. Record the output of each check, including the trust status, the resolved identity and the login result. The sequence is complete when both sides agree in writing that every check passed and that the test account behaves as the design expects.

Coordinating the AD team and the FreeIPA team on one change

Run the trust as one joint change with a single written scope that lists each party's actions in order. The AD team creates its half of the trust using the shared secret, and the FreeIPA team creates the matching half with ipa trust-add. Name one owner for the secret before anyone generates it. That owner decides where the secret is stored, who may read it, and when it is destroyed after both sides confirm the trust works. Keep the secret out of chat threads and tickets, and agree the change window with AD operations, because changes to domain controllers and AD replication are usually governed by their own approval process. Confirm the exact trust steps against the FreeIPA Trusts page and your AD team's change procedure before the scope is signed.

The AD team needs a precise list of what changes on their side: the trust object in the AD domain, its name and direction, the DNS records that let each side locate the other, and any service or administrative accounts used during setup. They should also see which AD groups FreeIPA will reference later, since those references are added in a separate step. The rollback plan must protect existing FreeIPA logins. Document that the trust addition does not change local IdM accounts, passwords or host enrollments, and state how to remove the trust object on both sides if validation fails. Ask the AD team to confirm that removal is supported in their environment, and record who has authority to trigger it during the change window.

FreeIPA admins must prove the topology is healthy before go-live. Confirm replication is clean across every replica, and take a full ipa-backup immediately before the change. Do not restore an older backup into an active replica topology, because the backup documentation warns that this can break replication. The shared test list should be agreed by both teams and run from both sides: DNS resolution of AD domain controllers from FreeIPA clients and of IdM servers from AD, a Kerberos ticket for a test AD user, an SSH login and a sudo check on a test host, and a login for an existing IdM user to confirm nothing regressed. Record the results in the change ticket and have both owners sign off before the secret is retired.

Protecting the shared secret and the trust boundary

The trust secret is the single credential that lets the two sides talk, so its handling, its rotation and the logs around it decide how well the trust holds up after a mistake. The cards below cover the secret itself, the boundary it creates, and the backup and replica state that can quietly change the trust.

Generating, transferring and storing the secret

The shared secret should be generated on the FreeIPA side during trust setup and handed to the AD team through a channel both teams have agreed on, not pasted into chat or email. Confirm who holds a copy, where it is stored while the trust is being configured, and that it is removed from scratch files and shell history afterward. Ask the AD team to document who could read the value in their own systems.

Limiting who can read the secret

Treat the trust secret as a privileged credential. Restrict read access on the FreeIPA servers to the administrators who run trust tasks, and confirm that replicas and backups inherit the same restriction. Ask the AD team to limit who can view or export the trust account on their domain controllers. A shared admin account used for trust work makes it hard to tell later who touched the secret.

Rotating the secret or resetting the trust

Agree in advance on what happens if the secret is suspected to be exposed: which side generates a replacement, how the trust is re-established, and how users are told to re-authenticate. Rotation touches both the FreeIPA and AD sides, so run it as one planned change with both teams present. Keep the runbook alongside the trust configuration so the steps are known before an incident.

Logging trust changes on the AD side

Ask the AD team to keep audit records for trust object creation, modification and deletion, and for any changes to the trust account, along with the time, the actor and the change ticket. Keep the FreeIPA side logs for the same window so both records can be matched. Confirm retention periods with your security team before setup, since trust events are often the first evidence in a review.

Defining the trust boundary

A one-way trust lets AD users authenticate to FreeIPA resources, but it does not give FreeIPA administrators rights in AD. Document which FreeIPA hosts, sudo rules and HBAC rules AD users can reach, and which ID ranges they receive, so the boundary is visible to both teams. Review the boundary after any rule change, since access granted through a group can reach further than intended.

Backups and replicas affect trust state

Trust state lives in FreeIPA's directory, so restoring an old backup or promoting a stale replica can bring back a trust configuration that no longer matches AD. The backup documentation warns that restoring an outdated backup into an active replica topology can break replication. Before any restore, confirm the trust state with the AD team, follow the restore cautions on the Backup and restore page, and test the procedure in a non-production environment.

What buyers ask before setting up a FreeIPA trust

Can our own team set up a FreeIPA trust with Active Directory without a partner?

Yes, a team with Linux, Kerberos, DNS and Active Directory skills can build a trust in-house, and the FreeIPA Trusts documentation describes the cross-forest trust that Samba components make possible. The harder question is whether those skills are present on both sides at the same time. The FreeIPA side needs people who can run the IdM servers and ID ranges, and the AD side needs people who can create the trust object and review it. Most teams that do this alone underestimate DNS preparation and validation. A partner is useful when the team lacks one of these skill sets or needs the work finished inside a fixed scope with written deliverables.

What makes a FreeIPA and AD trust take more or less effort?

The main drivers are the size and layout of the AD forest, the state of DNS, the ID range decision and the number of FreeIPA servers and trust agents. A single forest with clean DNS and one domain is far simpler than several domains with overlapping namespaces. The FreeIPA Trusts page requires that the IPA DNS domain must not overlap with any domain in the AD forest, so DNS renaming can add work before the trust starts. The ID range choice affects how UIDs and GIDs are assigned and is hard to change later. Each additional IdM server or trust agent adds configuration and testing across more hosts.

What does the Active Directory team need to provide?

The AD team controls the step that creates the trust on the Windows side, so they must agree to the trust direction, the trust type and the account that will perform the action. They also need to confirm forest and domain functional levels, domain controller versions and the DNS zones that must resolve the FreeIPA domain. They should review the trust settings and the accounts that AD users will use for Linux access. The shared-secret approach means FreeIPA administrators never receive domain admin credentials, so the AD team keeps control of the privileged step. Agree on a named contact, a change window and a rollback plan before work starts.

How long does a FreeIPA trust take to set up?

The duration depends on the confirmed scope, so no fixed number applies before the environment is reviewed. Timing is driven by how quickly DNS can be corrected, how many FreeIPA servers and trust agents must be configured, how many AD domains are involved and how long the AD team needs for its review and change approval. Ask the partner or your team to list each phase separately, including preparation, the FreeIPA half, the AD half, validation and handover. A written schedule tied to confirmed scope is more useful than a general estimate.

What should a fixed-scope quote for a FreeIPA trust state?

A fixed-scope quote should name the forest and domains in scope, the trust direction and type, the number of FreeIPA servers and trust agents to be configured, and the ID range approach. It should list the DNS changes the work includes and which of them the client must make. It should state the validation tests on both sides, the documents produced and the handover items. It should also say what is excluded, such as WinSync migration, ID views, sudo or HBAC rules for AD users, and Windows workstation work. Ask for the assumptions behind each line so that changes in scope can be priced openly.

What ongoing work follows a FreeIPA trust after go-live?

After go-live, the trust needs monitoring, periodic checks of DNS and ID ranges, and attention to FreeIPA and Windows updates that could affect the trust. Operations teams must also review access policy for AD users, including external groups, HBAC rules and sudo rules, as the organization changes. Changes to AD domains, domain controllers or functional levels should trigger a validation pass. Ongoing support can be handled by your own team or under a retainer, which DeployOpen offers for support, upgrades and continuous testing. Ask any provider to define which checks recur and who owns each one.

How do we check that the trust works before users depend on it?

Validation should run from both sides, with test accounts from AD and from IdM logging in to the Linux hosts in scope. Engineers should confirm that DNS resolves the AD domain and the IPA domain correctly from each server and client, that the trust reports as established on both sides, and that the expected ID mapping appears for AD users. They should also test Kerberos authentication, group membership and any sudo or SSH policy in place. Record the results and the commands used, so the AD team can repeat the checks after changes.

Limits and what to confirm in your environment

A FreeIPA trust touches DNS, Kerberos, authentication policy and the AD team's change controls at once. Confirm these six points before you agree on a design, because each one can rule out a trust direction or force extra components.

Windows Server and functional levels

Confirm that the AD forest and domain functional levels, and the domain controller versions, are supported by the FreeIPA and RHEL releases you plan to run. Support depends on the combination, so check it against the installed versions rather than the latest ones. The Windows Server versions sibling topic lists the combinations to verify with the AD team before the build starts.

DNS domain separation

The IPA DNS domain must not overlap with any domain in the AD forest. Ask the AD team for the full list of forest domains and the DNS zones they host, then compare them with your planned IPA domain. An overlap is a blocker, so resolve naming before any server is installed, and plan the forward zones described in the DNS sibling topic.

SMB encryption and Kerberos settings

Find out whether the AD estate requires SMB encryption, enforces specific Kerberos encryption types, or applies hardened Kerberos policy through group policy. These settings can affect how the trust authenticates and how file access behaves on Linux clients. Ask the AD team for the current policy, not the intended one, and record which settings they expect to remain unchanged.

Two-factor requirements and direction

Decide whether users who must present a second factor will authenticate through FreeIPA, through AD, or both. The trust direction determines which side can reach which resources and how Kerberos FAST behaves, so a one-way trust may not satisfy every two-factor requirement. Test the chosen direction against each user group that must sign in with OTP or a smart card before committing.

AD team policy on a shared secret

Confirm in writing that the AD team's security policy permits a trust established with a shared secret, and that they will run their half without handing domain admin credentials to the FreeIPA team. Ask who approves the change, who records the secret, how it is rotated and how a compromised trust is revoked. Many organizations route this through change control, so start that conversation early.

Trust controllers and agents

Determine whether your topology needs trust controllers or trust agents, how many each data center requires, and which packages each host needs. Placement affects the Kerberos limits on agents and the way AD users reach hosts in each site. The trust controllers and agents sibling topic covers the roles and counts to plan against before you size the servers.

How DeployOpen scopes and delivers a FreeIPA trust

DeployOpen approaches a shared-secret FreeIPA trust as two coordinated halves: the IdM side configured by the FreeIPA team and the AD side configured by the Windows team, with neither side needing the other's administrative credentials. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts.

How we scope

Confirm the AD forest, domain names and functional levels that the written scope will cover.
Agree which side configures which half, and who on the AD team signs off the trust object.
Record the DNS, realm and naming checks that must pass before any trust command runs.

How we build

Prepare the IdM side with the trust controller and ID range settings agreed in scope.
Coordinate the AD-side steps with your Windows team so domain admin credentials stay with them.
Test Kerberos resolution, user lookups and login from both directions before sign-off.

How we hand over

Deliver a runbook listing each command, the owner of each step and the expected output.
Document the shared secret handling, rotation steps and the validation checks used at sign-off.
Walk your FreeIPA and AD teams through the trust so they can run the checks without us.

How we support

Offer ongoing support for trust health checks and changes as a retainer, if your team wants it.
Review trust-related changes, such as new AD domains or ID range changes, against the documented design.
Keep the runbook and validation scripts current as your FreeIPA and AD environments are upgraded.

Setting up a FreeIPA trust with a shared secret