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

Various clarifications to structure

Browse source
This commit is contained in:
Travis Ralston 2020-08-21 08:34:35 -06:00
parent df74c7dbe3
commit 80214998f6
1 changed files with 38 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
proposals/1960-integrations-openid.md
View file

@ -1,4 +1,4 @@
# MSC1960: OpenID information exchange for widgets
# MSC1960: OpenID Connect information exchange for widgets
With the various integrations API proposals, widgets are left with no options to verify the
requesting user's ID if they need it. Widgets like the sticker picker must know who is making
@ -10,26 +10,50 @@ API proposed by [MSC1236](https://github.com/matrix-org/matrix-doc/issues/1236).
## Proposal
Room and account widgets may request a new OpenID object from the user so they can log in/register with
Room and account widgets may request new OpenID credentials from the user so they can log in/register with
the backing integration manager or other application. This is largely based on the prior art available
[here (riot-web#7153)](https://github.com/vector-im/riot-web/issues/7153). The rationale for such an
[here (element-web#7153)](https://github.com/vector-im/element-web/issues/7153). The rationale for such an
API is so that widgets can load things like a user's sticker packs or other information without having
to rely on secret strings. For example, a room could be used to let a user create custom sticker packs
via a common widget - it would be nice if that widget could auth the user without asking them to enter
their username and password into an iframe.
Widgets can request OpenID credentials from the user by sending a `fromWidget` action of `get_openid`
to initiate the token exchange process. The client should respond with an acknowledgement of
to initiate the token exchange process. The client responds with an acknowledgement of
`{"state":"request"}` (or `{"state":"blocked"}` if the client/user doesn't think the widget is safe).
The client should then prompt the user if the widget should be allowed to get details about the user,
The client then prompts the user if the widget should be allowed to get details about the user,
optionally providing a way for the user to always accept/deny the widget. If the user agrees, the
client sends a `toWidget` action of `openid_credentials` with `data` holding the raw OpenID credentials
object returned from the homeserver, and a `success: true` parameter. If the user denies the widget,
just `success: false` is returned in the `data` property. To lessen the number of requests, a client may
also respond to the original `get_openid` request with a `state` of `"allowed"`, `success: true`, and
the OpenID object (just like in the data for `openid_credentials`). The widget should not request OpenID
credentials until after it has exchanged capabilities with the client, however this is not required. The
widget should acknowledge the `openid_credentials` request with an empty response object.
object returned from the homeserver, and a `success: true` parameter, similar to the following:
```
{
"api": "fromWidget",
"requestId": "AABBCC",
"action": "openid_credentials",
"widgetId": "DDEEFF",
"data": {
"success": true,
"access_token": "SecretTokenHere",
"token_type": "Bearer",
"matrix_server_name": "example.com",
"expires_in": 3600
}
}
```
For clarity, the `data` consists of properties as returned by `/_matrix/client/r0/user/:userId/openid/request_token`
plus the `success` parameter.
If the user denies the widget, just `success: false` is returned in the `data` property.
To lessen the number of requests, a client can also respond to the original `get_openid` request with a
`state` of `"allowed"`, `success: true`, and the OpenID Connect credentials object (just like in the `data` for
`openid_credentials`).
The widget should not request OpenID credentials until after it has exchanged capabilities with the client,
however this is not required to wait for the capabiltiies exchange.
The widget acknowledges the `openid_credentials` request with an empty response object.
A successful sequence diagram for this flow is as follows:
@ -67,9 +91,9 @@ Prior to this proposal, widgets could use an undocumented `scalar_token` paramet
send it to the widget. Clients typically chose to send it if the widget's URL matched a whitelist for URLs
the client trusts. Widgets are now not able to rely on this behaviour with this proposal, although clients
may wish to still support it until adoption is complete. Widgets may wish to look into cookies and other
storage techniques to avoid continously requesting credentials.
storage techniques to avoid continously requesting credentials, regardless of how they got those credentials.
A proof of concept for this system is demonstrated [here](https://github.com/matrix-org/matrix-react-sdk/pull/2781).
An implementation of this proposal is [here](https://github.com/matrix-org/matrix-react-sdk/pull/2781).
The widget is left responsible for dealing with the OpenID object it receives, likely handing it off to
the integration manager it is backed by to exchange it for a long-lived Bearer token.
@ -77,7 +101,7 @@ the integration manager it is backed by to exchange it for a long-lived Bearer t
## Security considerations
The user is explicitly kept in the loop to avoid automatic and silent harvesting of private information.
Clients must ask the user for permission to send OpenID information to a widget, but may optionally allow
Clients must ask the user for permission to send OpenID Connect information to a widget, but may optionally allow
the user to always allow/deny the widget access. Clients are encouraged to notify the user when future
requests are automatically handled due to the user's prior selection (eg: an unobtrusive popup saying
"hey, your sticker picker asked for your information. [Block future requests]").