Merge pull request #3163 from matrix-org/travis/spec/msc2858-multisso

Describe social-sign-on (multiple SSO providers)

data/api/client-server/definitions/sso_login_flow.yaml

@@ -0,0 +1,82 @@
+# 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/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 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']

data/api/client-server/sso_login_redirect.yaml

@@ -28,7 +28,9 @@ paths:
         A web-based Matrix client should instruct the user's browser to
         navigate to this endpoint in order to log in via SSO.
 
-        The server MUST respond with an HTTP redirect to the SSO interface.
+        The server MUST respond with an HTTP redirect to the SSO interface,
+        or present a page which lets the user select an IdP to continue
+        with in the event multiple are supported by the server.
       operationId: redirectToSSO
       parameters:
         - in: query
@@ -44,3 +46,40 @@ paths:
           headers:
             Location:
               type: "string"
+  "/login/sso/redirect/{idpId}":
+    get:
+      summary: Redirect the user's browser to the SSO interface for an IdP.
+      description: |-
+        This endpoint is the same as `/login/sso/redirect`, though with an
+        IdP ID from the original `identity_providers` array to inform the
+        server of which IdP the client/user would like to continue with.
+
+        The server MUST respond with an HTTP redirect to the SSO interface
+        for that IdP.
+      operationId: redirectToSSO
+      parameters:
+        - in: path
+          type: string
+          name: idpId
+          required: true
+          description: |-
+            The `id` of the IdP from the `m.login.sso` `identity_providers`
+            array denoting the user's selection.
+        - in: query
+          type: string
+          name: redirectUrl
+          description: |-
+            URI to which the user will be redirected after the homeserver has
+            authenticated the user with SSO.
+          required: true
+      responses:
+        302:
+          description: A redirect to the SSO interface.
+          headers:
+            Location:
+              type: "string"
+        404:
+          description: |-
+            The IdP ID was not recognized by the server. The server is encouraged
+            to provide a user-friendly page explaining the error given the user
+            will be navigated to it.