+(for example, `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
+single line with the raw password.
+
+To verify certificates, you need to set `capath`. You can set it either
+directly to the CA certificate of your LDAP server, or to the system path
+containing all trusted CA certificates (`/etc/ssl/certs`).
+Additionally, you need to set the `verify` option, which can also be done over
+the web interface.
+
+The main configuration options for an LDAP server realm are as follows:
+
+* `Realm` (`realm`): The realm identifier for {pve} users
+
+* `Base Domain Name` (`base_dn`): The directory which users are searched under
+
+* `User Attribute Name` (`user_attr`): The LDAP attribute containing the
+ username that users will log in with
+
+* `Server` (`server1`): The server hosting the LDAP directory
+
+* `Fallback Server` (`server2`): An optional fallback server address, in case
+ the primary server is unreachable
+
+* `Port` (`port`): The port that the LDAP server listens on
+
+NOTE: In order to allow a particular user to authenticate using the LDAP server,
+you must also add them as a user of that realm from the {pve} server. This can
+be carried out automatically with <<pveum_ldap_sync, syncing>>.
+
+
+[[user-realms-ad]]
+Microsoft Active Directory (AD)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To set up Microsoft AD as a realm, a server address and authentication domain
+need to be specified. Active Directory supports most of the same properties as
+LDAP, such as an optional fallback server, port, and SSL encryption.
+Furthermore, users can be added to {pve} automatically via
+<<pveum_ldap_sync, sync>> operations, after configuration.
+
+As with LDAP, if {pve} needs to authenticate before it binds to the AD server,
+you must configure the 'Bind User' (`bind_dn`) property. This property is
+typically required by default for Microsoft AD.
+
+The main configuration settings for Microsoft Active Directory are:
+
+* `Realm` (`realm`): The realm identifier for {pve} users
+
+* `Domain` (`domain`): The AD domain of the server
+
+* `Server` (`server1`): The FQDN or IP address of the server
+
+* `Fallback Server` (`server2`): An optional fallback server address, in case
+ the primary server is unreachable
+
+* `Port` (`port`): The port that the Microsoft AD server listens on
+
+
+NOTE: Microsoft AD normally checks values like usernames without case
+sensitivity. To make {pve} do the same, you can disable the default
+`case-sensitive` option by editing the realm in the web UI, or using the CLI
+(change the `ID` with the realm ID):
+`pveum realm modify ID --case-sensitive 0`
+
+[[pveum_ldap_sync]]
+Syncing LDAP-Based Realms
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"]
+
+It's possible to automatically sync users and groups for LDAP-based realms (LDAP
+& Microsoft Active Directory), rather than having to add them to {pve} manually.
+You can access the sync options from the Add/Edit window of the web interface's
+`Authentication` panel or via the `pveum realm add/modify` commands. You can
+then carry out the sync operation from the `Authentication` panel of the GUI or
+using the following command:
+
+----
+pveum realm sync <realm>
+----
+
+Users and groups are synced to the cluster-wide configuration file,
+`/etc/pve/user.cfg`.
+
+
+Attributes to Properties
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the sync response includes user attributes, they will be synced into the
+matching user property in the `user.cfg`. For example: `firstname` or
+`lastname`.
+
+If the names of the attributes are not matching the {pve} properties, you can
+set a custom field-to-field map in the config by using the `sync_attributes`
+option.
+
+How such properties are handled if anything vanishes can be controlled via the
+sync options, see below.
+
+Sync Configuration
+^^^^^^^^^^^^^^^^^^
+
+The configuration options for syncing LDAP-based realms can be found in the
+`Sync Options` tab of the Add/Edit window.
+
+The configuration options are as follows:
+
+* `Bind User` (`bind_dn`): Refers to the LDAP account used to query users
+ and groups. This account needs access to all desired entries. If it's set, the
+ search will be carried out via binding; otherwise, the search will be carried
+ out anonymously. The user must be a complete LDAP formatted distinguished name
+ (DN), for example, `cn=admin,dc=example,dc=com`.
+
+* Groupname attr. (group_name_attr): Represents the
+ users' groups. Only entries which adhere to the usual character limitations of
+ the `user.cfg` are synced. Groups are synced with `-$realm` attached to the
+ name, in order to avoid naming conflicts. Please ensure that a sync does not
+ overwrite manually created groups.
+
+* `User classes` (`user_classes`): Objects classes associated with users.
+
+* `Group classes` (`group_classes`): Objects classes associated with groups.
+
+* `E-Mail attribute`: If the LDAP-based server specifies user email addresses,
+ these can also be included in the sync by setting the associated attribute
+ here. From the command line, this is achievable through the
+ `--sync_attributes` parameter.
+
+* `User Filter` (`filter`): For further filter options to target specific users.
+
+* `Group Filter` (`group_filter`): For further filter options to target specific
+ groups.
+
+NOTE: Filters allow you to create a set of additional match criteria, to narrow
+down the scope of a sync. Information on available LDAP filter types and their
+usage can be found at https://ldap.com/ldap-filters/[ldap.com].
+
+[[pveum_ldap_sync_options]]
+Sync Options
+^^^^^^^^^^^^
+
+[thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"]
+
+In addition to the options specified in the previous section, you can also
+configure further options that describe the behavior of the sync operation.
+
+These options are either set as parameters before the sync, or as defaults via
+the realm option `sync-defaults-options`.
+
+The main options for syncing are:
+
+* `Scope` (`scope`): The scope of what to sync. It can be either `users`,
+ `groups` or `both`.
+
+* `Enable new` (`enable-new`): If set, the newly synced users are enabled and
+ can log in. The default is `true`.
+
+* `Remove Vanished` (`remove-vanished`): This is a list of options which, when
+ activated, determine if they are removed when they are not returned from
+ the sync response. The options are:
+
+ - `ACL` (`acl)`: Remove ACLs of users and groups which were not returned
+ returned in the sync response. This most often makes sense together with
+ `Entry`.
+
+ - `Entry` (`entry`): Removes entries (i.e. users and groups) when they are
+ not returned in the sync response.
+
+ - `Properties` (`properties`): Removes properties of entries where the user
+ in the sync response did not contain those attributes. This includes
+ all properties, even those never set by a sync. Exceptions are tokens
+ and the enable flag, these will be retained even with this option enabled.
+
+* `Preview` (`dry-run`): No data is written to the config. This is useful if you
+ want to see which users and groups would get synced to the `user.cfg`.
+
+[[pveum_ldap_reserved_characters]]
+Reserved characters
+^^^^^^^^^^^^^^^^^^^
+
+Certain characters are reserved (see https://www.ietf.org/rfc/rfc2253.txt[RFC2253]) and cannot be
+easily used in attribute values in DNs without being escaped properly.
+
+Following characters need escaping:
+
+* Space ( ) at the beginning or end
+* Number sign (`#`) at the beginning
+* Comma (`,`)
+* Plus sign (`+`)
+* Double quote (`"`)
+* Forward slashes (`/`)
+* Angle brackets (`<>`)
+* Semicolon (`;`)
+* Equals sign (`=`)
+
+To use such characters in DNs, surround the attribute value in double quotes.
+For example, to bind with a user with the CN (Common Name) `Example, User`, use
+`CN="Example, User",OU=people,DC=example,DC=com` as value for `bind_dn`.
+
+This applies to the `base_dn`, `bind_dn`, and `group_dn` attributes.
+
+NOTE: Users with colons and forward slashes cannot be synced since these are
+reserved characters in usernames.
+
+[[pveum_openid]]
+OpenID Connect
+~~~~~~~~~~~~~~
+
+The main OpenID Connect configuration options are:
+
+* `Issuer URL` (`issuer-url`): This is the URL of the authorization server.
+Proxmox uses the OpenID Connect Discovery protocol to automatically configure
+further details.
++
+While it is possible to use unencrypted `http://` URLs, we strongly recommend to
+use encrypted `https://` connections.
+
+* `Realm` (`realm`): The realm identifier for {pve} users
+
+* `Client ID` (`client-id`): OpenID Client ID.
+
+* `Client Key` (`client-key`): Optional OpenID Client Key.
+
+* `Autocreate Users` (`autocreate`): Automatically create users if they do not
+exist. While authentication is done at the OpenID server, all users still need
+an entry in the {pve} user configuration. You can either add them manually, or
+use the `autocreate` option to automatically add new users.
+
+* `Username Claim` (`username-claim`): OpenID claim used to generate the unique
+username (`subject`, `username` or `email`).