freeipa/doc/designs/adtrust/oneway-trust-with-shared-secret.md

# One-way trust with shared secret

## Overview

FreeIPA does support trust to an Active Directory forest. The trust can be
established using administrative credentials from the forest root domain or
using a so-called shared secret. In the latter case no administrative access is
given to the remote side of the trust and each administrator performs their
configuration separately: FreeIPA administrator configures IPA side, Active
Directory administrator adds IPA forest as a trusted one on the Active
Directory side.

For trust to be active, one needs to validate it. Validation process includes a
sequences of DCE RPC calls that force a domain controller on the trusted side
to establish a so-called "secure channel" to a remote domain controller in the
trusting domain. This is an administrative operation and requires
administrative privileges to activate. If trust was established using a shared
secret, IPA side will lack ability to initiate a validation process.

At the same time, FreeIPA 4.6 or earlier versions do not include functionality
to allow a remote validation from Active Directory to happen before trust
objects are created and SSSD can retrieve information from the Active Directory
side. Unfortunately, the latter is not possible until trust is validated.

The purpose of this design is to extend FreeIPA setup to allow trust validation
to be initiated from Windows UI in case a shared secret is used to create a
trust agreement.

## Use Cases

As a FreeIPA administrator, I'd like to establish a trust between an Active
Directory forest and a FreeIPA deployment using a shared secret. As FreeIPA
administrator, I have no administrative access to Active Directory and would
like to delegate the operation to create trust on Active Directory side to my
counterpart in Active Directory forest.


## How to Use


1. Establish a one-way trust with a shared secret on IPA side:
   `ipa trust-add <ad-domain> --shared-secret`

2. On Windows side, open Active Directory Domain and Trusts tool
   * Open properties for the Windows forest
   * Choose 'Trusts' tab and press 'New trust' button there
   * Navigate through the trust wizard by entering:
      *  IPA forest name, then 'next'
      *  Choose 'Forest trust' on the Trust Type page
      *  Choose 'One-way: incoming' on the Direction of Trust page
      *  Choose 'This domain only' on the Sides of Trust page
      *  Enter the same shared secret one was using in step (1) with 'ipa trust-add'
   *  Complete trust wizard

3. Going back to the trust properties, one can now validate the trust from Windows side.

One limitation is that it is not possible to retrieve forest trust information
about IPA realm by Active Directory domain controllers due to the fact that
Samba configuration used by IPA does not support a remote query for this
information. It is only available when Samba is used in Samba AD configuration.

TODO: check whether it is possible to force to set forest trust information
from IPA side after both sides of trust are were configured.

## Design

There are two important parts of the solution. On IPA side, there is a module
to allow Samba to look up trusted domains and user/group information in IPA
LDAP. On the other side, there is support for POSIX identities of trusted
domain objects in SSSD.

### FreeIPA module for Samba passdb interface

FreeIPA provides a special module for Samba, `ipasam`, that looks up
information about trusted domains and user/group in FreeIPA LDAP. The module
also maintains trust-related information when trust is created via  DCE RPC
interfaces.

When trust is created, `ipasam` module needs to create a set of Kerberos
principals to allow Kerberos KDC to issue cross-realm ticket granting tickets.
These principals will have the same keys as trusted domain objects on Active
Directory level.

When a secure channel is established between two domain controllers from
separate trusted domains, both DCs rely on the trusted domain object account
credentials to be the same on both sides. However, since Samba has to perform
SMB to POSIX translation when running in POSIX environment, it also needs to
have a POSIX identity associated with the trusted domain object account.

As result, `ipasam` module needs to maintain POSIX attributes for the trusted
domain object account, along with Kerberos principals associated with the
trust.

### SSSD

When Windows successfully authenticates to Samba, Samba needs a POSIX identity
to run `smbd` processes as the authenticated 'user'. `smbd` and `winbindd`
processes use standard system calls to resolve authenticated user to a system
one (`getpwnam_r()`) and if the call fails, whole Windows request is rejected.

Given that trusted domain object accounts are associated with the cross-realm
Kerberos principals, they are located in a special subtree in FreeIPA LDAP:
`cn=trusts,$SUFFIX`. However, SSSD does not look by default in this subtree for
users. By default, SSSD configuration for user accounts looks in
`cn=users,cn=accounts,$SUFFIX` for `id_provider = ipa` and will not be able to
see trusted domain object accounts.

Thus, to allow Windows to successfully validate a one-way shared incoming trust
to FreeIPA, SSSD needs to resolve trusted domain object accounts as POSIX users
on IPA master side.


## Implementation

### FreeIPA `ipasam` module

`ipasam` module needs to create and maintain POSIX identities of the trusted
domain object accounts.

Following objects and their aliases are created and maintained by `ipasam`
module. In the description below `REMOTE` means Kerberos realm of the Active
Directory forest's root domain (e.g. `AD.EXAMPLE.COM`), `REMOTE-FLAT` is
NetBIOS name of the Active Directory forest's root domain (e.g. `AD`).
Correspondingly, `LOCAL` means FreeIPA Kerberos realm (e.g. `IPA.EXAMPLE.COM`)
and `LOCAL-FLAT` is the NetBIOS name of the FreeIPA primary domain (e.g.
`IPA`).

  Principal | Description
  --------- | -----------
  krbtgt/REMOTE@LOCAL | Cross-realm principal representing Active Directory forest root domain
  REMOTE-FLAT$@LOCAL | Trusted domain object account for the Active Directory forest root domain
  krbtgt/REMOTE-FLAT@LOCAL | Alias to REMOTE-FLAT$ TDO
  krbtgt/LOCAL@REMOTE | Cross-realm principal representing IPA domain in Active Directory forest to allow crross-realm TGT issuance from IPA KDC side
  krbtgt/LOCAL-FLAT@REMOTE | Trusted domain object account for IPA domain in Active Directory forest
  LOCAL-FLAT$@REMOTE | Alias to krbtgt/LOCAL-FLAT@REMOTE

For inbound trust `ipasam` module creates following principals:
  * `krbtgt/LOCAL@REMOTE`, enabled by default
  * `krbtgt/LOCAL-FLAT@REMOTE`, used by SSSD to talk to Active Directory domain
    controllers, with canonical name set to `krbtgt/LOCAL-FLAT@REMOTE` because
    Kerberos KDC must use this salt when issuing tickets for this principal. The
    use of this principal is disabled on IPA side (IPA KDC does not issue tickets
    in this name) --- we only retrieve a keytab for the principal in SSSD. SSSD
    retrieves a keytab for this principal using `LOCAL-FLAT$@REMOTE` Principal
    name.

For outbound trust `ipasam` module creates following principals:
  * `krbtgt/REMOTE@LOCAL`, enabled by default.
  * `REMOTE-FLAT$@LOCAL`, enabled by default. Used by a remote AD DC to
    authenticate against Samba on IPA master. This principal will have POSIX
    identity associated.


### SSSD

In IPA master mode, SSSD needs to start look into `cn=trusts,$SUFFIX` subtree
in addition to `cn=users,cn=accounts,$SUFFIX` subtree to find trusted domain
object accounts. This can be achieved either by explicitly adding a second
search base to `ldap_search_user_base` option in the `[domain/...]` section or
by automatically expanding a list of search bases when running in the IPA
master mode. The latter is already implemented in SSSD 1.16.3 and 2.1.0 with
https://pagure.io/SSSD/sssd/c/14faec9cd9437ef116ae054412d25ec2e820e409


Feature Management
------------------

We already allow to create a shared secret-based trust to Active Directory. No
functional change is needed in either Web UI or CLI.

Upgrade
-------

During upgrade POSIX identities need to be created for existing trust
agreements.