Move the idp `brand` assignments out to a registry

pull/977/head
Richard van der Hoff 4 years ago
parent ba3e204a48
commit dce9c9f09a

@ -25,10 +25,12 @@ Structure of this repository
contained in the specification, along with example JSON files. contained in the specification, along with example JSON files.
- ``meta``: documents outlining the processes involved when writing - ``meta``: documents outlining the processes involved when writing
documents, e.g. documentation style, guidelines. documents, e.g. documentation style, guidelines.
- ``registry``: Lists of identifiers for use in various parts of the Matrix protocol.
- ``scripts``: scripts to generate formatted versions of the - ``scripts``: scripts to generate formatted versions of the
documentation, typically HTML. documentation, typically HTML.
- ``specification``: the specification split up into sections. - ``specification``: the specification split up into sections.
.. _OpenAPI: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md .. _OpenAPI: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
.. _JSON Schema: http://json-schema.org/ .. _JSON Schema: http://json-schema.org/
@ -66,7 +68,7 @@ The above will write the rendered version of the specification to
Windows users Windows users
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
The ``source`` program does not exist on Windows, so instead run one of the The ``source`` program does not exist on Windows, so instead run one of the
``activate`` files in ``.\env\Scripts\`` to activate the virtual environment. ``activate`` files in ``.\env\Scripts\`` to activate the virtual environment.
If you're on Windows Vista or higher, be sure that the "Symbolic Links" If you're on Windows Vista or higher, be sure that the "Symbolic Links"

@ -79,20 +79,16 @@ of an object with the following fields:
"Common namespaced identifier grammar" as defined in "Common namespaced identifier grammar" as defined in
[MSC2758](https://github.com/matrix-org/matrix-doc/pull/2758). [MSC2758](https://github.com/matrix-org/matrix-doc/pull/2758).
Initially the following identifiers are specified: A registry of brand identifiers is maintained at
* `org.matrix.gitlab` [`matrix-doc/registry/m.login.sso_brand.md`](../registry/m.login.sso_brand.md). Contributors
* `org.matrix.github` are encouraged to add more brands to the registry.
* `org.matrix.apple`
* `org.matrix.google`
* `org.matrix.facebook`
* `org.matrix.twitter`
Server implementations are free to add additional brands, though they should Server implementations are free to add additional brands, though they should
be mindful of clients which do not recognise any given brand. be mindful of clients which do not recognise any given brand.
Clients are free to implement any set of brands they wish, including all or Clients are free to implement any set of brands they wish, including all or
any of the above, but are expected to apply a sensible unbranded fallback any of the brands listed in the registry, but are expected to apply a
for any brand they do not recognise/support. sensible unbranded fallback for any brand they do not recognise/support.
Where `icon` and `brand` are both present, it is recommended that clients Where `icon` and `brand` are both present, it is recommended that clients
which support the `brand` give precedence to `brand` over `icon`. which support the `brand` give precedence to `brand` over `icon`.
@ -175,5 +171,18 @@ the text.
## Unstable prefix ## Unstable prefix
Whilst in development use `org.matrix.msc2858.identity_providers` for the flow discovery and `/_matrix/client/unstable/org.matrix.msc2858/login/sso/redirect/{idp_id}` Whilst in development use `org.matrix.msc2858.identity_providers` for the flow
for the new endpoints. discovery and
`/_matrix/client/unstable/org.matrix.msc2858/login/sso/redirect/{idp_id}` for
the new endpoints.
When identity providers are listed under the experimental
`org.matrix.msc2858.identity_providers` field of the response to `/login`,
(instead of `identity_providers`), different values for the `brand` field are
used. In particular the following were defined:
* `org.matrix.gitlab` (now `com.gitlab`).
* `org.matrix.github` (now `com.github`).
* `org.matrix.apple` (now `com.apple`).
* `org.matrix.google` (now `com.google`).
* `org.matrix.facebook` (now `com.facebook`).
* `org.matrix.twitter` (now `com.twitter`).

@ -0,0 +1,49 @@
# `m.login.sso` `brand` identifier registry
The following is a list of identifiers for use in the optional `brand` field of the
`identity_providers` property of the response to the [`GET /_matrix/client/r0/login`
endpoint](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-login).
This field was originally proposed in
[MSC2858](https://github.com/matrix-org/matrix-doc/pull/2858).
Links to other organisations' branding guidelines are provided on an
informational basis, to help client developers understand the expected
behaviour. No guarantee is given as to their accuracy, and each client author
remains responsible for maintaining their application according to the latest
best practices.
## Assignments
<!--
Note that the following list is alphabetical by identifier - please keep it
that way!
-->
* Identifier: `com.apple`
Description: "Sign in with Apple". See
https://developer.apple.com/design/human-interface-guidelines/sign-in-with-apple/overview/buttons/.
* Identifier: `com.facebook`
Description: "Continue with Facebook". See
https://developers.facebook.com/docs/facebook-login/web/login-button/.
* Identifier: `com.github`
Description: Logos available at https://github.com/logos.
* Identifier: `com.gitlab`:
Description: Login in via the hosted https:/gitlab.com SaaS platform.
* Identifier: `com.google`:
Description: "Sign in with Google". See
https://developers.google.com/identity/branding-guidelines.
* Identifier: `com.twitter`
Description: "Log in with Twitter". See
https://developer.twitter.com/en/docs/authentication/guides/log-in-with-twitter#tab1.
## Requesting updates to the list
Members of the community wishing to add new brands to this list are encouraged
to open a pull request to update the list.
Contributors are reminded that identifiers for the `brand` field should follow
the [common textual identifier
grammar](https://github.com/matrix-org/matrix-doc/blob/rav/proposals/textual_identifier_grammar/proposals/2758-textual-id-grammar.md).
Loading…
Cancel
Save