# Copyright 2019 New Vector 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.
openapi: 3.1.0
info:
  title: Matrix Client-Server SSO Login API
  version: 1.0.0
paths:
  /login/sso/redirect:
    get:
      x-addedInMatrixVersion: "1.1"
      summary: Redirect the user's browser to the SSO interface.
      description: |-
        A web-based Matrix client should instruct the user's browser to
        navigate to this endpoint in order to log in via SSO.

        The server MUST respond with an HTTP redirect to the SSO interface,
        or present a page which lets the user select an IdP to continue
        with in the event multiple are supported by the server.
      operationId: redirectToSSO
      parameters:
        - in: query
          name: redirectUrl
          description: |-
            URI to which the user will be redirected after the homeserver has
            authenticated the user with SSO.
          required: true
          schema:
            type: string
      responses:
        "302":
          description: A redirect to the SSO interface.
          headers:
            Location:
              schema:
                type: string
      tags:
        - Session management
  "/login/sso/redirect/{idpId}":
    get:
      x-addedInMatrixVersion: "1.1"
      summary: Redirect the user's browser to the SSO interface for an IdP.
      description: |-
        This endpoint is the same as `/login/sso/redirect`, though with an
        IdP ID from the original `identity_providers` array to inform the
        server of which IdP the client/user would like to continue with.

        The server MUST respond with an HTTP redirect to the SSO interface
        for that IdP.
      operationId: redirectToIdP
      parameters:
        - in: path
          name: idpId
          required: true
          description: |-
            The `id` of the IdP from the `m.login.sso` `identity_providers`
            array denoting the user's selection.
          schema:
            type: string
        - in: query
          name: redirectUrl
          description: |-
            URI to which the user will be redirected after the homeserver has
            authenticated the user with SSO.
          required: true
          schema:
            type: string
      responses:
        "302":
          description: A redirect to the SSO interface.
          headers:
            Location:
              schema:
                type: string
        "404":
          description: |-
            The IdP ID was not recognized by the server. The server is encouraged
            to provide a user-friendly page explaining the error given the user
            will be navigated to it.
      tags:
        - Session management
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v3