IIIF Servers, CORS and the OPTIONS method

[Christopher Johnson]

Hi list,

I would like to make a general announcement about a technical topic that seems to be misunderstood by many institutions that are supporting IIIF image servers.  Actually supporting the CORS protocol (per the Fetch specification) requires an image server or proxy to handle the OPTIONS method.  Frequently, providers will simply add the "Access-Control-Allow-Origin" header to the default response configuration, but this is not sufficient.

There are new browser APIs like Service Workers that depend on CORS working correctly.  

Adding OPTIONS support to Apache is as simple as:

AllowMethods GET HEAD OPTIONS

Unfortunately, most of the guides on CORS for Apache omit this essential detail.  The server needs to accept an OPTIONS request and not just provide CORS headers.

You can test if your server supports OPTIONS with cURL:

curl -v -H "Origin: http://example.com" -X OPTIONS https://www.googleapis.com/discovery/v1/apis?fields=


The response should just provide the headers and not a body.

For CORS on nginx, see https://enable-cors.org/server_nginx.html

And for those of you who are supporting image servers and CORS with the OPTIONS method correctly, congratulations!

Christopher Johnson

Scientific Associate

Universitätsbibliothek Leipzig

[Christopher Johnson]

Hi list,

Just a quick follow up on this.  Logos should also be provided from servers that support CORS.  While current viewer implementations like Mirador and the UV are not using the crossorigin attribute for <img> elements, I believe that this should be done and perhaps even backported into existing releases as its continued omission could/should raise some security concerns.  

Note however that the browser will not do a preflght for crossorigin <img> so OPTIONS is not required for logos and thumbnails.  An OPTIONS preflight for XHR or Fetch on images or json should be done if the request includes the appropriate headers.  

The reason that unimplemented OPTIONS works currently for crossorigin JSON manifests (in general) is that (typically) the viewers are not providing request headers when it gets the JSON to let the browser know that the request is a non-simple CORS request, (for example, 

"x-requested-with": "XMLHttpRequest"

) and also that openseadragon does not use XHR (aka ajax) to fetch tiles or the info.json by default.  

Christopher Johnson

Scientific Associate

Universitätsbibliothek Leipzig