h1. Realm Join Integration

h2. Status

*This has been implemented and merged into Foreman 1.5 via #1809*

h2. Intro

This page covers ideas for joining hosts to FreeIPA realms or Active Directory domains when they're built, using a hypothetical foreman_realm plugin.

h2. DNS management

Related, but not actually realm joining.  Updates to DNS can be made via the normal smart proxy route, however for both FreeIPA and AD we require GSS-TSIG support for nsupdate.  This was completed for Foreman 1.2 via #1685.

h2. Realm configuration

foreman_realm should add a realm model and associate them with domains, plus everything needed to manage them.

* model: ForemanRealm::Realm

** associated with domain (one realm to many domains?)

** attribute: realm name

** attribute: proxy id

* controller and views: ForemanRealm::Realms

** index, update, edit, delete realms

* API controller: ForemanRealm::Api::V2::Realms

** index, update, delete realms

This would allow users to add/remove/edit realm information, have it associated with a remote smart proxy instance and associate with a domain (does this make sense?), which in turn is associated to a host.

A new orchestration hook (which runs when a host is created/destroyed) needs adding to call the proxy (via Foreman's proxy API) if the associated domain has a realm:

* app/models/foreman_realm/orchestration/realm.rb

** include this into Host::Managed

** calls proxy API to add/remove host from realm

** saves OTP into host.params (key/value attributes) for now, perhaps to a separate model later

The "kickstart templates":https://github.com/theforeman/community-templates would need updating to check for @@host.params["realm-otp"]@ or similar, then run the appropriate join command.

To support classes and hostgroups in IPA (see below), additional attributes could be added to Foreman's host groups (or whatever they get replaced with) to define the IPA classes that the host would have when created.

Guy Matz has implemented the orchestration and proxy API bit of this OK: https://github.com/guymatz/foreman/compare/develop...1809-add_IPA_support.  I'm not sure about the controllers and associating realms directly to hosts - needs some thought, perhaps associating with a domain isn't correct either.

h2. Host/computer creation

h3. Proxy support

The proxy should provide an API for creating hosts in realms (or computer objects in AD domains).  As an example:

* POST @/realm/:domain/:hostname@

** param: classes, array of clases to apply to host

* DELETE @/realm/:domain/:hostname@

(http://projects.theforeman.org/projects/smart-proxy/wiki/API)

It should advertise the "Realm" API feature.  Foreman core's proxy API and smart proxy model will need updating to understand this new feature.

Guy Matz has implemented much of this already, complete with vendor/provider support so IPA and other implementations can be swapped: https://github.com/guymatz/smart-proxy/compare/develop...1809-add_IPA_support

h4. FreeIPA

For FreeIPA, this can either call the @ipa host-add@ command or the XMLRPC API that backs it.  Here's an example of creating a user with minimal privileges that can create new hosts:

<pre>

# kinit admin

# ipa user-add --first=Host --last=Adder hadder

# ipa privilege-add "Add computers" --desc"Add computers"

# ipa privilege-add-permission "Add computers" --permissions="add hosts"

# ipa role-add "Host Adder" --desc="Can add new hosts"

# ipa role-add-privilege "Computer creator" --privilege="Add computers"

# ipa role-add-member "Computer creator" --user=hadder

# ipa-getkeytab -s `hostname` -p hadder@IDM.LAB.BOS.REDHAT.COM -k /root/hadder.keytab

# kinit -kt /root/hadder.keytab hadder@IDM.LAB.BOS.REDHAT.COM

# klist

Ticket cache: DIR::/run/user/0/krb5cc/tkt3GbmCZ

Default principal: hadder@IDM.LAB.BOS.REDHAT.COM    <<<<<

Valid starting       Expires              Service principal

06/14/2013 21:54:06  06/15/2013 21:54:06

krbtgt/IDM.LAB.BOS.REDHAT.COM@IDM.LAB.BOS.REDHAT.COM

</pre>

System user is now privileged to add hosts to IPA:

<pre>

# ipa host-add random.host.test --random --force

-----------------------------

Added host "random.host.test"

-----------------------------

  Host name: random.host.test

  Random password: K8-5rr0U8vL,

  Password: True

  Keytab: False

  Managed by: random.host.test

</pre>

He is unable to perform other administrative tasks as expected:

<pre>

# ipa host-mod random.host.test --desc=foo

ipa: ERROR: Insufficient access: Insufficient 'write' privilege to the

'description' attribute of entry

'fqdn=random.host.test,cn=computers,cn=accounts,dc=idm,dc=lab,dc=bos,dc=redhat,dc=com'.

</pre>

As a later step, classes can be assigned to hosts in IPA that associate it with hostgroups (not to be confused with Foreman host groups).

The attribute is called "userClass" in IPA LDAP, it is available by default with host entries under "--class" option. This is how it works:

1. We create a hostgroups to demonstrate how the automatic assignment of hosts to host groups works

<pre>

# ipa hostgroup-add webservers

Description: web servers

----------------------------

Added hostgroup "webservers"

----------------------------

  Host-group: webservers

  Description: web servers

</pre>

2. Create an automember rule for this hostgroup

<pre>

# ipa automember-add --type=hostgroup webservers

----------------------------------

Added automember rule "webservers"

----------------------------------

  Automember Rule: webservers

</pre>

3. The automember condition is hooked to the host's userclass attribute

<pre>

# ipa automember-add-condition --key=userclass --type=hostgroup

--inclusive-regex=^webserver webservers

----------------------------------

Added condition(s) to "webservers"

----------------------------------

  Automember Rule: webservers

  Inclusive Regex: userclass=^webserver

----------------------------

Number of conditions added 1

----------------------------

</pre>

Steps 1, 2 and 3 need to be done just once when the IPA is being configured.

4. Now this is the best part. When Foreman proxy adds a host, it can specify

the host class which will automatically triggers

<pre>

# ipa host-add web.example.com --force --class=webserver --class=mailserver

----------------------------

Added host "web.example.com"

----------------------------

  Host name: web.example.com

  Principal name: host/web.example.com@EXAMPLE.COM

  Class: webserver, mailserver                    <<<<<<<<<<

  Password: False

  Member of host-groups: webservers               <<<<<<<<<<

  Indirect Member of netgroup: webservers

  Keytab: False

  Managed by: web.example.com

</pre>

You can have more these rules in parallel.

h4. Active Directory

For AD, adcli can be used (available in F18+):

* http://fedoraproject.org/wiki/Features/ActiveDirectory

* https://fedoraproject.org/wiki/Features/AnacondaRealmIntegration (has an adcli example)

h3. Foreman support

foreman_realm should add an orchestration step to create and destroy the host object via the proxy.  The OTP used when creating should be stored.

h2. Joining hosts

foreman_realm could add a new %post snippet which uses the "realm" command (part of realmd) to join the host to the specified realm.

* http://www.freedesktop.org/software/realmd/docs/index.html (see joining sections)

For new anacondas, we could use this instead (maybe a second snippet):

* https://fedoraproject.org/wiki/Features/AnacondaRealmIntegration

For older (EL5/6/F18), it should also support the ipa* client tools as realm is only just getting FreeIPA support:

* http://fedoraproject.org/wiki/Features/RealmdFreeIpaSupport

Example: @ipa-client-install --password K8-5rr0U8vL,@