IIIF Auth scenario where more information is available through another service

[mejackreed]

🎩 /tip to @cbeer for large parts of this implementation

Description

While implementing a check-in / checkout system using IIIF Authentication, we found it desirable to display additional dynamic information to a user once that user had a IIIF Auth token. This type of information includes:

• availability of the item
• due date
• wait list information
• loan period information

While some of this information is custom to our implementation, we think other IIIF adopters using IIIF Auth may benefit from a generalized solution to provide additional information to an Auth'ed viewer.

Variation(s)

This is a step beyond the classic scenario of logging in / logging out to view IIIF image content. There may be other cases where an IIIF Auth token can be used to gain access to additional information using that token can provide a better user experience across interoperable clients. For instance, some auth use cases may only allow viewers access for a specified time.

Proposed Solutions

Provide an additional "auth information" service in a degraded response, that a viewer can use to provide more context to the auth service. We ended up doing this in our implementation. And while we realize these aren't valid IIIF services, we thought it would be useful perhaps to others as more adopt IIIF Auth.

IIIF Degraded Information Response

{
  "@context": "http://iiif.io/api/image/2/context.json",
  "@id": "https://sul-stacks-stage.stanford.edu/image/iiif/degraded_nz655fw7739%252Fnz655fw7739_0002",
  "protocol": "http://iiif.io/api/image",
  "width": 1591,
  "height": 2418,
  "sizes": [
    {
      "width": 263,
      "height": 400
    }
  ],
  "tiles": [
    {
      "width": 256,
      "height": 256,
      "scaleFactors": [
        1,
        2,
        4,
        8,
        16
      ]
    }
  ],
  "profile": [
    "http://iiif.io/api/image/2/level2",
    {
      "maxWidth": 400,
      "maxHeight": 400
    }
  ],
  "service": {
    "@context": "http://iiif.io/api/auth/1/context.json",
    "@id": "https://sul-stacks-stage.stanford.edu/auth/iiif/cdl/nz655fw7739/checkout",
    "profile": "http://iiif.io/api/auth/1/login",
    "label": "Available for checkout",
    "header": "SUNetID required: This item is available to Stanford affiliates only. Download is prohibited.",
    "confirmLabel": "Check out",
    "failureHeader": "Unable to authenticate",
    "failureDescription": "The authentication service cannot be reached.",
    "service": [
      {
        "@id": "https://sul-stacks-stage.stanford.edu/image/iiif/token/nz655fw7739",
        "profile": "http://iiif.io/api/auth/1/token"
      },
      {
        "@id": "https://sul-stacks-stage.stanford.edu/auth/iiif/cdl/nz655fw7739/checkin",
        "profile": "http://iiif.io/api/auth/1/logout",
        "label": "Check in early"
      },
+      {
+        "@id": "https://sul-stacks-stage.stanford.edu/cdl/nz655fw7739",
+        "profile": "http://iiif.io/api/auth/1/info"
+      },
      {
        "@id": "https://sul-stacks-stage.stanford.edu/auth/iiif/cdl/nz655fw7739/renew",
        "profile": "http://iiif.io/api/auth/1/renew"
      }
    ]
  }
}

Additional Background

Some examples of the different user experiences

With additional auth information

Without additional auth information

[tomcrane]

Discussed on Auth call -

This is a neat use of the Auth spec, reusing the token against other services. But wouldn't the implementation always be so specific that the specialised client knows what to do anyway, and telling it to do that via spec would be too complicated?

In the json above, the client would interpret the profile "http://iiif.io/api/auth/1/info" as "when I am a service for a resource that has a IIIF token service, you can use the token you get from that service to talk to me, too" - but that profile doesn't need to be specced because the particular info provided in each case could be anything...