Skip to content

Commands

Starting things

All from the repository's folder, in any shell. For LS Login, add -f compose.lslogin.yaml after docker compose. All but e2e work with both.

Command Does
docker compose build Builds the image
docker compose run --rm e2e Runs all scenarios against the mock (mock only)
docker compose up -d --wait services Starts the services
docker compose logs -f services Shows the services' logs: decoded claims only
docker compose run --rm session Starts a session
docker compose run --rm session --record /results/<file> The same, keeping results in results/<file>
docker compose down -v Removes everything

e2e refuses to start while services is running, as it starts its own.

Services and ports

Inside the containers' shared network namespace:

Role Port
Mock (mock only) 18990
gateway 18991
node 18992
orchestrator 18993
Login callback 18994
loop (mock only: its own next hop) 18995

Only the login callback is published on the host, on 127.0.0.1, and only for LS Login.

Each service has GET /report, with the token as a bearer token, and GET /healthz.

Session commands

Results are JSON. ok says whether the request succeeded; refusals are results, too. They're decoded claims, never tokens or secrets. Lines starting with # are ignored.

Tokens are kept under names you choose. Targets in --audience and --resource can be shorthands:

Shorthand Stands for
@<role> The client ID of a role, e.g., @gateway
@<role>.url Its resource indicator in URL form
@unregistered A target that no client has registered
Command Does Options
clients Shows the configured clients, never their secrets
discovery Shows what the provider's discovery document says, including scopes_supported and claims_supported
lifetimes Shows the lifetimes of all tokens of this session
login <name> Logs in a user via the dummy client --as <role>, --flow code\|device, --scope, --resource, --no-browser, --mock-user inside\|outside, --mock-issuer short\|rogue
exchange <name> Exchanges a token; --as is the exchanging client --as <role>, --from <token>, --audience, --resource, --scope, --requested-type access\|refresh, --auth auto\|basic\|post\|none, --tamper-subject, --no-rules
refresh <name> Redeems the refresh token held by a token of the session --as <role>, --from <token>, --audience, --resource, --scope
credentials <name> Gets a client's own token --as <role>, --scope
call <service> Calls a service with a token and shows what each hop saw, including the node's entitlements the claims they came from (entitlement_claims), and why some couldn't be read (entitlements_error) --token <token>, --save <name>, --hop-limit, --traceparent, --tamper, --id-token, --full
show <name> Shows the decoded claims of a token
userinfo <name> Calls user info with a token; shows all released claims, e.g., entitlements or eduperson_entitlement
introspect <name> Introspects a token as a client --as <role>, --refresh
revoke <name> Revokes a token as a client --as <role>, --refresh
wait-expiry <name> Blocks until a token has expired; Ctrl-C ends the wait --margin <seconds>
compare <first> <second> Compares what the last hop saw in two saved calls
help Shows the commands
quit Ends the session; all tokens are gone with it

Options that only make sense on the mock: --mock-user, --mock-issuer and --no-rules.

Reasons a service gives

With status 401, reason is one of missing, malformed, issuer, type, provider, key, signature, expired, audience or claims. Other statuses:

Status Meaning
400 Invalid Hop-Limit
403 The node's policy: refused: entitlement
502 The next hop couldn't be reached, the exchange for it was refused, or user info gave no answer (refused: userinfo): the row shows why
508 The hop limit is used up