Various clarifications to structure

Author: turt2live

proposals/1960-integrations-openid.md

@@ -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,17 +91,17 @@ 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.
 
 ## 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]").