Merge lp:~cjwatson/canonical-identity-provider/doc-macaroons into lp:canonical-identity-provider/release

[Colin Watson]

Document macaroon API endpoints.

[Matias Bordese (matiasb)]

LGTM

review: Approve

=== modified file 'docs/resources/token.txt'
--- docs/resources/token.txt	2013-12-04 13:49:39 +0000
+++ docs/resources/token.txt	2018-05-01 12:22:58 +0000
@@ -11,6 +11,7 @@
 
 * :ref:`OAuth token <token_oauth>`
 * :ref:`Password reset token <token_password>`
+* :ref:`Macaroon <macaroon>`
 
 
 .. _token_oauth:
@@ -71,7 +72,7 @@
 existing token will be returned (status code 200) instead of a new one being
 created (status code 201).
 
-If an otp (one-time-password) is provided then it will checked against any
+If an otp (one-time-password) is provided then it will be checked against any
 two factor devices registered for the account. If the otp does not match any
 devices then a 403 will be returned.
 
@@ -338,3 +339,290 @@
      "message": "Too many non-consumed tokens exist. Further token creation is not allowed until existing tokens are consumed.",
      "extra": {}
    }
+
+
+.. _macaroon:
+
+========
+Macaroon
+========
+
+A `macaroon` is a bearer token with fine-grained constraints.  See the
+`original paper <https://research.google.com/pubs/pub41892.html>`_ for
+details.
+
+Ubuntu SSO issues discharge macaroons, which can be bound to macaroons
+issued by other cooperating services to prove the user's identity.
+
+Use cases
+=========
+
+.. _macaroon_discharge:
+
+Issue a discharge macaroon
+--------------------------
+
+.. http:post:: /api/v2/tokens/discharge
+
+    Issues a new discharge macaroon
+
+    :form email: user's email address
+    :form password: user's password
+    :form caveat_id: the caveat ID addressed to Ubuntu SSO from the macaroon that is to be discharged
+    :form otp: one-time password (optional)
+
+    :status 200: macaroon issued
+    :status 400: invalid request data
+    :status 401: invalid credentials or otp password required
+    :status 403: invalid otp provided
+    :status 403: account is suspended or inactive
+    :status 403: email invalidated
+    :status 403: password does not meet security constraints
+
+The service that issued the macaroon that this discharge is to be bound to
+should have included a caveat in that macaroon addressed to Ubuntu SSO.  To
+issue an appropriate discharge macaroon, the caller must extract the ID of
+this caveat.  This can be done in Python as follows:
+
+.. code-block:: python
+
+   from pymacaroons import Macaroon
+
+   def extract_caveat_id(macaroon_raw):
+       macaroon = Macaroon.deserialize(macaroon_raw)
+       for caveat in macaroon.caveats:
+           if caveat.location == 'login.ubuntu.com':
+               return caveat.caveat_id
+       else:
+           raise ValueError('No login.ubuntu.com caveat found')
+
+If an otp (one-time-password) is provided then it will be checked against any
+two factor devices registered for the account. If the otp does not match any
+devices then a 403 will be returned.
+
+If an otp is required for the account, but not sent, then a 401 will be
+returned.
+
+
+Errors
+......
+
+* **INVALID_CREDENTIALS**: Provided email/password is not correct.
+
+  Error status code 401.
+
+  This error has no additional fields in ``extra``.
+
+* **ACCOUNT_SUSPENDED**: Account has been suspended.
+
+  Error status code 403.
+
+  This error has no additional fields in ``extra``.
+
+* **ACCOUNT_DEACTIVATED**: Account has been deactivated.
+
+  Error status code 403.
+
+  This error has no additional fields in ``extra``.
+
+* **EMAIL_INVALIDATED**: This email address has been invalidated.
+
+  Error status code 403.
+
+  This error has no additional fields in ``extra``.
+
+* **TWOFACTOR_REQUIRED**: 2-factor authentication required.
+
+  Error status code 401.
+
+  This error has no additional fields in ``extra``.
+
+* **TWOFACTOR_FAILURE**: The provided 2-factor key is not recognised.
+
+  Error status code 403.
+
+  This error has no additional fields in ``extra``.
+
+* **PASSWORD_POLICY_ERROR**: The user's password doesn't comply with the
+  security constraints in force for the account. It must be reset via the
+  web.
+
+  Error status code 403.
+
+  The ``extra`` field includes:
+
+  - ``location``: the domain to visit via the web to reset the password
+
+  - ``reason``: the reason why the password doesn't comply with the policy
+
+* **TOO_MANY_REQUESTS**: Too many requests from the same IP address.
+
+  Error status code 429.
+
+  This error has no additional fields in ``extra``.
+
+
+Examples
+........
+
+**Request**:
+
+.. sourcecode:: http
+
+   POST /api/v2/tokens/discharge HTTP/1.1
+   Host: login.ubuntu.com
+   Accept: application/json
+   Content-Type: application/json
+
+   {
+     "email": "[e-mail]",
+     "password": "thepassword",
+     "caveat_id": "{\"secret\": \"thesecret\", \"version\": 1}"
+   }
+
+If 2-factor authentication is required:
+
+.. sourcecode:: http
+
+   POST /api/v2/tokens/discharge HTTP/1.1
+   Host: login.ubuntu.com
+   Accept: application/json
+   Content-Type: application/json
+
+   {
+     "email": "[e-mail]",
+     "password": "the-password",
+     "caveat_id": "{\"secret\": \"the-secret\", \"version\": 1}",
+     "otp": "123456"
+   }
+
+**Response**:
+
+.. sourcecode:: http
+
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+
+   {
+     "discharge_macaroon": "the-macaroon"
+   }
+
+If credentials don't match:
+
+.. sourcecode:: http
+
+   HTTP/1.1 401 UNAUTHORIZED
+   Content-Type: application/json
+
+   {
+     "error_list": [
+       {
+         "code": "invalid-credentials",
+         "message": "Provided email/password is not correct."
+       }
+     ]
+   }
+
+If 2-factor authentication is required:
+
+.. sourcecode:: http
+
+   HTTP/1.1 401 UNAUTHORIZED
+   Content-Type: application/json
+
+   {
+     "error_list": [
+       {
+         "code": "twofactor-required",
+         "message": "2-factor authentication required."
+       }
+     ]
+   }
+
+
+.. _macaroon_refresh:
+
+Refresh a discharge macaroon
+----------------------------
+
+.. http:post:: /api/v2/tokens/refresh
+
+    Refreshes a discharge macaroon
+
+    :form discharge_macaroon: the serialized macaroon to be refreshed
+
+    :status 200: macaroon refreshed
+    :status 400: invalid request data
+    :status 401: discharge macaroon does not verify
+    :status 403: account is inactive
+
+Discharge macaroons are time-limited and must eventually be refreshed.  The
+need for this will be indicated by an error response from the cooperating
+service.  When this happens, the caller should send the old discharge
+macaroon to this endpoint, which will issue a refreshed version if the
+original credentials are still valid.
+
+Among other reasons, the discharge macaroon may fail to verify if the user's
+password has changed since it was issued.  In this case, the caller must
+:ref:`request a new discharge macaroon <macaroon_discharge>`.
+
+
+Errors
+......
+
+* **INVALID_CREDENTIALS**: The provided discharge macaroon is invalid, or
+  the user's password has changed since the discharge macaroon was issued.
+
+  Error status code 401.
+
+  This error has no additional fields in ``extra``.
+
+* **ACCOUNT_DEACTIVATED**: Account has been deactivated.
+
+  Error status code 403.
+
+  This error has no additional fields in ``extra``.
+
+
+Examples
+........
+
+**Request**:
+
+.. sourcecode:: http
+
+   POST /api/v2/tokens/refresh HTTP/1.1
+   Host: login.ubuntu.com
+   Accept: application/json
+   Content-Type: application/json
+
+   {
+     "discharge_macaroon": "the-old-macaroon"
+   }
+
+**Response**:
+
+.. sourcecode:: http
+
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+
+   {
+     "discharge_macaroon": "the-new-macaroon"
+   }
+
+If the user's password has changed:
+
+.. sourcecode:: http
+
+   HTTP/1.1 401 UNAUTHORIZED
+   Content-Type: application/json
+
+   {
+     "error_list": [
+       {
+         "code": "invalid-credentials",
+         "message": "Provided email/password is not correct."
+       }
+     ]
+   }