Skip to content

Commit 3b42684

Browse files
turt2liverichvdh
turt2live
authored and
richvdh
committed
Describe social-sign-on (multiple SSO providers)
Spec for [MSC2858](#2858)
1 parent 457f399 commit 3b42684

File tree

4 files changed

+207
-2
lines changed

4 files changed

+207
-2
lines changed

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

+18-1
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,12 @@ 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 persue, typically in the form of several "login with $service"
44+
buttons. These services, or "identity providers" (IdPs), are typically
45+
OpenID Connect, though the exact protocol used is not a concern for this
46+
specification.
47+
4248
#### Client login via SSO
4349

4450
An overview of the process is as follows:
@@ -49,6 +55,8 @@ An overview of the process is as follows:
4955
2. To initiate the `m.login.sso` login type, the Matrix client
5056
instructs the user's browser to navigate to the
5157
[`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect) endpoint on the user's homeserver.
58+
Note that this may be the IdP-dependent version of the endpoint if the
59+
user has selected one of the `identity_providers` from the flow.
5260
3. The homeserver responds with an HTTP redirect to the SSO user
5361
interface, which the browser follows.
5462
4. The authentication server and the homeserver interact to verify the
@@ -97,10 +105,15 @@ endpoint to use: for `m.login.cas`, use `/cas/redirect` and for
97105
otherwise the same.
98106
{{% /boxes/note %}}
99107

108+
{{% definition path="api/client-server/definitions/sso_login_flow" %}}
109+
100110
##### Client behaviour
101111

102112
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
113+
[`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect)
114+
(or [`/login/sso/redirect/{idpId}`](/client-server-api/#get_matrixclientr0loginssoredirectidpid)
115+
when using one of the `identity_providers`)
116+
with an appropriate `redirectUrl`. Once
104117
authentication is successful, the browser will be redirected to that
105118
`redirectUrl`.
106119

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

142155
##### Server behaviour
143156

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

146163
The server should handle

‎data-definitions/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.

‎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/data-definitions/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 properly
72+
display any IdP 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.

0 commit comments

Comments
 (0)