Merge pull request #395 from matrix-org/rav/kill_refresh_tokens

Remove references to refresh tokens and tokenrefresh

api/client-server/definitions/security.yaml

@@ -13,6 +13,6 @@
 # limitations under the License.
 accessToken:
   type: apiKey
-  description: The access_token returned by a call to ``/login`` or ``/tokenrefresh``
+  description: The access_token returned by a call to ``/login`` or ``/register``
   name: access_token
   in: query

api/client-server/login.yaml

@@ -90,15 +90,6 @@ paths:
                 description: |-
                   An access token for the account.
                   This access token can then be used to authorize other requests.
-                  The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
-                  There is no specific error message to indicate that a request has failed because
-                  an access token has expired; instead, if a client has reason to believe its
-                  access token is valid, and it receives an auth error, they should attempt to
-                  refresh for a new token on failure, and retry the request with the new token.
-              refresh_token:
-                type: string
-                description: |-
-                  Optional. A ``refresh_token`` may be exchanged for a new ``access_token`` using the |/tokenrefresh|_ API endpoint.
               home_server:
                 type: string
                 description: The hostname of the homeserver on which the account has been registered.
@@ -123,67 +114,3 @@ paths:
             "$ref": "definitions/error.yaml"
       tags:
         - Session management
-  "/tokenrefresh":
-    post:
-      summary: Exchanges a refresh token for an access token.
-      description: |-
-        Exchanges a refresh token for a new access token.
-        This is intended to be used if the access token has expired.
-
-        The server MUST invalidate the supplied ``refresh_token`` if the
-        request is successful. It MUST also invalidate the ``access_token``
-        which was issued at the same time as the ``refresh_token``, if it
-        has not already expired.
-      security:
-        - accessToken: []
-      parameters:
-        - in: body
-          name: body
-          schema:
-            type: object
-            example: |-
-              {
-                "refresh_token": "a1b2c3"
-              }
-            properties:
-              refresh_token:
-                type: string
-                description: The refresh token which was issued by the server.
-            required: ["refresh_token"]
-      responses:
-        200:
-          description: |-
-            The refresh token was accepted, and a new access token has been issued.
-            The passed refresh token is no longer valid and cannot be used.
-            A new refresh token will have been returned unless some policy does
-            not allow the user to continue to renew their session.
-          examples:
-            application/json: |-
-              {
-                "access_token": "bearwithme123",
-                "refresh_token": "exchangewithme987"
-              }
-          schema:
-            type: object
-            properties:
-              access_token:
-                type: string
-                description: |-
-                  An access token for the account.
-                  This access token can then be used to authorize other requests.
-                  The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
-              refresh_token:
-                type: string
-                description: Optional. A new ``refresh_token`` which may be exchanged for another new ``access_token``.
-        403:
-          description: |-
-            The exchange attempt failed. For example, the refresh token may have already been used.
-          examples:
-            application/json: |-
-              {"errcode": "M_FORBIDDEN"}
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-      tags:
-        - Session management

api/client-server/registration.yaml

@@ -39,6 +39,9 @@ paths:
 
         - `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.
 
+        If registration is successful, this endpoint will issue an access token
+        the client can use to authorize itself in subsequent requests.
+
       parameters:
         - in: query
           name: kind
@@ -90,8 +93,7 @@ paths:
               {
                 "user_id": "@cheeky_monkey:matrix.org",
                 "access_token": "abc123",
-                "home_server": "matrix.org",
+                "home_server": "matrix.org"
-                "refresh_token": "def456"
               }
           schema:
             type: object
@@ -104,16 +106,6 @@ paths:
                 description: |-
                   An access token for the account.
                   This access token can then be used to authorize other requests.
-                  The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
-                  There is no specific error message to indicate that a request has failed because
-                  an access token has expired; instead, if a client has reason to believe its
-                  access token is valid, and it receives an auth error, they should attempt to
-                  refresh for a new token on failure, and retry the request with the new token.
-              refresh_token:
-                type: string
-                # TODO: Work out how to linkify /tokenrefresh
-                description: |-
-                  (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
               home_server:
                 type: string
                 description: The hostname of the homeserver on which the account has been registered.

changelogs/client_server.rst

@@ -8,23 +8,11 @@
     which support push rules, but any other clients implementing
     the push rules API should be aware of this change. This
     makes it simple to mute rooms correctly in the API.
-
+    (`#373 <https://github.com/matrix-org/matrix-doc/pull/373>`_).
-- Spec clarifications:
+  - Remove ``/tokenrefresh`` from the API.
-
+    (`#395 <https://github.com/matrix-org/matrix-doc/pull/395>`_).
-  - Spell out the way that state is handled by ``POST /createRoom``
+  - Remove requirement that tokens used in token-based login be macaroons.
-    (`#362 <https://github.com/matrix-org/matrix-doc/pull/362>`_).
+    (`#395 <https://github.com/matrix-org/matrix-doc/pull/395>`_).
-  - Emphasise that ``POST /tokenrefresh`` should expire the access token
-    (`#363 <https://github.com/matrix-org/matrix-doc/pull/363>`_).
-  - Clarify the fields which are applicable to different types of push rule
-    (`#365 <https://github.com/matrix-org/matrix-doc/pull/365>`_).
-  - A number of clarifications to authentication
-    (`#371 <https://github.com/matrix-org/matrix-doc/pull/371>`_).
-  - Correct references to ``user_id`` which should have been ``sender``
-    (`#376 <https://github.com/matrix-org/matrix-doc/pull/376>`_).
-  - Correct inconsistent specification of ``redacted_because`` fields and their
-    values (`#378 <https://github.com/matrix-org/matrix-doc/pull/378>`_).
-  - Mark required fields in response objects as such
-    (`#394 <https://github.com/matrix-org/matrix-doc/pull/394>`_).
 
 - Changes to the API which will be backwards-compatible for clients:
 
@@ -44,6 +32,21 @@
   - Add "Send-to-Device messaging" module
     (`#386 <https://github.com/matrix-org/matrix-doc/pull/386>`_).
 
+- Spec clarifications:
+
+  - Spell out the way that state is handled by ``POST /createRoom``
+    (`#362 <https://github.com/matrix-org/matrix-doc/pull/362>`_).
+  - Clarify the fields which are applicable to different types of push rule
+    (`#365 <https://github.com/matrix-org/matrix-doc/pull/365>`_).
+  - A number of clarifications to authentication
+    (`#371 <https://github.com/matrix-org/matrix-doc/pull/371>`_).
+  - Correct references to ``user_id`` which should have been ``sender``
+    (`#376 <https://github.com/matrix-org/matrix-doc/pull/376>`_).
+  - Correct inconsistent specification of ``redacted_because`` fields and their
+    values (`#378 <https://github.com/matrix-org/matrix-doc/pull/378>`_).
+  - Mark required fields in response objects as such
+    (`#394 <https://github.com/matrix-org/matrix-doc/pull/394>`_).
+
 r0.2.0
 ======
 

specification/client_server_api.rst

@@ -158,14 +158,23 @@ recommended.
 
 Client Authentication
 ---------------------
+
 Most API endpoints require the user to identify themselves by presenting
 previously obtained credentials in the form of an ``access_token`` query
-parameter.
+parameter. An access token is typically obtained via the `Login`_ or
+`Registration`_ processes.
 
 When credentials are required but missing or invalid, the HTTP call will
 return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or
 ``M_UNKNOWN_TOKEN`` respectively.
 
+.. NOTE::
+
+   This specification does not mandate a particular format for the access
+   token. Clients should treat it as an opaque byte sequence. Servers are free
+   to choose an appropriate format. Server implementors may like to investigate
+   `macaroons <macaroon_>`_.
+
 User-Interactive Authentication API
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -460,8 +469,8 @@ server side, as well as potentially invalidating the token completely once the
 device has successfully logged in (e.g. when we receive a request from the
 newly provisioned access_token).
 
-The ``token`` must be a macaroon, with a caveat encoding the user id. There is
+The server must encode the user id in the ``token``. There is therefore no need
-therefore no need for the client to submit a separate username.
+for the client to submit a separate username.
 
 OAuth2-based
 <<<<<<<<<<<<
@@ -595,9 +604,9 @@ follows:
     "token": "<login token>"
   }
 
-As with `token-based`_ interactive login, the ``token`` must be a macroon with
+As with `token-based`_ interactive login, the ``token`` must encode the
-a caveat which includes the user id. In the case that the token is not valid, the
+user id. In the case that the token is not valid, the homeserver must respond
-homeserver must respond with ``403 Forbidden`` and an error code of ``M_FORBIDDEN``.
+with ``403 Forbidden`` and an error code of ``M_FORBIDDEN``.
 
 {{login_cs_http_api}}
 
@@ -615,6 +624,8 @@ This returns an HTML and JavaScript page which can perform the entire login
 process. The page will attempt to call the JavaScript function
 ``window.onLogin`` when login has been successfully completed.
 
+.. _Registration:
+
 Account registration and management
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1230,6 +1241,9 @@ have to wait in milliseconds before they can try again.
     homeserver come up with their own idea, causing totally unpredictable performance over
     federated rooms?
 
+.. References
+
+.. _`macaroon`: http://research.google.com/pubs/pub41892.html
 
 .. Links through the external API docs are below
 .. =============================================
@@ -1237,9 +1251,6 @@ have to wait in milliseconds before they can try again.
 .. |/initialSync| replace:: ``/initialSync``
 .. _/initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-initialsync
 
-.. |/tokenrefresh| replace:: ``/tokenrefresh``
-.. _/tokenrefresh: #post-matrix-client-%CLIENT_MAJOR_VERSION%-tokenrefresh
-
 .. |/sync| replace:: ``/sync``
 .. _/sync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-sync