freeipa/doc/designs/adtrust/sidconfig.md

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-sidoption.

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
...