Remove references to refresh tokens and tokenrefresh

refresh tokens are dead.
8 years ago · f4c7fdfd03
parent 1f45724bfd
commit f4c7fdfd03
5 changed files with 46 additions and 113 deletions
--- a/api/client-server/definitions/security.yaml
+++ b/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
--- a/api/client-server/login.yaml
+++ b/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
--- a/api/client-server/registration.yaml
+++ b/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",
-                "refresh_token": "def456"
+                "home_server": "matrix.org"
              }
          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.
--- a/changelogs/client_server.rst
+++ b/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.
-
- Spec clarifications:
-
-  - Spell out the way that state is handled by ``POST /createRoom``
-    (`#362 <https://github.com/matrix-org/matrix-doc/pull/362>`_).
-  - 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>`_).
+    (`#373 <https://github.com/matrix-org/matrix-doc/pull/373>`_).
+  - Remove ``/tokenrefresh`` from the API.
+    (`#395 <https://github.com/matrix-org/matrix-doc/pull/395>`_).
+  - Remove requirement that tokens used in token-based login be macaroons.
+    (`#395 <https://github.com/matrix-org/matrix-doc/pull/395>`_).

 - Changes to the API which will be backwards-compatible for clients:

@ -42,6 +30,21 @@
  - Add ``filter`` optional query param to ``/messages``
    (`#390 <https://github.com/matrix-org/matrix-doc/pull/390>`_).

+- 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
 ======

--- a/specification/client_server_api.rst
+++ b/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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

@ -249,7 +258,7 @@ complete auth type ``example.type.foo``, it might submit something like this:

  POST /_matrix/client/r0/endpoint HTTP/1.1
  Content-Type: application/json
-  
+
  {
    "a_request_parameter": "something",
    "another_request_parameter": "something else",
@ -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
-therefore no need for the client to submit a separate username.
+The server must encode the user id in the ``token``. There is therefore no need
+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
-a caveat which includes the user id. In the case that the token is not valid, the
-homeserver must respond with ``403 Forbidden`` and an error code of ``M_FORBIDDEN``.
+As with `token-based`_ interactive login, the ``token`` must encode the
+user id. In the case that the token is not valid, the homeserver must respond
+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