Integrate SID configuration into base IPA installers
****************************************************


Overview
========

FreeIPA is able to issue Kerberos tickets with PAC data when it is
configured for trust. The goal of this feature is to allow PAC
generation in the general use case, even without trust, as it is a
first step towards IPA-IPA trust.

Reference: https://pagure.io/freeipa/issue/8995

In order to generate PAC data for a kerberos principal, IPA needs to
assign a SID to the users and groups. IPA installers ("ipa-server-
install", "ipa-replica-install") must handle the configuration related
to SID:

* assign a NetBIOS name to the server

* assign a domain SID to the IPA domain

* configure the local id range with primary RID base and secondary RID
  base

* enable the sidgen plugin on 389ds server

The code handling these steps is already available in ipa-adtrust-
install and needs to be moved to the general installers.


Use Cases
=========


Fresh install
-------------

As administrator, I want to deploy an IPA topology that automatically
assigns SIDs to users and groups and issues kerberos tickets with PAC
data, without the need to configure IPA for trust.

If I later decide to configure IPA for trust, I can still run the
command "ipa-adtrust-install".


Existing installation, no trust
-------------------------------

As IPA administrator, I am managing an existing IPA installation
without any trust. I want to update IPA and have the choice of
enabling (or not) the generation of SIDs and PAC data.

If I choose to enable PAC data, I just need to run a command that
requires an admin kerberos ticket. The command handles the SID-related
configuration and prompts me whether I want to immediately generate
SIDs for existing users/groups or run that task later.


Existing installation, trust configured
---------------------------------------

In this topology with trust configured (the command "ipa-adtrust-
install" has been executed), IPA is already able to issue Kerberos
tickets with PAC data. Update does not modify the configuration.


Mixed topology
--------------

As IPA administrator, I am managing an existing server setup without
trust and without PAC data. I want to add a replica into my existing
topology and automatically enable PAC data generation, without the
need to configure IPA for trust.


How to Use
==========


Fresh installation
------------------

Run "ipa-server-install", with the ability to define:

* NetBIOS Name: if not specified, the default value is generated from
  the IPA domain name (transform the left-most label into uppercase,
  keep only ascii characters, digits and dashes).

* Primary RID base (default if not set: 1000)

* Secondary RID base (default if not set: 1000000)

On a replica: run "ipa-replica-install", with the ability to define
the same parameters as "ipa-server-install", plus the following
parameter:

* Run SIDgen task immediately: yes/no (default=no)

If conflicting values are specified in "ipa-replica-install", the
installer must warn that existing values will be overwritten (same
message as when "ipa-adtrust-install" is run multiple times with
conflicting values).


Upgrade
-------

* Run "dnf update *ipa-server". The upgrade doesn’t configure SID-
  related options and doesn’t enable PAC generation.

* Obtain a ticket for the admin (or any member of the admins group).

* Run the new command allowing to setup the SID-related configuration.

* Run the existing command to modify base RID and secondary base RID:

     ipa idrange-mod --rid-base INT --secondary-rid-base INT RANGENAME


Mixed topology
--------------

The existing server is not setup for PAC data generation. The future
replica is installed with the latest packages, containing the updated
installers.

Run "ipa-replica-install", with the ability to define:

* NetBIOS Name: if not specified, the default value is generated from
  the IPA domain name (transform the left-most label into uppercase,
  keep only ascii characters, digits and dashes).

* Primary RID base (default if not set: 1000)

* Secondary RID base (default if not set: 1000000)

* Run SIDgen task immediately: yes/no (default=no)


Design
======

Installers and SID-related options:

* the options "--add-sids", "--netbios-name", "--rid-base" and "--
  secondary-rid-base" are moved from ADTrustInstallInterface to a
  separate new InstallInterface: SIDInstallInterface.

* ADTrustInstallInterface now inherits from SIDInstallInterface.

* "adtrustinstance.ADTRUSTInstance.__init__" now accepts an additional
  parameter: "fulltrust". When set to True, the class ADTRUSTInstance
  configures the trust as usual. When set to False, only the SID-
  related part is executed.

* "ipa-server-install" and "ipa-replica-install" now always call
  "adtrust.install_check" and "adtrust.install", but the method is
  using the provided options (especially "options.setup_adtrust") to
  know if full configuration is required or only the SID-related part.

The "ipa-adtrust-install" code is already written in order to be
idempotent (can be called multiple times, even with different values),
and this property is of great value for this feature. It allows to
keep the changes as minimal as possible to the existing installers,
and call "ipa-adtrust-install" even if the SID-part is already setup.

New command to enable SID generation after an upgrade: as we don’t
want to automatically enable SID generation during an upgrade, a new
command is provided in order to manually enable the feature. The
command only requires an admin ticket (no need to be root) and relies
on the admin framework.

The command uses a mechanism similar to server_conncheck:

* the user must have Replication Administrators privilege

* the user launches an ipa command communicating with IPA framework

* the admin framework uses Dbus to get access a DBus interface that
  launches a command through oddjob, allowing the command to run as
  root. The oddjob command is a wrapper around
  "adtrustinstance.ADTRUSTInstance".


Implementation
==============

* Dependencies: no additional dependency on ipa-server package

* Backup and Restore: no new file to backup


Feature Management
==================


UI
--

No new UI for server/replica installation.

"IPA server / ID ranges" tab is already available and displays Primary
and Secondary RID base.

"IPA Server / Trusts / Global Trust Configuration" tab already
displays the NetBIOS Name and Security Identifier.

These values can also be added in the "IPA Server / Configuration"
tab.

The User View displays SMB attributes if they exist and could be
enhanced with a note if the user entry does not have any SID, pointing
the admin to a procedure in order to generate the missing SIDs.


CLI
---

+----------------------------------------------------+----------------------------------------------------+
| Command                                            | Options                                            |
|====================================================|====================================================|
| ipa-server-install                                 | [–netbios-name=NETBIOS_NAME] [–rid-base=RID_BASE]  |
|                                                    | [–secondary-rid- base=SECONDARY_RID_BASE]          |
+----------------------------------------------------+----------------------------------------------------+
| ipa-replica-install                                | [–netbios-name=NETBIOS_NAME] [–rid-base=RID_BASE]  |
|                                                    | [–secondary-rid- base=SECONDARY_RID_BASE] [–add-   |
|                                                    | sids]                                              |
+----------------------------------------------------+----------------------------------------------------+
| ipa config-mod                                     | –enable-sid [–add-sids] [–netbios-                 |
|                                                    | name=NETBIOS_NAME]                                 |
+----------------------------------------------------+----------------------------------------------------+


"ipa config-mod --enable-sid" details:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The "--enable-sid" option turns the feature on, and "--add-sids"
triggers the SIDgen task in order to immediately generate SID for
existing users or groups.

"--add-sids" requires the "--enable-sid"option.

The "--netbios-name" option specifies the NetBIOS Name and is
optional. If not provided, the NetBIOS Name is generated from the
leading part of the DNS name.

"--netbios-name" requires the "--enable-sid" option.


Configuration
-------------

When the feature is turned on, it is possible to modify the primary
and secondary RID bases for the local id range with the existing "ipa
idrange-mod" command.

The NetBIOS Name can be overwritten (with warning) when "ipa-adtrust-
install" is run.


Upgrade
=======

The upgrade does not turn on the feature. If the admin wants to enable
SID generation, he needs to update the packages and run the new
command "ipa config-mod --enable-sid".


Test plan
=========

Note: PRCI currently doesn’t have the ability to test upgrade.

Scenarios to be tested: fresh install, test PAC generation

* Add active user testuser (reinitialize password)

* On IPA server run "kinit -k" to get a ticket for "host/fqdn@REALM"

* On IPA server run "/usr/libexec/ipa/ipa-print-pac ticket testuser"
  and ensure that PAC data is properly displayed.

* Same test on IPA replica

Tests outside of PRCI:

* Existing topology without trust, update one server, ensure SID
  generation hasn’t been automatically enabled

* Existing topology without trust, update one server, manually enable
  SID generation with the new command

* Existing topology without trust, insert a new replica, ensure SID
  generation has been automatically enabled

* Existing topology with trust, update one server, ensure SID
  generation is still working

* Existing topology with trust, insert a new replica, ensure SID
  generation is still working

* Ensure that "ipa-adtrust-install" is still working with the previous
  scenarios.


Troubleshooting and debugging
=============================

When the feature is turned on (whatever the path, either through fresh
server installation, fresh replica installation, or with the new
command), the following LDAP entries are expected:

* "cn=ad,cn=trusts,dc=ipa,dc=test" which is a simple "nsContainer"

* "cn=ad,cn=etc,dc=ipa,dc=test" which is a simple "nsContainer"

* "cn=ipa.test,cn=ad,cn=etc,dc=ipa,dc=test": must define the NetBIOS
  Name in "ipaNTFlatName", the SID in "ipaNTSecurityIdentifier" and
  the default SMB group in "ipaNTFallbackPrimaryGroup"

* "cn=Default SMB Group,cn=groups,cn=accounts,dc=ipa,dc=test": must
  define a SID belonging to the IPA domain SID in
  "ipaNTSecurityIdentifier"

(replace ipa.test with the actual domain name and dc=ipa,dc=test with
the actual base DN).

The admin user must have a SID ending with -500 (well-known SID for
the domain administrator):

   # ipa user-show admin --all | grep ipantsecurityidentifier
     ipantsecurityidentifier: S-1-5-21-2633809701-976279387-419745629-500

The admins group must have a SID ending with -512 (well-known SID for
domain administrators group):

   # ipa group-show admins --all | grep ipantsecurityidentifier
     ipantsecurityidentifier: S-1-5-21-2633809701-976279387-419745629-512

The sidgen plugin must be enabled in /etc/dirsrv/slapd-IPA-
TEST/dse.ldif:

   dn: cn=IPA SIDGEN,cn=plugins,cn=config
   cn: IPA SIDGEN
   nsslapd-basedn: dc=ipa,dc=test
   nsslapd-plugin-depends-on-type: database
   nsslapd-pluginDescription: Add a SID to newly added or modified objects with u
    id pr gid numbers
   nsslapd-pluginEnabled: on
   nsslapd-pluginId: IPA SIDGEN postop plugin
   nsslapd-pluginInitfunc: ipa_sidgen_init
   nsslapd-pluginPath: libipa_sidgen
   nsslapd-pluginType: postoperation
   nsslapd-pluginVendor: FreeIPA project
   nsslapd-pluginVersion: FreeIPA/1.0
   objectClass: top
   objectClass: nsSlapdPlugin
   objectClass: extensibleObject

If the PAC data is not generated for a user, ensure that the user
contains a SID in its "ipantsecurityidentifier" attribute. If the SID
is missing, run the SIDgen task in order to generate SID for existing
users and groups:

* Find ipa base DN with: "grep basedn /etc/ipa/default.conf | cut -d=
  -f2-"

* Copy "/usr/share/ipa/ipa-sidgen-task-run.ldif" to "/tmp/ipa-sidgen-
  task-run.ldif"

* Edit the copy "/tmp/ipa-sidgen-task-run.ldif" and replace $SUFFIX
  with IPA base DN

* As root, launch the task (replace IPA-TEST with the proper value):
  "ldapmodify -H ldapi://%2Frun%2Fslapd-IPA-TEST.socket -f /tmp/ipa-
  sidgen-task-run.ldif"

In order to check if the PAC data gets added to the user ticket, on a
server:

   # kinit -k
   # /usr/libexec/ipa/ipa-print-pac ticket USERNAME

If the PAC data is properly added, the "ipa-print-pac" command
displays:

   # /usr/libexec/ipa/ipa-print-pac ticket testuser
   Password:
   Acquired credentials for testuser
   PAC_DATA: struct PAC_DATA
       num_buffers              : 0x00000005 (5)
       version                  : 0x00000000 (0)
       buffers: ARRAY(5)
           buffers: struct PAC_BUFFER
   ...
