diff --git a/README.rst b/README.rst index 61c27f15..8b04d8da 100644 --- a/README.rst +++ b/README.rst @@ -25,10 +25,12 @@ Structure of this repository contained in the specification, along with example JSON files. - ``meta``: documents outlining the processes involved when writing 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 documentation, typically HTML. - ``specification``: the specification split up into sections. + .. _OpenAPI: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md .. _JSON Schema: http://json-schema.org/ @@ -66,7 +68,7 @@ The above will write the rendered version of the specification to 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. If you're on Windows Vista or higher, be sure that the "Symbolic Links" diff --git a/proposals/2858-Multiple-SSO-Identity-Providers.md b/proposals/2858-Multiple-SSO-Identity-Providers.md index 298911b1..791efc1f 100644 --- a/proposals/2858-Multiple-SSO-Identity-Providers.md +++ b/proposals/2858-Multiple-SSO-Identity-Providers.md @@ -79,20 +79,16 @@ of an object with the following fields: "Common namespaced identifier grammar" as defined in [MSC2758](https://github.com/matrix-org/matrix-doc/pull/2758). - Initially the following identifiers are specified: - * `org.matrix.gitlab` - * `org.matrix.github` - * `org.matrix.apple` - * `org.matrix.google` - * `org.matrix.facebook` - * `org.matrix.twitter` + A registry of brand identifiers is maintained at + [`matrix-doc/registry/m.login.sso_brand.md`](../registry/m.login.sso_brand.md). Contributors + are encouraged to add more brands to the registry. Server implementations are free to add additional brands, though they should 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 - any of the above, but are expected to apply a sensible unbranded fallback - for any brand they do not recognise/support. + any of the brands listed in the registry, but are expected to apply a + sensible unbranded fallback for any brand they do not recognise/support. Where `icon` and `brand` are both present, it is recommended that clients which support the `brand` give precedence to `brand` over `icon`. @@ -175,5 +171,18 @@ the text. ## 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}` -for the new endpoints. +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}` 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`). diff --git a/registry/m.login.sso_brand.md b/registry/m.login.sso_brand.md new file mode 100644 index 00000000..a001ab8e --- /dev/null +++ b/registry/m.login.sso_brand.md @@ -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 + + + + * 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).