# Copyright 2021 The Matrix.org Foundation C.I.C.
#
# 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.
type: object
title: m.login.sso flow schema
properties:
  type:
    type: string
    enum: ["m.login.sso"]
    description: The string `m.login.sso`
    example: "m.login.sso"
  identity_providers:
    type: array
    description: |-
      Optional identity providers (IdPs) to present to the user. These would
      appear (typically) as distinct buttons for the user to interact with,
      and would map to the appropriate IdP-dependent redirect endpoint for that
      IdP.
    example: [
      {"id": "com.example.idp.github", "name": "GitHub", "brand": "github"},
      {"id": "com.example.idp.gitlab", "name": "GitLab", "icon": "mxc://example.com/abc123"},
    ]
    items:
      type: object
      title: IdP
      description: An identity provider.
      properties:
        id:
          type: string
          description: |-
            Opaque string chosen by the homeserver, uniquely identifying
            the IdP from other IdPs the homeserver might support. Should
            use the [Opaque identifier Grammar](/appendices#opaque-identifiers).
          example: "com.example.idp.github"
        name:
          type: string
          description: |-
            Human readable description for the IdP, intended to be shown to
            the user.
          example: "Github"
        icon:
          type: string
          description: |-
            Optional `mxc://` URI to provide an image/icon representing the IdP.
            Intended to be shown alongside the `name` if provided.

            {{% boxes/note %}}
            Clients SHOULD use the deprecated [`/download`](/client-server-api/#get_matrixmediav3downloadservernamemediaid)
            and [`/thumbnail`](/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)
            endpoints to retrieve this media item because clients will not have
            an access token they can authenticate with yet. Servers SHOULD ensure
            media used for IdP icons is excluded from the freeze described by the
            [Content Repository module's Client Behaviour section](/client-server-api/#content-repo-client-behaviour).

            This may be addressed in the future with proposals like [MSC4148](https://github.com/matrix-org/matrix-spec-proposals/pull/4148),
            or removed entirely through the transition to OIDC.
            {{% /boxes/note %}}
          example: "mxc://example.org/abc123"
        brand:
          type: string
          description: |-
            Optional UI hint for what kind of common SSO provider is being
            described in this IdP. Matrix maintains a registry of identifiers
            [in the matrix-spec repo](https://github.com/matrix-org/matrix-spec/blob/main/informal/idp-brands.md)
            to ensure clients and servers are aligned on major/common brands.

            Clients should prefer the `brand` over the `icon`, when both are
            provided. Clients are not required to support any particular `brand`,
            including those in the registry, though are expected to be able to
            present any IdP based off the `name`/`icon` to the user regardless.

            Unregistered brands are permitted using the [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar),
            though excluding the namespace requirements. For example, `examplesso`
            is a valid brand which is not in the registry but still permitted.
            Servers should be mindful that clients might not support their unregistered
            brand usage as intended by the server.
          example: "github"
      required: ['id', 'name']

required: ['type']