diff --git a/api/client-server/cas_login_ticket.yaml b/api/client-server/cas_login_ticket.yaml deleted file mode 100644 index a08565a0d..000000000 --- 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/api/client-server/cas_login_redirect.yaml b/api/client-server/sso_login_redirect.yaml similarity index 53% rename from api/client-server/cas_login_redirect.yaml rename to api/client-server/sso_login_redirect.yaml index abe9069b5..acbafc578 100644 --- a/api/client-server/cas_login_redirect.yaml +++ b/api/client-server/sso_login_redirect.yaml @@ -1,4 +1,4 @@ -# Copyright 2016 OpenMarket Ltd +# 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. @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Client-Server CAS Login API" + title: "Matrix Client-Server SSO Login API" version: "1.0.0" host: localhost:8008 schemes: @@ -21,34 +21,26 @@ schemes: - http basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% paths: - "/login/cas/redirect": + "/login/sso/redirect": get: - summary: Redirect the user's browser to the CAS interface. + 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 CAS. + navigate to this endpoint in order to log in via SSO. - 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 + 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 CAS. + authenticated the user with SSO. required: true responses: 302: - description: A redirect to the CAS interface. + description: A redirect to the SSO interface. headers: Location: type: "string" diff --git a/changelogs/client_server/newsfragments/1789.feature b/changelogs/client_server/newsfragments/1789.feature new file mode 100644 index 000000000..97c1e5ca9 --- /dev/null +++ b/changelogs/client_server/newsfragments/1789.feature @@ -0,0 +1 @@ +Add a generic SSO login API. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 82a576f14..4df838142 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1016,9 +1016,14 @@ 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``. +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``. + {{login_cs_http_api}} {{logout_cs_http_api}} diff --git a/specification/modules/cas_login.rst b/specification/modules/cas_login.rst deleted file mode 100644 index 5de980575..000000000 --- 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 new file mode 100644 index 000000000..6dd4a3329 --- /dev/null +++ b/specification/modules/sso_login.rst @@ -0,0 +1,113 @@ +.. 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 client login +================ + +.. _module: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: + +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. + +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 +---------------- + +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. 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. 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/sso/redirect| replace:: ``/login/sso/redirect`` +.. _/login/sso/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-sso-redirect diff --git a/specification/targets.yaml b/specification/targets.yaml index 93e1b8a6b..4172e617f 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -61,7 +61,7 @@ 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 - modules/stickers.rst