More docs clarification for script authenticator (#20444)

* More docs clarification for script authenticator
closes #20009


Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>

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.