Separate identifiers, shared secrets and key pairs

Setup

In the lesson, the clinic portal's server calls an outside laboratory's API. Here lab-print-orders plays that server-to-server caller, and Lab Photos plays the verifier. You need openssl 3.x, the toolkit, and Ava with her passkey.

1. On this lab page choose Lab Photos and press Start.

2. Work in an empty folder for this lab's local files, and set the variables:

mkdir -p ~/btl-keys-lab && cd ~/btl-keys-lab
ISSUER=https://tenant-<id>.beyondthelogin.dev
ORDERS_ID=<lab-print-orders client ID>
read -rs ORDERS_SECRET

Walkthrough

1. What a credential is. Present the identifier alone, then the identifier with its credential:

curl -s -d grant_type=client_credentials -d client_id="$ORDERS_ID" "$ISSUER/oauth/token" | jq
curl -s -u "$ORDERS_ID:$ORDERS_SECRET" -d grant_type=client_credentials -d scope=prints.create "$ISSUER/oauth/token" | jq '{token_type, scope}'

Expected: 401 with invalid_client for the identifier alone, then a token.

Why it matters: the client ID says which client is calling and can be known by anyone. The secret is the evidence, and it is only useful while its holder keeps it from others.

2. Watch the shared secret travel. Rerun the second request with -v and find the Authorization: Basic header. Decode just the part before the colon:

curl -sv -u "$ORDERS_ID:$ORDERS_SECRET" -d grant_type=client_credentials -d scope=prints.create "$ISSUER/oauth/token" 2>&1 >/dev/null \
  | sed -n 's/^> Authorization: Basic //p' | tr -d '\r' | base64 -d | cut -d: -f1

The part after the colon is the secret itself, merely encoded.

Why it matters: with this method the shared secret goes with every request. TLS protects it in transit, but anyone who captures or logs one request can reuse it.

3. The verifier's copy. In Clients, look for a way to view lab-print-orders's secret again. There is none, only Rotate secret.

Why it matters: because the holder sends the secret itself, the tenant can keep only a hash of it, just as it does for passwords.

4. Prove knowledge without sending the secret, with HMAC. The tenant does not accept HMAC-signed requests, so this runs locally:

LAB_KEY=$(openssl rand -hex 32)
printf 'GET /results/48213' | openssl dgst -sha256 -hmac "$LAB_KEY"
printf 'GET /results/48214' | openssl dgst -sha256 -hmac "$LAB_KEY"

Why it matters: the key never travels, and each request gets its own tag. But the verifier holding LAB_KEY can produce exactly the same tags, so a thief who steals the verifier's copy can make requests that look like the clinic's.

5. A key pair, locally:

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out clinic.key
openssl pkey -in clinic.key -pubout -out clinic.pub
printf 'GET /results/48213' > req.txt
openssl dgst -sha256 -sign clinic.key -out req.sig req.txt
openssl dgst -sha256 -verify clinic.pub -signature req.sig req.txt

Expected: Verified OK. Now try to sign with the public key, openssl dgst -sha256 -sign clinic.pub -out x.sig req.txt: it fails, because a public key cannot sign.

Why it matters: the verifier holds only clinic.pub. Stealing it lets an attacker verify signatures, nothing more, so any number of verifiers can share it.

6. Prove possession with a fresh challenge. The verifier creates a challenge, the holder signs it, and the verifier checks it. Then the verifier creates a new challenge and checks the old answer against it:

openssl rand -hex 16 > challenge.txt
openssl dgst -sha256 -sign clinic.key -out answer.sig challenge.txt
openssl dgst -sha256 -verify clinic.pub -signature answer.sig challenge.txt
openssl rand -hex 16 > challenge.txt
openssl dgst -sha256 -verify clinic.pub -signature answer.sig challenge.txt

Expected: Verified OK, then Verification failure.

Why it matters: a fresh challenge makes a recorded answer useless. The key itself never left its holder.

7. Your tenant publishes only public keys:

GET $ISSUER/oauth/jwks HTTP/1.1
Accept: application/json

Check it from the shell too: curl -s "$ISSUER/oauth/jwks" | jq '.keys[] | {kid, kty, alg, has_private_part: has("d")}'. Every key shows has_private_part: false.

Why it matters: anyone can fetch these keys to verify the tenant's tokens; a thief who copies them gains nothing.

8. Passkeys are key pairs. Open DevTools > Network and sign in as Ava with her passkey at $ISSUER/login. The tenant sends a challenge; the browser returns authenticatorData, clientDataJSON (which contains that challenge and the tenant's origin) and a signature.

Why it matters: this is step 6 with the private key held by the authenticator. The tenant stores only Ava's public key, so a breach of its database reveals nothing that could sign in as her.

9. Bearer behavior. Sign in as Ava through $ISSUER/token-decoder and copy her access token. In a different terminal or on another machine, call UserInfo with it:

read -rs TOKEN
curl -s -H "Authorization: Bearer $TOKEN" "$ISSUER/oidc/userinfo" | jq .sub

Expected: Ava's sub.

Why it matters: a bearer token works for whoever presents it, unlike the challenge-signed proofs above. Binding a token to a key (G14) changes that.

10. Whose key is it? curl -s "$ISSUER/.well-known/openid-configuration" | jq -r .jwks_uri.

Why it matters: verifiers trust these public keys because they fetched them over HTTPS from the issuer they were configured with, not because a message pointed to them. Certificates, in the next labs, explain why that HTTPS connection can be trusted.

Planned walkthrough

These steps need client authentication with a private key (G8, private_key_jwt) and per-client key sets (G56), plus DPoP (G14).

1. On lab-print-orders, register clinic.pub as a JWK, switch the authentication method to private_key_jwt, and delete the shared secret.

2. The toolkit builds and signs a client assertion with your own clinic.key, as your own client, with a unique jti and a short exp, and requests a token:

curl -s -d grant_type=client_credentials -d scope=prints.create \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  --data-urlencode "client_assertion=$ASSERTION" "$ISSUER/oauth/token" | jq '{token_type, scope}'

3. Send the same assertion again. Expected: 401 with invalid_client, because its jti was already used. No secret travelled, and a recorded assertion is useless.

4. With DPoP, request a token bound to the key, then present it from another terminal without a fresh proof. Expected: refused, unlike step 9.

Break it

1. Send the secret in the request body instead of the header:

curl -s -d grant_type=client_credentials -d client_id="$ORDERS_ID" --data-urlencode "client_secret=$ORDERS_SECRET" "$ISSUER/oauth/token" | jq

Expected: 401 with invalid_client, and Audit shows reason unsupported_auth_method. The verifier, not the client, decides how clients must prove themselves.

2. Generate a second key pair and verify req.sig with its public key. Expected: Verification failure.

Check your work

Press Check my progress. It looks for:

• oauth.token rejected with reason unsupported_auth_method for lab-print-orders (the identifier alone).

• oauth.token succeeded for lab-print-orders.

• oidc.userinfo succeeded with reason userinfo_served (the copied bearer token).

• oauth.token rejected with reason unsupported_auth_method for lab-print-orders (the secret in the body).

Your terminal should also show Verified OK and Verification failure from the local steps.

Cleanup

1. Keep clinic.key and clinic.pub only if you want them for the Storing and using keys lab, which compares them with the tenant's keys. Otherwise delete the folder: cd ~ && rm -r ~/btl-keys-lab.

2. Run unset LAB_KEY TOKEN.

Missing infrastructure

• G8 Client authentication beyond client_secret_basic. The tenant cannot accept private_key_jwt, so a client cannot prove possession of a private key at the token endpoint. Once it exists, the planned walkthrough replaces the shared secret with a signed assertion.

• G14 DPoP. Tokens cannot be bound to a key, so step 9 cannot be contrasted with a token that needs a fresh proof from the client's key.

• G56 Client key sets. A client cannot register clinic.pub (or a JWKS URL) for the tenant to verify its assertions against.