Acquiring and using auth credentials

[tomcrane]

If there is a #184, then there must be access control.

This could be at the network level - the repository is not exposed to the internet at all, or it is restricted by IP, but if you can see it you can read and write.

However it's likely that more fine-grained access control will be required; the Manifest Editor will need to be able to acquire and use tokens to interact with the storage API. And it's likely some users will be able to read, some to read and write, and even that differing levels of access to different resources are required.

The Manifest Editor needs to be able to acquire access tokens for the storage API using OAuth2.
We don't need to (and shouldn't) specify what's going on inside those tokens - e.g., a likely implementation would use JWT but the Manifest Editor as a client doesn't need to know that and regards any tokens as opaque.

The token is a matter for the token issuer and the token consumer (the storage API).

However, the storage spec can be opinionated about the OAuth2 exchange, so that the Manifest Editor can be a client of any implementation of the storage spec. (Note how this is completely unlike IIIF Auth, because it's a direct API consumption, not an indirect media consumption). That is, there is a particular profile or pattern of OAuth2 that the Manifest Editor and the Storage Server implement.

[tomcrane]

Summary of discussion from Slack

For both IIIF-Browser (#43) and Manifest Editor, interaction with the repository will need to use cookies for the MVP, as CRKN can ensure the user is logged in.

In the MVP, the Manifest Editor and the IIIF Browser will rely on the fact that the user is already logged in and has a cookie on the same domain as the Manifest Editor and the Storage Service, and that the storage service can validate this cookie (probably by sending the value to some service) to authorize the API request (whether it’s a PUT, POST or GET).

In the long run the Manifest Editor should participate in the OAuth2 flow Authorization Code Flow with Proof Key for Code Exchange (PKCE) to acquire Access Tokens for the storage service. A simpler explainer.

Our eventual IIIF storage spec needs to describe this interaction sufficiently so that the Manifest Editor could go up against any implementation of the storage service and successfully obtain an access token. That can come later, as it would potentially also provide an extension to the IIIF specification itself.

For MVP assume that cookies are present, and that the Manifest Editor has a flag to send cookies when interacting (GET, POST, PUT) with particular domains. The onus is on the storage service to issue these cookies correctly.

We can have config in the ME like:

{
   "auth" : {
      "iiif-repository.crkn-rcdr.ca": "cookies",
      "future-repo.example.org": "oauth2-pkce"
   }
}

Extra notes:

Comparison with IIIF Auth

---

The current IIIF Auth spec describes a flow that allows a user to acquire a cookie, and the manifest editor could follow that flow to be confident that the user has that cookie, but the manifest editor scenario - an API client making fetch or xhr requests for (typically) JSON resources is specifically not what the current IIIF Auth flow is designed for; the IIIF Auth spec at the moment assumes that the IIIF resources themselves - manifests, etc - are not protected - only the image tiles (and now in v2 any Content Resource like a video, PDF etc); and that the client (i.e., the executing JavaScript) doesn't need to make direct credentialled requests because it generates elements like <img/> tags that cause the browser to make content requests, which fall under a different security context.

However with our REST / Storage API we are outside the scope of the IIIF Auth spec (as it currently stands) so we can add in additional requirements. We can make the manifest editor make credentials: "include" fetch requests for the IIIF resources. This puts some extra constraints on the server, it needs to not set Access-Control-Allow-Origin: * and instead use the specific domain of the request; it needs to be careful with Access-Control-Allow-Credentials, use of the SameSite cookie attribute etc; it needs to be designed to support browser-based clients making API requests that use cookies for auth rather than bearer tokens, which makes it fragile in the face of changing browser security policies.

This is all doable, but if we were to make a more formal spec for interop between the IIIF repository and clients like viewers and the manifest editor, then that spec should not use cookies and instead be token-based, as these are API interactions initiated from script, not content interactions initiated by the browser (for which cookies are fine). Machine-to-machine callers would use these tokens anyway. This is what I mean when I talk about IIIF needing a common profile/pattern for an OAuth2 interaction for interoperability of API resources - this is a counterpart to the Auth flow spec, not a replacement or an alternative.

Sorry for overcomplicating it... just looking ahead to interoperability, which for the IIIF repository will need a common understanding between client and server of how to negotiate auth. The current IIIF auth spec does not provide this, it provides a mechanism for the client to send the user to some external auth process and then observe some of the results, but remains unaware of what that auth process is. If cookies are being used the Manifest Editor needs to be aware of this aspect of protocol - it would need to know to send credentialled requests, for example, and later if the protocol changed to tokens it would need to know to participate in a particular OAuth2 flow and include the tokens it obtained in the API requests - i.e., it's aware of the protocol in a way that the UV is not when it participates in IIIF Auth.