diff --git a/docs/documentation/server_development/topics/providers.adoc b/docs/documentation/server_development/topics/providers.adoc
index 1eb3ddcb3a..ce9c0b08e7 100644
--- a/docs/documentation/server_development/topics/providers.adoc
+++ b/docs/documentation/server_development/topics/providers.adoc
@@ -256,7 +256,8 @@ the `ScriptModel` to access script metadata
 `realm`::
 the `RealmModel`
 `user`::
-the current `UserModel`
+the current `UserModel`. Note that `user` is available when your script authenticator is configured in the authentication flow in a way that is triggered after
+another authenticator succeeded in establishing user identity and set the user into the authentication session.
 `session`::
 the active `KeycloakSession`
 `authenticationSession`::
@@ -288,6 +289,21 @@ function authenticate(context) {
 }
 ----
 
+===== Where to add script authenticator
+
+A possible use of script authenticator is to do some checks at the end of the authentication. Note that if you want
+your script authenticator to be always triggered (even for instance during SSO re-authentication with the identity cookie), you may need to add it as REQUIRED at the end
+of the authentication flow and encapsulate the existing authenticators into a separate REQUIRED authentication subflow. This need is because the REQUIRED and ALTERNATIVE executions
+should not be at the same level. For example, the authentication flow configuration should appear as follows:
+[source]
+----
+- User-authentication-subflow REQUIRED
+-- Cookie ALTERNATIVE
+-- Identity-provider-redirect ALTERNATIVE
+...
+- Your-Script-Authenticator REQUIRED
+----
+
 ==== Create a JAR with the scripts to deploy
 
 NOTE: JAR files are regular ZIP files with a `.jar` extension.