6.8 KiB
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 the request and as such need a way to get accurate information about who is contacting them.
This proposal introduces a way for widgets (room and account) to do so over the fromWidget
API proposed by MSC1236.
Proposal
Room and account widgets may request new OpenID Connect 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 (element-web#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 Connect credentials from the user by sending a fromWidget
action of get_openid
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 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 Connect credentials
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 Connect 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:
+-------+ +---------+ +---------+
| User | | Client | | Widget |
+-------+ +---------+ +---------+
| | |
| | Capabilities negotiation |
| |<-----------------------------------------|
| | |
| | Capabilities negotiation |
| |----------------------------------------->|
| | |
| | fromWidget get_openid request |
| |<-----------------------------------------|
| | |
| | ack with state "request" |
| |----------------------------------------->|
| | |
| Ask if the widget can have information | |
|<--------------------------------------------| |
| | |
| Approve | |
|-------------------------------------------->| |
| | |
| | toWidget openid_credentials request |
| |----------------------------------------->|
| | |
| | acknowledge request (empty response) |
| |<-----------------------------------------|
Prior to this proposal, widgets could use an undocumented scalar_token
parameter if the client chose to
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, regardless of how they got those credentials.
An implementation of this proposal is here.
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.
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 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]").