+* `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_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`.