+Users and groups are synced to the cluster-wide configuration file,
+`/etc/pve/user.cfg`.
+
+
+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`.
+
+* `Full` (`full`): If set, the sync uses the LDAP directory as a source of
+ truth, overwriting information set manually in the `user.cfg` and deleting
+ users and groups which are not present in the LDAP directory. If not set, only
+ new data is written to the configuration, and no stale users are deleted.
+
+* `Purge ACLs` (`purge`): If set, sync removes all corresponding ACLs when
+ removing users and groups. This is only useful with the option `full`.
+
+* `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_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`).
+
+Username mapping
+^^^^^^^^^^^^^^^^
+
+The OpenID Connect specification defines a single unique attribute
+('claim' in OpenID terms) named `subject`. By default, we use the
+value of this attribute to generate {pve} usernames, by simple adding
+`@` and the realm name: `${subject}@${realm}`.
+
+Unfortunately, most OpenID servers use random strings for `subject`, like
+`DGH76OKH34BNG3245SB`, so a typical username would look like
+`DGH76OKH34BNG3245SB@yourrealm`. While unique, it is difficult for
+humans to remember such random strings, making it quite impossible to
+associate real users with this.
+
+The `username-claim` setting allows you to use other attributes for
+the username mapping. Setting it to `username` is preferred if the
+OpenID Connect server provides that attribute and guarantees its
+uniqueness.
+
+Another option is to use `email`, which also yields human readable
+usernames. Again, only use this setting if the server guarantees the
+uniqueness of this attribute.
+
+Examples
+^^^^^^^^
+
+Here is an example of creating an OpenID realm using Google. You need to
+replace `--client-id` and `--client-key` with the values
+from your Google OpenID settings.
+
+----
+pveum realm add myrealm1 --type openid --issuer-url https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim email
+----
+
+The above command uses `--username-claim email`, so that the usernames on the
+{pve} side look like `example.user@google.com@myrealm1`.
+
+Keycloak (https://www.keycloak.org/) is a popular open source Identity
+and Access Management tool, which supports OpenID Connect. In the following
+example, you need to replace the `--issuer-url` and `--client-id` with
+your information:
+
+----
+pveum realm add myrealm2 --type openid --issuer-url https://your.server:8080/auth/realms/your-realm --client-id XXX --username-claim username
+----
+
+Using `--username-claim username` enables simple usernames on the
+{pve} side, like `example.user@myrealm2`.
+
+WARNING: You need to ensure that the user is not allowed to edit
+the username setting themselves (on the Keycloak server).