--- type: module weight: 220 --- ### SSO client login/authentication 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 OpenID Connect, "Central Authentication Service" (CAS) and SAML. This module allows a Matrix homeserver to delegate user authentication to an external authentication server supporting one of these protocols. In this process, there are three systems involved: - A Matrix client, using the APIs defined this specification, which is seeking to authenticate a user to a Matrix homeserver. - A Matrix homeserver, implementing the APIs defined in this specification, but which is delegating user authentication to the authentication server. - An "authentication server", which is responsible for authenticating the user. This specification is concerned only with communication between the Matrix client and the homeserver, and is independent of the SSO protocol used to communicate with the authentication server. Different Matrix homeserver implementations might support different SSO protocols. Clients and homeservers implementing the SSO flow will need to consider both [login](#login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is similar in both cases, but there are slight differences. Typically, SSO systems require a single "callback" URI to be configured at the authentication server. Once the user is authenticated, their browser is redirected to that URI. It is up to the Matrix homeserver implementation to implement a suitable endpoint. 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. Homeservers may optionally expose multiple possible SSO options for 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 An overview of the process is as follows: 1. The Matrix client calls [`GET /login`](/client-server-api/#get_matrixclientr0login) to find the supported login types, and the homeserver includes a flow with `"type": "m.login.sso"` in the response. 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 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. 6. The client exchanges the login token for an access token by calling the [`/login`](/client-server-api/#post_matrixclientr0login) endpoint with a `type` of `m.login.token`. For native applications, typically steps 1 to 4 are carried out by opening an embedded web view. These steps are illustrated as follows: ``` Matrix Client Matrix Homeserver Auth Server | | | |-------------(0) GET /login----------->| | |<-------------login types--------------| | | | | | Webview | | | | | | |----->| | | | |--(1) GET /login/sso/redirect-->| | | |<---------(2) 302---------------| | | | | | | |<========(3) Authentication process================>| | | | | | |<--(4) redirect to redirectUrl--| | |<-----| | | | | | |---(5) POST /login with login token--->| | |<-------------access token-------------| | ``` {{% boxes/note %}} In the older [r0.4.0 version](https://matrix.org/docs/spec/client_server/r0.4.0.html#cas-based-client-login) of this specification it was possible to authenticate via CAS when the homeserver 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. {{% /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) (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`. {{% http-api spec="client-server" api="sso_login_redirect" %}} ###### Security considerations 1. CSRF attacks via manipulation of parameters on the `redirectUrl` Clients should validate any requests to the `redirectUrl`. In particular, it may be possible for attackers to falsify any query parameters, leading to cross-site request forgery (CSRF) attacks. For example, consider a web-based client at `https://client.example.com`, which wants to initiate SSO login on the homeserver at `server.example.org`. It does this by storing the homeserver name in a query parameter for the `redirectUrl`: it redirects to `https://server.example.org/login/sso/redirect?redirectUrl=https://client.example.com?hs=server.example.org`. An attacker could trick a victim into following a link to `https://server.example.org/login/sso/redirect?redirectUrl=https://client.example.com?hs=evil.com`, which would result in the client sending a login token for the victim's account to the attacker-controlled site `evil.com`. To guard against this, clients MUST NOT store state (such as the address of the homeserver being logged into) anywhere it can be modified by external processes. Instead, the state could be stored in [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) or in a cookie. 2. For added security, clients SHOULD include a unique identifier in the `redirectUrl` and reject any callbacks that do not contain a recognised identifier, to guard against unsolicited login attempts and replay attacks. ##### 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 `/_matrix/client/%CLIENT_MAJOR_VERSION%/login/sso/redirect` as follows: 1. It should build a suitable request for the SSO system. 2. It should store enough state that the flow can be securely resumed after the SSO process completes. One way to do this is by storing a cookie which is stored in the user's browser, by adding a `Set-Cookie` header to the response. 3. It should redirect the user's browser to the SSO login page with the appropriate parameters. See also the "Security considerations" below. ###### Handling the callback from the Authentication server Note that there will normally be a single callback URI which is used for both login and user-interactive authentication: it is up to the homeserver implementation to distinguish which is taking place. The homeserver should validate the response from the SSO system: this may require additional calls to the authentication server, and/or may require checking a signature on the response. The homeserver then proceeds as follows: 1. The homeserver MUST map the user details received from the authentication server to a valid [Matrix user identifier](/appendices#user-identifiers). The guidance in [Mapping from other character sets](/appendices#mapping-from-other-character-sets) may be useful. 2. If the generated user identifier represents a new user, it should be registered as a new user. 3. The homeserver should generate a short-term login token. This is an opaque token, suitable for use with the `m.login.token` type of the [`/login`](/client-server-api/#post_matrixclientr0login) API. The lifetime of this token SHOULD be limited to around five seconds. 4. The homeserver adds a query parameter of `loginToken`, with the value of the generated login token, to the `redirectUrl` given in the `/_matrix/client/%CLIENT_MAJOR_VERSION%/login/sso/redirect` request. (Note: `redirectURL` may or may not include existing query parameters. If it already includes one or more `loginToken` parameters, they should be removed before adding the new one.) 5. The homeserver redirects the user's browser to the URI thus built. ##### Security considerations 1. Homeservers should ensure that login tokens are not sent to malicious clients. For example, consider a homeserver at `server.example.org`. An attacker tricks a victim into following a link to `https://server.example.org/login/sso/redirect?redirectUrl=https://evil.com`, resulting in a login token being sent to the attacker-controlled site `evil.com`. This is a form of cross-site request forgery (CSRF). To mitigate this, Homeservers SHOULD confirm with the user that they are happy to grant access to their matrix account to the site named in the `redirectUrl`. This can be done either *before* redirecting to the SSO login page when handling the `/_matrix/client/%CLIENT_MAJOR_VERSION%/login/sso/redirect` endpoint, or *after* login when handling the callback from the authentication server. (If the check is performed before redirecting, it is particularly important that the homeserver guards against unsolicited authentication attempts as below). It may be appropriate to whitelist a set of known-trusted client URLs in this process. In particular, the homeserver's own [login fallback](#login-fallback) implementation could be excluded. 2. For added security, homeservers SHOULD guard against unsolicited authentication attempts by tracking pending requests. One way to do this is to set a cookie when handling `/_matrix/client/%CLIENT_MAJOR_VERSION%/login/sso/redirect`, which is checked and cleared when handling the callback from the authentication server. #### SSO during User-Interactive Authentication [User-interactive authentication](#user-interactive-authentication-api) is used by client-server endpoints which require additional confirmation of the user's identity (beyond holding an access token). Typically this means that the user must re-enter their password, but for homeservers which delegate to an SSO server, this means redirecting to the authentication server during user-interactive auth. The implemementation of this is based on the [Fallback](#fallback) mechanism for user-interactive auth. #### Client behaviour Clients do not need to take any particular additional steps beyond ensuring that the fallback mechanism has been implemented, and treating the `m.login.sso` authentication type the same as any other unknown type (i.e. they should open a browser window for `/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/m.login.sso/fallback/web?session=`. Once the flow has completed, the client retries the request with the session only.) #### Server behaviour ##### Redirecting to the Authentication server The server should handle `/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/m.login.sso/fallback/web` in much the same way as `/_matrix/client/%CLIENT_MAJOR_VERSION%/login/sso/redirect`, which is to say: 1. It should build a suitable request for the SSO system. 2. It should store enough state that the flow can be securely resumed after the SSO process completes. One way to do this is by storing a cookie which is stored in the user's browser, by adding a `Set-Cookie` header to the response. 3. It should redirect the user's browser to the SSO login page with the appropriate parameters. See also the "Security considerations" below. ###### Handling the callback from the Authentication server Note that there will normally be a single callback URI which is used for both login and user-interactive authentication: it is up to the homeserver implementation to distinguish which is taking place. The homeserver should validate the response from the SSO system: this may require additional calls to the authentication server, and/or may require checking a signature on the response. The homeserver then returns the [user-interactive authentication fallback completion](#fallback) page to the user's browser. ###### Security considerations 1. Confirming the operation The homeserver SHOULD confirm that the user is happy for the operation to go ahead. The goal of the user-interactive authentication operation is to guard against a compromised `access_token` being used to take over the user's account. Simply redirecting the user to the SSO system is insufficient, since they may not realise what is being asked of them, or the SSO system may even confirm the authentication automatically. For example, the homeserver might serve a page with words to the effect of: > A client is trying to remove a device from your account. To > confirm this action, re-authenticate with single sign-on. If you > did not expect this, your account may be compromised! This confirmation could take place before redirecting to the SSO authentication page (when handling the `/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/m.login.sso/fallback/web` endpoint), or *after* authentication when handling the callback from the authentication server. (If the check is performed before redirecting, it is particularly important that the homeserver guards against unsolicited authentication attempts as below). 2. For added security, homeservers SHOULD guard against unsolicited authentication attempts by tracking pending requests. One way to do this is to set a cookie when handling `/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/m.login.sso/fallback/web`, which is checked and cleared when handling the callback from the authentication server.