Access Control

This page is about end-user access control for assets and the services derived from them — not about authenticating to the platform’s own APIs, which use the customer credentials described in the Overview.

Configuration is not yet available through the API

Access control is enforced at runtime today, but the resources that configure it — roles, access (auth) services and role providers — cannot yet be created or edited through the REST API. They are set up by the service team on request. The API design for managing them is tracked in protagonist #538; this page will be extended when it lands.

Summary

• An Asset has roles: an array of URIs. An asset with no roles is open. An asset with roles can only be accessed by a user whose session holds at least one of them.
• A Space has a defaultRoles property, but it is not currently applied to assets registered into the space (see the caution there; protagonist #1253). Set roles on each asset.
• A user acquires roles by interacting with an access service in the browser, using the IIIF Authorization Flow API 2.0. The access service delegates to a role provider — the thing that decides which roles this user gets.
• Two role provider types are available: clickthrough (the user accepts a statement; no identity is needed) and OIDC (the user signs in with your identity provider, and its claims are mapped to roles).

Roles

Roles are opaque URIs of the form {api}/customers/{customer}/roles/{roleId}. They mean something to you — “faculty”, “reading-room”, “accepted-terms” — but to the platform they are just labels to match between an asset and a user’s session. Set them on each asset with the roles property (a space’s defaultRoles is stored but not yet applied).

For image assets, openFullMax lets an access-controlled image be served openly below a given size, so thumbnails can be public while the full image is restricted — see Size Restrictions.

Roles apply to assets. Adjuncts are not access-controlled, and a manifest generated by the platform is itself public: it is the image, audio and video services inside it that are protected.

What a viewer sees

When a IIIF viewer meets a protected resource it follows the IIIF Auth 2.0 flow, entirely from the service descriptions the platform includes in the Image API and Presentation API responses:

1. a probe service tells the viewer whether the current session can access the resource;
2. if not, the viewer opens the access service in a new window — the clickthrough page or your identity provider’s login — and on success the platform establishes a session (a cookie) carrying the roles obtained from the role provider;
3. the viewer obtains an access token for that session and retries the probe, then loads the content;
4. a logout service ends the session.

No integration work is needed on the viewer side beyond IIIF Auth 2.0 support, which the common viewers have.

What is not yet possible

Until the management API exists you cannot, through the API:

• list, create or modify the roles a customer has (the roles, authServices and roleProviders links on the Customer resource are present but currently return 404);
• create an access service or configure a role provider (OIDC endpoints and claim-to-role mappings, clickthrough text);
• inspect or revoke user sessions.

If you need access control configured for your assets, ask the service team, quoting the role URIs you want to use.