Add information on how to request tokens for federated users

Add information describing the authentication process required
to retrieve an unscoped and scoped token, as a federated user.

Change-Id: I9abffcd3f3e5a886bf5e7e184faed6aa7bd5c684
blueprint: saml-id

openstack-identity-api/v3/src/markdown/identity-api-v3-os-federation-ext.md

@@ -642,3 +642,90 @@ This is an example that is similar to the previous, but displays how multiple
             }
         ]
     }
+
+Authenticating
+--------------
+
+### Request an unscoped OS-FEDERATION token: `POST /auth/tokens`
+
+A federated user may request an unscoped token, which can be used to get
+a scoped token.
+
+Request Parameters:
+
+To authenticate with the OS-FEDERATION extension, `saml2` must be specified as an
+authentication method.
+
+Example request:
+
+    {
+        "auth": {
+            "identity": {
+                "methods": [
+                    "saml2"
+                ],
+                "saml2": {
+                    "identity_provider": {"id": "ACME"},
+                    "protocol": {"id": "SAML"}
+                }
+            }
+        }
+    }
+
+The returned token will contain information about the groups to which the federated
+user belongs.
+
+Example Identity API token response: [Various OpenStack token responses](identity-api-v3.md#authentication-responses)
+
+Example of an OS-FEDERATION token:
+
+    {
+        "token": {
+            "methods": [
+                "saml2"
+            ],
+            "user": {
+                "id": "username%40example.com",
+                "name": "username@example.com",
+                "OS-FEDERATION": {
+                    "identity_provider": {"id": "ACME"},
+                    "protocol": {"id": "SAML"}
+                },
+                "OS-FEDERATION:groups": [
+                    {"id": "abc123"},
+                    {"id": "bcd234"}
+                ]
+            }
+        }
+    }
+
+### Request a scoped OS-FEDERATION token: `POST /auth/tokens`
+
+A federated user may request a scoped token, by using the unscoped token.
+A project or domain may be specified by either id or name. An id is sufficient to
+uniquely identify a project or domain.
+
+Request Parameters:
+
+To authenticate with the OS-FEDERATION extension, `saml2` must be specified as an
+authentication method, and the unscoped token specified in the id field.
+
+Example request:
+
+    {
+        "auth": {
+            "identity": {
+                "methods": [
+                    "saml2"
+                ],
+                "saml2": {
+                    "id": "--federated-token-id--"
+                }
+            }
+        },
+        "scope": {
+            "project": {
+                "id": "263fd9"
+            }
+        }
+    }