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

Attempt to clarify the MSC.

Browse source
This commit is contained in:
Patrick Cloke 2020-03-09 14:00:28 -04:00
parent c69a747bae
commit f48bbd3278
1 changed files with 47 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

90
proposals/xxxx-ui-interactive-auth-for-sso.md
View file

@ -1,6 +1,4 @@
# User-Interactive Auth for SSO-backed homeservers # User-Interactive Auth for SSO-backed homeserver
## Background
Certain endpoints, such as `DELETE /_matrix/client/r0/devices/{deviceId}` and Certain endpoints, such as `DELETE /_matrix/client/r0/devices/{deviceId}` and
`POST /_matrix/client/r0/account/3pid/add`, require the user to reconfirm their `POST /_matrix/client/r0/account/3pid/add`, require the user to reconfirm their
@ -9,15 +7,17 @@ entire account.
On a normal homeserver, this is done by prompting the user to enter their 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 password. However, on a homeserver where users authenticate via a single-sign-on
system, the user doesn't have a password, so this doesn't work. Instead we need system, the user doesn't have a password registered with the homeserver. Instead
to delegate that check to the SSO system. we need to delegate that check to the SSO system.
At the protocol level, this means adding support for SSO to At the protocol level, this means adding support for SSO to
[user-interactive auth](https://matrix.org/docs/spec/client_server/r0.6.0#user-interactive-authentication-api). [user-interactive auth](https://matrix.org/docs/spec/client_server/r0.6.0#user-interactive-authentication-api).
### The current implementation 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.
Or, "how UI Auth works, in practice": ### UI Auth Overview
When the client calls one of the protected endpoints, it initially returns a 401 When the client calls one of the protected endpoints, it initially returns a 401
response. For example: response. For example:
@ -52,7 +52,7 @@ The client:
* discovers there is a flow it knows how to follow * discovers there is a flow it knows how to follow
* carries out the first "stage" of that flow (m.login.password) * carries out the first "stage" of that flow (m.login.password)
ie, the client prompts the user to enter a password. In this example, the client prompts the user to enter a password.
The client then resubmits with an additional 'auth' param, with "type" giving The client then resubmits with an additional 'auth' param, with "type" giving
the name of the authentication type it has just carried out. That completes the the name of the authentication type it has just carried out. That completes the
@ -89,24 +89,25 @@ additional params as part of this auth type.
window for `/_matrix/client/r0/auth/m.login.sso/fallback/web?session=<...>` 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). with session set to the UI-Auth session id (from the "auth" dict).
The homeserver returns a page which says words to the effect of "A client is The homeserver returns a page which asks for the user's confirmation before
trying to remove a device/add an email address/take over your account. To proceeding. See the security considerations section below for why this is
confirm this action, **re-authenticate with single sign-on**. If you did not necessary. For example, the page could say words to the effect of:
expect this, your account may be compromised!"
See security section below. > 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. 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 3. The SSO provider validates the user, and redirects the browser back to the
homeserver. homeserver.
4. The homeserver validates the response from the SSO provider, updates the 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 user-interactive auth session to show that the SSO has completed,
fallback auth completion page as specced: [serves the fallback auth completion page as specced](https://matrix.org/docs/spec/client_server/r0.6.0#fallback).
https://matrix.org/docs/spec/client_server/r0.6.0#fallback
5. The client resubmits its original request, with its original session id, 5. The client resubmits its original request, with its original session id,
which now hopefully completes. which now should complete.
Note that the post-SSO URL on the homeserver is left up to the homeserver Note that the post-SSO URL on the homeserver is left up to the homeserver
implementation rather than forming part of the spec. 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 * 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 practice it will need to be the same as that already used for the login flow
@ -216,47 +217,50 @@ implementation rather than forming part of the spec.
{} {}
``` ```
A few notes: ## Alternatives
* The security of this relies on UI-Auth sessions only being used for the same An alternative client flow where the fallback auth ends up redirecting to a
request as they were initiated for. I don't think that's currently enforced. given URI, instead of doing JavaScript postMessage foo could be considered.
* We might consider an alternative client flow where the fallback auth ends up This is probably an orthogonal change to the fallback auth though.
redirecting to a given URI, instead of doing javascript postMessage foo. I
think that's an orthogonal change to the fallback auth though.
* In theory, any clients that already implement the fallback process for
unknown authentication types will work fine without modification.
Unfortunately, I don't think Riot (on any platform) is among them.
## Security considerations ## Security considerations
### Why we need user to confirm before the SSO flow
Recall that the thing we are trying to guard against here is a single leaked Recall that the thing we are trying to guard against here is a single leaked
access-token being used to take over an entire account. So let's assume the access-token being used to take over an entire account. So let's assume the
attacker has got hold of an access token for your account. What happens if we attacker has got hold of an access token for your account. What happens if the
skip the confirmation step? confirmation step is skipped?
The attacker, who has your access token, starts a UI-Auth session to add his The attacker, who has your access token, starts a UI Authentication session to
email address to your account. add their email address to your account.
He then sends you a link "hey, check out this cool video!"; the link leads (via They then sends you a link "hey, check out this cool video!"; the link leads (via
an innocent-looking url shortener) to an innocent-looking URL shortener or some other phishing technique) to
`/_matrix/client/r0/auth/m.login.sso/fallback/web?session=<...>`, with the ID of `/_matrix/client/r0/auth/m.login.sso/fallback/web?session=<...>`, with the ID of
the session that he just created. the session that he just created.
Recall that we're skipping the confirmation step, so the server redirects Since there is no confirmation step, the server redirects directly to the SSO
straight to the SSO provider. provider.
It's common for SSO providers to redirect straight back to the app if you've It's common for SSO providers to redirect straight back to the app if you've
recently authenticated with them; even in the best case, the SSO provider shows recently authenticated with them; even in the best case, the SSO provider shows
some innocent message along the lines of "Confirm that you want to sign in to an innocent message along the lines of "Confirm that you want to sign in to
<your matrix homeserver>". <your Matrix homeserver>".
So the SSO completes, and the attacker's session is validated. After redirecting back to the homeserver, the SSO is completed and the
attacker's session is validated. They are now able to make their malicious
change to your account.
By telling the user what's about to happen as clearly as we can, and making them This problem can be mitigated by clearly telling the user what is about to happen.
confirm, we can mitigate this problem.
### Reusing UI-Auth sessions
The security of this relies on UI-Auth sessions only being used for the same
request as they were initiated for. It is not believed that this is currently
enforced.
## Unstable prefix ## Unstable prefix
We should use a vendor prefix here until this hits the spec. A vendor prefix of `org.matrix.login.sso` (instead of `m.login.sso` is proposed
until this is part of the specification.
`org.matrix.login.sso` ?