realmd is an on-demand system D-Bus service, whose primary purpose is to enable Linux to work seamlessly out of the box with network authentication realms (like Kerberos, with primary focus on AD and IPA). Specifically, the realmd service supports discovering a domain, joining a domain, leaving a domain, and more.

Currently there is only support for Kerberos realms.

Some of the D-Bus clients that interact with realmd are:

Realmd can be run in two different modes (with some slight changes in behavior depending on the mode)

Realmd is typically used (whether at install time or afterwards) by a D-Bus client to discover the KDC for a Kerberos domain and to join the machine to that domain using membership software. This will involve changes on the server made by server software, as well as artifacts (keytab, configuration file) that are output by realmd on the machine for consumption by client software that will subsequently be responsible for Kerberos authentication.

For active-directory server software, realmd supports:

For IPA server software, realmd supports:

A GDBusObject is associated with an object path and is essentially a container of GDBusInterfaces. On the service side, this is implemented using GDBusObjectSkeletons and GDBusInterfaceSkeletons (with corresponding GDBusObjectProxy and GDBusProxy components on the client side). The base GDBusObjectSkeletons used by realmd are RealmKerberos and RealmProvider (each with its own subclasses and interfaces). The objects are linked, in that a RealmProvider object creates a RealmKerberos object during the Discover process. The type of RealmKerberos object that is created depends on the type of RealmProvider that is used. Only those RealmKerberos objects that implement the RealmKerberosMembership GInterface can be used to join or leave a domain.

The main purpose of the Discover method is to verify that a specified domain is valid, emitting logs and diagnostic information in the process. RealmProviders discover the authoritative KDCs for the specified domain by querying DNS for SRV records and creating appropriate RealmKerberos objects to encapsulate the KDC information. Certain types of RealmKerberos objects (i.e. RealmSamba and RealmSssdAd) can subsequently be used as part of the Join process.

RealmAllProvider is special in that it serves all realm types. A client that wants to use all of the RealmProviders (Samba, Sssd, Kerberos) can contact each RealmProvider (at its unique object path). Alternatively and usually, the client simply contacts the RealmAllProvider, which is special in that it serves as an aggregation point and container for all of the other RealmProviders. When Discover is called on RealmAllProvider, it calls the Discover methods of each of the other RealmProviders, collects the results (array of RealmKerberos objects), and returns an aggregated result (array of object paths pointing to RealmKerberos objects) to the client. The AllProvider also connects to a notify signal, so that if any of its sub-providers change state, AllProvider can also update its state accordingly.

A RealmProvider object supports the Discover method, and is characterized by:

The primary goal of joining a machine to a domain is to enroll the machine with the domain's KDC, thereby enabling subsequent Kerberos user authentication. This results in the creation of a secret shared between the machine and KDC (i.e. a keytab), as well as changes to the appropriate configuration file on the machine. Conversely, the primary goal of leaving a domain is to unenroll the machine from the domain's KDC, removing the keytab and removing the changes that were previously made to the appropriate configuration file during enrollment. Both the join and leave operations require appropriate credentials, where each credential is represented by the credential owner and the credential type. Different RealmKerberos objects support different credentials, and different credentials may be supported for join and leave. Before performing the join, any required packages or files are installed.

Possible credential owners: admin, user, computer, none

Possible credential types: password, secret (otp), automatic (default/system creds)

A RealmKerberos object supports the Join, Leave, Deconfigure, and ChangeLoginPolicy methods. It is characterized by:

When realmd starts up (realm-daemon.c:main), it registers each of its RealmProviders (except RealmAllProvider) with its GDBusObjectManagerServer, which in turn exports (onto a specific object path) the GDBusInterfaces for each RealmProvider onto the GDBusConnection. As RealmKerberos objects are dynamically created, they are similarly registered with the Object Manager and exported.

Note that only GDBusInterfaces that are exported onto the GDBusConnection are capable of receiving method call messages from the client. When a message is received by the worker thread of the service's GDBusConnection, the message's {object_path, iface_name} are mapped to a GDBusInterfaceSkeleton, which emits a signal. The enclosing GDBusObjectSkeleton catches the signal and executes the callback registered for that signal (usually set in RealmProvider's constructed method).

Since RealmAllProvider is just an aggregation point, it is not managed by the GDBusObjectManagerServer,but it is directly exported onto the GDBusConnection using g_dbus_connection_register_object(). The ObjectManager and Service objects are also directly exported onto the GDBusConnection.

The following is a subset of objects and interfaces registered with the GDBusObjectManagerServer and/or exported onto the GDBusConnection.

GDBusConnection: stores {object_path, iface_name} => GDBusInterfaceSkeleton

GDBusObjectManagerServer: stores object_path => GDBusObjectSkeleton

realmd includes a rough example provider, which can be used as a mock provider for testing against. It is disabled by default. The example provider discovers realms that match *example.com.

Set the example setting to yes in the [providers] section of the settings to enable it.

[providers]
example = yes
# example = no

Some settings of the example provider.

[example]
# What domain to return for a default discovery
default = default.example.com
# How long to delay a successful discovery, in seconds
example-discovery-delay = 1.3
# How long to delay a unsuccessful disocvery
example-non-discovery-delay = 0.9

You can tweak various options per example realm.

[default.example.com]
# Mock administrator account required to join
example-administrator = Administrator
# Password for above mock admin account
example-password = bureaucracy
# How long to delay when joining this domain, in seconds.
example-join-delay = 2.5
# How long to delay when leaving
example-leave-delay = 1
# Whether to disallow leaving without a password
example-no-auto-leave = yes