diff --git a/api/client-server/definitions/security.yaml b/api/client-server/definitions/security.yaml index 0668eb95..bb78f0e3 100644 --- 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 diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml index 3ca397ea..7731f507 100644 --- 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 diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 6da04d45..8145824e 100644 --- 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. diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index da9a0ff2..60d2de17 100644 --- 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 `_). - - Emphasise that ``POST /tokenrefresh`` should expire the access token - (`#363 `_). - - Clarify the fields which are applicable to different types of push rule - (`#365 `_). - - A number of clarifications to authentication - (`#371 `_). - - Correct references to ``user_id`` which should have been ``sender`` - (`#376 `_). - - Correct inconsistent specification of ``redacted_because`` fields and their - values (`#378 `_). - - Mark required fields in response objects as such - (`#394 `_). + (`#373 `_). + - Remove ``/tokenrefresh`` from the API. + (`#395 `_). + - Remove requirement that tokens used in token-based login be macaroons. + (`#395 `_). - Changes to the API which will be backwards-compatible for clients: @@ -44,6 +32,21 @@ - Add "Send-to-Device messaging" module (`#386 `_). +- Spec clarifications: + + - Spell out the way that state is handled by ``POST /createRoom`` + (`#362 `_). + - Clarify the fields which are applicable to different types of push rule + (`#365 `_). + - A number of clarifications to authentication + (`#371 `_). + - Correct references to ``user_id`` which should have been ``sender`` + (`#376 `_). + - Correct inconsistent specification of ``redacted_because`` fields and their + values (`#378 `_). + - Mark required fields in response objects as such + (`#394 `_). + r0.2.0 ====== diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 6eb24823..77dc90b6 100644 --- 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 `_. + 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": "" } -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