# User-Interactive Auth for SSO-backed homeserver Certain endpoints, such as `DELETE /_matrix/client/r0/devices/{deviceId}` and `POST /_matrix/client/r0/account/3pid/add`, require the user to reconfirm their identity, as a guard against a leaked access token being used to take over an entire account. On a normal homeserver, this is done by prompting the user to enter their password. However, on a homeserver where users authenticate via a single-sign-on system, the user doesn't have a password registered with the homeserver. Instead we need to delegate that check to the SSO system. At the protocol level, this means adding support for SSO to [user-interactive authentication API](https://matrix.org/docs/spec/client_server/r0.6.0#user-interactive-authentication-api). In theory, any clients that already implement the fallback process for unknown authentication types will work fine without modification. It is unknown whether this is widely supported among clients. ## Proposal We add an `m.login.sso` authentication type to the UI auth spec. There are no additional params as part of this auth type. 1. If the client wants to complete that authentication type, it opens a browser window for `/_matrix/client/r0/auth/m.login.sso/fallback/web?session=<...>` with session set to the UI-Auth session id (from the "auth" dict). The homeserver returns a page which asks for the user's confirmation before proceeding. See the security considerations section below for why this is necessary. For example, the page could say words to the effect of: > A client is trying to remove a device/add an email address/take over your > account. To confirm this action, **re-authenticate with single sign-on**. > If you did not expect this, your account may be compromised! 2. The link, once the user clicks on it, goes to the SSO provider's page. 3. The SSO provider validates the user, and redirects the browser back to the homeserver. 4. The homeserver validates the response from the SSO provider, updates the user-interactive auth session to show that the SSO has completed, [serves the fallback auth completion page as specced](https://matrix.org/docs/spec/client_server/r0.6.0#fallback). 5. The client resubmits its original request, with its original session id, which now should complete. Note that the post-SSO URL on the homeserver is left up to the homeserver implementation rather than forming part of the specification, choices might be limited by the chosen SSO implementation, for example: * SAML2 servers typically only support one URL per service provider, so in practice it will need to be the same as that already used for the login flow (for synapse, it's /_matrix/saml2/authn_response) - and the server needs to be able to figure out if it's doing SSO for a login attempt or an SSO attempt. * CAS doesn't have the same restriction. ### Example flow: 0. Client submits the request, which the server says requires SSO: ``` POST /_matrix/client/r0/delete_devices HTTP/1.1 Content-Type: application/json Authorization: Bearer xyzzy { "devices": ["FSVVTZRRAA"] } HTTP/1.1 401 Unauthorized Content-Type: application/json { "flows": [ { "stages": [ "m.login.sso" ] } ], "params": {}, "session": "dTKfsLHSAJeAhqfxUsvrIVJd" } ``` 1. Client opens a browser window for the fallback endpoint: ``` GET /_matrix/client/r0/auth/m.login.sso/fallback/web ?session=dTKfsLHSAJeAhqfxUsvrIVJd HTTP/1.1 HTTP/1.1 200 OK
can delete device pls? clicky ``` 2. The user clicks the confirmation link which goes to the SSO provider's site: ``` GET https://sso_provider/validate?SAMLRequest=