Move the idp `brand` assignments out to a registry

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"

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:
+   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
    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
+   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
    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}`
+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`).

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
+
+<!--
+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).