Merge "Add documentation for Auth Receipts and MFA"

6 files changed, 367 insertions, 3 deletions

diff --git a/api-ref/source/v3/authenticate-v3.inc b/api-ref/source/v3/authenticate-v3.inc
index 45d3f58f8..6e3cc62ab 100644
--- a/api-ref/source/v3/authenticate-v3.inc
+++ b/api-ref/source/v3/authenticate-v3.inc
@@ -10,7 +10,7 @@ optionally, grants authorization on a specific project, domain, or the
 deployment system.
 
 The body of an authentication request must include a payload that
-specifies the authentication method, which is ``password`` or
+specifies the authentication methods, which are normally just ``password`` or
 ``token``, the credentials, and, optionally, the authorization
 scope. You can scope a token to a project, domain, the deployment system, or
 the token can be unscoped. You cannot scope a token to multiple scope targets.
@@ -18,6 +18,16 @@ the token can be unscoped. You cannot scope a token to multiple scope targets.
 Tokens have IDs, which the Identity API returns in the
 ``X-Subject-Token`` response header.
 
+In the case of multi-factor authentication (MFA) more than one authentication
+method needs to be supplied to authenticate. As of v3.12 a failure due to MFA
+rules only partially being met will result in an auth receipt ID being returned
+in the response header ``Openstack-Auth-Receipt``, and a response body that
+details the receipt itself and the missing authentication methods. Supplying
+the auth receipt ID in the ``Openstack-Auth-Receipt`` header in a follow-up
+authentication request, with the missing authentication methods, will result in
+a valid token by reusing the successful methods from the first request. This
+allows MFA authentication to be a multi-step process.
+
 After you obtain an authentication token, you can:
 
 - Make REST API requests to other OpenStack services. You supply the
@@ -74,6 +84,10 @@ These authentication errors can occur:
 |                        | - The specified ``X-Auth-Token`` header is not valid.                |
 |                        |                                                                      |
 |                        | - The authentication credentials are not valid.                      |
+|                        |                                                                      |
+|                        | - Not all MFA rules were satisfied.                                  |
+|                        |                                                                      |
+|                        | - The specified ``Openstack-Auth-Receipt`` header is not valid.      |
 +------------------------+----------------------------------------------------------------------+
 | ``Forbidden (403)``    | The identity was successfully authenticated but it is not            |
 |                        | authorized to perform the requested action.                          |
@@ -621,6 +635,168 @@ Example
    :language: javascript
 
 
+Multi-Step authentication (2-Factor Password and TOTP example)
+==============================================================
+
+.. rest_method::  POST /v3/auth/tokens
+
+Authenticates an identity and generates a token. Uses the password
+authentication method, then the totp method, with an auth receipt in between.
+
+This assumes that MFA has been enabled for the user, and a rule has been
+defined requiring authentication with both password and totp.
+
+The first request body must at least include a payload that specifies one of
+``password`` or ``totp`` authentication methods which includes the credentials
+in addition to an optional scope. If only one method is supplied then an auth
+receipt will be returned. Scope is not retained in the receipt and must be
+resupplied in subsequent requests.
+
+While it is very possible to supply all the required auth methods at once, this
+example shows the multi-step process which is likely to be more common.
+
+More than 2 factors can be used but the same process applies to those as well;
+either all auth methods are supplied at once, or in steps with one or more auth
+receipts in between.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens``
+
+First Request
+-------------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+  - nocatalog: nocatalog
+  - name: user_name
+  - auth: auth
+  - user: user
+  - scope: scope_string
+  - password: password
+  - id: user_id
+  - identity: identity
+  - methods: auth_methods_passwd
+
+Example
+~~~~~~~
+
+.. literalinclude:: ./samples/auth/requests/project-id-password.json
+   :language: javascript
+
+Response
+--------
+
+Here we are expecting a 401 status, and a returned auth receipt.
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+  - Openstack-Auth-Receipt: Openstack-Auth-Receipt
+  - methods: auth_methods_receipt
+  - expires_at: receipt_expires_at
+  - issued_at: receipt_issued_at
+  - user: user
+  - required_auth_methods: required_auth_methods
+
+Status Code
+~~~~~~~~~~~
+
+.. rest_status_code:: success status.yaml
+
+  - 401: auth_receipt
+
+.. rest_status_code:: error status.yaml
+
+  - 400
+  - 401: auth_failed
+  - 403
+  - 404
+
+Auth Receipt Example
+~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ./samples/auth/responses/auth-receipt-password.json
+   :language: javascript
+
+Second Request
+--------------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+  - Openstack-Auth-Receipt: Openstack-Auth-Receipt
+  - nocatalog: nocatalog
+  - name: user_name
+  - auth: auth
+  - user: user
+  - scope: scope_string
+  - totp: totp
+  - id: user_id
+  - identity: identity
+  - methods: auth_methods_totp
+
+Example
+~~~~~~~
+
+.. literalinclude:: ./samples/auth/requests/project-id-totp.json
+   :language: javascript
+
+Response
+--------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+  - X-Subject-Token: X-Subject-Token
+  - region_id: region_id_required
+  - methods: auth_methods_passwd
+  - roles: roles
+  - url: endpoint_url
+  - region: endpoint_region
+  - token: token
+  - expires_at: expires_at
+  - system: system_scope_response_body_optional
+  - domain: domain_scope_response_body_optional
+  - project: project_scope_response_body_optional
+  - issued_at: issued_at
+  - catalog: catalog
+  - user: user
+  - audit_ids: audit_ids
+  - interface: endpoint_interface
+  - endpoints: endpoints
+  - type: endpoint_type
+  - id: user_id
+  - name: user_name
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success status.yaml
+
+  - 201
+
+.. rest_status_code:: error status.yaml
+
+  - 400
+  - 401: auth_receipt_failure
+  - 403
+  - 404
+
+Project-Scoped Password and TOTP Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ./samples/auth/responses/project-scoped-password-totp.json
+  :language: javascript
+
+
 Validate and show information for token
 =======================================
 
diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index 30b649e1f..e34b425cb 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/api-ref/source/v3/parameters.yaml
@@ -1,4 +1,12 @@
 # variables in header
+Openstack-Auth-Receipt:
+  description: |
+    The auth receipt.  A partially successful authentication
+    response returns the auth receipt ID in this header rather than in the
+    response body.
+  in: header
+  required: true
+  type: string
 X-Auth-Token:
   description: |
     A valid authentication token for an
@@ -477,8 +485,8 @@ auth_domain:
   type: object
 auth_methods:
   description: |
-    The authentication method, which is ``password``,
-    ``token``, or both methods.  Indicates the accumulated set of
+    The authentication methods, which are commonly ``password``,
+    ``token``, or other methods.  Indicates the accumulated set of
     authentication methods that were used to obtain the token. For
     example, if the token was obtained by password authentication, it
     contains ``password``. Later, if the token is exchanged by using
@@ -506,6 +514,19 @@ auth_methods_passwd:
   in: body
   required: true
   type: array
+auth_methods_receipt:
+  description: |
+    The authentication methods, which are commonly ``password``,
+    ``totp``, or other methods.  Indicates the accumulated set of
+    authentication methods that were used to obtain the receipt. For
+    example, if the receipt was obtained by password authentication, it
+    contains ``password``. Later, if the receipt is exchanged by using
+    another authentication method one or more times, the
+    subsequently created receipts could contain both ``password`` and
+    ``totp`` in their ``methods`` attribute.
+  in: body
+  required: true
+  type: array
 auth_methods_token:
   description: |
     The authentication method. For token
@@ -513,6 +534,13 @@ auth_methods_token:
   in: body
   required: true
   type: array
+auth_methods_totp:
+  description: |
+    The authentication method. For totp
+    authentication, specify ``totp``.
+  in: body
+  required: true
+  type: array
 auth_token:
   description: |
     A ``token`` object. The token authentication
@@ -1433,6 +1461,38 @@ projects:
   in: body
   required: true
   type: array
+receipt_expires_at:
+  description: |
+    The date and time when the receipt expires.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss.sssZ
+
+    For example, ``2015-08-27T09:49:58.000000Z``.
+
+    A ``null`` value indicates that the receipt never expires.
+  in: body
+  required: true
+  type: string
+receipt_issued_at:
+  description: |
+    The date and time when the receipt was issued.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss.sssZ
+
+    For example, ``2015-08-27T09:49:58.000000Z``.
+  in: body
+  required: true
+  type: string
 region_id_not_required:
   description: |
     (Since v3.2) The ID of the region that contains
@@ -1604,6 +1664,13 @@ request_service_id_registered_limit_body_not_required:
   in: body
   required: false
   type: string
+required_auth_methods:
+  description: |
+    A list of authentication rules that may be used with the auth receipt
+    to complete the authentication process.
+  in: body
+  required: true
+  type: list of lists
 resource_limit:
   description: |
     The override limit.
@@ -1909,6 +1976,12 @@ token:
   in: body
   required: true
   type: object
+totp:
+  description: |
+    The ``totp`` object, contains the authentication information.
+  in: body
+  required: true
+  type: object
 user:
   description: |
     A ``user`` object.
diff --git a/api-ref/source/v3/samples/auth/requests/project-id-totp.json b/api-ref/source/v3/samples/auth/requests/project-id-totp.json
new file mode 100644
index 000000000..fdfcc971e
--- /dev/null
+++ b/api-ref/source/v3/samples/auth/requests/project-id-totp.json
@@ -0,0 +1,20 @@
+{
+    "auth": {
+        "identity": {
+            "methods": [
+                "totp"
+            ],
+            "totp": {
+                "user": {
+                    "id": "ee4dfb6e5540447cb3741905149d9b6e",
+                    "passcode": "123456"
+                }
+            }
+        },
+        "scope": {
+            "project": {
+                "id": "a6944d763bf64ee6a275f1263fae0352"
+            }
+        }
+    }
+}
diff --git a/api-ref/source/v3/samples/auth/responses/auth-receipt-password.json b/api-ref/source/v3/samples/auth/responses/auth-receipt-password.json
new file mode 100644
index 000000000..40f64f87f
--- /dev/null
+++ b/api-ref/source/v3/samples/auth/responses/auth-receipt-password.json
@@ -0,0 +1,20 @@
+{
+    "receipt":{
+        "expires_at":"2018-07-05T08:39:23.000000Z",
+        "issued_at":"2018-07-05T08:34:23.000000Z",
+        "methods": [
+            "password"
+        ],
+        "user": {
+            "domain": {
+                "id": "default",
+                "name": "Default"
+            },
+            "id": "ee4dfb6e5540447cb3741905149d9b6e",
+            "name": "admin"
+        }
+    },
+    "required_auth_methods": [
+        ["totp", "password"]
+    ]
+}
diff --git a/api-ref/source/v3/samples/auth/responses/project-scoped-password-totp.json b/api-ref/source/v3/samples/auth/responses/project-scoped-password-totp.json
new file mode 100644
index 000000000..6b84e3efe
--- /dev/null
+++ b/api-ref/source/v3/samples/auth/responses/project-scoped-password-totp.json
@@ -0,0 +1,67 @@
+{
+    "token": {
+        "audit_ids": [
+            "3T2dc1CGQxyJsHdDu1xkcw"
+        ],
+        "catalog": [
+            {
+                "endpoints": [
+                    {
+                        "id": "068d1b359ee84b438266cb736d81de97",
+                        "interface": "public",
+                        "region": "RegionOne",
+                        "region_id": "RegionOne",
+                        "url": "http://example.com/identity"
+                    },
+                    {
+                        "id": "8bfc846841ab441ca38471be6d164ced",
+                        "interface": "admin",
+                        "region": "RegionOne",
+                        "region_id": "RegionOne",
+                        "url": "http://example.com/identity"
+                    },
+                    {
+                        "id": "beb6d358c3654b4bada04d4663b640b9",
+                        "interface": "internal",
+                        "region": "RegionOne",
+                        "region_id": "RegionOne",
+                        "url": "http://example.com/identity"
+                    }
+                ],
+                "type": "identity",
+                "id": "050726f278654128aba89757ae25950c",
+                "name": "keystone"
+            }
+        ],
+        "expires_at": "2015-11-07T02:58:43.578887Z",
+        "is_domain": false,
+        "issued_at": "2015-11-07T01:58:43.578929Z",
+        "methods": [
+            "password",
+            "totp"
+        ],
+        "project": {
+            "domain": {
+                "id": "default",
+                "name": "Default"
+            },
+            "id": "a6944d763bf64ee6a275f1263fae0352",
+            "name": "admin"
+        },
+        "roles": [
+            {
+                "id": "51cc68287d524c759f47c811e6463340",
+                "name": "admin"
+            }
+        ],
+        "user": {
+            "domain": {
+                "id": "default",
+                "name": "Default"
+            },
+            "id": "ee4dfb6e5540447cb3741905149d9b6e",
+            "name": "admin",
+            "password_expires_at": "2016-11-06T15:32:17.000000"
+        }
+    }
+}
diff --git a/api-ref/source/v3/status.yaml b/api-ref/source/v3/status.yaml
index 4cecc2ceb..e026069ac 100644
--- a/api-ref/source/v3/status.yaml
+++ b/api-ref/source/v3/status.yaml
@@ -27,6 +27,14 @@
 401:
   default: |
     User must authenticate before making a request.
+  auth_failed: |
+    Authentication attempt has failed.
+  auth_receipt: |
+    User has successfully supplied some auth methods, but not enough for full
+    authentication.
+  auth_receipt_failure: |
+    Authentication attempt has failed. Either the auth receipt has expired, or
+    the additional auth methods supplied were invalid.
 403:
   default: |
     Policy does not allow current user to do this operation.