diff --git a/doc/source/external-auth.rst b/doc/source/external-auth.rst
index 4b545e4f57..b3f9f29b9d 100644
--- a/doc/source/external-auth.rst
+++ b/doc/source/external-auth.rst
@@ -37,6 +37,27 @@ provided by Keystone:
   the domain for the user. If this variable is not present, the configured
   default domain will be used. The ``REMOTE_USER`` variable is the username.
 
+.. CAUTION::
+
+    You should disable the external auth method if you are currently using
+    federation. External auth and federation both use the ``REMOTE_USER``
+    variable. Since both the mapped and external plugin are being invoked to
+    validate attributes in the request environment, it can cause conflicts.
+
+    For example, imagine there are two distinct users with the same username
+    `foo`, one in the `Default` domain while the other is in the `BAR` domain.
+    The external Federation modules (i.e. mod_shib) sets the ``REMOTE_USER``
+    attribute to `foo`. The external auth module also tries to set the
+    ``REMOTE_USER`` attribute to `foo` for the `Default` domain. The
+    federated mapping engine maps the incoming identity to `foo` in the `BAR`
+    domain. This results in user_id conflict since both are using different
+    user_ids to set `foo` in the `Default` domain and the `BAR` domain.
+
+    To disable this, simply remove `external` from the `methods` option in
+    `keystone.conf`::
+
+       methods = external,password,token,oauth1
+
 Using HTTPD authentication
 ==========================