# 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: enum
    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
            be between 1 and 255 characters in length, containing unreserved
            characters under [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt)
            (`ALPHA  DIGIT  "-" / "." / "_" / "~"`). Clients are not intended
            to parse or infer meaning from opaque strings.
          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.
          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']