Skip to content

docs: consent and lifetime of delegated access - #35

Merged
uniqueg merged 2 commits into
devfrom
docs/28-delegated-access
Nov 13, 2026
Merged

uniqueg merged 2 commits into
devfrom
docs/28-delegated-access

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Summary

Documents how a workflow engine (Conquest) gets bounded, explicitly consented access for long runs, and how much of it LS Login supports today, based on what the testbed's code actually does.

  • New page, Testbed > Delegated access (docs/testbed/delegated-access.md): the six points of the issue (consent once, bounded grant, least privilege downstream, user control, new consent only on change, delegation in tokens), each with what it needs from the identity provider, what we know of LS Login (cited by A/C number), what the testbed does and shows, and what's open. Ends with the questions still to find out from LS Login and where each gets answered.
  • Design (product-neutral): the grant behind "Work that outlasts the request", with OpenID Connect Core section 11, RFC 9700 section 4.14, RFC 7009 and RFC 6749 section 6.
  • Assumptions and constraints: C11 (no sender-constrained tokens in the discovery document), C12 (whether the profile's "Revoke consent" ends refresh tokens is unknown), what the operator's pages say on consent and privacy, and the /oidc/ discovery document as read on 2026-11-13.
  • T4: a "Binding and reuse" step in the second session (another client redeems the refresh token, then a rotated one is reused), with expectation 6, a question and a record row. It runs in the second session because reuse detection may end every refresh token of a login, and T5 needs the first session's.
  • T1: note whether the consent page mentions offline access. Tests index: the new T4 question, and a question outside the tests on seeing and revoking grants. Limits: binding and reuse detection never ran.

What the docs state as limitations or open, from the code:

  • login requests offline_access without prompt=consent, which OpenID Connect Core section 11 asks for. Whether LS Login still issues a refresh token is observed in T1. No code change here.
  • Consent goes to the portal client. The orchestrator has no authorization code flow, so its refresh token can only come from an exchange, without user consent to Conquest.
  • Services validate access tokens offline, so revoking a refresh token doesn't reach access tokens already issued (up to 1 hour).
  • revoke reports ok on HTTP 200, which RFC 7009 also returns for invalid tokens; the following refresh is what counts.

LS Login sources: the team's answers of 2026-11-03 (A6, A7, C1, C5), the public discovery document (read 2026-11-13), and the operator's public pages "Understanding consent pages" and "Privacy: what data does Perun AAI keep about me?". Nothing is claimed beyond them.

Not done here: the issue also asks to record LS Login's answers in the M4.4 auth flow document. There are no answers yet. They come from T4 and the questions outside the tests at the event.

Light lane: docs only. The new tb> lines use existing commands and run in the end-to-end run. I reviewed the diff myself; no reviewer subagents.

Verification

  • uv run mkdocs build --strict: built, no warnings
  • uv run pytest: 239 passed, 100% coverage
  • uv run pre-commit run --all-files: all hooks passed
  • docker compose build && docker compose run --rm -T e2e: 50/50 checks passed, including 75 commands of the test pages (the new T4 lines among them)
  • CI on the PR: all jobs passed (Lint, Test, Docs, End-to-end tests, CI passed), and the Read the Docs preview built

Declined review findings

None.

Open questions

None.

Closes #28

🤖 Generated with Claude Code

Summary by Sourcery

Document and test the consent, lifetime, revocation, and delegation properties required for long-running workflow access.

New Features:

  • Add documentation describing delegated access requirements, LS Login’s current support, testbed behavior, and unresolved provider questions.

Enhancements:

  • Clarify the intended consent, bounded lifetime, least-privilege, revocation, token delegation, and user-control model for long-running workflows.
  • Document LS Login assumptions and limitations, including token binding, refresh-token behavior, revocation effects, and consent coverage.
  • Extend the T4 test procedure and test records to investigate refresh-token binding, rotation, and reuse detection.
  • Update login guidance and test indexes to capture offline-access consent and questions about viewing and revoking grants.

Documentation:

  • Publish the new Delegated access page in the testbed documentation navigation and link it from relevant design, assumptions, limits, and test pages.

Tests:

  • Add end-to-end documentation steps for checking refresh-token binding and reuse detection.

Add a Testbed page that takes the six points of delegated access for
long-running work (consent once, bounded grant, least privilege
downstream, user control, new consent only on change, delegation in
tokens) one by one: what each needs from the identity provider, what
is known of LS Login, with sources, what the testbed does, and what
is open.

- Design: spell out the grant behind work that outlasts the request.
- Assumptions: C11 (no sender-constrained tokens), C12 (effect of
  "Revoke consent" on refresh tokens unknown), the discovery document
  of 2026-11-13 and what the operator's pages say about consent.
- T4: steps for binding of refresh tokens and reuse detection, in the
  second session, with expectation, question and record row.
- T1: note whether the consent page mentions offline access.
- Tests index: a question outside the tests on seeing and revoking
  grants.

Closes #28

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg uniqueg self-assigned this Nov 13, 2026
@sourcery-ai

sourcery-ai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

Configuration

Add the delegated-access documentation page to the Testbed navigation.

  • mkdocs.yml L74

Documentation

Define the intended delegated-access grant and explain how each design requirement maps to LS Login knowledge, testbed behavior, and open questions.

  • docs/background/design.md L58-65
  • docs/testbed/delegated-access.md L1-101

Record the discovery metadata and operator documentation that underpin the stated LS Login constraints and unknowns.

  • docs/testbed/assumptions.md L44-45, L62-64, L78-82

Extend the test guidance to observe offline-access consent, refresh-token lifetime and security behavior, revocation effects, and the limits of mock evidence.

  • docs/testbed/limits.md L49
  • docs/tests/index.md L103, L125-134
  • docs/tests/t1-call-chain.md L37, L128
  • docs/tests/t4-lifetime.md L98-110, L130-138 (+2 small edits)

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@read-the-docs-community

read-the-docs-community Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

@uniqueg
uniqueg marked this pull request as ready for review November 13, 2026 20:57
@sourcery-ai

sourcery-ai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Linked issues

Checked at commit 6e5e372

#28 docs: consent and lifetime of delegated access · 8 of 9 met

# Requirement Status Notes
1 Document explicit, one-time consent for offline access, including what the engine may do and for how long. ✅ Met The delegated-access page describes the consent needed and distinguishes it from what is known about LS Login and the testbed.
2 Document a bounded grant, rotation with reuse detection, and refresh-token use by the engine as a confidential client. ✅ Met The page sets out these needs and documents LS Login's known lifetime and the open T4 checks for rotation, reuse, and client binding.
3 Document least-privilege downstream access using short-lived tokens for the one TES or WES needed by each step, without forwarding the refresh token. ✅ Met The page describes this approach and documents what the testbed does and what remains to verify about audience restriction.
4 Document user visibility and revocation of grants, and revocation when a workflow is cancelled. ✅ Met The page states the requirement and documents the profile's Revoke consent option, the revocation endpoint, and the testbed's revocation check.
5 Document that new consent is needed for broader scopes, other services, or more sensitive data, not merely because time has passed. ✅ Met The page states this requirement and notes the limits of what is known about LS Login's scope handling and registered targets.
6 Document delegation through an act claim and the LS Login gap and testbed alternative. ✅ Met The page describes the act requirement, LS Login's lack of support, and the testbed's reliance on token fields and service logs.
7 Document the relevant LS Login discovery-document findings and the available operator documentation on consent and revocation. ✅ Met The assumptions page records the discovery findings read on 2026-11-13 and summarizes the operator's consent and privacy pages.
8 Identify the LS Login questions about refresh-token lifetime, rotation and reuse, grant visibility and revocation, and exchanged-token audience restriction. ✅ Met The delegated-access page lists these questions and points to the T1, T4, or outside-the-tests documentation for each.
9 Record LS Login's answers in the documentation and the M4.4 auth flow document. ❌ Not addressed No answers are recorded, and the M4.4 auth flow document is not updated; the pull request says the answers are still pending.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 5 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/tests/index.md" line_range="131" />
<code_context>
+
+- Does it also end the refresh tokens that the service holds? And the access tokens issued with them?
+- Does logging out at LS Login end refresh tokens?
+- **If neither:** only the service itself can end a run's access early, by revoking at `/oidc/revoke`, and Conquest's docs have to say so to users.
+
+Checking it by hand ends the session's refresh tokens, so do it last, if at all: revoke the consent of the client in the profile, then try `refresh` once more.
</code_context>
<issue_to_address>
**Revocation leaves issued tokens usable**

When a user or operator relies on revocation to stop access immediately, the statement that revoking at `/oidc/revoke` ends a run's access early overstates what revocation guarantees: services accept already-issued access tokens based on local token validation, and those tokens can remain valid until expiry. Users may expect access to stop immediately even though the delegated-access page notes that it may continue for up to an hour.

Clarify that revocation stops future refreshes but may not invalidate already-issued access tokens before they expire.
</issue_to_address>

### Comment 2
<location path="docs/testbed/assumptions.md" line_range="44" />
<code_context>
 | C8 | Test accounts only, as sessions record their claims. | Our choice |
 | C9 | FOCA doesn't exchange tokens yet, so the testbed has its own small implementation. | FOCA 0.19.0 |
 | C10 | The new proxy stack may change the `aud` rule, `act` and lifetimes. Nothing specific to the current stack should be hard-coded in FOCA or proTES. | Follows from A3, A6, A7, C1 |
+| C11 | No sender-constrained tokens: the discovery document lists neither DPoP nor certificate-bound tokens. A refresh token is bound to a client only by that client's authentication, so only a confidential client's refresh token is bound to anything at all. | [What we've seen](#what-weve-seen), 2026-11-13 |
+| C12 | Nothing public says whether users can see or revoke a service's refresh tokens. The profile's "Revoke consent" withdraws a service's use of personal data; whether it also ends refresh tokens, we don't know. | [What public documents say](#what-public-documents-say) |

</code_context>
<issue_to_address>
**Public tokens appear unbound to any client**

When readers use C11 to assess what protects a public client's refresh token, c11 says a public client's refresh token is bound to nothing, but OAuth still associates it with the issued `client_id`. A public client lacks authenticated proof of its identity; another client cannot redeem the token under its own identity, though it can impersonate the same public client.

Revise C11 to distinguish the token's association with its `client_id` from the public client's lack of authenticated proof of identity.

Also at `docs/testbed/delegated-access.md:40`.
</issue_to_address>

### Comment 3
<location path="docs/tests/t4-lifetime.md" line_range="103" />
<code_context>
+In the same second session, as reuse detection may end every refresh token of a login, and later tests need those of the first. Another client tries the refresh token first, then the client refreshes twice, then reuses the older one:
+
+```text
+tb> refresh exp-other --as gateway --from exp-new
+tb> refresh exp-new2 --as client --from exp-new
+tb> refresh exp-reuse --as client --from exp-new
</code_context>
<issue_to_address>
**Gateway refusals look like client binding**

When the documented registrations are used and the gateway lacks the refresh-token flow, lS Login can refuse `exp-other` because the gateway is not permitted to use the refresh-token flow, before testing whether the token is bound to another client. The test treats that refusal as evidence of binding, so callers cannot distinguish the two outcomes.

Enable the refresh-token flow for the gateway before using its refusal as evidence of client binding.

Also at `docs/tests/t4-lifetime.md:109`.
</issue_to_address>

### Comment 4
<location path="docs/tests/t4-lifetime.md" line_range="103-104" />
<code_context>
+In the same second session, as reuse detection may end every refresh token of a login, and later tests need those of the first. Another client tries the refresh token first, then the client refreshes twice, then reuses the older one:
+
+```text
+tb> refresh exp-other --as gateway --from exp-new
+tb> refresh exp-new2 --as client --from exp-new
+tb> refresh exp-reuse --as client --from exp-new
+tb> refresh exp-after --as client --from exp-new2
</code_context>
<issue_to_address>
**Cross-client rotation disrupts reuse test**

When LS Login accepts `exp-other` and rotates its refresh token, `exp-other` consumes and rotates `exp-new`, so the next command reuses a stale token. The later refusals cannot cleanly establish client-side rotation or reuse detection, leaving the results ambiguous.

Use a separate refresh token for the cross-client attempt so `exp-new` remains available for the client-side rotation and reuse sequence.
</issue_to_address>

### Comment 5
<location path="docs/testbed/delegated-access.md" line_range="45" />
<code_context>
+**Testbed.**
+
+- `refresh` reports `refresh_token_rotated`: `true` if a new refresh token came back, `false` if the same one did, `null` if none did. Without a new one, the session keeps the old one, as RFC 6749 allows.
+- [T4](../tests/t4-lifetime.md#31-days-idle-or-absolute) compares `exp` of two refresh tokens, 10 minutes apart, to tell an idle limit from an absolute one, if the tokens are JWTs or introspection shows `exp`. The 31 days themselves can't be waited for.
+- [T4](../tests/t4-lifetime.md#binding-and-reuse) tries to redeem the client's refresh token as another client, and to reuse a rotated one.
+- On the mock, none of this is evidence: any client can redeem any refresh token, and nothing rotates or ends ([What the mock can't show](limits.md#what-the-mock-cant-show)).
</code_context>
<issue_to_address>
**Sliding expiry hides grant cap**

When the provider slides each token’s `exp` but separately caps the lifetime of the grant, the comparison only shows whether the individual refresh token’s `exp` slides; it cannot rule out a separate absolute expiry for the grant. The page treats a sliding `exp` as an idle-only limit and says runs can continue indefinitely, so callers may plan runs that the grant will terminate early.

Describe the comparison as evidence of a sliding token-expiry window, and require provider confirmation or a test of the grant-level cap before concluding that runs can continue indefinitely.
</issue_to_address>

Sourcery assessment

Approval pending. 5 findings to address first.

Blocking findings: docs/tests/index.md:131, docs/testbed/assumptions.md:44, docs/tests/t4-lifetime.md:103, docs/tests/t4-lifetime.md:104, docs/testbed/delegated-access.md:45


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread docs/tests/index.md Resolved
Comment thread docs/testbed/assumptions.md Resolved
Comment thread docs/tests/t4-lifetime.md Resolved
Comment thread docs/tests/t4-lifetime.md Resolved
Comment thread docs/testbed/delegated-access.md Resolved
- Revocation stops further refreshes, but access tokens already issued
  stay usable until they expire.
- A public client's refresh token still belongs to its client ID; it
  lacks proof of the client's identity, not an association.
- T4: test binding with the orchestrator, which has the refresh token
  flow, and only after the reuse sequence, so that a cross-client
  refresh can't rotate the token the sequence needs.
- A moving `exp` doesn't rule out a cap on the whole grant.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg
uniqueg merged commit 03199d6 into dev Nov 13, 2026
7 checks passed
@uniqueg
uniqueg deleted the docs/28-delegated-access branch November 13, 2026 21:13
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.

docs: consent and lifetime of delegated access

1 participant