diff --git a/api-ref/source/v3-ext/federation.inc b/api-ref/source/v3-ext/federation.inc
index eaf07c1e64..b02f973461 100644
--- a/api-ref/source/v3-ext/federation.inc
+++ b/api-ref/source/v3-ext/federation.inc
@@ -147,37 +147,53 @@ Required attributes:
 
    ::
 
-       {
-           "user": {
-               "name": "{0}"
-           }
-       }
+       [
+           {
+               "local": [
+                   {
+                       "user": {
+                           "name": "{0}"
+                       }
+                   }
+               ],
+            }
+        ]
 
    If the ``user`` attribute is missing when processing an assertion, server
    tries to directly map ``REMOTE_USER`` environment variable. If this variable
    is also unavailable the server returns an HTTP ``401 Unauthorized`` error.
 
-   If the ``user`` has domain specified, the user is treated as existing in the
-   backend, hence the server will fetch user details (id, name, roles, groups).
+   If the ``user`` has the attribute ``type`` set to ``local`` as well as a
+   domain specified, the user is treated as existing in the local keystone
+   backend, and the server will attempt to fetch user details (id, name, roles,
+   groups) from the identity backend.
 
    If, however, the user does not exist in the backend, the server will
    respond with an appropriate HTTP error code.
 
-   If no domain is specified in the local rule, user is deemed ephemeral
-   and becomes a member of service domain named ``Federated``.
+   If the ``type`` attribute is not set to ``local`` in the local rule and no
+   domain is specified, the user is deemed ephemeral and becomes a member of
+   service identity provider's domain.
 
-   An example of user object mapping to an existing user:
+   An example of user object mapping to an existing local user:
 
    ::
 
-       {
-            "user": {
-                "name": "username"
-                "domain": {
-                    "name": "domain_name"
-                }
+       [
+           {
+               "local": [
+                   {
+                        "user": {
+                            "name": "username",
+                            "type": "local",
+                            "domain": {
+                                "name": "domain_name"
+                            }
+                        }
+                   }
+               ],
             }
-       }
+        ]
 
 
    For attribute type and value mapping, identify the local resource type,
@@ -185,20 +201,32 @@ Required attributes:
 
    ::
 
-       {
-           "group": {
-               "id": "89678b"
+       [
+           {
+               "local": [
+                   {
+                       "group": {
+                           "id": "89678b"
+                       }
+                   }
+               ],
            }
-       }
+       ]
 
    This assigns authorization attributes, by way of role assignments on the
    specified group, to ephemeral users.
 
    ::
 
-       {
-           "group_ids": "{0}"
-       }
+       [
+           {
+               "local": [
+                   {
+                       "group_ids": "{0}"
+                   }
+               ],
+            }
+        ]
 
    It is also possible to map multiple groups by providing a list of group ids.
    Those group ids can also be white/blacklisted.
diff --git a/doc/source/advanced-topics/federation/mapping_combinations.rst b/doc/source/advanced-topics/federation/mapping_combinations.rst
index d325f9b46f..4ce67fc222 100644
--- a/doc/source/advanced-topics/federation/mapping_combinations.rst
+++ b/doc/source/advanced-topics/federation/mapping_combinations.rst
@@ -406,6 +406,41 @@ Group ids and names can be provided in the local section:
         ]
     }
 
+Users can be mapped to local users that already exist in keystone's identity
+backend by setting the ``type`` attribute of the user to ``local`` and providing
+the domain to which the local user belongs:
+
+.. code-block:: json
+
+    {
+        "local": [
+            {
+                "user": {
+                    "name": "local_user",
+                    "type": "local",
+                    "domain": {
+                        "name": "local_domain"
+                    }
+                }
+            }
+        ]
+    }
+
+The user is then treated as existing in the local identity backend, and the
+server will attempt to fetch user details (id, name, roles, groups) from the
+identity backend. The local user and domain are not generated dynamically, so
+if they do not exist in the local identity backend, authentication attempts
+will result in a 401 Unauthorized error.
+
+If you omit the ``type`` attribute or set it to ``ephemeral`` or do not provide a
+domain, the user is deemed ephemeral and becomes a member of the identity
+provider's domain. It will not be looked up in the local keystone backend, so
+all of its attributes must come from the IdP and the mapping rules.
+
+.. NOTE::
+    Domain ``Federated`` is a service domain - it cannot be listed, displayed,
+    added or deleted.  There is no need to perform any operation on it prior to
+    federation configuration.
 
 Output
 ------
@@ -451,24 +486,9 @@ If a mapping is valid you will receive the following output:
             ]
     }
 
-The ``type`` parameter specifies the type of user being mapped. The 2 possible
-user types are ``local`` and ``ephemeral``.``local`` is displayed if the user
-has a domain specified. The user is treated as existing in the backend, hence
-the server will fetch user details (id, name, roles, groups).``ephemeral`` is
-displayed for a user that does not exist in the backend.
-
-The ``id`` parameter in the service domain specifies the domain a user belongs
-to. ``Federated`` will be displayed if no domain is specified in the local rule.
-User is deemed ephemeral and becomes a member of service domain named ``Federated``.
-If the domain is specified the local domain's id will be displayed.
 If the mapped user is local, mapping engine will discard further group
 assigning and return set of roles configured for the user.
 
-.. NOTE::
-    Domain ``Federated`` is a service domain - it cannot be listed, displayed,
-    added or deleted.  There is no need to perform any operation on it prior to
-    federation configuration.
-
 Regular Expressions
 -------------------