073ce659df
Since we already have three of these, and I'm about to add a fourth, let's pull it out to a common definition. We could, of course, keep defining the grammar each time it's used, but defining it in an appendix helps us be consistent for future API design.
78 lines
3.3 KiB
YAML
78 lines
3.3 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.
|
|
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']
|