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 |