# 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.