diff --git a/doc/Makefile.am b/doc/Makefile.am
index 4490688..50fb777 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -33,14 +33,17 @@ EXTRA_DIST = \
version.xml \
samba_data_tool_path.xml.in \
samba_data_tool_path.xml \
+ permissions.xml \
$(NULL)
CLEANFILES = \
$(man8_MANS) \
+ permissions.xml \
$(NULL)
XSLTPROC_FLAGS = \
--nonet \
+ --xinclude \
--stringparam man.output.quietly 1 \
--stringparam funcsynopsis.style ansi \
--stringparam man.th.extra1.suppress 1 \
@@ -50,6 +53,13 @@ XSLTPROC_FLAGS = \
XSLTPROC_MAN = \
$(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
+permissions.xml: ../library/adenroll.c adcli.xml
+ echo "" > $@
+ grep '".*".*/\* :ADPermissions: ' $< | sed -e 's#.*"\(.*\)".*/\* :ADPermissions: \(.*\)\*/$$#\1\2#' | sed -e 's#\*##g' >> $@
+ echo "" >> $@
+
+$(man8_MANS): permissions.xml
+
.xml.8:
$(AM_V_GEN) $(XSLTPROC_MAN) $<
diff --git a/doc/adcli.xml b/doc/adcli.xml
index 1437679..cc44fd8 100644
--- a/doc/adcli.xml
+++ b/doc/adcli.xml
@@ -885,6 +885,138 @@ Password for Administrator:
+
+ Delegated Permissions
+ It is common practice in AD to not use an account from the Domain
+ Administrators group to join a machine to a domain but use a dedicated
+ account which only has permissions to join a machine to one or more OUs
+ in the Active Directory tree. Giving the needed permissions to a single
+ account or a group in Active Directory is called Delegation. A typical
+ example on how to configured Delegation can be found in the Delegation
+ section of the blog post
+ Who can add workstation to the domain.
+
+
+ When using an account with delegated permissions with adcli
+ basically the same applies as well. However some aspects are explained
+ here in a bit more details to better illustrate different concepts of
+ Active Directory and to make it more easy to debug permissions issues
+ during the join. Please note that the following is not specific to
+ adcli but applies to all applications which would like to modify
+ certain properties or objects in Active Directory with an account with
+ limited permissions.
+
+ First, as said in the blog post it is sufficient to have
+ "Create computer object" permissions to join a
+ computer to a domain. But this would only work as expected if the
+ computer object does not exist in Active Directory before the join.
+ Because only when a new object is created Active Directory does not
+ apply additional permission checks on the attributes of the new
+ computer object. This means the delegated user can add any kind of
+ attribute with any value to a new computer object also long as they
+ meet general constraints like e.g. that the attribute must be defined
+ in the schema and is allowed in a objectclass of the object, the value
+ must match the syntax defined in the schema or that the
+ must be unique in the domain.
+
+ If you want to use the account with delegated permission to
+ remove computer objects in Active Directory (adcli delete-computer) you
+ should of course make sure that the account has
+ "Delete computer object" permissions.
+
+ If the computer object already exists the
+ "Create computer object" permission does not apply
+ anymore since now an existing object must be modified. Now permissions
+ on the individual attributes are needed. e.g.
+ "Read and write Account Restrictions" or
+ "Reset Password". For some attributes Active
+ Directory has two types of permissions the plain
+ "Read and Write" permissions and the
+ "Validated Write" permissions. For the latter case
+ there are two specific permissions relevant for adcli, namely
+
+ Validated write to DNS host name
+ Validated write to service principal name
+
+ Details about the validation of the values can be found in the
+ "Validated Writes" section of
+ [MS-ADTS], especially
+ dNSHostName
+ and
+ servicePrincipalName.
+ To cut it short for "Validated write to DNS host name"
+ the domain part of the fully-qualified hostname must either match the
+ domain name of the domain you want to join to or must be listed in the
+ attribute. And for
+ "Validated write to service principal name" the
+ hostname part of the service principal name must match the name stored
+ in or some other attributes which are
+ not handled by adcli. This also means that
+ cannot be empty or only contain a short
+ name if the service principal name should contain a fully-qualified
+ name.
+
+ To summarize, if you only have validated write permissions you
+ should make sure the domain part of the hostname matches the domain you
+ want to join or use the with a matching
+ name.
+
+ The plain read write permissions do not run additional
+ validations but the attribute values must still be in agreement with
+ the general constraints mentioned above. If the computer object already
+ exists adcli might need the following permissions which are also needed
+ by Windows clients to modify existing attributes:
+
+ Reset Password
+ Read and write Account Restrictions
+ Read and (validated) write to DNS host name
+ Read and (validated) write to service principal name
+
+ additionally adcli needs
+
+ Read and write msDS-supportedEncryptionTypes
+
+ This is added for security reasons to avoid that Active Directory
+ stores Kerberos keys with (potentially weaker) encryption types than
+ the client supports since Active Directory is often configured to still
+ support older (weaker) encryption types for compatibility reasons.
+
+
+ All other attributes are only set or modified on demand, i.e.
+ adcli must be called with an option the would set or modify the given
+ attribute. In the following the attributes adcli can modify together
+ with the required permissions are listed:
+
+
+
+ For the management of users and groups (adcli create-user,
+ adcli delete-user, adcli create-group, adcli delete-group) the same
+ applies only for different types of objects, i.e. users and groups.
+ Since currently adcli only supports the creation and the removal of
+ user and group objects it is sufficient to have the
+ "Create/Delete User objects" and
+ "Create/Delete Group objects" permissions.
+
+ If you want to manage group members as well (adcli add-member,
+ adcli remove-member) "Read/Write Members" permissions
+ are needed as well.
+
+ Depending on the version of Active Directory the
+ "Delegation of Control Wizard" might offer some
+ shortcuts for common task like e.g.
+
+ Create, delete and manage user accounts
+ Create, delete and manage groups
+ Modify the membership of a group
+
+ The first 2 shortcuts will provided full access to user and group
+ objects which, as explained above, is more than currently is needed.
+ After using those shortcut it is a good idea to verify in the
+ "Security" tab in the "Properties"
+ of the related Active Directory container that the assigned permissions
+ meet the expectations.
+
+
Bugs
diff --git a/library/adenroll.c b/library/adenroll.c
index e745295..98e9786 100644
--- a/library/adenroll.c
+++ b/library/adenroll.c
@@ -71,19 +71,25 @@ static krb5_enctype v51_earlier_enctypes[] = {
0
};
+/* The following list containst all attributes handled by adcli, some are
+ * read-only and the others can be written as well. To properly document the
+ * required permissions each attribute which adcli tries to modify should have
+ * a comment starting with ':ADPermissions:' and the related permissions in AD
+ * on the same line. Multiple permissions can be seperated with a '*'. For all
+ * other attribute a suitable comment is very welcome. */
static char *default_ad_ldap_attrs[] = {
- "sAMAccountName",
- "userPrincipalName",
- "msDS-KeyVersionNumber",
- "msDS-supportedEncryptionTypes",
- "dNSHostName",
- "servicePrincipalName",
- "operatingSystem",
- "operatingSystemVersion",
- "operatingSystemServicePack",
- "pwdLastSet",
- "userAccountControl",
- "description",
+ "sAMAccountName", /* Only set during creation */
+ "userPrincipalName", /* :ADPermissions: Read/Write userPrincipal Name */
+ "msDS-KeyVersionNumber", /* Manages by AD */
+ "msDS-supportedEncryptionTypes", /* :ADPermissions: Read/Write msDS-SupportedEncryptionTypes */
+ "dNSHostName", /* :ADPermissions: Read/Write dNSHostName * Read and write DNS host name attributes * Validated write to DNS host name */
+ "servicePrincipalName", /* :ADPermissions: Read/Write servicePrincipalName * Validated write to service principal name */
+ "operatingSystem", /* :ADPermissions: Read/Write Operating System */
+ "operatingSystemVersion", /* :ADPermissions: Read/Write Operating System Version */
+ "operatingSystemServicePack", /* :ADPermissions: Read/Write operatingSystemServicePack */
+ "pwdLastSet", /* Managed by AD */
+ "userAccountControl", /* :ADPermissions: Read/Write userAccountControl */
+ "description", /* :ADPermissions: Read/Write Description */
NULL,
};