IIIF Auth 2

IIIF Auth v2 handles IIIF Authorization Flow API 2.0 requests and is an implmementation of DLCS RFC 012

Role Provider Types

The following role provider types are supported, this will be extended over time:

• clickthrough - auth service will render agreement, on accepting the user is granted specified roles. Not external dependencies.
• oidc - external authorization server is used for login, claims are mapped to DLCS roles, see DLCS RFC 008

Running

There is a Dockerfile and docker-compose file for running app:

# build docker image
docker build -t iiif-auth-2:local .  

# run image
docker run -it --rm \
    --name iiif-auth-2 \
    -p "8014:80" \
    iiif-auth-2:local

# run via docker-compose
docker compose up

For local debugging there are 2 docker compose files available:

• docker-compose.db.yml - runs an empty postgres instance. Running sln with RunMigrations=true will scaffold DB.
• docker-compose.local.yml - runs the above and also an nginx container, which is:
  • Running on https://localhost:5040.
  • Proxying /auth/v2/probe/* and /* to localhost:5013. This is the http port for Orchestrator as defined in launchSettings.json
  • Proxying /auth/v2/* to localhost:7149. This is the http port for iiif-auth-v2, as defined in launchSettings.json

# run postgres DB only
$ docker compose -f docker-compose.db.yml up

# run postgres DB and nginx proxy
$ docker compose -f docker-compose.local.yml up

Warning

That nginx container uses a self-signed cert. This will show browser errors but is enough for local testing.

Configuration

The following appSetting configuration values are supported:

Name	Description	Default
OrchestratorRoot	Base URI for Orchestrator, used to generate links
DefaultSignificantGestureTitle	Fallback title to use on SignificantGesture.cshtml	"Click to continue"
DefaultSignificantGestureMessage	Fallback message to use on SignificantGesture.cshtml	"You will now be redirected to DLCS to login"
Auth__CookieNameFormat	Name of issued cookie, {0} value replaced with customer Id	"dlcs-auth2-{0}
Auth__SessionTtl	Default TTL for sessions + cookies (in seconds)	600
Auth__RefreshThreshold	UserSession expiry not refreshed if LastChecked within this number of secs	120
Auth__JwksTtl	How long to cache results of JWKS calls for, in secs	600
GesturePathTemplateForDomain	Dictionary that allows control of domain-specific significant gesture paths. {customerId} replaced.
OAuthCallbackPathTemplateForDomain	Dictionary that allows control of domain-specific oauth2 callback paths. {customerId} + {accessService} replaced.
RunMigrations	If true, EF migrations will be run when app runs	false

A note on Dictionarys for domain-specific paths. A key of "Default" serves as fallback but isn't necessary if the default value matches the canonical DLCS path.

Migrations

Migrations can be added by running the following:

cd src/IIIFAuth2

dotnet ef migrations add "{migration-name}" -p IIIFAuth2.API -o Data/Migrations

Migrations are applied on startup, regardless of environment, if "RunMigrations" = "true".

Local Development

This service is an extension of DLCS Protagonist and when deployed will run under the same host as the main DLCS, with routing rules controlled at load-balancer level.

Below are steps for running iiif-auth-v2 and Orchestrator locally:

1. Run docker compose -f docker-compose.local.yml up
2. In iiif-auth-v2 set "OrchestratorRoot": "https://localhost:5040" appSetting (nginx port)
3. In orchestrator set "Auth__Auth2ServiceRoot": "https://localhost:7049/auth/v2/" appSetting (default from auth-services launchSettings)