Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-09 04:54:09 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Make CAS a subset of SSO

Browse source
This commit is contained in:
Travis Ralston 2019-01-09 14:41:46 -07:00
parent 3e7a5f5ea4
commit d6c33ea0a5
4 changed files with 101 additions and 133 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
specification/client_server_api.rst
View file

@ -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 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``. with ``403 Forbidden`` and an error code of ``M_FORBIDDEN``.
To log in with through a Central Authentication Service (CAS) or via Single If the homeserver advertises ``m.login.sso`` as a viable flow, and the client
Sign-On (SSO), clients should first make a request to ``GET /login`` to ensure supports it, the client should redirect the user to the ``/redirect`` endpoint
the homeserver supports the appropriate login type. Clients should use the for `Single Sign-On <#sso-client-login>`_. After authentication is complete, the
`CAS endpoints`_ to complete logins for ``m.login.cas`` and the `SSO endpoints`_ client will need to submit a ``/login`` request matching ``m.login.token``.
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 If the homeserver advertises ``m.login.cas`` as a viable flow, and the client
.. _`SSO endpoints`: #sso-based-client-login 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}} {{login_cs_http_api}}

119
specification/modules/cas_login.rst
View file

@ -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
<https://github.com/apereo/cas/blob/master/docs/cas-server-documentation/protocol/CAS-Protocol-Specification.md>`_
(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

97
specification/modules/sso_login.rst
View file

@ -12,14 +12,14 @@
.. See the License for the specific language governing permissions and .. See the License for the specific language governing permissions and
.. limitations under the License. .. limitations under the License.
SSO-based client login SSO client login
====================== ================
.. _module:sso_login: .. _module:sso_login:
Single Sign-On (SSO) is a generic web-based protocol for logging in users. 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 As a special case, the Matrix specification supports `CAS-based login <#cas-based-client-login>`_
is applicable to a wider range of SSO protocols. as well as a subset of SSO login.
An overview of the process, as used in Matrix, is as follows: 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. lifetime of this token SHOULD be limited to around five seconds.
CAS-based client login
----------------------
.. _module:cas_login:
`Central Authentication Service
<https://github.com/apereo/cas/blob/master/docs/cas-server-documentation/protocol/CAS-Protocol-Specification.md>`_
(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| replace:: ``/login``
.. _/login: #post-matrix-client-%CLIENT_MAJOR_VERSION%-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| replace:: ``/login/sso/redirect``
.. _/login/sso/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-sso-redirect .. _/login/sso/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-sso-redirect
.. _`CAS-based client login`: #cas-based-client-login

1
specification/targets.yaml
View file

@ -61,7 +61,6 @@ groups: # reusable blobs of files when prefixed with 'group:'
- modules/account_data.rst - modules/account_data.rst
- modules/admin.rst - modules/admin.rst
- modules/event_context.rst - modules/event_context.rst
- modules/cas_login.rst
- modules/sso_login.rst - modules/sso_login.rst
- modules/dm.rst - modules/dm.rst
- modules/ignore_users.rst - modules/ignore_users.rst