diff --git a/docs/pages/desktop-access/rbac.mdx b/docs/pages/desktop-access/rbac.mdx
index 80e7cc79fc785..0f010619a4e82 100644
--- a/docs/pages/desktop-access/rbac.mdx
+++ b/docs/pages/desktop-access/rbac.mdx
@@ -30,6 +30,12 @@ spec:
# if unspecified. If one or more of the user's roles has disabled
# the clipboard, then it will be disabled.
desktop_clipboard: true
+
+ # Specify whether local users should be created automatically at connection
+ # time. By default, this feature is disabled, and the user must already exist.
+ # Note: this is applicable to local users only and is not supported in Active
+ # Directory environments.
+ create_desktop_user: true
allow:
# Label selectors for desktops this role has access to.
windows_desktop_labels:
@@ -123,6 +129,81 @@ allow:
windows_desktop_logins: ["{{internal.windows_logins}}"]
```
+### Automatic User Creation
+
+
+Teleport versions prior to 12.3 don't support the options shown below.
+
+
+Teleport's Desktop Service can be configured to automatically create local
+Windows users upon login.
+
+#### Configuration
+
+
+Automatic user provisioning is only supported for local users, and does
+not take effect in Active Directory environments.
+
+
+This feature is disabled by default, and can be enabled by setting the
+`create_desktop_user` role option on one of the user's roles.
+
+```yaml
+kind: role
+version: v6
+metadata:
+ name: allow-user-provisioning
+spec:
+ options:
+ create_desktop_user: true
+ allow:
+ windows_desktop_labels: { '*': '*' }
+ windows_desktop_logins: jane
+```
+
+When a Teleport user connects to a desktop, Teleport checks each of the user's
+roles that match the desktop. If at least one role matches the desktop but does
+not include `create_desktop_user: true`, automatic user creation will be
+disabled. Roles that do not match the desktop's labels will not be checked.
+
+In order to create the user, the requested username must be present in one of the
+role's `windows_desktop_logins`.
+
+#### User management
+
+By default, the newly-created user will be placed in two Windows groups:
+
+- `Remote Desktop Users`: a built-in Windows group allowing remote desktop access
+- `Teleport Users`: a custom group that Teleport places all
+ automatically-created users in
+
+To add the user to additional groups, specify the `desktop_groups` role option:
+
+```yaml
+kind: role
+version: v6
+metadata:
+ name: allow-user-provisioning
+spec:
+ options:
+ create_desktop_user: true
+ allow:
+ windows_desktop_labels: { '*': '*' }
+ windows_desktop_logins: jane
+ desktop_groups:
+ - developers
+ # to make the newly-created user an administrator
+ - Administrators
+ # IdP trait templating is also supported
+ - '{{external.desktop_groups}}'
+```
+
+Teleport will never delete users that are created via automatic user provisioning.
+This ensures that the user's profile is preserved for future logins. Teleport will
+disable the account when the session completes (and automatically re-enable it on
+future connection attempts). This ensures that user accounts created by Teleport
+can only be accessed via Teleport.
+
## Clipboard Access
In order for a user to copy and paste between a remote desktop and their local