You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
91 lines
4.2 KiB
YAML
91 lines
4.2 KiB
YAML
# 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']
|