document CAS login

Following the spirit of "document how it is, not how we wish it was", document
the CAS login bits.

api/client-server/cas_login_redirect.yaml

@@ -0,0 +1,53 @@
+# 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``.
+
+      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"

api/client-server/cas_login_ticket.yaml

@@ -0,0 +1,65 @@
+# 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.
+      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: |-
+                 redirectUrl=https://client.example.com/?hs=https%3A%2F%2Fserver.example.com&loginToken=secrettoken
+        401:
+          description: The server was unable to validate the CAS ticket.

api/client-server/login.yaml

@@ -47,7 +47,9 @@ paths:
             properties:
               type:
                 type: string
-                description: The login type being used. Currently only "m.login.password" is supported.
+                description: |-
+                  The login type being used. One of ``m.login.password`` or
+                  ``m.login.token``.
               user:
                 type: string
                 description: The fully qualified user ID or just local part of the user ID, to log in.
@@ -59,8 +61,14 @@ paths:
                 description: Third party identifier for the user.
               password:
                 type: string
-                description: The user's password.
+                description: |-
-            required: ["type", "password"]
+                  Required when ``type`` is ``m.login.password``. The user's
+                  password.
+              token:
+                type: string
+                description: |-
+                  Required when ``type`` is ``m.login.token``. The login token.
+            required: ["type"]
 
       responses:
         200:

specification/client_server_api.rst

@@ -554,6 +554,15 @@ explicitly, as follows:
 In the case that the homeserver does not know about the supplied 3pid, the
 homeserver must respond with 403 Forbidden.
 
+To log in using a login token, a client should submit an auth dict as follows:
+
+.. code:: json
+
+  {
+    "type": "m.login.token",
+    "token": "<login token>"
+  }
+
 {{login_cs_http_api}}
 
 {{logout_cs_http_api}}

specification/modules/cas_login.rst

@@ -0,0 +1,65 @@
+.. 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.
+
+CAS-based client login
+======================
+
+.. _module:cas_login:
+
+Central Authentication Service (CAS) is a web-based single sign-on protocol.
+
+Client behaviour
+----------------
+
+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.
+
+If successful, the user is redirected back to the client via the redirectUrl given to the
+homeserver on the initial redirect request. In the url will be a loginToken query parameter
+which contains a Matrix login token which the client should then use to complete the login
+via the Token-based process described above.
+
+
+{{cas_login_redirect_cs_http_api}}
+{{cas_login_ticket_cs_http_api}}
+
+
+.. |/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

specification/targets.yaml

@@ -52,6 +52,7 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/account_data.rst
     - modules/admin.rst
     - modules/event_context.rst
+    - modules/cas_login.rst
 
 
 title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]