Skip to content

Commit c11efb3

Browse files
turt2liverichvdh
turt2live
authored and
richvdh
committed
Merge pull request #3163 from matrix-org/travis/spec/msc2858-multisso
Describe social-sign-on (multiple SSO providers)
2 parents fb3dde1 + 2c3d7b1 commit c11efb3

File tree

6 files changed

+207
-2
lines changed

6 files changed

+207
-2
lines changed

‎changelogs/client_server/newsfragments/3163.feature

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Multiple SSO providers are possible through `m.login.sso` as per [MSC2858](https://github.com/matrix-org/matrix-doc/pull/2858).

‎changelogs/client_server/newsfragments/3163.new

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
`/login/sso/redirect/{idpId}` has been added as per [MSC2858](https://github.com/matrix-org/matrix-doc/pull/2858).

‎content/client-server-api/modules/sso_login.md

+16-1
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,10 @@ authentication the homeserver should provide a means for the
3939
administrator to configure where the CAS server is and the REST
4040
endpoints which consume the ticket.
4141

42+
Homeservers may optionally expose multiple possible SSO options for
43+
the user to pursue, typically in the form of several "log in with $provider"
44+
buttons. These are known as "identity providers" (IdPs).
45+
4246
#### Client login via SSO
4347

4448
An overview of the process is as follows:
@@ -49,6 +53,8 @@ An overview of the process is as follows:
4953
2. To initiate the `m.login.sso` login type, the Matrix client
5054
instructs the user's browser to navigate to the
5155
[`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect) endpoint on the user's homeserver.
56+
Note that this may be the IdP-dependent version of the endpoint if the
57+
user has selected one of the `identity_providers` from the flow.
5258
3. The homeserver responds with an HTTP redirect to the SSO user
5359
interface, which the browser follows.
5460
4. The authentication server and the homeserver interact to verify the
@@ -97,10 +103,15 @@ endpoint to use: for `m.login.cas`, use `/cas/redirect` and for
97103
otherwise the same.
98104
{{% /boxes/note %}}
99105

106+
{{% definition path="api/client-server/definitions/sso_login_flow" %}}
107+
100108
##### Client behaviour
101109

102110
The client starts the process by instructing the browser to navigate to
103-
[`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect) with an appropriate `redirectUrl`. Once
111+
[`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect)
112+
(or [`/login/sso/redirect/{idpId}`](/client-server-api/#get_matrixclientr0loginssoredirectidpid)
113+
when using one of the `identity_providers`)
114+
with an appropriate `redirectUrl`. Once
104115
authentication is successful, the browser will be redirected to that
105116
`redirectUrl`.
106117

@@ -141,6 +152,10 @@ authentication is successful, the browser will be redirected to that
141152

142153
##### Server behaviour
143154

155+
Servers should note that `identity_providers` are optional, and older clients
156+
might not interpret the value correctly. In these cases, the client will use
157+
the generic `/redirect` endpoint instead of the `/redirect/{idpId}` endpoint.
158+
144159
###### Redirecting to the Authentication server
145160

146161
The server should handle

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

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Copyright 2021 The Matrix.org Foundation C.I.C.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
type: object
15+
title: m.login.sso flow schema
16+
properties:
17+
type:
18+
type: enum
19+
enum: ["m.login.sso"]
20+
description: The string `m.login.sso`
21+
example: "m.login.sso"
22+
identity_providers:
23+
type: array
24+
description: |-
25+
Optional identity providers (IdPs) to present to the user. These would
26+
appear (typically) as distinct buttons for the user to interact with,
27+
and would map to the appropriate IdP-dependent redirect endpoint for that
28+
IdP.
29+
example: [
30+
{"id": "com.example.idp.github", "name": "GitHub", "brand": "github"},
31+
{"id": "com.example.idp.gitlab", "name": "GitLab", "icon": "mxc://example.com/abc123"},
32+
]
33+
items:
34+
type: object
35+
title: IdP
36+
description: An identity provider.
37+
properties:
38+
id:
39+
type: string
40+
description: |-
41+
Opaque string chosen by the homeserver, uniquely identifying
42+
the IdP from other IdPs the homeserver might support. Should
43+
be between 1 and 255 characters in length, containing unreserved
44+
characters under [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt)
45+
(`ALPHA DIGIT "-" / "." / "_" / "~"`). Clients are not intended
46+
to parse or infer meaning from opaque strings.
47+
example: "com.example.idp.github"
48+
name:
49+
type: string
50+
description: |-
51+
Human readable description for the IdP, intended to be shown to
52+
the user.
53+
example: "Github"
54+
icon:
55+
type: string
56+
description: |-
57+
Optional MXC URI to provide an image/icon representing the IdP.
58+
Intended to be shown alongside the `name` if provided.
59+
example: "mxc://example.org/abc123"
60+
brand:
61+
type: string
62+
# TODO @@TR: Actually link to "common identifier format" section when it exists.
63+
description: |-
64+
Optional UI hint for what kind of common SSO provider is being
65+
described in this IdP. Matrix maintains a registry of identifiers
66+
[in the matrix-doc repo](https://github.com/matrix-org/matrix-doc/blob/master/informal/idp-brands.md)
67+
to ensure clients and servers are aligned on major/common brands.
68+
69+
Clients should prefer the `brand` over the `icon`, when both are
70+
provided. Clients are not required to support any particular `brand`,
71+
including those in the registry, though are expected to be able to
72+
present any IdP based off the `name`/`icon` to the user regardless.
73+
74+
Unregistered brands are permitted using the Standard Identifier Format,
75+
though excluding the namespace requirements. For example, `examplesso`
76+
is a valid brand which is not in the registry but still permitted.
77+
Servers should be mindful that clients might not support their unregistered
78+
brand usage as intended by the server.
79+
example: "github"
80+
required: ['id', 'name']
81+
82+
required: ['type']

‎data/api/client-server/sso_login_redirect.yaml

+40-1
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,9 @@ paths:
2828
A web-based Matrix client should instruct the user's browser to
2929
navigate to this endpoint in order to log in via SSO.
3030
31-
The server MUST respond with an HTTP redirect to the SSO interface.
31+
The server MUST respond with an HTTP redirect to the SSO interface,
32+
or present a page which lets the user select an IdP to continue
33+
with in the event multiple are supported by the server.
3234
operationId: redirectToSSO
3335
parameters:
3436
- in: query
@@ -44,3 +46,40 @@ paths:
4446
headers:
4547
Location:
4648
type: "string"
49+
"/login/sso/redirect/{idpId}":
50+
get:
51+
summary: Redirect the user's browser to the SSO interface for an IdP.
52+
description: |-
53+
This endpoint is the same as `/login/sso/redirect`, though with an
54+
IdP ID from the original `identity_providers` array to inform the
55+
server of which IdP the client/user would like to continue with.
56+
57+
The server MUST respond with an HTTP redirect to the SSO interface
58+
for that IdP.
59+
operationId: redirectToSSO
60+
parameters:
61+
- in: path
62+
type: string
63+
name: idpId
64+
required: true
65+
description: |-
66+
The `id` of the IdP from the `m.login.sso` `identity_providers`
67+
array denoting the user's selection.
68+
- in: query
69+
type: string
70+
name: redirectUrl
71+
description: |-
72+
URI to which the user will be redirected after the homeserver has
73+
authenticated the user with SSO.
74+
required: true
75+
responses:
76+
302:
77+
description: A redirect to the SSO interface.
78+
headers:
79+
Location:
80+
type: "string"
81+
404:
82+
description: |-
83+
The IdP ID was not recognized by the server. The server is encouraged
84+
to provide a user-friendly page explaining the error given the user
85+
will be navigated to it.

‎informal/idp-brands.md

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# SSO IdP brand registry
2+
3+
This informal document contains specification for common brands that clients might experience
4+
in the wild as part of `m.login.sso` flows. To add your brand, open a PR against this document
5+
with the relevant additions (using the existing specification as reference) - an MSC is not
6+
required. Once opened, mention your PR in [#sct-office:matrix.org](https://matrix.to/#/#sct-office:matrix.org)
7+
on Matrix so it doesn't end up lost.
8+
9+
Please also take some time to read the [contributing guidelines](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst)
10+
for an overview of PR requirements.
11+
12+
<!--
13+
Author's note: This document intentionally has 2 blank lines between brands for easier distinction
14+
in the plaintext version. Please maintain them for new & existing brands.
15+
-->
16+
17+
## Brands
18+
19+
For the brands listed here, the `identifier` would be used as the `brand` value in an IdP definition
20+
under `m.login.sso`'s flow.
21+
22+
Note that each brand may have their own requirements for how they are represented by clients, such as
23+
Facebook/Twitter wanting their signature blues for button backgrounds whereas GitHub is not as particular
24+
about the press requirements. Clients should not rely on this document for guidance on press requirements
25+
and instead refer to the brands individually.
26+
27+
28+
### Apple
29+
30+
**Identifier**: `apple`
31+
32+
Suitable for "Sign in with Apple": see https://developer.apple.com/design/human-interface-guidelines/sign-in-with-apple/overview/buttons/.
33+
34+
35+
### Facebook
36+
37+
**Identifier**: `facebook`
38+
39+
"Continue with Facebook": see https://developers.facebook.com/docs/facebook-login/web/login-button/.
40+
41+
42+
### GitHub
43+
44+
**Identifier**: `github`
45+
46+
Logos available at https://github.com/logos.
47+
48+
49+
### GitLab
50+
51+
**Identifier**: `gitlab`
52+
53+
Logos available at https://about.gitlab.com/press/press-kit/.
54+
55+
56+
### Google
57+
58+
**Identifier**: `google`
59+
60+
Suitable for "Google Sign-In": see https://developers.google.com/identity/branding-guidelines.
61+
62+
63+
### Twitter
64+
65+
**Identifier**: `twitter`
66+
67+
Suitable for "Log in with Twitter": see https://developer.twitter.com/en/docs/authentication/guides/log-in-with-twitter#tab1.

0 commit comments

Comments
 (0)