Remove CAS login and reference it against r0.4.0

The SSO module should cover what CAS provides, and r0.4.0 is good as a reference for how CAS could be implemented without us repeating it here.
6 years ago · aeb524ef89
parent 510468a3b1
commit aeb524ef89
4 changed files with 18 additions and 218 deletions
--- a/api/client-server/cas_login_redirect.yaml
+++ b/api/client-server/cas_login_redirect.yaml
@ -1,54 +0,0 @@
 # Copyright 2016 OpenMarket Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
 swagger: '2.0'
 info:
  title: "Matrix Client-Server CAS Login API"
  version: "1.0.0"
 host: localhost:8008
 schemes:
  - https
  - http
 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 paths:
  "/login/cas/redirect":
    get:
      summary: Redirect the user's browser to the CAS interface.
      description: |-
        A web-based Matrix client should instruct the user's browser to
        navigate to this endpoint in order to log in via CAS.
        The server MUST respond with an HTTP redirect to the CAS interface. The
        URI MUST include a ``service`` parameter giving the path of the
        |/login/cas/ticket|_ endpoint (including the ``redirectUrl`` query
        parameter).
        For example, if the endpoint is called with
        ``redirectUrl=https://client.example.com/?q=p``, it might redirect to
        ``https://cas.example.com/?service=https%3A%2F%2Fserver.example.com%2F_matrix%2Fclient%2F%CLIENT_MAJOR_VERSION%%2Flogin%2Fcas%2Fticket%3FredirectUrl%3Dhttps%253A%252F%252Fclient.example.com%252F%253Fq%253Dp``.
      operationId: redirectToCAS
      parameters:
        - in: query
          type: string
          name: redirectUrl
          description: |-
            URI to which the user will be redirected after the homeserver has
            authenticated the user with CAS.
          required: true
      responses:
        302:
          description: A redirect to the CAS interface.
          headers:
            Location:
              type: "string"
--- a/api/client-server/cas_login_ticket.yaml
+++ b/api/client-server/cas_login_ticket.yaml
@ -1,66 +0,0 @@
 # Copyright 2016 OpenMarket Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
 swagger: '2.0'
 info:
  title: "Matrix Client-Server CAS Login API"
  version: "1.0.0"
 host: localhost:8008
 schemes:
  - https
  - http
 basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 paths:
  "/login/cas/ticket":
    get:
      summary: Receive and validate a CAS login ticket.
      description: |-
        Once the CAS server has authenticated the user, it will redirect the
        browser to this endpoint (assuming |/login/cas/redirect|_ gave it the
        correct ``service`` parameter).
        The server MUST call ``/proxyValidate`` on the CAS server, to validate
        the ticket supplied by the browser.
        If validation is successful, the server must generate a Matrix login
        token. It must then respond with an HTTP redirect to the URI given in
        the ``redirectUrl`` parameter, adding a ``loginToken`` query parameter
        giving the generated token.
        If validation is unsuccessful, the server should respond with a ``401
        Unauthorized`` error, the body of which will be displayed to the user.
      operationId: loginByCASTicket
      parameters:
        - in: query
          type: string
          name: redirectUrl
          description: |-
            The ``redirectUrl`` originally provided by the client to
            |/login/cas/redirect|_.
          required: true
        - in: query
          type: string
          name: ticket
          description: |-
            CAS authentication ticket.
          required: true
      responses:
        302:
          description: A redirect to the Matrix client.
          headers:
            Location:
              type: "string"
              x-example: |-
                 https://client.example.com/?q=p&loginToken=secrettoken
        401:
          description: The server was unable to validate the CAS ticket.
--- a/specification/client_server_api.rst
+++ b/specification/client_server_api.rst
@ -1024,12 +1024,6 @@ supports it, the client should redirect the user to the ``/redirect`` endpoint
 for `Single Sign-On <#sso-client-login>`_. After authentication is complete, the
 client will need to submit a ``/login`` request matching ``m.login.token``.
 If the homeserver advertises ``m.login.cas`` as a viable flow, and the client
 supports it, the client should redirect the user to the ``/redirect`` endpoint
 for `CAS <#cas-based-client-login>`_. Just like SSO authentication, the client
 is expected to submit a ``/login`` request matching ``m.login.token`` upon
 successful authentication.
 {{login_cs_http_api}}
 {{logout_cs_http_api}}
--- a/specification/modules/sso_login.rst
+++ b/specification/modules/sso_login.rst
@ -34,8 +34,17 @@ An overview of the process, as used in Matrix, is as follows:
 4. The SSO server and the homeserver interact to verify the user's identity
   and other authentication information, potentially using a number of redirects.
-7. The Matrix client receives the login token and passes it to the |/login|_
+5. The browser is directed to the ``redirectUrl`` provided by the client with
-   API.
+   a ``loginToken`` query parameter for the client to log in with.
 .. Note::
   In the older `r0.4.0 version <https://matrix.org/docs/spec/client_server/r0.4.0.html#cas-based-client-login>`_
   of this specification it was possible to authenticate via CAS when the server
   provides a ``m.login.cas`` login flow. This specification deprecates the use
   of ``m.login.cas`` to instead prefer ``m.login.sso``, which is the same process
   with the only change being which redirect endpoint to use: for ``m.login.cas``, use
   ``/cas/redirect`` and for ``m.login.sso`` use ``/sso/redirect`` (described below).
   The endpoints are otherwise the same.
 Client behaviour
 ----------------
@ -61,7 +70,11 @@ Server behaviour
 The URI for the SSO system to be used should be configured on the server by the
 server administrator. The server is expected to set up any endpoints required to
-interact with that SSO system.
+interact with that SSO system. For example, for CAS authentication the homeserver
 should provide a means for the administrator to configure where the CAS server is
 and the REST endpoints which consume the ticket. A good reference for how CAS could
 be implemented is available in the older `r0.4.0 version <https://matrix.org/docs/spec/client_server/r0.4.0.html#cas-based-client-login>`_
 of this specification.
 Handling the redirect endpoint
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -90,98 +103,11 @@ as a new user.
 Finally, the server should generate a short-term login token. The generated
 token should be a macaroon, suitable for use with the ``m.login.token`` type of
 the |/login|_ API, and `token-based interactive login <#token-based>`_. The
-lifetime of this token SHOULD be limited to around five seconds.
+lifetime of this token SHOULD be limited to around five seconds. This token is
-
+given to the client via the ``loginToken`` query parameter previously mentioned.
 CAS-based client login
 ----------------------
 .. _module:cas_login:
 `Central Authentication Service
 <https://github.com/apereo/cas/blob/master/docs/cas-server-documentation/protocol/CAS-Protocol-Specification.md>`_
 (CAS) is a web-based single sign-on protocol. The protocol defined here is an
 extension of the SSO protocol defined in this module: it is largely the same,
 but has some specific details which make it different.
 An overview of the process, as used in Matrix, is as follows:
 1. The Matrix client instructs the user's browser to navigate to the
   |/login/cas/redirect|_ endpoint on the user's homeserver.
 2. The homeserver responds with an HTTP redirect to the CAS user interface,
   which the browser follows.
 3. The CAS system authenticates the user.
 4. The CAS server responds to the user's browser with a redirect back to the
   |/login/cas/ticket|_ endpoint on the homeserver, which the browser
   follows. A 'ticket' identifier is passed as a query parameter in the
   redirect.
 5. The homeserver receives the ticket ID from the user's browser, and makes a
   request to the CAS server to validate the ticket.
 6. Having validated the ticket, the homeserver responds to the browser with a
   third HTTP redirect, back to the Matrix client application. A login token
   is passed as a query parameter in the redirect.
 7. The Matrix client receives the login token and passes it to the |/login|_
   API.
 Client behaviour
 ~~~~~~~~~~~~~~~~
 The client starts the process by instructing the browser to navigate to
 |/login/cas/redirect|_ with an appropriate ``redirectUrl``. Once authentication
 is successful, the browser will be redirected to that ``redirectUrl``.
 {{cas_login_redirect_cs_http_api}}
 {{cas_login_ticket_cs_http_api}}
 Server behaviour
 ~~~~~~~~~~~~~~~~
 The URI for the CAS system to be used should be configured on the server by the
 server administrator.
 Handling the redirect endpoint
 ++++++++++++++++++++++++++++++
 When responding to the ``/login/cas/redirect`` endpoint, the server must
 generate a URI for the CAS login page. The server should take the base CAS URI
 described above, and add a ``service`` query parameter. This parameter MUST be
 the URI of the ``/login/cas/ticket`` endpoint, including the ``redirectUrl``
 query parameter. Because the homeserver may not know its base URI, this may
 also require manual configuration.
 Handling the authentication endpoint
 ++++++++++++++++++++++++++++++++++++
 When responding to the ``/login/cas/ticket`` endpoint, the server MUST make a
 request to the CAS server to validate the provided ticket. The server MAY also
 check for certain user attributes in the response. Any required attributes
 should be configured by the server administrator.
 Once the ticket has been validated, the server MUST map the CAS ``user_id``
 to a valid `Matrix user identifier <../index.html#user-identifiers>`_. The
 guidance in `Mapping from other character sets
 <../index.html#mapping-from-other-character-sets>`_ may be useful.
 If the generated user identifier represents a new user, it should be registered
 as a new user.
 Finally, the server should generate a short-term login token. The generated
 token should be a macaroon, suitable for use with the ``m.login.token`` type of
 the |/login|_ API, and `token-based interactive login <#token-based>`_. The
 lifetime of this token SHOULD be limited to around five seconds.
 .. |/login| replace:: ``/login``
 .. _/login: #post-matrix-client-%CLIENT_MAJOR_VERSION%-login
 .. |/login/cas/redirect| replace:: ``/login/cas/redirect``
 .. _/login/cas/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-redirect
 .. |/login/cas/ticket| replace:: ``/login/cas/ticket``
 .. _/login/cas/ticket: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-ticket
 .. |/login/sso/redirect| replace:: ``/login/sso/redirect``
 .. _/login/sso/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-sso-redirect