Move Assertion API to its own file

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

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

Change-Id: I0ad565619744eb7f7b3c2fb33971d8d8ab4e22ea

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

@@ -304,94 +304,4 @@ to ``ss:mem:``.
 
 .. include:: federation/auth/auth.inc
 
-
-.. TODO(samueldmq): This is the Generating Assertions API, move it to its own
-   file.
-.. *New in version 1.1*
-
-Generate a SAML assertion
-=========================
-
-.. rest_method::  POST /v3/auth/OS-FEDERATION/saml2
-
-A user may generate a SAML assertion document based on the scoped token that is
-used in the request.
-
-Request Parameters:
-
-To generate a SAML assertion, a user must provides a scoped token ID and
-Service Provider ID in the request body.
-
-Request Example
----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/saml-assertion-request.json
-   :language: javascript
-
-The response will be a full SAML assertion. Note that for readability the
-certificate has been truncated. Server will also set two HTTP headers:
-``X-sp-url`` and ``X-auth-url``. The former is the URL where assertion should
-be sent, whereas the latter remote URL where token will be issued once the
-client is finally authenticated.
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/saml-assertion-response.xml
-   :language: xml
-
-For more information about how a SAML assertion is structured, refer to the
-`specification <http://saml.xml.org/saml-specifications>`__.
-
-Generate an ECP wrapped SAML assertion
-======================================
-
-.. rest_method::  POST /v3/auth/OS-FEDERATION/saml2/ecp
-
-A user may generate a SAML assertion document to work with the
-*Enhanced Client or Proxy* (ECP) profile based on the scoped token that is
-used in the request.
-
-Request Parameters:
-
-To generate an ECP wrapped SAML assertion, a user must provides a scoped token
-ID and Service Provider ID in the request body.
-
-Request Example
----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/ecp-saml-assertion-request.json
-   :language: javascript
-
-The response will be an ECP wrapped SAML assertion. Note that for readability
-the certificate has been truncated. Server will also set two HTTP headers:
-``X-sp-url`` and ``X-auth-url``. The former is the URL where assertion should
-be sent, whereas the latter remote URL where token will be issued once the
-client is finally authenticated.
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/ecp-saml-assertion-response.xml
-   :language: xml
-
-
-Retrieve Metadata properties
-============================
-
-.. rest_method::  GET /v3/OS-FEDERATION/saml2/metadata
-
-A user may retrieve Metadata about an Identity Service acting as an Identity
-Provider.
-
-The response will be a full document with Metadata properties. Note that for
-readability, this example certificate has been truncated.
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/OS-FEDERATION/metadata-response.xml
-   :language: xml
-
-For more information about how a SAML assertion is structured, refer to the
-`specification <http://saml.xml.org/saml-specifications>`__.
+.. include:: federation/assertion/assertion.inc

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

@@ -0,0 +1,90 @@
+.. -*- rst -*-
+
+*New in version 1.1*
+
+Generate a SAML assertion
+=========================
+
+.. rest_method::  POST /v3/auth/OS-FEDERATION/saml2
+
+A user may generate a SAML assertion document based on the scoped token that is
+used in the request.
+
+Request Parameters:
+
+To generate a SAML assertion, a user must provides a scoped token ID and
+Service Provider ID in the request body.
+
+Request Example
+---------------
+
+.. literalinclude:: federation/assertion/samples/saml-assertion-request.json
+   :language: javascript
+
+The response will be a full SAML assertion. Note that for readability the
+certificate has been truncated. Server will also set two HTTP headers:
+``X-sp-url`` and ``X-auth-url``. The former is the URL where assertion should
+be sent, whereas the latter remote URL where token will be issued once the
+client is finally authenticated.
+
+Response Example
+----------------
+
+.. literalinclude:: federation/assertion/samples/saml-assertion-response.xml
+   :language: xml
+
+For more information about how a SAML assertion is structured, refer to the
+`specification <http://saml.xml.org/saml-specifications>`__.
+
+Generate an ECP wrapped SAML assertion
+======================================
+
+.. rest_method::  POST /v3/auth/OS-FEDERATION/saml2/ecp
+
+A user may generate a SAML assertion document to work with the
+*Enhanced Client or Proxy* (ECP) profile based on the scoped token that is
+used in the request.
+
+Request Parameters:
+
+To generate an ECP wrapped SAML assertion, a user must provides a scoped token
+ID and Service Provider ID in the request body.
+
+Request Example
+---------------
+
+.. literalinclude:: federation/assertion/samples/ecp-saml-assertion-request.json
+   :language: javascript
+
+The response will be an ECP wrapped SAML assertion. Note that for readability
+the certificate has been truncated. Server will also set two HTTP headers:
+``X-sp-url`` and ``X-auth-url``. The former is the URL where assertion should
+be sent, whereas the latter remote URL where token will be issued once the
+client is finally authenticated.
+
+Response Example
+----------------
+
+.. literalinclude:: federation/assertion/samples/ecp-saml-assertion-response.xml
+   :language: xml
+
+
+Retrieve Metadata properties
+============================
+
+.. rest_method::  GET /v3/OS-FEDERATION/saml2/metadata
+
+A user may retrieve Metadata about an Identity Service acting as an Identity
+Provider.
+
+The response will be a full document with Metadata properties. Note that for
+readability, this example certificate has been truncated.
+
+Response Example
+----------------
+
+.. literalinclude:: federation/assertion/samples/metadata-response.xml
+   :language: xml
+
+For more information about how a SAML assertion is structured, refer to the
+`specification <http://saml.xml.org/saml-specifications>`__.

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

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