Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/about/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,15 +48,15 @@ Tokens are kept under names you choose. Targets in `--audience` and `--resource`
| Command | Does | Options |
|---|---|---|
| `clients` | Shows the configured clients, never their secrets | |
| `discovery` | Shows what the provider's discovery document says | |
| `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 | `--token <token>`, `--save <name>`, `--hop-limit`, `--traceparent`, `--tamper`, `--id-token`, `--full` |
| `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 released entitlements | |
| `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>` |
Expand Down
4 changes: 3 additions & 1 deletion docs/setup/client-registration.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ Register them at the [service registration app](https://services.aai.lifescience
| `tx-test-client` | Krini with a backend | confidential | authorization code with PKCE, refresh token, token exchange, device code | `openid`, `entitlements`, `offline_access` |
| `tx-test-public` | Krini without a backend | public, PKCE | as `tx-test-client` | as `tx-test-client` |

Other clients of the same issuer got entitlements with the scope and claim `eduperson_entitlement` ([What we've seen](../testbed/assumptions.md#what-weve-seen)). If [T3](../tests/t3-groups.md) shows none with `entitlements`, ask for `eduperson_entitlement` on each client, too.

Redirect URI of the last two: `http://localhost:18994/callback`. The others have none.

Resource indicators:
Expand Down Expand Up @@ -80,7 +82,7 @@ The VO admins perform group assignments to the resource. The client maintainer c

1. Create a resource for the relevant VO on the facility representing the client.
2. Send the VO admins links to the resource and the groups to assign. Ask them to complete the assignment and confirm it. Verify that the groups appear among the resource's assigned groups.
3. Log in with a test account belonging to the assigned group, and use the session's `userinfo <token-name>` command to inspect the released entitlements. Compare the exact value with `TESTBED_REQUIRED_ENTITLEMENT` in `lslogin.env`; do not assume the example value matches.
3. Log in with a test account belonging to the assigned group, and use the session's `userinfo <token-name>` command to inspect the released entitlements. Compare the exact value with `TESTBED_REQUIRED_ENTITLEMENT` in `lslogin.env`; do not assume the example value matches. Note the claim it came in, too: `entitlements` or `eduperson_entitlement` ([What we've seen](../testbed/assumptions.md#what-weve-seen)).
4. Repeat the release setup for each service that needs it. For this testbed, follow the facility list above, preserving the deliberate omission for the orchestrator in T3.
5. Use T3 to verify that a user outside the required group can still log in but receives 403 from the node.

Expand Down
1 change: 1 addition & 0 deletions docs/setup/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ All settings are environment variables.
| `TESTBED_GATEWAY_RESOURCE` | The same for the gateway | |
| `TESTBED_ORCHESTRATOR_RESOURCE` | The same for the orchestrator | |
| `TESTBED_REQUIRED_ENTITLEMENT` | The value that the node's policy requires, from any entitlement or capability; empty for no policy. `ECP_CLN` in the template is an example | On the mock: a made-up one |
| `TESTBED_ENTITLEMENT_CLAIMS` | Claims of user info that the node reads entitlements from, comma-separated. It takes the union of their values, and its row names the claims that were there (`entitlement_claims`). A claim of another type is skipped and named in `entitlements_error`: then only the other claims can allow the user, and without the entitlement in them, the node answers 502. Applies to the mock, too, which releases `entitlements`. LS Login's docs name `entitlements`; other clients of the same issuer got `eduperson_entitlement` ([What we've seen](../testbed/assumptions.md#what-weve-seen)) | `entitlements,eduperson_entitlement` |
| `TESTBED_TARGET_PARAM` | How services name their next hop in exchanges: see below | `audience` |
| `TESTBED_EXCHANGE_SCOPE` | `scope` that services request in exchanges; empty for none | |
| `TESTBED_ISSUER` | Issuer, exactly as in tokens. For trying another stack, e.g., `https://login.aai.lifescience-ri.eu/cas/oidc` (never tried) | `https://login.aai.lifescience-ri.eu/oidc/` |
Expand Down
6 changes: 4 additions & 2 deletions docs/setup/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,11 @@

**A token is "not yet valid".** Check the machine's clock: as in FOCA, there's no leeway.

**A node answers 502 with `refused: userinfo`.** The node couldn't find out the entitlements: `entitlements_error` in its row says why. This isn't a decision about the user. Perhaps the exchanged token lacks a scope for user info: see `TESTBED_EXCHANGE_SCOPE`.
**A node answers 502 with `refused: userinfo`.** The node couldn't find out the entitlements: `entitlements_error` in its row says why, e.g., a claim in `TESTBED_ENTITLEMENT_CLAIMS` that isn't a list of strings. This isn't a decision about the user. Perhaps the exchanged token lacks a scope for user info: see `TESTBED_EXCHANGE_SCOPE`.

**A node answers 403 for a member of the group.** The release is probably missing on the exchanging client ([C4](../testbed/assumptions.md#constraints)).
**A node answers 200, but its row has `entitlements_error`.** A claim in `TESTBED_ENTITLEMENT_CLAIMS` wasn't a list of strings and was skipped; another claim held the entitlement. Record which claim it was, and what `userinfo` shows in it.

**A node answers 403 for a member of the group.** The release is probably missing on the exchanging client ([C4](../testbed/assumptions.md#constraints)). Check `entitlement_claims` in the node's row, too: if it's empty, user info held none of the claims in `TESTBED_ENTITLEMENT_CLAIMS`. Compare with what `userinfo` shows, and add the claim that holds them.

**A service answers 502 with `refused: exchange`.** LS Login refused the next hop's exchange, or couldn't be reached. The row says which.

Expand Down
4 changes: 3 additions & 1 deletion docs/testbed/assumptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Our own assumptions, from no statement at all:

These pages describe Perun and its proxy. They cover several Perun instances, so they may not describe LS Login exactly.

- [Entitlements](https://perunaai.atlassian.net/wiki/spaces/PERUN/pages/209813518/Entitlements): in OIDC, request the `entitlements` scope to receive the values in the `entitlements` claim at the UserInfo endpoint, as specified by [AARC-G069](https://aarc-community.org/guidelines/aarc-g069/). The testbed uses only this scope and claim name. A group entitlement is released for each group the user is in, if that group is assigned to a resource on the facility of the service.
- [Entitlements](https://perunaai.atlassian.net/wiki/spaces/PERUN/pages/209813518/Entitlements): in OIDC, request the `entitlements` scope to receive the values in the `entitlements` claim at the UserInfo endpoint, as specified by [AARC-G069](https://aarc-community.org/guidelines/aarc-g069/). Other clients of the same issuer got another claim, though: see [What we've seen](#what-weve-seen). The testbed's login asks for the scope `entitlements`, and the node reads both claims (`TESTBED_ENTITLEMENT_CLAIMS` in [Configuration](../setup/configuration.md#settings)). A group entitlement is released for each group the user is in, if that group is assigned to a resource on the facility of the service.
- [Group entitlement](https://perunaai.atlassian.net/wiki/spaces/PERUN/pages/350879786/Group+entitlement): the value depends on group names, in the form `<NAMESPACE>:group:<GROUP>[:<SUBGROUP>*][#<AUTHORITY>]`, so it changes if a group is renamed or moved.
- [Resource capability](https://perunaai.atlassian.net/wiki/spaces/PERUN/pages/351272963/Resource+capability): the alternative that doesn't depend on group names. The Entitlements page recommends it for that reason.
- [Facility](https://perunaai.atlassian.net/wiki/spaces/PERUN/pages/2252570626/Facility) and [Resource](https://perunaai.atlassian.net/wiki/spaces/PERUN/pages/2261055/Resource): the entities behind A9.
Expand Down Expand Up @@ -80,4 +80,6 @@ The `/oidc/` document again, on 2026-11-13, for [delegated access](delegated-acc
- **Listed:** the scope `offline_access`; the grants `refresh_token` and token exchange; a revocation endpoint, `https://login.aai.lifescience-ri.eu/oidc/revoke`; an introspection endpoint; the token endpoint authentication methods `client_secret_basic`, `client_secret_post` and `none`.
- **Not listed:** `prompt_values_supported`, `dpop_signing_alg_values_supported`, `tls_client_certificate_bound_access_tokens` and `backchannel_logout_supported`. A missing field doesn't prove that a feature is missing, but no standard way of binding tokens to a client instance is advertised ([C11](#constraints)).

Entitlements as LS Login released them to other clients of the `/oidc/` issuer (read on 2026-11-12 and 2026-11-15, recorded in [generic-issues#46](https://github.com/elixir-cloud-aai/generic-issues/issues/46)): in the claim **`eduperson_entitlement`**, not `entitlements`, and in user info only. The access token carried the scope `eduperson_entitlement`, but not the values. Which claim the testbed's clients get with the scope `entitlements` is unknown until [T1](../tests/t1-call-chain.md) and [T3](../tests/t3-groups.md) have run, so the node reads both, and trusts them equally. That's only safe if LS Login fills both from Perun's groups, not from attributes of a user's home organisation, which nothing public says. Once T3 has shown which claim the clients get, set `TESTBED_ENTITLEMENT_CLAIMS` to that one.

A login token of Krini's, seen by us on 2026-10-20: `typ` was `at+jwt`, and `aud` held the client's ID.
2 changes: 1 addition & 1 deletion docs/testbed/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ With the orchestrator in the chain, the client exchanges for the orchestrator, a
## What the services do

- **Validation:** as in FOCA's `foca.security.auth._validate()` with its defaults (checked against FOCA 0.19.0): trusted issuer, `typ` is `at+jwt`, discovery, signature (RS256), `exp`, `iat`, `iss`, `sub`, `aud`, no leeway. Unlike FOCA, it tells the caller the reason.
- **Node:** validates, reads entitlements from user info, applies its own policy (403 without the group, 502 if user info gives no answer), reports what it saw.
- **Node:** validates, reads entitlements from user info (both `entitlements` and `eduperson_entitlement` by default), applies its own policy (403 without the group, 502 if user info gives no answer), reports what it saw.
- **Gateway:** validates, exchanges the token for the next hop, forwards, reports all hops. With another role, the same code is the orchestrator. Authorisation at the gateway only covers who may use the gateway.
- **`Hop-Limit` header:** further forwards allowed, by default 8; at 0 a forwarding service answers 508. It's custom, as `Max-Forwards` only applies to TRACE and OPTIONS.
- **`traceparent`:** valid [W3C Trace Context](https://www.w3.org/TR/trace-context/) values pass through unchanged, others are replaced.
Expand Down
4 changes: 2 additions & 2 deletions docs/tests/t1-call-chain.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ tb> clients
tb> discovery
```

Provider `lslogin`, `ls_login_rules_emulated: false`, all five clients, and token exchange among the grant types. No testbed rule applies from here on: refusals are LS Login's own, with `refused_by: provider`.
Provider `lslogin`, `ls_login_rules_emulated: false`, all five clients, and token exchange among the grant types. Note which of `entitlements` and `eduperson_entitlement` are in `scopes_supported` and `claims_supported`: the node reads both claims ([T3](t3-groups.md)). No testbed rule applies from here on: refusals are LS Login's own, with `refused_by: provider`.

### Login: user to client

Expand Down Expand Up @@ -124,7 +124,7 @@ Discovery at `/oidc/` lists the auth method `none`, and at `/cas/oidc` doesn't (

| Step | Record | Result |
|---|---|---|
| Provider and clients | Provider, grant types | |
| Provider and clients | Provider, grant types, and which entitlement scopes and claims are listed | |
| Login | `sub`, `typ`, `aud`, `client_id`, `exp` minus `iat`, whether there's a refresh token, what the consent page lists, and whether it mentions offline access | |
| Hop 1 | Which parameter works, `aud`, `client_id`, `azp`, `exp` minus `iat`, `scope`, `typ` | |
| URL form | `aud`, the status of the call | |
Expand Down
11 changes: 9 additions & 2 deletions docs/tests/t3-groups.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,13 @@ tb> exchange to-node-s --as gateway --from to-gw --audience @node --scope "openi
tb> userinfo to-node-s
```

The node reads entitlements from `entitlements` and `eduperson_entitlement` (`TESTBED_ENTITLEMENT_CLAIMS`), and its row names the claims it found them in (`entitlement_claims`). Note which of the two `userinfo user` shows. If it shows neither, log in with account A again, with the other scope, once, and note whether the registration allows it:

```text
tb> login u2 --as client --scope "openid eduperson_entitlement offline_access"
tb> userinfo u2
```

### Account A through the chain

```text
Expand Down Expand Up @@ -100,7 +107,7 @@ We derived the example from a known entitlement of the same form ([A12](../testb
| Step | Record | Result |
|---|---|---|
| Release per client | The entitlements for each line. Does `introspect --as node` differ? Does the exchange need the `scope`? | |
| Exact value | The entitlement in user info, compared with `TESTBED_REQUIRED_ENTITLEMENT` | |
| Account A | Status, `policy` at the node | |
| Exact value | The entitlement in user info, compared with `TESTBED_REQUIRED_ENTITLEMENT`; the claim it came in (`entitlements` or `eduperson_entitlement`) and the scope it took: `entitlements`, or `eduperson_entitlement` from `u2`, and whether the registration allowed that | |
| Account A | Status, `policy` and `entitlement_claims` at the node | |
| Account B | Login, exchange, status and `refused` at the node | |
| Group release | Which role it took, and who granted it | TrustedFacilityAdmin within the relevant VO; not granted for this setup, so the VO admins assign groups on request ([Client registration](../setup/client-registration.md#who-can-assign-groups)) |
4 changes: 4 additions & 0 deletions lslogin.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,10 @@ TESTBED_ORCHESTRATOR_RESOURCE=https://tx-test-orchestrator.elixir-on.cloud/

# The node's policy; an example, to be compared with what `userinfo` shows
TESTBED_REQUIRED_ENTITLEMENT="urn:geant:lifescience-ri.eu:group:elixir:ECP_CLN#aai.lifescience-ri.eu"
# Claims of user info that hold entitlements, comma-separated; the node takes
# the union. LS Login's docs name `entitlements`, but other clients of the
# same issuer got `eduperson_entitlement`
TESTBED_ENTITLEMENT_CLAIMS=entitlements,eduperson_entitlement

# How services name their next hop in exchanges: audience, resource,
# resource-url or both
Expand Down
48 changes: 36 additions & 12 deletions src/testbed/service.py
Original file line number Diff line number Diff line change
Expand Up @@ -110,29 +110,52 @@ def __init__(
def _entitlements(self, token: str, claims: dict[str, Any]) -> dict[str, Any]:
"""Get the user's entitlements from user info, as computed for this token.

The values are the union of all configured claims, in order of
appearance, as providers differ in the claim they release them in. A
claim that is `null` counts as absent. A claim of another type is
skipped and named in `error`: the policy then allows the user only if
another claim holds the entitlement, and otherwise makes no decision.

Args:
token: Validated access token.
claims: Verified claims of the token.

Returns:
Entitlements, or the reason why there are none to show.
Entitlements, the names of the claims they were read from, and the
reason why some or all couldn't be read, if any.
"""
try:
userinfo = self.tokens.userinfo(token)
except Refused as exc:
return {"values": [], "error": exc.view()}
return {"values": [], "claims": [], "error": exc.view()}
except Exception:
logger.exception("User info request failed")
return {"values": [], "error": "user info request failed"}
return {"values": [], "claims": [], "error": "user info request failed"}
if userinfo.get("sub") != claims.get("sub"):
return {"values": [], "error": "user info is about another subject"}
found = userinfo.get("entitlements", [])
found = [found] if isinstance(found, str) else found
if not isinstance(found, list) or not all(
isinstance(item, str) for item in found
):
return {"values": [], "error": "entitlements is not a list of strings"}
return {"values": found}
return {
"values": [],
"claims": [],
"error": "user info is about another subject",
}
values: dict[str, None] = {}
sources = []
invalid = []
for name in self.settings.entitlement_claims:
found = userinfo.get(name)
if found is None:
continue
found = [found] if isinstance(found, str) else found
if not isinstance(found, list) or not all(
isinstance(item, str) for item in found
):
invalid.append(name)
continue
sources.append(name)
Comment thread
uniqueg marked this conversation as resolved.
Resolved
values.update(dict.fromkeys(found))
result: dict[str, Any] = {"values": list(values), "claims": sources}
if invalid:
result["error"] = f"{', '.join(invalid)}: not a list of strings"
return result

def check(self, headers: Any) -> RequestContext:
"""Check an incoming request.
Expand Down Expand Up @@ -195,7 +218,8 @@ def _apply_policy(self, report: dict[str, Any]) -> None:

A user without the entitlement is told so (403) rather than treated as
unauthenticated (401), so that portals can offer a way to get access. If
user info gave no answer, nobody knows, so that isn't a 403 (502).
the entitlements couldn't be fully read, and those that could don't hold
it, nobody knows, so that isn't a 403 (502).

Args:
report: Report of the service, updated with the decision.
Expand Down
3 changes: 3 additions & 0 deletions src/testbed/session.py
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,7 @@ def hop_rows(report: dict[str, Any]) -> list[dict[str, Any]]:
"scope": claims.get("scope"),
"lifetime": current.get("lifetime", {}).get("exp_minus_iat"),
"entitlements": current.get("entitlements", {}).get("values"),
"entitlement_claims": current.get("entitlements", {}).get("claims"),
"entitlements_error": current.get("entitlements", {}).get("error"),
"policy": current.get("policy"),
"hop_limit": current.get("hop_limit"),
Expand Down Expand Up @@ -670,6 +671,8 @@ def _discovery(self) -> dict[str, Any]:
"device_authorization_endpoint",
"introspection_endpoint",
"revocation_endpoint",
"scopes_supported",
"claims_supported",
)
return {"ok": True, **{key: document.get(key) for key in fields}}

Expand Down
Loading
Loading