Move Federation Auth API to its own file

Change I2423030bd0849c051d22f63bf60b6a5f41f72574 migrated Federation
api-ref docs into keystone repository.

Moving Auth API to its own file is one of the TODO comments left there,
which is being addressed in this change.

Change-Id: Icd0c293c1a326c9bf3fe1ca01c96e3908ac33db3

api-ref/source/v3-ext/federation.inc

@@ -302,88 +302,7 @@ to ``ss:mem:``.
 
 .. include:: federation/projects-domains/projects-domains.inc
 
-
-.. TODO(samueldmq): This is the Federation Authentication API, move it to its
-   own file.
-
-Request an unscoped OS-FEDERATION token
-=======================================
-
-.. rest_method::  GET /v3/OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth
-
-A federated ephemeral user may request an unscoped token, which can be used to
-get a scoped token.
-
-If the user is mapped directly (mapped to an existing user), a standard,
-unscoped token will be issued.
-
-Due to the fact that this part of authentication is strictly connected with the
-SAML2 authentication workflow, a client should not send any data, as the
-content may be lost when a client is being redirected between Service Provider
-and Identity Provider. Both HTTP methods - GET and POST should be allowed as
-Web Single Sign-On (WebSSO) and Enhanced Client Proxy (ECP) mechanisms have
-different authentication workflows and use different HTTP methods while
-accessing protected endpoints.
-
-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>`__
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/unscoped-token-response.json
-   :language: javascript
-
-
-Request a scoped OS-FEDERATION token
-====================================
-
-.. rest_method::  POST /v3/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 Example
----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/scoped-token-request.json
-   :language: javascript
-
-Similarly to the returned unscoped token, the returned scoped token will have
-an ``OS-FEDERATION`` section added to the ``user`` portion of the token.
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/scoped-token-response.json
-   :language: javascript
-
-
-Web Single Sign On authentication (New in version 1.2)
-======================================================
-
-.. rest_method::  GET /v3/auth/OS-FEDERATION/websso/{protocol}?origin=https%3A//horizon.example.com
-
-For Web Single Sign On (WebSSO) authentication, users are expected to enter
-another URL endpoint. Upon successful authentication, instead of issuing a
-standard unscoped token, keystone will issue JavaScript code that redirects
-the web browser to the originating Horizon. An unscoped federated token will
-be included in the form being sent.
-
-
-Web Single Sign On authentication (New in version 1.3)
-======================================================
-
-.. rest_method::  GET /v3/auth/OS-FEDERATION/identity_providers/{idp_id}/protocol/{protocol_id}/websso?origin=https%3A//horizon.example.com
-
-In contrast to the above route, this route begins a Web Single Sign On request
-that is specific to the supplied Identity Provider and Protocol. Keystone will
-issue JavaScript that handles redirections in the same way as the other route.
-An unscoped federated token will be included in the form being sent.
+.. include:: federation/auth/auth.inc
 
 
 .. TODO(samueldmq): This is the Generating Assertions API, move it to its own

api-ref/source/v3-ext/federation/auth/auth.inc

@@ -0,0 +1,80 @@
+.. -*- rst -*-
+
+Request an unscoped OS-FEDERATION token
+=======================================
+
+.. rest_method::  GET /v3/OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth
+
+A federated ephemeral user may request an unscoped token, which can be used to
+get a scoped token.
+
+If the user is mapped directly (mapped to an existing user), a standard,
+unscoped token will be issued.
+
+Due to the fact that this part of authentication is strictly connected with the
+SAML2 authentication workflow, a client should not send any data, as the
+content may be lost when a client is being redirected between Service Provider
+and Identity Provider. Both HTTP methods - GET and POST should be allowed as
+Web Single Sign-On (WebSSO) and Enhanced Client Proxy (ECP) mechanisms have
+different authentication workflows and use different HTTP methods while
+accessing protected endpoints.
+
+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>`__
+
+Response Example
+----------------
+
+.. literalinclude:: federation/auth/samples/unscoped-token-response.json
+   :language: javascript
+
+
+Request a scoped OS-FEDERATION token
+====================================
+
+.. rest_method::  POST /v3/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 Example
+---------------
+
+.. literalinclude:: federation/auth/samples/scoped-token-request.json
+   :language: javascript
+
+Similarly to the returned unscoped token, the returned scoped token will have
+an ``OS-FEDERATION`` section added to the ``user`` portion of the token.
+
+Response Example
+----------------
+
+.. literalinclude:: federation/auth/samples/scoped-token-response.json
+   :language: javascript
+
+
+Web Single Sign On authentication (New in version 1.2)
+======================================================
+
+.. rest_method::  GET /v3/auth/OS-FEDERATION/websso/{protocol}?origin=https%3A//horizon.example.com
+
+For Web Single Sign On (WebSSO) authentication, users are expected to enter
+another URL endpoint. Upon successful authentication, instead of issuing a
+standard unscoped token, keystone will issue JavaScript code that redirects
+the web browser to the originating Horizon. An unscoped federated token will
+be included in the form being sent.
+
+
+Web Single Sign On authentication (New in version 1.3)
+======================================================
+
+.. rest_method::  GET /v3/auth/OS-FEDERATION/identity_providers/{idp_id}/protocol/{protocol_id}/websso?origin=https%3A//horizon.example.com
+
+In contrast to the above route, this route begins a Web Single Sign On request
+that is specific to the supplied Identity Provider and Protocol. Keystone will
+issue JavaScript that handles redirections in the same way as the other route.
+An unscoped federated token will be included in the form being sent.

api-ref/source/v3-ext/federation/auth/parameters.yaml

@@ -0,0 +1,7 @@
+# variables in header
+
+# variables in path
+
+# variables in query
+
+# variables in body