Document required AD ACLs (#541)

* Document required AD ACLs

* Document how to configure the ACL rules manually

* Add a warning about empty-looking ACL rules

Author: nightkr

docs/modules/secret-operator/pages/secretclass.adoc

@@ -219,6 +219,56 @@ If the same AD domain _is_ shared between multiple Kubernetes clusters, the foll
 * The Kubernetes Nodes' names and fully qualified domain names
 * The Kubernetes Namespaces' names (only Namespaces that use Kerberos)
 
+[#ad-acl]
+===== Access Control
+
+The Secret Operator needs permission to create users in the configured base container
+(`kerberosKeytab.admin.activeDirectory.userDistinguishedName`), as well as to reset their passwords.
+
+The easiest way to configure this is to run the following PowerShell script:
+
+// FIXME: This script is copied from ad-init, can we share this somehow?
+
+[source,powershell]
+----
+Import-Module ActiveDirectory
+# Change these variables to fit your environment
+$ou_path = "AD:OU=SDP,DC=sble,DC=test"
+$secretop = [System.Security.Principal.SecurityIdentifier]::New("S-1-5-21-1256652973-2063416196-3566311115-1103")
+
+$acl = Get-ACL -Path $ou_path
+$user_schema_guid = "bf967aba-0de6-11d0-a285-00aa003049e2"
+$password_reset_right_guid = "00299570-246d-11d0-a768-00aa006e0529"
+$ou_create_children_rule = [System.DirectoryServices.ActiveDirectoryAccessRule]::New(
+  $secretop,
+  [System.DirectoryServices.ActiveDirectoryRights]::CreateChild,
+  [System.Security.AccessControl.AccessControlType]::Allow,
+  $user_schema_guid,
+  [System.DirectoryServices.ActiveDirectorySecurityInheritance]::None
+)
+$ou_reset_passwords_rule = [System.DirectoryServices.ExtendedRightAccessRule]::New(
+  $secretop,
+  [System.Security.AccessControl.AccessControlType]::Allow,
+  $password_reset_right_guid,
+  [System.DirectoryServices.ActiveDirectorySecurityInheritance]::Children
+)
+$acl.AddAccessRule($ou_create_children_rule)
+$acl.AddAccessRule($ou_reset_passwords_rule)
+Set-ACL -Path $ou_path -AclObject $acl
+----
+
+NOTE: The "reset passwords" rule created by the script will show up as applying no permissions in ADSI Edit.
+      This is because ADSI Edit is unaware of the extended right that it grants. The rule _should not_ be
+      deleted or modified manually, or the operator will break. If the rule has been tampered with, run the
+      script again to fix the problem.
+
+Alternatively, it can be configured manually using the graphical "ADSI Edit" tool. Secret Operator's user needs two permission rules
+on the base container:
+
+- On the container itself: Create User objects
+- On descendants of the container: Reset Password (this is not visible in the GUI, but is granted by the "All extended rights" toggle)
+
+
 [#ad-samaccountname]
 ===== Custom `samAccountName` generation
 
@@ -273,7 +323,7 @@ spec:
           passwordCacheSecret:
             namespace: default
             name: secret-operator-ad-passwords
-          userDistinguishedName: CN=Users,DC=sble,DC=test
+          userDistinguishedName: OU=SDP,DC=sble,DC=test
           schemaDistinguishedName: CN=Schema,CN=Configuration,DC=sble,DC=test
       adminKeytabSecret:
         namespace: default
@@ -290,8 +340,8 @@ spec:
 `kerberosKeytab.admin.activeDirectory.ldapServer`:: An AD LDAP server, such as the AD Domain Controller. This _must_ match the server's FQDN, or GSSAPI authentication will fail.
 `kerberosKeytab.admin.activeDirectory.ldapTlsCaSecret`:: Reference (`name` and `namespace`) to a K8s `Secret` object containing the TLS CA (in `ca.crt`) that the LDAP server's certificate should be authenticated against.
 `kerberosKeytab.admin.activeDirectory.passwordCacheSecret`:: Reference (`name` and `namespace`) to a K8s `Secret` object where workload passwords will be stored. This _must not_ be accessible to end users.
-`kerberosKeytab.admin.activeDirectory.userDistinguishedName`:: The root Distinguished Name (DN) where service accounts should be provisioned, typically `CN=Users,\{domain_dn\}`.
-`kerberosKeytab.admin.activeDirectory.schemaDistinguishedName`:: The root Distinguished Name (DN) for AD-managed schemas, typically `CN=Schema,CN=Configuration,\{domain_dn\}`.
+`kerberosKeytab.admin.activeDirectory.userDistinguishedName`:: The root Distinguished Name (DN) of the container where service accounts should be provisioned, such as `OU=SDP,\{domain_dn\}`.
+`kerberosKeytab.admin.activeDirectory.schemaDistinguishedName`:: The root Distinguished Name (DN) of the container for AD-managed schemas, typically `CN=Schema,CN=Configuration,\{domain_dn\}`.
 `kerberosKeytab.adminKeytabSecret`:: Reference (`name` and `namespace`) to a K8s `Secret` object where a keytab with administrative privileges is stored in the key `keytab`.
 `kerberosKeytab.adminPrincipal`:: The name of the Kerberos principal to be used by the Secret Operator. This should be provided by the Kerberos administrator. The credentials for this principal must be stored in the keytab (`adminKeytabSecret`).