search

solid / data-interoperability-panel

Repository for the Solid Data Interoperability Panel
MIT License
51 stars 19 forks source link

Clarify Application Registration Discovery #287

Open woutermont opened 2 years ago

woutermont commented 2 years ago

Recently, a number of questions came up on Gitter (gitter.im/solid/webid-profile, starting Oct 21 22:17) and in private conversation with @jeff-zucker, that make it clear to me the SAI text surounding the Application Registration Discovery is far from clear to a lot of readers. They pertain most importantly to the section on Authorization. I elborate here on them as to clarify things immediately to some of the readers, and leave it up to the panel how to do so in the documents.

A first crucial point might be overlooked because it is only mentioned in subsubsection after a whole lot of less crucial schema's and tables, while in fact it is the starting point of it al. The text is rather clear i.m.o., although concrete mention of "WebID" might provide easier hooks for readers:

The Authorization Agent for a given Social Agent can be discovered by de-referencing the identity [actually the identifier, e.g. the WebID] of that Social Agent, and extracting the object value of the interop:hasAuthorizationAgent statement from the Social Agent graph in the returned identity profile document [i.e. identity document, e.g. WebID Document].

In the application primer, this is quite clear:

Every user has an Authorization Agent which can be discovered from their WebID Document via interop:hasAuthorizationAgent predicate.

It was raised a number of types that this could/should also be a Link-header.

A second point of confusion centers around the myth that apps would need their own servers to use SAI. This is not true. The only servers involved in a SAI process are:

The last two roles are combined in the current SAI draft as the Authorization Agent. All servers are thus user-specific, not app-specific. An app only needs to find the AA in the user's WebID, and this AA points the app to its Registration in some user-side indexes. No need for the app to host anything. If the app needs more access, it redirects to the AA, who asks the user for approval, and updates the indexes accordingly.

This should be clear from the application primer (and is exactly why this document is separate from the AA primer), but might be more confusing in the full specification, since these aspects are treated alongside eachother there.

A third question is how the app should approach the AA. Both the specification's subsection and the application primer skip over this quite nonchalant. Neither actually specify how the WebID and Client ID are communicated to AA; that is to say, the reader is left to infer that from the example. Indeed, this is done by the standard authorization header used in Solid: an access token containing the WebID of the user and the ClientID of the application.

Finally, it occured to some that the Data Registrations would be copies of the actual data. This would, of course, make interoperability harder instead of easier, plus take a great deal more trouble. Luckily, this assumption is not true: the Application Registrations of two different apps contain pointers to the same Data Registrations (in as far as they can access the same data). So apps have (partly) their own discovery mechanisms, but always to the same data. The AA simply keeps the mapping from the App to the data it can access. Since Data Registrations are indeed often described in the specification within their role in app-specific discovery, it might be a good idea to clarify that they are indeed the same over the whole range of apps a user has.

justinwb commented 2 years ago

@woutermont @jeff-zucker where would be the most constructive place to make these clarifications?

elf-pavlik commented 2 years ago

A third question is how the app should approach the AA. Both the specification's subsection and the application primer skip over this quite nonchalant. Neither actually specify how the WebID and Client ID are communicated to AA; that is to say, the reader is left to infer that from the example

If you refer to how the app redirects to AA for authorization this part is under specified indeed. In the implementation I've been working on I took a simple approach which adds interop:hasAuthorizationRedirectEndpoint to AA's ClientID document where app redirects adding it's own ClientID as client_id query parameter. I know that you took a different approach which is as I remember is modeled after RFC 9126: OAuth 2.0 Pushed Authorization Requests (PAR)

We should meet ASAP to discuss both approaches and reconcile them into something that will go into a spec!

woutermont commented 2 years ago

Thank @elf-pavlik! Definitely something we should look into very soon!

What I meant, though, was the interaction on AR-discovery: it is not specified explicitly that the request should contain a token including WebID and ClientID (which is crucial). This is only vaguely inferable from an example.