Merge pull request #2454 from matrix-org/clokep/ui-interactive-auth-for-sso
MSC2454: Support UI interactive auth for SSOpull/2527/head
Travis Ralston
5 years ago
committed by
GitHub
commit
4cd4e19bf8
@ -0,0 +1,230 @@
|
||||
# User-Interactive Authentication 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 the
|
||||
[user-interactive authentication API](https://matrix.org/docs/spec/client_server/r0.6.0#user-interactive-authentication-api).
|
||||
|
||||
In theory, once SSO is added as a possible flow for authentication, any clients
|
||||
that already implement the [fallback process for unknown authentication types](https://matrix.org/docs/spec/client_server/r0.6.0#fallback)
|
||||
will work fine without modification. It is unknown whether this is widely
|
||||
supported among clients.
|
||||
|
||||
## Proposal
|
||||
|
||||
An [additional authentication type](https://matrix.org/docs/spec/client_server/r0.6.0#authentication-types)
|
||||
of `m.login.sso` is added to the user-interactive authentication specification.
|
||||
|
||||
There are no additional parameters as part of this authentication type. As per
|
||||
the user-interactive authentication specification, the only parameter included in
|
||||
the `auth` dictionary should be the session ID from the homeserver, e.g.:
|
||||
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"session": "<session ID>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Detailed fallback authentication flow:
|
||||
|
||||
The following is a re-iteration of the [fallback authentication flow](https://matrix.org/docs/spec/client_server/r0.6.0#fallback),
|
||||
but with details filled in for the proposed new authentication type.
|
||||
|
||||
When choosing this authentication flow, the following should occur:
|
||||
|
||||
1. If the client wants to complete authentication using SSO, 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, and
|
||||
[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:
|
||||
|
||||
A more complete example is provided below in which a user attempts to delete
|
||||
a device and is pushed into the user interactive authentication process with
|
||||
SSO being the only possible 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
|
||||
|
||||
<body>
|
||||
A client is trying to remove a device from your account. To confirm this
|
||||
action, <a href="https://sso_provider/validate?SAMLRequest=...">re-authenticate with single sign-on</a>.
|
||||
If you did not expect this, your account may be compromised!
|
||||
</body>
|
||||
```
|
||||
|
||||
2. The user clicks the confirmation link which goes to the SSO provider's site:
|
||||
|
||||
```
|
||||
GET https://sso_provider/validate?SAMLRequest=<etc> HTTP/1.1
|
||||
|
||||
<SAML/CAS or other SSO data>
|
||||
```
|
||||
|
||||
3. The SSO provider validates the user and ends up redirecting the browser back
|
||||
to the homeserver. The example below shows a 302 for simplicity, this might
|
||||
vary based on SSO implementation.
|
||||
|
||||
```
|
||||
HTTP/1.1 302 Moved
|
||||
Location: https://homeserver/_matrix/saml2/authn_response?
|
||||
SAMLResponse=<etc>
|
||||
```
|
||||
|
||||
4. The browser sends the SSO response to the homeserver, which validates it and
|
||||
shows the fallback auth completion page:
|
||||
|
||||
```
|
||||
GET /_matrix/saml2/authn_response?SAMLResponse=<etc>
|
||||
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
|
||||
<script>
|
||||
if (window.onAuthDone) {
|
||||
window.onAuthDone();
|
||||
} else if (window.opener && window.opener.postMessage) {
|
||||
window.opener.postMessage("authDone", "*");
|
||||
}
|
||||
</script>
|
||||
|
||||
<p>Thank you.</p>
|
||||
<p>You may now close this window and return to the application.</p>
|
||||
```
|
||||
|
||||
5. The client closes the browser popup if it is still open, and resubmits its
|
||||
original request, which now succeeds:
|
||||
|
||||
```
|
||||
POST /_matrix/client/r0/delete_devices HTTP/1.1
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer xyzzy
|
||||
|
||||
{
|
||||
"auth": {
|
||||
"session": "dTKfsLHSAJeAhqfxUsvrIVJd"
|
||||
}
|
||||
}
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
## Alternatives
|
||||
|
||||
An alternative client flow where the fallback auth ends up redirecting to a
|
||||
given URI, instead of doing JavaScript `postMessage` foo could be considered.
|
||||
This is probably an orthogonal change to the fallback auth though.
|
||||
|
||||
## 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
|
||||
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 the
|
||||
confirmation step is skipped?
|
||||
|
||||
The attacker, who has your access token, starts a UI Authentication session to
|
||||
add their email address to your account.
|
||||
|
||||
They then sends you a link "hey, check out this cool video!"; the link leads (via
|
||||
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
|
||||
the session that he just created.
|
||||
|
||||
Since there is no confirmation step, the server redirects directly to the SSO
|
||||
provider.
|
||||
|
||||
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
|
||||
an innocent message along the lines of "Confirm that you want to sign in to
|
||||
<your Matrix homeserver>".
|
||||
|
||||
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.
|
||||
|
||||
This problem can be mitigated by clearly telling the user what is about to happen.
|
||||
|
||||
### Reusing User Interactive Authentication sessions
|
||||
|
||||
The security of this relies on User Interactive Authentication sessions only
|
||||
being used for the same request as they were initiated for. This security is not
|
||||
only a concern for the proposed SSO authentication type. It is not believed
|
||||
that this is currently enforced in implementations.
|
||||
|
||||
## Unstable prefix
|
||||
|
||||
A vendor prefix of `org.matrix.login.sso` is proposed (instead of `m.login.sso`)
|
||||
until this is part of the specification.
|
||||
Loading…
Reference in New Issue