From 7e3f72a95c2636cdd9003639358d374e48a6a494 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 1 May 2021 00:47:55 -0600 Subject: [PATCH 1/7] Describe social-sign-on (multiple SSO providers) Spec for [MSC2858](https://github.com/matrix-org/matrix-doc/pull/2858) --- .../client-server-api/modules/sso_login.md | 19 ++++- data-definitions/idp-brands.md | 67 +++++++++++++++ .../definitions/sso_login_flow.yaml | 82 +++++++++++++++++++ .../api/client-server/sso_login_redirect.yaml | 41 +++++++++- 4 files changed, 207 insertions(+), 2 deletions(-) create mode 100644 data-definitions/idp-brands.md create mode 100644 data/api/client-server/definitions/sso_login_flow.yaml diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md index eb6a0bb9..71bd32bb 100644 --- a/content/client-server-api/modules/sso_login.md +++ b/content/client-server-api/modules/sso_login.md @@ -39,6 +39,12 @@ authentication the homeserver should provide a means for the administrator to configure where the CAS server is and the REST endpoints which consume the ticket. +Homeservers may optionally expose multiple possible SSO options for +the user to persue, typically in the form of several "login with $service" +buttons. These services, or "identity providers" (IdPs), are typically +OpenID Connect, though the exact protocol used is not a concern for this +specification. + #### Client login via SSO An overview of the process is as follows: @@ -49,6 +55,8 @@ An overview of the process is as follows: 2. To initiate the `m.login.sso` login type, the Matrix client instructs the user's browser to navigate to the [`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect) endpoint on the user's homeserver. + Note that this may be the IdP-dependent version of the endpoint if the + user has selected one of the `identity_providers` from the flow. 3. The homeserver responds with an HTTP redirect to the SSO user interface, which the browser follows. 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 otherwise the same. {{% /boxes/note %}} +{{% definition path="api/client-server/definitions/sso_login_flow" %}} + ##### Client behaviour The client starts the process by instructing the browser to navigate to -[`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect) with an appropriate `redirectUrl`. Once +[`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect) +(or [`/login/sso/redirect/{idpId}`](/client-server-api/#get_matrixclientr0loginssoredirectidpid) +when using one of the `identity_providers`) +with an appropriate `redirectUrl`. Once authentication is successful, the browser will be redirected to that `redirectUrl`. @@ -141,6 +154,10 @@ authentication is successful, the browser will be redirected to that ##### Server behaviour +Servers should note that `identity_providers` are optional, and older clients +might not interpret the value correctly. In these cases, the client will use +the generic `/redirect` endpoint instead of the `/redirect/{idpId}` endpoint. + ###### Redirecting to the Authentication server The server should handle diff --git a/data-definitions/idp-brands.md b/data-definitions/idp-brands.md new file mode 100644 index 00000000..87bbc32d --- /dev/null +++ b/data-definitions/idp-brands.md @@ -0,0 +1,67 @@ +# SSO IdP brand registry + +This informal document contains specification for common brands that clients might experience +in the wild as part of `m.login.sso` flows. To add your brand, open a PR against this document +with the relevant additions (using the existing specification as reference) - an MSC is not +required. Once opened, mention your PR in [#sct-office:matrix.org](https://matrix.to/#/#sct-office:matrix.org) +on Matrix so it doesn't end up lost. + +Please also take some time to read the [contributing guidelines](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst) +for an overview of PR requirements. + + + +## Brands + +For the brands listed here, the `identifier` would be used as the `brand` value in an IdP definition +under `m.login.sso`'s flow. + +Note that each brand may have their own requirements for how they are represented by clients, such as +Facebook/Twitter wanting their signature blues for button backgrounds whereas Github is not as particular +about the press requirements. Clients should not rely on this document for guidance on press requirements +and instead refer to the brands individually. + + +### Apple + +**Identifier**: `apple` + +Suitable for "Sign in with Apple": see https://developer.apple.com/design/human-interface-guidelines/sign-in-with-apple/overview/buttons/. + + +### Facebook + +**Identifier**: `facebook` + +"Continue with Facebook": see https://developers.facebook.com/docs/facebook-login/web/login-button/. + + +### GitHub + +**Identifier**: `github` + +Logos available at https://github.com/logos. + + +### Gitlab + +**Identifier**: `gitlab` + +Logos available at https://about.gitlab.com/press/press-kit/. + + +### Google + +**Identifier**: `google` + +Suitable for "Google Sign-In": see https://developers.google.com/identity/branding-guidelines. + + +### Twitter + +**Identifier**: `twitter` + +Suitable for "Log in with Twitter": see https://developer.twitter.com/en/docs/authentication/guides/log-in-with-twitter#tab1. diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml new file mode 100644 index 00000000..c1f9102d --- /dev/null +++ b/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/data-definitions/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 properly + display any IdP 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'] diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml index acbafc57..8c92a3ce 100644 --- a/data/api/client-server/sso_login_redirect.yaml +++ b/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. From a9a15fe4a00b72059323971125e9fb43cc9234f2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 1 May 2021 00:49:47 -0600 Subject: [PATCH 2/7] Add changelogs --- changelogs/client_server/newsfragments/3163.feature | 1 + changelogs/client_server/newsfragments/3163.new | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/3163.feature create mode 100644 changelogs/client_server/newsfragments/3163.new diff --git a/changelogs/client_server/newsfragments/3163.feature b/changelogs/client_server/newsfragments/3163.feature new file mode 100644 index 00000000..8595394f --- /dev/null +++ b/changelogs/client_server/newsfragments/3163.feature @@ -0,0 +1 @@ +Multiple SSO providers are possible through `m.login.sso` as per [MSC2858](https://github.com/matrix-org/matrix-doc/pull/2858). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/3163.new b/changelogs/client_server/newsfragments/3163.new new file mode 100644 index 00000000..ba41fd8d --- /dev/null +++ b/changelogs/client_server/newsfragments/3163.new @@ -0,0 +1 @@ +`/login/sso/redirect/{idpId}` has been added as per [MSC2858](https://github.com/matrix-org/matrix-doc/pull/2858). \ No newline at end of file From fae88b823ec1050d86c8f3d87b6122ae43330aa8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 1 May 2021 00:54:14 -0600 Subject: [PATCH 3/7] Move brand registry out of structured data directory Markdown is not structured data. --- data/api/client-server/definitions/sso_login_flow.yaml | 2 +- {data-definitions => informal}/idp-brands.md | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename {data-definitions => informal}/idp-brands.md (100%) diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index c1f9102d..00410a92 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/data/api/client-server/definitions/sso_login_flow.yaml @@ -63,7 +63,7 @@ properties: 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/data-definitions/idp-brands.md) + [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 diff --git a/data-definitions/idp-brands.md b/informal/idp-brands.md similarity index 100% rename from data-definitions/idp-brands.md rename to informal/idp-brands.md From 641d2adfa01c5b50947a7db7c388b20d5435fd73 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 3 May 2021 08:21:09 -0600 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Patrick Cloke --- content/client-server-api/modules/sso_login.md | 2 +- informal/idp-brands.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md index 71bd32bb..c9f95413 100644 --- a/content/client-server-api/modules/sso_login.md +++ b/content/client-server-api/modules/sso_login.md @@ -40,7 +40,7 @@ administrator to configure where the CAS server is and the REST endpoints which consume the ticket. Homeservers may optionally expose multiple possible SSO options for -the user to persue, typically in the form of several "login with $service" +the user to pursue, typically in the form of several "login with $service" buttons. These services, or "identity providers" (IdPs), are typically OpenID Connect, though the exact protocol used is not a concern for this specification. diff --git a/informal/idp-brands.md b/informal/idp-brands.md index 87bbc32d..1dbf0c8d 100644 --- a/informal/idp-brands.md +++ b/informal/idp-brands.md @@ -20,7 +20,7 @@ For the brands listed here, the `identifier` would be used as the `brand` value under `m.login.sso`'s flow. Note that each brand may have their own requirements for how they are represented by clients, such as -Facebook/Twitter wanting their signature blues for button backgrounds whereas Github is not as particular +Facebook/Twitter wanting their signature blues for button backgrounds whereas GitHub is not as particular about the press requirements. Clients should not rely on this document for guidance on press requirements and instead refer to the brands individually. From e6245f667db5937752eae6014f3cd7583decdafc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 3 May 2021 08:22:10 -0600 Subject: [PATCH 5/7] Clarify provider naming --- content/client-server-api/modules/sso_login.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md index c9f95413..fe3f5322 100644 --- a/content/client-server-api/modules/sso_login.md +++ b/content/client-server-api/modules/sso_login.md @@ -40,10 +40,8 @@ administrator to configure where the CAS server is and the REST endpoints which consume the ticket. Homeservers may optionally expose multiple possible SSO options for -the user to pursue, typically in the form of several "login with $service" -buttons. These services, or "identity providers" (IdPs), are typically -OpenID Connect, though the exact protocol used is not a concern for this -specification. +the user to pursue, typically in the form of several "login with $provider" +buttons. These are known as "identity providers" (IdPs). #### Client login via SSO From 67b62cfe43155c78b18b038304c5133f59b68739 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 3 May 2021 08:23:27 -0600 Subject: [PATCH 6/7] Clarify render approach --- data/api/client-server/definitions/sso_login_flow.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index 00410a92..6aa03282 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/data/api/client-server/definitions/sso_login_flow.yaml @@ -68,8 +68,8 @@ properties: 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 properly - display any IdP regardless. + 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` From 70d9deb2e8fad6a376a424ffd411f746d928b8ed Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 3 May 2021 19:33:15 -0600 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: Hubert Chathi --- content/client-server-api/modules/sso_login.md | 2 +- data/api/client-server/definitions/sso_login_flow.yaml | 4 ++-- informal/idp-brands.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md index fe3f5322..2bc3916b 100644 --- a/content/client-server-api/modules/sso_login.md +++ b/content/client-server-api/modules/sso_login.md @@ -40,7 +40,7 @@ administrator to configure where the CAS server is and the REST endpoints which consume the ticket. Homeservers may optionally expose multiple possible SSO options for -the user to pursue, typically in the form of several "login with $provider" +the user to pursue, typically in the form of several "log in with $provider" buttons. These are known as "identity providers" (IdPs). #### Client login via SSO diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index 6aa03282..0dd011b3 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/data/api/client-server/definitions/sso_login_flow.yaml @@ -27,8 +27,8 @@ properties: 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"}, + {"id": "com.example.idp.github", "name": "GitHub", "brand": "github"}, + {"id": "com.example.idp.gitlab", "name": "GitLab", "icon": "mxc://example.com/abc123"}, ] items: type: object diff --git a/informal/idp-brands.md b/informal/idp-brands.md index 1dbf0c8d..24f91811 100644 --- a/informal/idp-brands.md +++ b/informal/idp-brands.md @@ -46,7 +46,7 @@ Suitable for "Sign in with Apple": see https://developer.apple.com/design/human- Logos available at https://github.com/logos. -### Gitlab +### GitLab **Identifier**: `gitlab`