From 3e7a5f5ea4841e96508f6eed7e950736a714abc9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 9 Jan 2019 00:09:38 -0700 Subject: [PATCH 1/5] Initial draft for SSO support --- api/client-server/sso_login_redirect.yaml | 46 ++++++++++ specification/client_server_api.rst | 12 ++- specification/modules/sso_login.rst | 100 ++++++++++++++++++++++ specification/targets.yaml | 1 + 4 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 api/client-server/sso_login_redirect.yaml create mode 100644 specification/modules/sso_login.rst diff --git a/api/client-server/sso_login_redirect.yaml b/api/client-server/sso_login_redirect.yaml new file mode 100644 index 00000000..acbafc57 --- /dev/null +++ b/api/client-server/sso_login_redirect.yaml @@ -0,0 +1,46 @@ +# Copyright 2019 New Vector Ltd +# +# 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. +swagger: '2.0' +info: + title: "Matrix Client-Server SSO Login API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +paths: + "/login/sso/redirect": + get: + summary: Redirect the user's browser to the SSO interface. + description: |- + 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. + operationId: redirectToSSO + parameters: + - 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" diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 82a576f1..973d3b55 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1016,9 +1016,19 @@ follows: } As with `token-based`_ interactive login, the ``token`` must encode the -user id. In the case that the token is not valid, the homeserver must respond +user ID. In the case that the token is not valid, the homeserver must respond with ``403 Forbidden`` and an error code of ``M_FORBIDDEN``. +To log in with through a Central Authentication Service (CAS) or via Single +Sign-On (SSO), clients should first make a request to ``GET /login`` to ensure +the homeserver supports the appropriate login type. Clients should use the +`CAS endpoints`_ to complete logins for ``m.login.cas`` and the `SSO endpoints`_ +for ``m.login.sso``. In either case, the client is expected to redirect the user +to the appropriate ``/redirect`` endpoint. + +.. _`CAS endpoints`: #cas-based-client-login +.. _`SSO endpoints`: #sso-based-client-login + {{login_cs_http_api}} {{logout_cs_http_api}} diff --git a/specification/modules/sso_login.rst b/specification/modules/sso_login.rst new file mode 100644 index 00000000..a493c851 --- /dev/null +++ b/specification/modules/sso_login.rst @@ -0,0 +1,100 @@ +.. Copyright 2019 New Vector Ltd +.. +.. 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. + +SSO-based client login +====================== + +.. _module:sso_login: + +Single Sign-On (SSO) is a generic web-based protocol for logging in users. +This section is the more generic version of `CAS-based client login`_ and +is applicable to a wider range of SSO protocols. + +An overview of the process, as used in Matrix, is as follows: + +1. The Matrix client instructs the user's browser to navigate to the + |/login/sso/redirect|_ endpoint on the user's homeserver. + +2. The homeserver responds with an HTTP redirect to the SSO user interface, + which the browser follows. + +3. The SSO system authenticates the user. + +4. The SSO server and the homeserver interact to verify the user's identity + and other authentication information, potentially using a number of redirects. + +7. The Matrix client receives the login token and passes it to the |/login|_ + API. + +Client behaviour +---------------- + +The client starts the process by instructing the browser to navigate to +|/login/sso/redirect|_ with an appropriate ``redirectUrl``. Once authentication +is successful, the browser will be redirected to that ``redirectUrl``. + +.. TODO-spec + + Should we recommend some sort of CSRF protection here (specifically, we + should guard against people accidentally logging in by sending them a link + to ``/login/sso/redirect``. + + Maybe we should recommend that the ``redirectUrl`` should contain a CSRF + token which the client should then check before sending the login token to + ``/login``? + +{{sso_login_redirect_cs_http_api}} + +Server behaviour +---------------- + +The URI for the SSO system to be used should be configured on the server by the +server administrator. The server is expected to set up any endpoints required to +interact with that SSO system. + +Handling the redirect endpoint +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When responding to the ``/login/sso/redirect`` endpoint, the server must +generate a URI for the SSO login page with any appropriate parameters. + +.. TODO-spec: + + It might be nice if the server did some validation of the ``redirectUrl`` + parameter, so that we could check that aren't going to redirect to a non-TLS + endpoint, and to give more meaningful errors in the case of + faulty/poorly-configured clients. + +Handling the authentication endpoint +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once the homeserver has verified the user's identity with the SSO system, it +MUST map the user ID to a valid `Matrix user identifier <../index.html#user-identifiers>`_. +The guidance in `Mapping from other character sets +<../index.html#mapping-from-other-character-sets>`_ may be useful. + +If the generated user identifier represents a new user, it should be registered +as a new user. + +Finally, the server should generate a short-term login token. The generated +token should be a macaroon, suitable for use with the ``m.login.token`` type of +the |/login|_ API, and `token-based interactive login <#token-based>`_. The +lifetime of this token SHOULD be limited to around five seconds. + + +.. |/login| replace:: ``/login`` +.. _/login: #post-matrix-client-%CLIENT_MAJOR_VERSION%-login +.. |/login/sso/redirect| replace:: ``/login/sso/redirect`` +.. _/login/sso/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-sso-redirect +.. _`CAS-based client login`: #cas-based-client-login diff --git a/specification/targets.yaml b/specification/targets.yaml index 93e1b8a6..493814ac 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -62,6 +62,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/admin.rst - modules/event_context.rst - modules/cas_login.rst + - modules/sso_login.rst - modules/dm.rst - modules/ignore_users.rst - modules/stickers.rst From d6c33ea0a5d5ea17cfe54a2aa4828831a5025042 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 9 Jan 2019 14:41:46 -0700 Subject: [PATCH 2/5] Make CAS a subset of SSO --- specification/client_server_api.rst | 19 ++--- specification/modules/cas_login.rst | 119 ---------------------------- specification/modules/sso_login.rst | 97 +++++++++++++++++++++-- specification/targets.yaml | 1 - 4 files changed, 102 insertions(+), 134 deletions(-) delete mode 100644 specification/modules/cas_login.rst diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 973d3b55..03d71246 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1019,15 +1019,16 @@ As with `token-based`_ interactive login, the ``token`` must encode the user ID. In the case that the token is not valid, the homeserver must respond with ``403 Forbidden`` and an error code of ``M_FORBIDDEN``. -To log in with through a Central Authentication Service (CAS) or via Single -Sign-On (SSO), clients should first make a request to ``GET /login`` to ensure -the homeserver supports the appropriate login type. Clients should use the -`CAS endpoints`_ to complete logins for ``m.login.cas`` and the `SSO endpoints`_ -for ``m.login.sso``. In either case, the client is expected to redirect the user -to the appropriate ``/redirect`` endpoint. - -.. _`CAS endpoints`: #cas-based-client-login -.. _`SSO endpoints`: #sso-based-client-login +If the homeserver advertises ``m.login.sso`` as a viable flow, and the client +supports it, the client should redirect the user to the ``/redirect`` endpoint +for `Single Sign-On <#sso-client-login>`_. After authentication is complete, the +client will need to submit a ``/login`` request matching ``m.login.token``. + +If the homeserver advertises ``m.login.cas`` as a viable flow, and the client +supports it, the client should redirect the user to the ``/redirect`` endpoint +for `CAS <#cas-based-client-login>`_. Just like SSO authentication, the client +is expected to submit a ``/login`` request matching ``m.login.token`` upon +successful authentication. {{login_cs_http_api}} diff --git a/specification/modules/cas_login.rst b/specification/modules/cas_login.rst deleted file mode 100644 index 5de98057..00000000 --- a/specification/modules/cas_login.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. Copyright 2016 OpenMarket Ltd -.. -.. 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. - -CAS-based client login -====================== - -.. _module:cas_login: - -`Central Authentication Service -`_ -(CAS) is a web-based single sign-on protocol. - -An overview of the process, as used in Matrix, is as follows: - -1. The Matrix client instructs the user's browser to navigate to the - |/login/cas/redirect|_ endpoint on the user's homeserver. - -2. The homeserver responds with an HTTP redirect to the CAS user interface, - which the browser follows. - -3. The CAS system authenticates the user. - -4. The CAS server responds to the user's browser with a redirect back to the - |/login/cas/ticket|_ endpoint on the homeserver, which the browser - follows. A 'ticket' identifier is passed as a query parameter in the - redirect. - -5. The homeserver receives the ticket ID from the user's browser, and makes a - request to the CAS server to validate the ticket. - -6. Having validated the ticket, the homeserver responds to the browser with a - third HTTP redirect, back to the Matrix client application. A login token - is passed as a query parameter in the redirect. - -7. The Matrix client receives the login token and passes it to the |/login|_ - API. - -Client behaviour ----------------- - -The client starts the process by instructing the browser to navigate to -|/login/cas/redirect|_ with an appropriate ``redirectUrl``. Once authentication -is successful, the browser will be redirected to that ``redirectUrl``. - -.. TODO-spec - - Should we recommend some sort of CSRF protection here (specifically, we - should guard against people accidentally logging in by sending them a link - to ``/login/cas/redirect``. - - Maybe we should recommend that the ``redirectUrl`` should contain a CSRF - token which the client should then check before sending the login token to - ``/login``? - -{{cas_login_redirect_cs_http_api}} -{{cas_login_ticket_cs_http_api}} - -Server behaviour ----------------- - -The URI for the CAS system to be used should be configured on the server by the -server administrator. - -Handling the redirect endpoint -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When responding to the ``/login/cas/redirect`` endpoint, the server must -generate a URI for the CAS login page. The server should take the base CAS URI -described above, and add a ``service`` query parameter. This parameter MUST be -the URI of the ``/login/cas/ticket`` endpoint, including the ``redirectUrl`` -query parameter. Because the homeserver may not know its base URI, this may -also require manual configuration. - -.. TODO-spec: - - It might be nice if the server did some validation of the ``redirectUrl`` - parameter, so that we could check that aren't going to redirect to a non-TLS - endpoint, and to give more meaningful errors in the case of - faulty/poorly-configured clients. - -Handling the authentication endpoint -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When responding to the ``/login/cas/ticket`` endpoint, the server MUST make a -request to the CAS server to validate the provided ticket. The server MAY also -check for certain user attributes in the response. Any required attributes -should be configured by the server administrator. - -Once the ticket has been validated, the server MUST map the CAS ``user_id`` -to a valid `Matrix user identifier <../index.html#user-identifiers>`_. The -guidance in `Mapping from other character sets -<../index.html#mapping-from-other-character-sets>`_ may be useful. - -If the generated user identifier represents a new user, it should be registered -as a new user. - -Finally, the server should generate a short-term login token. The generated -token should be a macaroon, suitable for use with the ``m.login.token`` type of -the |/login|_ API, and `token-based interactive login <#token-based>`_. The -lifetime of this token SHOULD be limited to around five seconds. - - -.. |/login| replace:: ``/login`` -.. _/login: #post-matrix-client-%CLIENT_MAJOR_VERSION%-login -.. |/login/cas/redirect| replace:: ``/login/cas/redirect`` -.. _/login/cas/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-redirect -.. |/login/cas/ticket| replace:: ``/login/cas/ticket`` -.. _/login/cas/ticket: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-ticket diff --git a/specification/modules/sso_login.rst b/specification/modules/sso_login.rst index a493c851..977278a7 100644 --- a/specification/modules/sso_login.rst +++ b/specification/modules/sso_login.rst @@ -12,14 +12,14 @@ .. See the License for the specific language governing permissions and .. limitations under the License. -SSO-based client login -====================== +SSO client login +================ .. _module:sso_login: Single Sign-On (SSO) is a generic web-based protocol for logging in users. -This section is the more generic version of `CAS-based client login`_ and -is applicable to a wider range of SSO protocols. +As a special case, the Matrix specification supports `CAS-based login <#cas-based-client-login>`_ +as well as a subset of SSO login. An overview of the process, as used in Matrix, is as follows: @@ -93,8 +93,95 @@ the |/login|_ API, and `token-based interactive login <#token-based>`_. The lifetime of this token SHOULD be limited to around five seconds. +CAS-based client login +---------------------- + +.. _module:cas_login: + +`Central Authentication Service +`_ +(CAS) is a web-based single sign-on protocol. The protocol defined here is an +extension of the SSO protocol defined in this module: it is largely the same, +but has some specific details which make it different. + +An overview of the process, as used in Matrix, is as follows: + +1. The Matrix client instructs the user's browser to navigate to the + |/login/cas/redirect|_ endpoint on the user's homeserver. + +2. The homeserver responds with an HTTP redirect to the CAS user interface, + which the browser follows. + +3. The CAS system authenticates the user. + +4. The CAS server responds to the user's browser with a redirect back to the + |/login/cas/ticket|_ endpoint on the homeserver, which the browser + follows. A 'ticket' identifier is passed as a query parameter in the + redirect. + +5. The homeserver receives the ticket ID from the user's browser, and makes a + request to the CAS server to validate the ticket. + +6. Having validated the ticket, the homeserver responds to the browser with a + third HTTP redirect, back to the Matrix client application. A login token + is passed as a query parameter in the redirect. + +7. The Matrix client receives the login token and passes it to the |/login|_ + API. + +Client behaviour +~~~~~~~~~~~~~~~~ + +The client starts the process by instructing the browser to navigate to +|/login/cas/redirect|_ with an appropriate ``redirectUrl``. Once authentication +is successful, the browser will be redirected to that ``redirectUrl``. + +{{cas_login_redirect_cs_http_api}} +{{cas_login_ticket_cs_http_api}} + +Server behaviour +~~~~~~~~~~~~~~~~ + +The URI for the CAS system to be used should be configured on the server by the +server administrator. + +Handling the redirect endpoint +++++++++++++++++++++++++++++++ + +When responding to the ``/login/cas/redirect`` endpoint, the server must +generate a URI for the CAS login page. The server should take the base CAS URI +described above, and add a ``service`` query parameter. This parameter MUST be +the URI of the ``/login/cas/ticket`` endpoint, including the ``redirectUrl`` +query parameter. Because the homeserver may not know its base URI, this may +also require manual configuration. + +Handling the authentication endpoint +++++++++++++++++++++++++++++++++++++ + +When responding to the ``/login/cas/ticket`` endpoint, the server MUST make a +request to the CAS server to validate the provided ticket. The server MAY also +check for certain user attributes in the response. Any required attributes +should be configured by the server administrator. + +Once the ticket has been validated, the server MUST map the CAS ``user_id`` +to a valid `Matrix user identifier <../index.html#user-identifiers>`_. The +guidance in `Mapping from other character sets +<../index.html#mapping-from-other-character-sets>`_ may be useful. + +If the generated user identifier represents a new user, it should be registered +as a new user. + +Finally, the server should generate a short-term login token. The generated +token should be a macaroon, suitable for use with the ``m.login.token`` type of +the |/login|_ API, and `token-based interactive login <#token-based>`_. The +lifetime of this token SHOULD be limited to around five seconds. + + .. |/login| replace:: ``/login`` .. _/login: #post-matrix-client-%CLIENT_MAJOR_VERSION%-login +.. |/login/cas/redirect| replace:: ``/login/cas/redirect`` +.. _/login/cas/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-redirect +.. |/login/cas/ticket| replace:: ``/login/cas/ticket`` +.. _/login/cas/ticket: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-ticket .. |/login/sso/redirect| replace:: ``/login/sso/redirect`` .. _/login/sso/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-sso-redirect -.. _`CAS-based client login`: #cas-based-client-login diff --git a/specification/targets.yaml b/specification/targets.yaml index 493814ac..4172e617 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -61,7 +61,6 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/account_data.rst - modules/admin.rst - modules/event_context.rst - - modules/cas_login.rst - modules/sso_login.rst - modules/dm.rst - modules/ignore_users.rst From 510468a3b1736d55a4823596bc6359ed2fccb0c8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 9 Jan 2019 15:31:04 -0700 Subject: [PATCH 3/5] Changelog --- changelogs/client_server/newsfragments/1789.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1789.feature diff --git a/changelogs/client_server/newsfragments/1789.feature b/changelogs/client_server/newsfragments/1789.feature new file mode 100644 index 00000000..97c1e5ca --- /dev/null +++ b/changelogs/client_server/newsfragments/1789.feature @@ -0,0 +1 @@ +Add a generic SSO login API. From aeb524ef89f2ef6751dd0b7067c225b0c8a6a7c2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 16 Jan 2019 16:13:53 -0700 Subject: [PATCH 4/5] Remove CAS login and reference it against r0.4.0 The SSO module should cover what CAS provides, and r0.4.0 is good as a reference for how CAS could be implemented without us repeating it here. --- api/client-server/cas_login_redirect.yaml | 54 ----------- api/client-server/cas_login_ticket.yaml | 66 ------------- specification/client_server_api.rst | 6 -- specification/modules/sso_login.rst | 110 ++++------------------ 4 files changed, 18 insertions(+), 218 deletions(-) delete mode 100644 api/client-server/cas_login_redirect.yaml delete mode 100644 api/client-server/cas_login_ticket.yaml diff --git a/api/client-server/cas_login_redirect.yaml b/api/client-server/cas_login_redirect.yaml deleted file mode 100644 index abe9069b..00000000 --- a/api/client-server/cas_login_redirect.yaml +++ /dev/null @@ -1,54 +0,0 @@ -# Copyright 2016 OpenMarket Ltd -# -# 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. -swagger: '2.0' -info: - title: "Matrix Client-Server CAS Login API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% -paths: - "/login/cas/redirect": - get: - summary: Redirect the user's browser to the CAS interface. - description: |- - A web-based Matrix client should instruct the user's browser to - navigate to this endpoint in order to log in via CAS. - - The server MUST respond with an HTTP redirect to the CAS interface. The - URI MUST include a ``service`` parameter giving the path of the - |/login/cas/ticket|_ endpoint (including the ``redirectUrl`` query - parameter). - - For example, if the endpoint is called with - ``redirectUrl=https://client.example.com/?q=p``, it might redirect to - ``https://cas.example.com/?service=https%3A%2F%2Fserver.example.com%2F_matrix%2Fclient%2F%CLIENT_MAJOR_VERSION%%2Flogin%2Fcas%2Fticket%3FredirectUrl%3Dhttps%253A%252F%252Fclient.example.com%252F%253Fq%253Dp``. - - operationId: redirectToCAS - parameters: - - in: query - type: string - name: redirectUrl - description: |- - URI to which the user will be redirected after the homeserver has - authenticated the user with CAS. - required: true - responses: - 302: - description: A redirect to the CAS interface. - headers: - Location: - type: "string" diff --git a/api/client-server/cas_login_ticket.yaml b/api/client-server/cas_login_ticket.yaml deleted file mode 100644 index a08565a0..00000000 --- a/api/client-server/cas_login_ticket.yaml +++ /dev/null @@ -1,66 +0,0 @@ -# Copyright 2016 OpenMarket Ltd -# -# 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. -swagger: '2.0' -info: - title: "Matrix Client-Server CAS Login API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% -paths: - "/login/cas/ticket": - get: - summary: Receive and validate a CAS login ticket. - description: |- - Once the CAS server has authenticated the user, it will redirect the - browser to this endpoint (assuming |/login/cas/redirect|_ gave it the - correct ``service`` parameter). - - The server MUST call ``/proxyValidate`` on the CAS server, to validate - the ticket supplied by the browser. - - If validation is successful, the server must generate a Matrix login - token. It must then respond with an HTTP redirect to the URI given in - the ``redirectUrl`` parameter, adding a ``loginToken`` query parameter - giving the generated token. - - If validation is unsuccessful, the server should respond with a ``401 - Unauthorized`` error, the body of which will be displayed to the user. - operationId: loginByCASTicket - parameters: - - in: query - type: string - name: redirectUrl - description: |- - The ``redirectUrl`` originally provided by the client to - |/login/cas/redirect|_. - required: true - - in: query - type: string - name: ticket - description: |- - CAS authentication ticket. - required: true - responses: - 302: - description: A redirect to the Matrix client. - headers: - Location: - type: "string" - x-example: |- - https://client.example.com/?q=p&loginToken=secrettoken - 401: - description: The server was unable to validate the CAS ticket. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 03d71246..4df83814 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1024,12 +1024,6 @@ supports it, the client should redirect the user to the ``/redirect`` endpoint for `Single Sign-On <#sso-client-login>`_. After authentication is complete, the client will need to submit a ``/login`` request matching ``m.login.token``. -If the homeserver advertises ``m.login.cas`` as a viable flow, and the client -supports it, the client should redirect the user to the ``/redirect`` endpoint -for `CAS <#cas-based-client-login>`_. Just like SSO authentication, the client -is expected to submit a ``/login`` request matching ``m.login.token`` upon -successful authentication. - {{login_cs_http_api}} {{logout_cs_http_api}} diff --git a/specification/modules/sso_login.rst b/specification/modules/sso_login.rst index 977278a7..57188500 100644 --- a/specification/modules/sso_login.rst +++ b/specification/modules/sso_login.rst @@ -34,8 +34,17 @@ An overview of the process, as used in Matrix, is as follows: 4. The SSO server and the homeserver interact to verify the user's identity and other authentication information, potentially using a number of redirects. -7. The Matrix client receives the login token and passes it to the |/login|_ - API. +5. The browser is directed to the ``redirectUrl`` provided by the client with + a ``loginToken`` query parameter for the client to log in with. + +.. Note:: + In the older `r0.4.0 version `_ + of this specification it was possible to authenticate via CAS when the server + provides a ``m.login.cas`` login flow. This specification deprecates the use + of ``m.login.cas`` to instead prefer ``m.login.sso``, which is the same process + with the only change being which redirect endpoint to use: for ``m.login.cas``, use + ``/cas/redirect`` and for ``m.login.sso`` use ``/sso/redirect`` (described below). + The endpoints are otherwise the same. Client behaviour ---------------- @@ -61,7 +70,11 @@ Server behaviour The URI for the SSO system to be used should be configured on the server by the server administrator. The server is expected to set up any endpoints required to -interact with that SSO system. +interact with that SSO system. For example, for CAS 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. A good reference for how CAS could +be implemented is available in the older `r0.4.0 version `_ +of this specification. Handling the redirect endpoint ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -90,98 +103,11 @@ as a new user. Finally, the server should generate a short-term login token. The generated token should be a macaroon, suitable for use with the ``m.login.token`` type of the |/login|_ API, and `token-based interactive login <#token-based>`_. The -lifetime of this token SHOULD be limited to around five seconds. - - -CAS-based client login ----------------------- - -.. _module:cas_login: - -`Central Authentication Service -`_ -(CAS) is a web-based single sign-on protocol. The protocol defined here is an -extension of the SSO protocol defined in this module: it is largely the same, -but has some specific details which make it different. - -An overview of the process, as used in Matrix, is as follows: - -1. The Matrix client instructs the user's browser to navigate to the - |/login/cas/redirect|_ endpoint on the user's homeserver. - -2. The homeserver responds with an HTTP redirect to the CAS user interface, - which the browser follows. - -3. The CAS system authenticates the user. - -4. The CAS server responds to the user's browser with a redirect back to the - |/login/cas/ticket|_ endpoint on the homeserver, which the browser - follows. A 'ticket' identifier is passed as a query parameter in the - redirect. - -5. The homeserver receives the ticket ID from the user's browser, and makes a - request to the CAS server to validate the ticket. - -6. Having validated the ticket, the homeserver responds to the browser with a - third HTTP redirect, back to the Matrix client application. A login token - is passed as a query parameter in the redirect. - -7. The Matrix client receives the login token and passes it to the |/login|_ - API. - -Client behaviour -~~~~~~~~~~~~~~~~ - -The client starts the process by instructing the browser to navigate to -|/login/cas/redirect|_ with an appropriate ``redirectUrl``. Once authentication -is successful, the browser will be redirected to that ``redirectUrl``. - -{{cas_login_redirect_cs_http_api}} -{{cas_login_ticket_cs_http_api}} - -Server behaviour -~~~~~~~~~~~~~~~~ - -The URI for the CAS system to be used should be configured on the server by the -server administrator. - -Handling the redirect endpoint -++++++++++++++++++++++++++++++ - -When responding to the ``/login/cas/redirect`` endpoint, the server must -generate a URI for the CAS login page. The server should take the base CAS URI -described above, and add a ``service`` query parameter. This parameter MUST be -the URI of the ``/login/cas/ticket`` endpoint, including the ``redirectUrl`` -query parameter. Because the homeserver may not know its base URI, this may -also require manual configuration. - -Handling the authentication endpoint -++++++++++++++++++++++++++++++++++++ - -When responding to the ``/login/cas/ticket`` endpoint, the server MUST make a -request to the CAS server to validate the provided ticket. The server MAY also -check for certain user attributes in the response. Any required attributes -should be configured by the server administrator. - -Once the ticket has been validated, the server MUST map the CAS ``user_id`` -to a valid `Matrix user identifier <../index.html#user-identifiers>`_. The -guidance in `Mapping from other character sets -<../index.html#mapping-from-other-character-sets>`_ may be useful. - -If the generated user identifier represents a new user, it should be registered -as a new user. - -Finally, the server should generate a short-term login token. The generated -token should be a macaroon, suitable for use with the ``m.login.token`` type of -the |/login|_ API, and `token-based interactive login <#token-based>`_. The -lifetime of this token SHOULD be limited to around five seconds. +lifetime of this token SHOULD be limited to around five seconds. This token is +given to the client via the ``loginToken`` query parameter previously mentioned. .. |/login| replace:: ``/login`` .. _/login: #post-matrix-client-%CLIENT_MAJOR_VERSION%-login -.. |/login/cas/redirect| replace:: ``/login/cas/redirect`` -.. _/login/cas/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-redirect -.. |/login/cas/ticket| replace:: ``/login/cas/ticket`` -.. _/login/cas/ticket: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-ticket .. |/login/sso/redirect| replace:: ``/login/sso/redirect`` .. _/login/sso/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-sso-redirect From 82ee3a6035bb56240898f23a40fc83c2fd92c7e3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 17 Jan 2019 11:18:48 -0700 Subject: [PATCH 5/5] Adjust wording for SSO introduction --- specification/modules/sso_login.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/modules/sso_login.rst b/specification/modules/sso_login.rst index 57188500..6dd4a332 100644 --- a/specification/modules/sso_login.rst +++ b/specification/modules/sso_login.rst @@ -17,9 +17,9 @@ SSO client login .. _module:sso_login: -Single Sign-On (SSO) is a generic web-based protocol for logging in users. -As a special case, the Matrix specification supports `CAS-based login <#cas-based-client-login>`_ -as well as a subset of SSO login. +Single Sign-On (SSO) is a generic term which refers to protocols which allow +users to log into applications via a single web-based authentication portal. +Examples include "Central Authentication Service" (CAS) and SAML. An overview of the process, as used in Matrix, is as follows: