adding "migrating" note

Author: phil198

modules/ROOT/pages/authentication-authorization/auth-providers.adoc

@@ -34,6 +34,18 @@ The way that the matching lookup is done depends on the type of provider. For ex
 == Enabling User Auth Providers mode
 When the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting is set to `true`, the lookups described above will be performed when the user authenticates, and a matching user Auth Provider *must* exist in order for a user to be able to successfully authenticate and authorize.
 
+== Migrating to Auth Providers mode
+If you have existing users in the database and you want to migrate to Auth Providers mode, you can use the `ALTER USER ... SET AUTH` command to attach Auth Provider(s) to an existing user. Until you change `dbms.security.require_local_user` to `true`, this will have no impact on the users' ability to authenticate and authorize as they always have done.
+
+Once the process of adding Auth Providers to your users is completed, you can then set `dbms.security.require_local_user` to true and restart the DBMS to complete the migration. After this time, only users with a corresponding Auth Provider in the database will be able to authenticate and authorize.
+
+[NOTE]
+====
+Existing users which were created using the original `CREATE USER ... SET PASSWORD` syntax, will implicitly have the native (username / password) Auth Provider, so that would not need to be added explicitly using `SET AUTH`.
+
+To be certain about which Auth Providers are attached to a user, you can use the xref:authentication-authorization/manage-users.adoc#access-control-list-users[`SHOW USERS WITH AUTH`] command to see the Auth Providers attached to a user.
+====
+
 == Examples
 For examples of how to use Auth Providers with different authentication providers, see the following sections: