Follow a step-up challenge from challenge to retry

Setup

You need lab-printer-app with lab-tmp-at-signin (including the auth_time mapping), APP_ID, API_ID, API_SECRET and the REFRESH value from Read what an access token says about how and when Ava signed in. Keep Ava signed in to Lab Photos in your browser.

1. In its own terminal, start the local photo API with a two-minute deletion policy. It validates tokens by introspection as lab-photo-api and logs allowed or challenged for each request:

btl-lab resource --port 8766 --mode introspect --audience "$ISSUER/resource" --delete-max-age 120

2. Get an everyday token from your saved refresh token, as the app would each morning:

RESP=$(curl -s "$ISSUER/oauth/token" -d grant_type=refresh_token --data-urlencode "client_id=$APP_ID" --data-urlencode "refresh_token=$REFRESH")
TOKEN=$(jq -r .access_token <<<"$RESP"); REFRESH=$(jq -r .refresh_token <<<"$RESP"); unset RESP

If the refresh token has expired or was revoked, repeat step 1 of the previous lab instead.

3. Press Start on this page with Lab Photos selected.

Walkthrough

1. Make sure Ava's last sign-in is more than two minutes old (btl-lab decode "$TOKEN" shows auth_time), then try to delete a photo:

curl -s -D hdr.txt -o /dev/null -w '%{http_code}\n' -X DELETE -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8766/photos/9137
grep -i www-authenticate hdr.txt

The status is 401 and the header reads Bearer error="insufficient_user_authentication", max_age="120". The API logs challenged.

Why it matters: the token is valid and carries photos.delete; only the sign-in behind it is too old. The status is 401 because the remedy is a different token.

2. Read the requirement from the challenge exactly as received:

MAXAGE=$(sed -n 's/.*max_age="\([0-9]*\)".*/\1/p' hdr.txt); echo "$MAXAGE"

Why it matters: the app copies the API's requirement into the authorization request instead of inventing its own.

3. Ask for a new sign-in. Start btl-lab callback, then:

eval "$(btl-lab pkce)"; eval "$(btl-lab state)"
echo "$ISSUER/oauth/authorize?response_type=code&client_id=$APP_ID&redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback&scope=photos.read%20photos.delete&max_age=$MAXAGE&state=$STATE&code_challenge=$CHALLENGE&code_challenge_method=S256"

Open the URL in the browser where Ava is still signed in. Lab Photos asks her to sign in again instead of continuing silently. Sign in with her password (the planned walkthrough adds the passkey requirement), approve, check state and iss, then exchange the code:

read -rs CODE
STEP_TOKEN=$(curl -s "$ISSUER/oauth/token" -d grant_type=authorization_code --data-urlencode "client_id=$APP_ID" --data-urlencode "code=$CODE" \
  --data-urlencode redirect_uri=http://127.0.0.1:8765/callback --data-urlencode "code_verifier=$VERIFIER" | jq -r .access_token); unset CODE

Why it matters: max_age tells the authorization server that a session older than the limit does not count, even though it is still active. Everything else is an ordinary request, with a fresh state and PKCE challenge.

4. Retry the original request with the new token:

curl -s -o /dev/null -w '%{http_code}\n' -X DELETE -H "Authorization: Bearer $STEP_TOKEN" http://127.0.0.1:8766/photos/9137

The status is 204 and the API logs allowed. For the lab, btl-lab decode "$STEP_TOKEN" shows an auth_time a few seconds old; the app itself never decodes it. It just retries and lets the API decide.

Why it matters: the API makes the final decision both times, from the token alone.

5. Freshness runs out. Wait two more minutes and call again with the same token. GET /photos still returns 200, but DELETE /photos/9137 is challenged again.

Why it matters: a stepped-up sign-in meets the deletion policy only for its window. After that the app must decide whether to ask Ava again or stop.

Planned walkthrough

These steps need tenant-defined acr values (G20) and acr in access tokens (G48). A hosted photo API (G3) would replace the local one.

1. Start the API with a strength requirement too: --delete-acr urn:btl:acr:phishing-resistant (planned option). The challenge becomes Bearer error="insufficient_user_authentication", acr_values="urn:btl:acr:phishing-resistant", max_age="120".

2. The step-up request adds &acr_values=urn%3Abtl%3Aacr%3Aphishing-resistant. Lab Photos, whose authentication policy maps that value to passkey sign-in, prompts for Ava's passkey rather than her password, and treats the value as a requirement, not a preference.

3. The new access token carries "acr": "urn:btl:acr:phishing-resistant" and a fresh auth_time, introspection returns both, and the API compares acr exactly with its accepted list.

Break it

1. Leave the requirement out of the step-up request. Run step 3 again without &max_age=$MAXAGE. Lab Photos reuses Ava's existing session without a prompt, so Audit shows code_issued with no new user_signed_in. The new token's auth_time is the old one, and the retry is challenged again.

Why it matters: a step-up request that does not carry the requirement produces another token the API refuses.

Check your work

Press Check my progress. The checks look in Lab Photos for the new sign-in forced by max_age, the step-up code and its exchange for lab-printer-app, and the photo API's introspection of the new token. The API's own log shows challenged, allowed, then challenged again after the window.

Cleanup

Stop the local API. Keep TOKEN (the everyday token), STEP_TOKEN, REFRESH and lab-tmp-at-signin for the next lab, or, if you stop here, assign lab-printer-app back to the tenant default manager, delete lab-tmp-at-signin, delete hdr.txt and unset the token variables.

Missing infrastructure

• G20 acr and acr_values: the strength half of the challenge, honored as a requirement, with the tenant's own mapping from acr values to sign-in methods.

• G48 Authentication context in access tokens: acr in the access token and introspection response, so the API can check strength as well as freshness.

• G3 Sample protected resource API: a hosted photo API with a configurable deletion policy, so the challenge comes from a real tenant service instead of btl-lab resource on loopback.