The authorize()delegate method can be used to implement authorization logic ranging from simple to complex. A skeleton with documented parameters and return values is present in the delegates.rb.sample file. By default, it just returns true, authorizing all requests.
The authorization method will be called upon every request to a public endpoint, and should therefore be written to be efficient.
Implementations should assume that the underlying source image exists. The existence check will happen separately.
Allow only requests for half-scale images or smaller
Allow only requests for identifiers matching a certain pattern
Allow only JPEG output
Allow only certain user agents
This is not foolproof, as user agents can be faked.
Allow only requests that supply a valid token in a header
Restrict a region of an image
In this example, requests for images containing any part of the bottom right quadrant of the source image will be denied.
With HTTP Basic authentication, the server sends an HTTP 401 (Unauthorized) status code along with a WWW-Authenticate: Basic header, which tells the client that subsequent requests must include an Authorization header containing encoded credentials. (Web browsers will normally prompt for these and store them for a time.)
The IIIF Authentication API 1.0 describes general patterns of access-restricting IIIF resources, including images, in a standard way. The authorize() delegate method can be used in ways that conform to this API's notions of "all or nothing" and "tiered" access.
For both of these:
extra_iiif_2_information_response_keys() must return the authentication services used by the API, which you must provide.
The authorize() method must accept bearer tokens from the client, and return a status of 200 (or true) for authorized requests; 302 for redirects; and 401 for unauthorized requests.
Tiered Access can be used to redirect to any of a number of "virtual" reduced-quality versions ("tiers") of an image based on authorization status.
The IIIF Authorization API is indifferent about how a quality tier system should work. Cantaloupe uses a resolution-based system that limits the maximum available resolution. For example, a fully-authorized user might be able to access the full resolution of an image, whereas an unauthorized user might be able to access only a half-resolution version.
This works transparently with zooming viewer clients, limiting the maximum available zoom level.
URI identifiers of scale-constrained images have a suffix in the format -numerator:denominator. So, for example, if the client requests image.tif/full/max/0/default.jpg, but is only authorized to access a half-resolution version, it is redirected to image.tif-1:2/full/max/0/default.jpg, from which it is allowed to retrieve the full size of a dynamically half-sized version of image.tif.