Skip to content

Handle IpRestriction roles - #1344

Merged
donaldgray merged 8 commits into
developfrom
feature/ip_role
Nov 10, 2026
Merged

donaldgray merged 8 commits into
developfrom
feature/ip_role

Conversation

@donaldgray

@donaldgray donaldgray commented Oct 30, 2026 •

Copy link
Copy Markdown
Member

What does this change?

Orchestrator support for the IpRestriction role-provider added to iiif-auth-v2 (see the dlcs/iiif-auth-v2#68). Requests from known CIDR ranges (e.g. a reading room) can be granted ip: roles without signing in. Auth2 evaluates these from the client IP on each request; they are never stored in a session. Orchestrator's job is to:

  1. Work out the real client IP
  2. Call iiif-auth-v2 (forwarding that IP) in cases where it previously short-circuited because there was no token or cookie. It uses the ip: prefix for this.

This PR also has two related changes that came up while doing this: predictable ordering of manifest-level access services, and info.json always returning 200 (behind a rollback flag).

IP roles

  • Detecting IP roles: new DLCS.Model.Auth.RoleX with IsIpRole() / ContainsIpRole(). A role is an IP role if its final path segment starts with ip: (e.g. https://api.dlcs.io/customers/2/roles/ip:reading-room). This is the same convention as iiif-auth-v2. The prefix lets Orchestrator decide, without a lookup, whether it needs to call Auth2.
  • Client IP: the IP forwarded to Auth2 comes from a new IClientIpResolver. Forwarded headers config (ConfigureForwardedHeaders, DLCS.Web) is unchanged: x-forwarded-for isn't processed, so Connection.RemoteIpAddress remains the direct caller.
    • Orchestrator can be reached both via CloudFront → ALB and directly via the ALB, so the client's position in XFF varies: 2nd from right via CloudFront, rightmost directly. See internal ADR for discussion around this.
    • Requests via a CDN in front of the load balancer (CloudFront today, but nothing is CloudFront-specific) are identified by a secret shared header the CDN adds (Auth:CdnOriginVerify, default header X-Origin-Verify). With a valid secret the 2nd XFF entry from the right is used, otherwise the rightmost. With no secrets configured it's always the rightmost.
    • The secret check is in ClientIpCaptureMiddleware, which runs before forwarded headers middleware. It captures the received XFF and caller IP, compares the secret in constant time (SHA256 + FixedTimeEquals, any configured secret, so it can be rotated), then removes the header so it's never logged or proxied downstream. YARP copies request headers to image servers and S3.
    • The resolver also requires the caller (load balancer) to be in KnownNetworks/KnownProxies, as the built-in middleware does.
  • IIIFAuth2Client:
    • When roles contain an IP role, probe_internal and verifyaccess requests carry X-Forwarded-For: <client-ip>. The header isn't sent for other roles.
    • The probe access token is now optional, and no Authorization header is sent without one.
    • If there's no token and no IP role, missingCredentials is returned without calling Auth2 (shortcut response)
  • Probe (ProbeServiceSupport): the item is now looked up before the bearer-token check. A missing token still returns 401 (missingCredentials) unless the item has an IP role, in which case Auth2 is called with no token. Behaviour for items without IP roles is unchanged, including not-found items without a token.
  • Content access (AssetAccessValidator): Auth2 verifyaccess is called when there's an Auth2 cookie or the roles contain an IP role. This covers images, files, timebased and adjuncts.
  • verifyaccess caching: results are cached in memory for a very short time, so a burst of requests for one image (e.g. hundreds of deep zoom tiles) doesn't make hundreds of verifyaccess calls.
    • Granted results are cached for 5s and denied (401/403) results for 2s by default. Both use the existing cache-override mechanism, with new CacheOverrideKeys.VerifyAccess / VerifyAccessDenied keys (Caching:TimeToLive:Memory:Overrides:VerifyAccess). Setting both to 0 disables caching.
    • The key is deliverable + canonical roles string (as sent) + client IP + a SHA256 of the customer's Auth2 cookie value.
      • The client IP is only included when there's an IP role, as that's the only time it's forwarded.
      • The cookie value comes from the new AuthCookieManager.GetAuth2CookieValueForCustomer. It's hashed so raw session ids aren't kept in cache keys.
      • Results are never shared between users, e.g. a signed-in user behind the same NAT as others.
      • The deliverable is deliberately part of the key. Auth2 currently decides from customer + roles only, but the deliverable is part of the verifyaccess contract, and planned appointment-based roles will make the decision depend on it. Deep zoom tiles all share a deliverable, so this costs nothing in the main burst case.
      • Anything else Auth2's decision comes to depend on must also be added to the key (GetVerifyAccessCacheKey).
    • Errors (exceptions, or statuses other than 2xx/401/403) are not cached and still return false.

Manifest access service ordering

ManifestV3Builder.GetDistinctAccessServices now orders the manifest-level services with external profile first, then by id. This ensures viewers will attempt external first.

  • Previously the order depended on the order of a ConcurrentDictionary filled by parallel GetAuthServices calls, so it could differ between builds of the same manifest.
  • The order inside each resource's embedded probe service (the one clients choose from) is the order iiif-auth-v2 returns, which is already external first.

info.json always 200

For restricted images, info.json now returns 200 with Cache-Control: public, regardless of credentials. This is #1132

  • With Auth2, the client works out access via the probe service, not the info.json status code.
  • Previously Auth2 assets always got 401 from info.json, which broke some Auth2 implementations.
  • InfoJsonCanBeNon200=true flag restores the previous behaviour (401 + private, bearer-token validation and Auth1 token refresh). This is a rollback switch while Auth1 support is removed; there are no Auth1 users. This feature flag will be dropped in future when we remove auth1 support.
  • InfoJsonService also now logs and returns null if a stored info.json deserialises to null (unlikely in practice, was to silence warning).

Infrastructure Changes

Note

This PR requires infrastructure changes.

  • Required:
    • Set KnownNetworks on Orchestrator to the load balancer subnets. The client IP is only resolved from X-Forwarded-For if the caller is in KnownNetworks, and with the default AllNetworks any caller that can reach Orchestrator directly could spoof its IP. The same applies to iiif-auth-v2.
    • CloudFront deployments: add a custom origin header (X-Origin-Verify by default) to the CloudFront origin, with the same secret as Auth:CdnOriginVerify:Secrets. Store the secret in Secrets Manager and inject it into both. To rotate, add the new value to Orchestrator's Secrets first, switch CloudFront over, then remove the old value.
    • Orchestrator reaches Auth2 through the public ALB, which appends Orchestrator's IP (the NAT gateway's public IP) to the forwarded XFF. iiif-auth-v2 needs ForwardLimit=2, with the VPC CIDR and the NAT gateway public IPs in its KnownNetworks. Otherwise it treats the client IP as unknown and doesn't grant IP roles. Restrict /auth/v2/probe_internal* and /auth/v2/verifyaccess* on the ALB to the NAT gateway IPs with a source-ip listener rule.
  • Optional: None.

Configuration Changes

Note

This PR introduces configuration changes.

Service AppSetting Required? Description Default
Orchestrator KnownNetworks N (strongly recommended) Existing setting. Comma-separated CIDR ranges of proxies that x-forwarded-* headers are accepted from. Now also checked before resolving the client IP from x-forwarded-for "AllNetworks"
Orchestrator Auth:CdnOriginVerify:HeaderName N Name of the custom header the CDN (e.g. CloudFront) adds to identify requests that came through it X-Origin-Verify
Orchestrator Auth:CdnOriginVerify:Secrets N (required behind a CDN) Accepted values for the CDN header. More than one is allowed for rotation. If empty, the rightmost XFF entry is always used as the client IP []
Orchestrator Auth:InternalProxyHops N Optional additional proxies between LB and Orchestrator. Defaults to 1 for Varnish. 1
Orchestrator Caching:TimeToLive:Memory:Overrides:VerifyAccess N Seconds to cache a granted verifyaccess result. Set this and VerifyAccessDenied to 0 to disable 5 (code default)
Orchestrator Caching:TimeToLive:Memory:Overrides:VerifyAccessDenied N Seconds to cache a denied (401/403) verifyaccess result 2 (code default)
Orchestrator InfoJsonCanBeNon200 N If true, info.json for restricted images returns 401 when the user doesn't have access (legacy behaviour, rollback switch) false

Breaking Changes

Caution

This PR introduces breaking changes.

Service Description Notes
Orchestrator GET /iiif-img/{id}/info.json for restricted images returns 200 instead of 401 Set InfoJsonCanBeNon200=true to revert
Orchestrator GET /iiif-img/{id}/info.json for restricted images returns Cache-Control: public instead of private Body no longer varies by user. Reverts with the same flag, but CDN-cached responses persist until they expire

Resolves #1342
Resolves #1132

Required for handling IP based access control
Update calls to iiif-auth-v2 to handle IP roles, adding XFF if IP role
is present and altering logic so that existence of cookie is no longer
deciding factor in shortcuts
This is auth2 handling, the probe service serves as a separate way for
client to check what status the are to expect.
Auth1 used info.json. I've added a feature flag to enable the old
behaviour again should we run into issues - this should be a relatively
short lived feature flag once we remove auth1.
Extended CacheSettings helpers to allow default to be passed if
override not found.
Updated GetRolesString to ensure consistent order
@donaldgray
donaldgray requested a review from a team as a code owner October 30, 2026 17:43
@donaldgray
donaldgray marked this pull request as draft November 2, 2026 14:08
CDN can include a header with shared secret. This is then used to
determine which XFF to forward to iiif-auth requests
@donaldgray
donaldgray marked this pull request as ready for review November 2, 2026 15:55
Varnish side car in deployed environment adds a potential hope that
isn't accounted for
@donaldgray
donaldgray merged commit 4b22ad0 into develop Nov 10, 2026
16 checks passed
@donaldgray
donaldgray deleted the feature/ip_role branch November 10, 2026 13:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

IP role provider Update info.json behaviour for iiif auth v2

2 participants