org.freedesktop.realmd.KerberosMembership: realmd

org.freedesktop.realmd.KerberosMembership

Methods

Join  (IN  (ssv) credentials,
       IN  a{sv} options);
Leave (IN  (ssv) credentials,
       IN  a{sv} options);

Properties

SuggestedAdministrator     readable   s
SupportedJoinCredentials   readable   a(ss)
SupportedLeaveCredentials  readable   a(ss)

Description

An interface used to configure this machine by joining a realm.

It sets up a computer/host account in the realm for this machine and a keytab to track the credentials for that account.

The various properties are guaranteed to have been updated before the operation methods return, if they change state.

Method Details

The Join() method

Join (IN  (ssv) credentials,
      IN  a{sv} options);

Join this machine to the realm and enroll the machine.

If this method returns successfully, then the machine will be joined to the realm. It is not necessary to restart services or the machine afterward. Relevant properties on the realm will be updated before the method returns.

The credentials should be set according to one of the supported credentials returned by org.freedesktop.realmd.Kerberos:SupportedJoinCredentials. The first string in the tuple is the type, the second string is the owner, and the variant contains the credential contents See the discussion at org.freedesktop.realmd.Kerberos:SupportedJoinCredentials for more information.

options can contain, but is not limited to, the following values:

automatic-id-mapping: a boolean value whether to turn on automatic UID/GID mapping. If not specified the default will come from realmd.conf configuration.
operation: a string identifier chosen by the client, which can then later be passed to Cancel() in order to cancel the operation
computer-ou: a string containing an LDAP DN for an organizational unit where the computer account should be created
user-principal: a string containing an kerberos user principal name to be set on the computer account
membership-software: a string containing the membership software identifier that the returned realms should match.
manage-system: a boolean which controls whether this machine should be managed by the realm or domain or not. Defaults to true.

This method requires authorization for the PolicyKit action called org.freedesktop.realmd.configure-realm.

In addition to common DBus error results, this method may return:

org.freedesktop.realmd.Error.Failed: may be returned if the join failed for a generic reason.
org.freedesktop.realmd.Error.Cancelled: returned if the operation was cancelled.
org.freedesktop.realmd.Error.NotAuthorized: returned if the calling client is not permitted to perform a join operation.
org.freedesktop.realmd.Error.AuthenticationFailed: returned if the credentials passed did not authenticate against the realm correctly. It is appropriate to prompt the user again.
org.freedesktop.realmd.Error.AlreadyEnrolled: returned if already enrolled in this realm, or if already enrolled in another realm (if enrolling in multiple realms is not supported).
org.freedesktop.realmd.Error.BadHostname: returned if the machine has a hostname that is not usable for a join or is in conflict with those in the domain.
org.freedesktop.realmd.Error.Busy: returned if the service is currently performing another operation like join or leave.

IN (ssv) credentials:

IN a{sv} options:

The Leave() method

Leave (IN  (ssv) credentials,
       IN  a{sv} options);

Leave the realm and unenroll the machine.

If this method returns successfully, then the machine will have left the domain and been unenrolled. It is not necessary to restart services or the machine afterward. Relevant properties on the realm will be updated before the method returns.

options can contain, but is not limited to, the following values:

operation: a string identifier chosen by the client, which can then later be passed to Cancel() in order to cancel the operation

This method requires authorization for the PolicyKit action called org.freedesktop.realmd.deconfigure-realm.

In addition to common DBus error results, this method may return:

org.freedesktop.realmd.Error.Failed: may be returned if the unenroll failed for a generic reason.
org.freedesktop.realmd.Error.Cancelled: returned if the operation was cancelled.
org.freedesktop.realmd.Error.NotAuthorized: returned if the calling client is not permitted to perform an unenroll operation.
org.freedesktop.realmd.Error.AuthenticationFailed: returned if the credentials passed did not authenticate against the realm correctly. It is appropriate to prompt the user again.
org.freedesktop.realmd.Error.NotEnrolled: returned if not enrolled in this realm.
org.freedesktop.realmd.Error.Busy: returned if the service is currently performing another operation like join or leave.

IN (ssv) credentials:

IN a{sv} options:

Property Details

The "SuggestedAdministrator" property

SuggestedAdministrator  readable   s

common administrator name The common administrator name for this type of realm. This can be used by clients as a hint when prompting the user for administrative authentication.

The "SupportedJoinCredentials" property

SupportedJoinCredentials  readable   a(ss)

credentials supported for joining Various kinds of credentials that are supported when calling the org.freedesktop.realmd.Kerberos.Join() method.

Each credential is represented by a type and an owner. The type denotes which kind of credential is passed to the method. The owner indicates to the client how to prompt the user or obtain the credential, and to the service how to use the credential.

The various types are:

ccache: the credentials should contain an array of bytes as a ay containing the data from a kerberos credential cache file.
password: the credentials should contain a pair of strings as a (ss) representing a name and password. The name may contain a realm in the standard kerberos format. If a realm is missing, it will default to this realm.
secret: the credentials should contain a string secret as an ay array of bytes. This is usually used for one time passwords. To pass a string here, encode it in UTF-8, and place the resulting bytes in the value.
automatic: the credentials should contain an empty string as a s. Using automatic indicates that default or system credentials are to be used.

The various owners are:

administrator: the credentials belong to a kerberos administrator principal. The caller may use this as a hint to prompt the user for administrative credentials.
user: the credentials belong to a kerberos user principal. The caller may use this as a hint to prompt the user for his (possibly non-administrative) credentials.
computer: the credentials belong to a computer account.
none: the credentials have an unspecified owner, such as a one time password.

The "SupportedLeaveCredentials" property

SupportedLeaveCredentials  readable   a(ss)

credentials supported for leaving Various kinds of credentials that are supported when calling the org.freedesktop.realmd.Kerberos.Leave() method.

See org.freedesktop.realmd.Kerberos:SupportedJoinCredentials for a discussion of what the values represent.