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.
matrix-spec/data/api/client-server/definitions/sso_login_flow.yaml

83 lines
3.5 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: 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
# TODO @@TR: Actually link to "common identifier format" section when it exists.
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-doc repo](https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/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 properly
display any IdP regardless.
Unregistered brands are permitted using the Standard Identifier Format,
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']