DEV Community: DarkEdges

Step-up MFA, attenuation, and what's honestly not done

DarkEdges — Sun, 04 Oct 2026 11:51:54 +0000

Repo: darkedges/pf12.3-biscuit-datalog-tokens

We've covered why a hybrid works, the token generator plugin, and the Terraform plus end-to-end test. Part 3 ended with alice holding orders:write and still getting a 403. This part unlocks that write, narrows the token in a few ways, and then says plainly what doesn't work yet.

1. Why the write was refused

orders-api's policy has three rules:

allow if scope("orders:read"), operation("read");
allow if scope("orders:write"), operation("write"), amr("mfa") trusting authority, ed25519/<attestation key>;
deny if true;

A write needs the scope and an amr("mfa") fact. It also has to be a fact the service trusts. trusting authority, ed25519/<key> means: look for amr("mfa") in the authority block (PingFederate's) or in a block signed by the attestation key, and nowhere else.

When no allow rule matches, Biscuit only reports that deny if true matched, which tells you nothing. So orders-api works out which requirement is missing and says so:

{
  "allowed": false,
  "operation": "write",
  "reason": "write requires amr(\"mfa\") signed by ed25519/59c06655… (step-up)",
  "resource": "/orders/123"
}

The gotcha in `trusting`

My first version of that rule was:

allow if scope("orders:write"), operation("write"), amr("mfa") trusting ed25519/<attestation key>;

It never matched, even with the attestation present. trusting replaces a rule's default scope; it doesn't add to it. Without authority in the list, the rule could no longer see scope("orders:write") in PingFederate's authority block. It failed silently, with no error. If you write Biscuit policies with third-party blocks, trusting authority, <key> is almost always what you mean.

2. Step-up: an attestation as a third-party block

Biscuit has a mechanism designed for exactly this: third-party blocks. The holder sends a request derived from its token to an attestor. The attestor signs a block (here containing amr("mfa")) bound to that specific token, and the holder appends it. Nobody else can move that block onto a different token, and the attestor never sees the token itself.

In the demo app, Add MFA attestation does exactly that. The Token tab then shows a second block:

1  third-party · attestation    signed by ed25519/59c06655…
   amr("mfa");

POST again and it's a 200. From the command line, make mfa followed by make call does the same.

The honest part: PingFederate isn't the attestor yet

The design I wanted was PingFederate signs the attestation, right after it has run MFA. It has the user's session and knows MFA happened, and it already holds signing keys. biscuit-java even has the API for it.

It doesn't work today. biscuit-java 4.0.1, the latest on Maven Central, still uses the legacy third-party request format, which carries a previousKey. biscuit-auth 6 (Rust, which orders-api and the demo app use) sends the newer format with a previous_signature, and rejects the legacy one. Hand a Rust-made request to biscuit-java and you get:

InvalidProtocolBufferException: Message missing required fields: previousKey

So the demo simulates PingFederate's attestor with a separate Ed25519 key in .keys/attestation.env, signing with biscuit-auth. The flow, the policy and the trust model are exactly what PingFederate would do. Only the signer is a stand-in.

There are three ways to get the real thing:

biscuit-java catches up with the newer third-party format. Then the attestor can be a small PingFederate endpoint or plugin.
A sidecar attestor next to PingFederate, using biscuit-auth. PingFederate decides that MFA happened; the sidecar signs.
Step up at the IdP and re-exchange. This works today, and it's the most "hybrid" option. Run MFA in PingFederate and put the amr claim in the JWT. Then make another token exchange and map amr into the authority block. The generator already allows an amr fact; it's in the default fact list. The cost is a round trip to PingFederate for step-up, which you'd make anyway for the MFA itself. The demo doesn't wire this up, because its HTML form login has no MFA, but nothing in the plugin stops it.

3. Attenuation: narrowing without asking

With the write unlocked, the demo app's Attenuate buttons append blocks that only ever narrow the token:

Button	Block appended	Effect
Read-only	`check if operation("read");`	POST → `403`, naming the failed check
Only this order	`check if resource($r), $r == "/orders/999";`	`/orders/999` → 200, `/orders/123` → 403
Expire in 60 s	`check if time($t), $t <= <now+60s>;`	Valid for a minute, even though PingFederate gave it five
Custom	your Datalog	e.g. `check if operation("read");`

None of these call PingFederate, and none need a key. This is the Trust Lab's delegation step, now on a token that started life in an enterprise IdP. A gateway can hand a downstream service a token that's read-only, for one order, for one minute, in microseconds.

Two properties are worth checking yourself in the app:

Values can't inject Datalog. The order ID and the time go into the block as parameters, not pasted text. Even so, the app only accepts order IDs of letters, digits, - and _.
A holder can't widen a token. Append a block that says amr("mfa"); scope("orders:admin"); yourself and POST: still 403. Facts in an ordinary appended block aren't trusted by the policy. Only the authority block and the attestation key are.

Seal finishes the token: no further blocks can be appended, and the app disables those buttons. Fresh Biscuit from PingFederate runs the exchange again.

4. Revocation and certificate binding

The standalone demo (make demo, 19 checks, no PingFederate needed) covers two things the web app doesn't:

Revocation. Each block has a revocation ID. Revoke the authority block's ID, which the plugin logs at mint time, and the original token and every narrowed copy fail. A token with a different ID is unaffected.
Certificate binding. A token minted with a cnf_x5t_s256 attribute only works when presented over the matching client certificate.

What is not proven

The prototype works end to end. That's different from being production-ready:

PingFederate as the MFA attestor: blocked by the biscuit-java format gap above; the demo simulates it.
Revocation distribution: orders-api reads revoked IDs from a file. Getting them to every service quickly, by push, pull or short lifetimes, is a design problem I haven't solved here.
Introspection: PingFederate can confirm a narrowed Biscuit's signature, but not whether it's authorized. That depends on request facts only the service has. active: true would mean "authentic and unexpired", nothing more.
Policy governance: each service carries its own Datalog. Keeping policies consistent across services needs version control, review and tests, like any other code.
Ecosystem: PingAccess and off-the-shelf gateways don't understand Biscuits. The hybrid sidesteps this by keeping JWTs at the edge, but it's a real limit on how far in the Biscuit can go.
Demo shortcuts: HS256 JWTs with a symmetric key, generated secrets in local Terraform state, self-signed TLS, and the root key in a PingFederate config field rather than an HSM.
Size: every block adds bytes. The demo's token grew from 436 bytes (one block) to about 1 KB (four blocks). Seal early if headers matter.

Back to the Trust Lab's list

Part 4 of the Trust Lab ended with what a production version would need. Here's where an IdP-minted root moves the needle, and where it doesn't:

Trust Lab production need	With PingFederate minting the root
Persistent keys with rotation	Better. The key lives in the IdP's encrypted config; `root_key_id` supports rotation
Revocation	Partly. IDs are logged at mint and revoking the authority block cascades; distribution is still open
Authenticated transports	Better. Certificate binding via `cnf_x5t_s256`
Payer consent	Possible. PingFederate's consent and authorization policies run before the exchange
Durable accounting, reconciliation	Unchanged; that's the clearinghouse's job, not the IdP's

Wrapping up

The thing I set out to test was whether an existing enterprise IdP could be the root of trust for Biscuits without giving up anything that makes either side useful. I think the answer is yes:

PingFederate keeps login, MFA, consent and client governance.
The edge keeps speaking OAuth.
One token exchange turns an access token into a capability that services can narrow, delegate and check offline.

Try to break it. Clone the repo, run make up tf-plan tf-apply web, and see if you can make orders-api accept a write it shouldn't. If you work on PingFederate or Biscuit, I'd especially like feedback on the fact vocabulary, the reserved names, and the step-up options. Open an issue on GitHub.

Thanks for reading the series.

Configuring PingFederate token exchange with Terraform, and testing it end to end

DarkEdges — Sun, 04 Oct 2026 11:51:35 +0000

Repo: darkedges/pf12.3-biscuit-datalog-tokens

Part 2 built a token generator plugin. On its own it does nothing: PingFederate needs a login, an access token manager, a client, a processor policy, a generator instance, a generator group and a mapping between them before a single Biscuit comes out.

This part configures all of that with Terraform, then runs the full flow in a browser: log in, exchange, call an API, get refused, and see why.

1. The stack

docker-compose.yaml runs two things:

pingfederate: PingFederate 12.3.3 with the getting-started server profile, built from the multi-stage Dockerfile from Part 2, so the plugin is already deployed.
terraform: a hashicorp/terraform container in a tools profile. It reaches the admin API at https://pingfederate:9999 on the compose network, so you don't need Terraform on your machine.

Everything runs through make:

make up          # build the image (plugin compiled and tested inside Docker) and start PingFederate
make tf-plan     # generate the Biscuit root key once, init, plan → terraform/tfplan
make tf-apply    # apply the saved plan
make tf-creds    # generated passwords for alice and bob, and the client secret
make web         # orders-api + the demo web app, prints "Ready" when 8090 is listening

2. What Terraform creates

Seventeen resources take a blank PingFederate to a working token exchange:

Piece	Resource
Demo users `alice` and `bob`, with generated passwords	`random_password` + `pingfederate_password_credential_validator`
HTML form login	`pingfederate_idp_adapter` + `pingfederate_oauth_idp_adapter_mapping`
Scopes `orders:read`, `orders:write`	`pingfederate_oauth_server_settings`
JWT access tokens carrying `username`	`pingfederate_oauth_access_token_manager` + `pingfederate_oauth_access_token_mapping`
Client `orders-web`: authorization code, refresh token, token exchange	`pingfederate_oauth_client`
Validates the incoming JWT	`pingfederate_idp_token_processor`
Picks `subject`, `client_id`, `scope`	`pingfederate_oauth_token_exchange_processor_policy`
The Biscuit generator instance	`restapi_object` → `/sp/tokenGenerators`
Routes the Biscuit token type to it	`restapi_object` → `/oauth/tokenExchange/generator/groups`
Policy attributes → generator contract	`pingfederate_oauth_token_exchange_token_generator_mapping`
Makes that group the default	`pingfederate_oauth_token_exchange_generator_settings`

The token exchange pipeline from Part 1 maps directly onto the last six rows.

Validating the subject token

The processor is PingFederate's built-in BearerAccessTokenTokenProcessor, pointed at the same access token manager that issued the JWT. PingFederate validates its own tokens, with no JWKS plumbing:

resource "pingfederate_idp_token_processor" "access_token" {
  processor_id = "biscuitAccessTokenProcessor"
  plugin_descriptor_ref = {
    id = "org.sourceid.wstrust.processor.oauth.BearerAccessTokenTokenProcessor"
  }
  configuration = {
    fields = [
      { name = "Access Token Manager", value = pingfederate_oauth_access_token_manager.jwt.manager_id },
      { name = "Scope value as single string", value = "true" },
    ]
  }
  # core: aud, authorization_details, client_id, expires_at, iss, scope; extended: username
}

The processor's core contract has client_id and scope, but not the user. The user arrives as the extended attribute username, which has to match the access token manager's contract.

The processor policy: what PingFederate lets through

This is the governance point from Part 1. The policy chooses which attributes go to the generator. This is where you'd add issuance criteria, such as "only this client" or "only if the token has this scope":

resource "pingfederate_oauth_token_exchange_processor_policy" "biscuit" {
  policy_id = "biscuitExchange"
  name      = "Access token to Biscuit"
  # "subject" is a built-in core attribute of every processor policy.
  attribute_contract = {
    extended_attributes = [{ name = "client_id" }, { name = "scope" }]
  }
  processor_mappings = [{
    subject_token_type      = "urn:ietf:params:oauth:token-type:access_token"
    subject_token_processor = { id = pingfederate_idp_token_processor.access_token.processor_id }
    attribute_contract_fulfillment = {
      subject   = { source = { type = "SUBJECT_TOKEN" }, value = "username" }
      client_id = { source = { type = "SUBJECT_TOKEN" }, value = "client_id" }
      scope     = { source = { type = "SUBJECT_TOKEN" }, value = "scope" }
    }
  }]
}

(The comment is there because I tried to declare subject myself, and the provider refuses: it's read-only.)

3. The provider gap: `restapi` for two objects

The PingFederate Terraform provider (1.10.0, the latest at the time of writing) has no resource for SP token generators or token exchange generator groups. Those are exactly the two objects this project needs.

Rather than shell out to scripts, I used the generic Mastercard/restapi provider against the admin API. Those objects still go through plan, apply and destroy like everything else. Abridged from token_exchange.tf, where the literals are variables:

resource "restapi_object" "biscuit_generator" {
  path      = "/sp/tokenGenerators"
  object_id = "biscuit"
  data = jsonencode({
    id                  = "biscuit"
    name                = "Biscuit token generator"
    pluginDescriptorRef = { id = "com.darkedges.pingfederate.biscuit.BiscuitTokenGenerator" }
    configuration = { fields = [
      { name = "Root Private Key", value = var.biscuit_root_private_key },
      { name = "Root Key ID", value = "1" },
      { name = "Issuer", value = var.pf_runtime_url },
      { name = "Token Lifetime (seconds)", value = "300" },
      { name = "Audiences", value = "orders-api" },
      { name = "Fact Attributes", value = "subject,client_id,scope" },
    ] }
    attributeContract = {
      coreAttributes     = [{ name = "subject" }]
      extendedAttributes = [{ name = "client_id" }, { name = "scope" }]
    }
  })
  ignore_server_additions = true
  ignore_changes_to       = ["configuration.fields", "attributeContract.extendedAttributes"]
}

Those last two lines took three plans to get right. After the first apply, every plan showed both objects changed, because PingFederate adds things:

location and lastModified fields;
an empty resourceUris list on the group;
the private key returned as encryptedValue instead of value;
extended attributes in a different order.

ignore_server_additions ignores fields the server adds but still detects changes to fields you set. Now a plan straight after an apply says No changes, and editing the Terraform still triggers an update.

The generator group is the piece that makes requested_token_type work:

resource "restapi_object" "biscuit_generator_group" {
  path      = "/oauth/tokenExchange/generator/groups"
  object_id = "biscuit"
  data = jsonencode({
    id   = "biscuit"
    name = "Biscuit"
    generatorMappings = [{
      requestedTokenType = "urn:darkedges:params:oauth:token-type:biscuit"
      tokenGenerator     = { id = restapi_object.biscuit_generator.object_id }
      defaultMapping     = true
    }]
  })
  ignore_server_additions = true
}

4. Smaller things worth knowing

The root key is generated by the plugin itself. make tf-plan runs the plugin jar's keygen inside the PingFederate container, so you don't need a JDK. It writes the result to a git-ignored terraform/biscuit.auto.tfvars. Terraform passes the private key to PingFederate, and the services get the public key.
The JWT symmetric key must be hex. With the access token manager's "Encoding" field left blank, PingFederate expects the HS256 key as hex. My first apply failed with Key with key id 'k1' is not valid hex, and random_bytes.hex fixed it.
Generated secrets live in Terraform state. Demo passwords, the client secret and the JWT key are random_* resources. That's fine for a lab, but in production you'd source them from a vault.
Destroy is clean. make tf-destroy removes all 17 resources in dependency order. PingFederate clears the default generator group reference itself when the group goes.

5. Testing it end to end

With PingFederate running and Terraform applied, make web starts two things: orders-api (Rust, biscuit-auth 6) on port 8091, and the demo web app on port 8090. It prints a "Ready" line only once both are listening.

Open http://localhost:8090 and log in as alice, with the password from make tf-creds. The app runs a standard authorization code flow against PingFederate's HTML form, then does the token exchange. The Token tab shows the Biscuit PingFederate minted:

issuer("https://localhost:9031");
user("alice");
client("orders-web");
scope("orders:read");
scope("orders:write");
check if time($t), $t <= 2026-10-04T11:23:13Z;
check if audience($a), {"orders-api"}.contains($a);

It's labelled authority · minted by PingFederate and marked signature verified against PingFederate's public key.

The HTTP activity tab lists every call in order, each with Request / Response tabs. The request is a runnable curl with Copy curl, and the response is the JSON with Copy response:

#	Call	Result
1	Authorization code → access token (JWT)	`200`, `token_type=Bearer`, `expires_in=3599`
2	Token exchange: JWT → Biscuit	`200`, `issued_token_type=…:biscuit`, `token_type=N_A`, `expires_in=299`
3	`GET /orders/123` with the Biscuit	`200`, `{"allowed": true, "user": "alice"}`
4	`POST /orders/123` with the Biscuit	`403`, `write requires amr("mfa") signed by ed25519/59c0… (step-up)`

Call 3 shows the point of the whole design: orders-api didn't call PingFederate. It verified the signature with the public key, added facts about the request (operation("read"), resource("/orders/123"), audience("orders-api"), the time), and evaluated its policy locally.

Call 4 is the cliffhanger. Alice has orders:write, but the policy also wants proof of MFA, as a block signed by a key PingFederate controls. That's Part 4.

Without a browser

The same flow runs from the command line, which is handy for CI or for seeing the raw calls:

make auto-login LOGIN_USER=bob   # fills in PingFederate's HTML form with curl
make exchange                    # JWT → Biscuit, prints its Datalog
make api-pf                      # orders-api in another terminal
make call                        # GET → 200, POST → 403

In Part 4 we unlock that write: a step-up MFA attestation appended as a third-party block, then attenuation and sealing in the demo app. Then the honest part: what this design doesn't solve yet, and the library gap that stops PingFederate from being the attestor today.

Building a PingFederate token generator that mints Biscuits

DarkEdges — Sun, 04 Oct 2026 11:51:23 +0000

Repo: darkedges/pf12.3-biscuit-datalog-tokens, plugin source in pf-biscuit-generator/

Part 1 argued for a hybrid: PingFederate issues JWTs at the edge, and token exchange turns them into Biscuits for everything inside. This part builds the one piece PingFederate doesn't ship, a token generator that mints a Biscuit.

It's a few hundred lines of Java. Most of the interesting decisions aren't in the Java, though. They're about what you let into the authority block.

1. The SDK contract

PingFederate's token exchange calls token generators through the same SDK interface its WS-Trust STS uses, org.sourceid.wstrust.plugin.generate.TokenGenerator. A generator does three things:

describes itself: its name, admin UI fields, the token type it produces, and its attribute contract;
receives configuration when an admin saves the instance;
generates a token from a map of attributes.

The descriptor is where the token type lives. That URN is what clients send as requested_token_type:

public static final String TOKEN_TYPE = "urn:darkedges:params:oauth:token-type:biscuit";

descriptor = new TokenPluginDescriptor(NAME, this, gui, TOKEN_TYPE, Set.of("subject"));
descriptor.setSupportsExtendedContract(true);

The core contract is just subject. The extended contract lets an admin add client_id, scope, group, amr or anything else the processor policy provides, without changing code.

The admin UI exposes six fields:

Field	Becomes
Root Private Key	The Ed25519 key that signs the authority block (an encrypted field)
Root Key ID	`root_key_id` in the token, for key rotation
Issuer	`issuer("…")`
Token Lifetime (seconds)	`check if time($t), $t <= <now + lifetime>`
Audiences	`check if audience($a), {…}.contains($a)`
Fact Attributes	Which contract attributes become facts

The plugin uses biscuit-java 4.0.1, the JVM implementation of Biscuit.

2. Attributes in, facts out, and never as strings

This is the first design rule, and it's easy to get wrong. The tempting implementation is string building:

// DON'T
token.add_authority_fact("user(\"" + subject + "\")");

If a subject ever contains alice"); scope("orders:admin, you've just let an attribute value write Datalog. In an IdP, attribute values come from directories, upstream federation partners and user-editable profiles. They aren't safe input.

So every value goes through biscuit-java's builder API as a string term. A term is data and is never parsed as Datalog:

token.set_context("pingfederate:token-exchange");
token.add_authority_fact(fact("issuer", List.of(string(issuer))));

for (Map.Entry<String, String> e : factAttributes.entrySet())
{
    for (String value : values(attributes, e.getKey()))
    {
        token.add_authority_fact(fact(e.getValue(), List.of(string(value))));
    }
}

The checks are built the same way: predicates, variables and expressions, not strings. Here's the expiry:

// check if time($t), $t <= <expiresAt>
token.add_authority_check(check(
        pred("time", List.of(var("t"))),
        new Expression.Binary(Expression.Op.LessOrEqual,
                new Expression.Value(var("t")),
                new Expression.Value(date(Date.from(expiresAt))))));

There's a unit test that mints a token for the subject mallory"); scope("orders:write. It checks that the result contains exactly one scope fact and that a write is still refused.

A small but useful detail: OAuth's scope arrives as one space-separated string. The minter splits it into one scope("…") fact per scope, so Datalog policies can match individual scopes.

3. The fact names a minter must refuse

The second design rule is subtler, and I think it's the most important thing in this article.

A Biscuit authorizer combines facts from two places:

the token, whose authority block is trusted;
the service itself, which adds ambient facts describing the request it's handling: time(...), operation("read"), resource("/orders/123"), audience("orders-api").

Then it runs a policy like:

allow if scope("orders:read"), operation("read");
allow if scope("orders:write"), operation("write"), amr("mfa") trusting authority, ed25519/<attestation key>;
deny if true;

By default, the authorizer trusts authority-block facts exactly as much as its own. So if any PingFederate attribute were ever mapped to a fact called operation, a token could carry operation("write") and satisfy the write rule on a read request. The token would be forging facts about the request.

So the minter has a reserved list, and refuses to start if an admin maps an attribute onto any of these names:

public static final Set<String> RESERVED_FACTS = Set.of(
        "time", "operation", "resource", "audience", "tls_client_cert_sha256", "issuer", "hop");

issuer is on the list because the plugin sets it from configuration. hop is reserved for services to tag delegation hops.

The broader lesson: the fact vocabulary is a contract between your IdP and every service that verifies its tokens. Which names the IdP asserts (user, client, scope, group, amr) and which names services assert (time, operation, resource) must never overlap. Write it down and version it.

4. Checks that bind the token

Beyond expiry and audience, the minter supports one more check: certificate binding, the Biscuit equivalent of RFC 8705's cnf.x5t#S256. If the processor policy supplies a cnf_x5t_s256 attribute, the authority block gets:

check if tls_client_cert_sha256($c), $c == "<thumbprint>";

The service adds tls_client_cert_sha256(...) from its mTLS handshake. A stolen token presented over a different client certificate fails the check. The standalone demo covers all three cases: no certificate, the wrong certificate, and the right one.

5. Getting the output right: what I disassembled

A generator returns a SecurityToken. For anything that isn't SAML, that means a BinarySecurityToken, an XML-era type with "encoded data" and an encoding type. The SDK doesn't document what the OAuth token exchange endpoint does with it. Would PingFederate base64 the data again? Decode it? Wrap it?

So I disassembled the class that builds the token exchange response in PingFederate 12.3.3, TokenGeneratorOutputGenerationStrategy, with javap -c. It does three things:

returns BinarySecurityToken.getEncodedData() verbatim as access_token;
sets token_type to N_A;
computes expires_in from getExpiryDate() if one is set.

That's good news: the Biscuit's native base64url serialization passes through untouched, and verifiers can read it directly. The generator sets the encoding type and the expiry date so expires_in is correct:

BinarySecurityToken bst = new BinarySecurityToken(XmlIDUtil.createID(), TOKEN_TYPE);
bst.setEncodingType(BinarySecurityToken.BASE64_URL_ENCODING_TYPE);
bst.setEncodedData(minted.token());
bst.setCreatedDate(new Date());
bst.setExpiryDate(Date.from(minted.expiresAt()));
return bst;

The same mint also logs the authority block's revocation ID along with the subject. Revoking that ID revokes the token and every narrowed copy made from it, because each appended block chains from the authority block. Logging it at mint time is what makes revocation possible later.

6. Keys and rotation

The root key is Ed25519, stored in an encrypted configuration field, so PingFederate replicates it across a cluster like any other secret. The plugin's jar is also a CLI, so you can generate the key with the same code that uses it:

java -jar pf.plugins.biscuit-token-generator.jar keygen
# private=49309A02…
# public=ed25519/0155b736…

The Root Key ID goes into each token. Verifiers look up the public key by that ID, which is how you rotate: publish the new public key, switch the generator to the new key ID, then retire the old key once no unexpired tokens use it.

One biscuit-java detail cost me a test run: Biscuit.from_b64url(token, publicKey) drops root_key_id. The overload that takes a KeyDelegate receives the ID, which is the one you want for rotation anyway.

7. Packaging: shading, and building against the image

Two practical problems:

Classpath clashes. PingFederate ships its own vavr (0.10.2) and protobuf, and biscuit-java needs slightly different versions. The plugin is a shaded jar with every dependency relocated under com.darkedges.pingfederate.biscuit.shaded.*, so it can't collide with the server's classpath.

Where the SDK comes from. The SDK jars aren't on Maven Central, so the Dockerfile takes them from the PingFederate image itself. A build stage copies /opt/server/server/default/lib out of pingidentity/pingfederate:2511-12.3.3, compiles and tests the plugin on JDK 11, and the final stage copies the jar into deploy/. The plugin always compiles against exactly the version it runs on.

There's one runtime gotcha with the Ping Docker images. The server runs from /opt/out/instance, and the startup hooks copy /opt/server into it only on a fresh volume. Rebuild the image while the volume persists and you're still running the old jar. The repo's make redeploy wipes the volume for that reason.

8. Tests and an interop check

The plugin has two test classes:

BiscuitMinterTest: authority facts, expiry, wrong audience, wrong key, attenuation, injection, the reserved-name refusal, and certificate binding.
BiscuitTokenGeneratorTest: drives the plugin through PingFederate's own SDK types, Configuration, TokenContext, AttributeValue and BinarySecurityToken, and verifies the output.

Two findings from writing them:

biscuit-java's default authorizer budget is 5 ms. A cold JVM blows through that on the first evaluation and throws a Timeout. Pass RunLimits explicitly.
The SDK test needs PingFederate internals. XmlIDUtil.createID() starts PingFederate's internal registry, which uses reflection that JDK 17+ blocks without --add-opens. I run the tests on JDK 11, as the Docker build does.

The interop check matters most: tokens minted by biscuit-java in PingFederate verify in biscuit-auth 6 (Rust) using only the public key. That's what Part 3's resource server uses.

The plugin is half the story. In Part 3 we configure PingFederate around it with Terraform: the login, the JWT token manager, the processor policy and the generator mapping. Two resources need the generic restapi provider, because the PingFederate provider has no resource for token generators. Then we test it end to end in a browser.

Who mints the first Biscuit? PingFederate, token exchange and a hybrid model

DarkEdges — Sun, 04 Oct 2026 11:51:04 +0000

Repo: darkedges/pf12.3-biscuit-datalog-tokens

In the Biscuit Trust Lab series, Alice asked PlannerCo to do some work. PlannerCo split it between ResearchCo and ComputeCo, ResearchCo passed part of it to SearchCo, and every hop narrowed the token it was handed. Nobody called home to ask permission, and nobody could widen what they'd been given.

There was one thing that series never answered: where did Alice's first token come from? In the lab, the platform minted it. In a real company, Alice doesn't exist until an identity provider says she does. She logs in with a password and probably MFA, against a directory the security team runs, through an IdP that every application already trusts.

This series is about closing that gap with PingFederate. Over four parts:

Who mints the first Biscuit? Why a hybrid of JWTs and Biscuits works, and how OAuth token exchange joins them (this article).
Building a PingFederate token generator that mints Biscuits: the SDK plugin, the Datalog design rules, and what I had to disassemble to get the output right.
Configuring the exchange with Terraform and testing it end to end: 17 resources, two of which the provider can't manage, and a demo app that shows every request and response.
Step-up MFA, attenuation, and what's honestly not done, including a library gap that stops PingFederate from being the MFA attestor today.

Two token models, two strengths

If you've read the Trust Lab, you know what Biscuits are good at. If you've run an IdP, you know what JWTs are good at. The problem is that they're good at different things:

	JWT access token from your IdP	Biscuit
Who can narrow it	Only the issuer, by minting a new one	Anyone holding it, offline, by appending a block
Can a holder widen it?	No (it's signed)	No (appended blocks can only add checks)
Authorization logic	Claims, interpreted by each service's code	Datalog policy, evaluated with the token's facts
Delegation across hops	Token exchange back at the IdP for each hop	Append and pass on
Who understands it	Everything: gateways, PingAccess, API managers, every OAuth library	Biscuit libraries only
Login, MFA, consent, client registration	Built into the IdP	Not its job

Neither column wins. JWTs are what the outside world speaks: browsers, mobile apps, API gateways, and the edge of your network all expect OAuth. Biscuits are better once the token is inside, moving between services or companies that need to narrow it as it goes.

The hybrid: JWTs at the edge, Biscuits inside

So don't choose. Let each format do what it's good at, and put a well-defined seam between them:

                north-south: standard OAuth                       east-west: capabilities
 Browser ──login──▶ PingFederate ──JWT──▶ client / gateway ──Biscuit──▶ service A ──narrowed Biscuit──▶ service B
                         ▲                     │
                         └── token exchange ───┘
                             (JWT in, Biscuit out)

The seam is OAuth 2.0 Token Exchange, RFC 8693. The client presents the JWT it already has as the subject_token and asks for a different kind of token back:

curl -k -X POST 'https://localhost:9031/as/token.oauth2' \
  -u "orders-web:$CLIENT_SECRET" \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode "subject_token=$JWT" \
  --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \
  --data-urlencode 'requested_token_type=urn:darkedges:params:oauth:token-type:biscuit'

And PingFederate answers:

{
  "access_token": "CAESiwMKoAIKBmlzc3VlcgoWaHR0cHM6Ly9sb2NhbGhvc3Q6OTAzMQoFYWxp…",
  "issued_token_type": "urn:darkedges:params:oauth:token-type:biscuit",
  "token_type": "N_A",
  "expires_in": 299
}

That access_token is a Biscuit, signed with an Ed25519 key that PingFederate holds. token_type: N_A is RFC 8693's way of saying "this isn't an OAuth access token in the usual sense". The requested token type is a URN I made up. RFC 8693 lets you define your own, and PingFederate routes on it.

Here's what's inside, its authority block:

issuer("https://localhost:9031");
user("alice");
client("orders-web");
scope("orders:read");
scope("orders:write");
check if time($t), $t <= 2026-10-04T11:23:13Z;
check if audience($a), {"orders-api"}.contains($a);

Everything in it came from PingFederate: the user it authenticated, the client it registered, the scopes it granted, the lifetime and audience policy it enforces. From here on, the Trust Lab mechanics apply unchanged: append a block, narrow it, pass it on.

Why this works as a hybrid

It's tempting to see token exchange as a workaround. I think it's the right design, for five reasons.

1. PingFederate stays the authority. Login, MFA, account lockout, consent, client registration, scope policy and auditing all stay where they are. The Biscuit doesn't replace any of it. It carries the result of it, signed by the same IdP that produced it.

2. Nothing at the edge has to change. Browsers, mobile apps, PingAccess and your API gateway keep speaking standard OAuth. Only the components that want offline narrowing ever see a Biscuit.

3. PingFederate decides what goes into the root token. Token exchange runs through a processor policy in PingFederate. It validates the incoming JWT, picks the attributes it trusts (subject, client, scope), and can refuse to issue at all. That's the hook for central governance: the set of facts in the authority block is controlled in one place, not by whoever builds a client.

4. Below the seam, delegation stops costing a round trip. With JWTs only, each hop that wants a narrower token has to go back to the IdP and exchange again. With a Biscuit, the hop appends check if operation("read") and moves on. PingFederate is consulted once, at the seam.

5. It answers the Trust Lab's production list. Part 4 of the Trust Lab ended with what a production version would need, including persistent keys with rotation and revocation. An IdP already has key management. Here the Biscuit carries a root_key_id so verifiers can pick the right key during rotation, and every mint logs the authority block's revocation ID.

Bridging back to the Trust Lab

Put Alice's company IdP in front of the Trust Lab scenario and the chain becomes:

Alice logs in to PingFederate at her company and gets a JWT, like any other OAuth app.
PlannerCo, a registered OAuth client, exchanges that JWT for a Biscuit. The authority block says user("alice"), client("plannerco"), and the scopes Alice's company allows.
PlannerCo attenuates and delegates to ResearchCo and ComputeCo, exactly as in Part 2 of the Trust Lab.
Each receiver checks the chain with PingFederate's public key and its own policy, like the receiver's authorizer in Part 3. None of them needs to call PingFederate.

The hands-on parts of this series use a smaller example from the repository so you can run it: users alice and bob, a client called orders-web, and an orders-api that lets you read with orders:read but only write with orders:write plus an MFA attestation. The mechanics are the same.

What's inside PingFederate

Token exchange in PingFederate is a small pipeline. It's worth seeing the parts before we build one of them:

subject_token (JWT)
   │
   ▼
Token processor ............ validates the JWT with the access token manager that issued it
   │
   ▼
Processor policy ........... picks subject, client_id, scope; can reject
   │
   ▼
Generator mapping .......... maps policy attributes onto the generator's contract
   │
   ▼
Token generator ............ ← this is the plugin: turns attributes into a Biscuit
   ▲
Generator group ............ routes requested_token_type=…:biscuit to the generator

Everything except the generator ships with PingFederate. The generator is a Java plugin written against the PingFederate SDK's TokenGenerator interface, and that's the subject of the next part.

What this doesn't do

I'd rather say this up front:

PingFederate can mint the root token, but it can't yet sign the MFA attestation block. The Java Biscuit library is a format version behind the Rust one for third-party blocks. Part 4 covers this and the workaround.
PingFederate can't introspect a narrowed Biscuit meaningfully. It can check the signature, but whether a request is authorized depends on facts only the receiving service has.
Off-the-shelf gateways don't understand Biscuits. That's why the hybrid keeps JWTs at the edge.

In Part 2 we build the token generator: the SDK interface, how attributes become Datalog facts without injection, which fact names a minter must refuse to issue, and the detail I only found by disassembling PingFederate's token exchange code.

If you want to jump ahead, the README gets you from git clone to a PingFederate-minted Biscuit in about ten commands.

Credits without a mutable token: reservations, idempotency and receipts

DarkEdges — Sun, 04 Oct 2026 06:23:20 +0000

The first three parts of this series covered authority: who may do what, on whose behalf, and who decides. This last part covers money.

darkedges / biscuit-trust-lab

An interactive Cloudflare Pages playground for exploring Biscuit delegation, Datalog authorization, trust between independent operators, and shared clearinghouse billing.

Relay — Biscuit network lab

A Cloudflare Pages demonstration of independent operators accepting delegated tasks, applying local Datalog policies, and billing the original payer through a shared clearinghouse. Biscuit tokens and Ed25519 signatures are real; operators, work, and credits are simulated.

Live demo: biscuits.demos.darkedges.com

Run locally

Use Node.js 22 or newer and pnpm 11:

pnpm install
pnpm dev

Open http://127.0.0.1:8795. On this development computer, pnpm dev:lan binds to 10.0.0.35:8795 for other devices on the same network. Change that address in package.json if your computer has a different LAN IP. The interface starts a demo run automatically.

On Windows, ./start.ps1 starts the Pages preview and installs dependencies if needed. Use ./start.ps1 -BindAddress 10.0.0.35 for LAN access.

Deploy to Cloudflare Pages

The Pages output directory is web, as declared in wrangler.jsonc. web/_worker.js handles /api/run and /api/health and forwards other requests to Pages assets. Dependencies, including Biscuit WebAssembly, are bundled…

View on GitHub

Why the balance isn't in the token

It's tempting to put budget(100) in the Biscuit and have each hop append spent(5). That doesn't work:

Tokens are immutable and copyable. Two holders of the same token can each spend "the remaining 95". Nothing in the token stops concurrent use.
Appended blocks can't change facts. A later block can't reduce an earlier balance. It can only add checks.
Spending is shared state. Search and compute run in parallel under the same request, so the shared budget has to live in one place.

So the token carries who pays and for which request (payer, request_id). A clearinghouse holds the ledger for that request. Authorization is local, and accounting is coordinated. That's the line in the footer of the demo.

Reserve → execute → settle (or release)

Each billable call goes through the same lifecycle:

The operator authorizes the call (part 3).
The clearinghouse authorizes it again, then reserves credits and returns a signed grant.
The operator does the work.
The operator signs a completion receipt bound to that grant, and the clearinghouse settles.
If the work fails, the clearinghouse releases the reservation instead.

Reserved and settled credits both count against the budget, so promised money can't be promised twice.

Serializing reservations in single-threaded JavaScript

JavaScript is single-threaded, so it might seem that a race can't happen. But reserveLocked contains awaits (SHA-256 fingerprinting and signing the grant) between reading the used total and recording the reservation. Two reservations can interleave at those points and both see the same available balance.

The lab chains reservations onto a promise queue:

reserve(payload) {
  const pending = this.reservationQueue.then(() => this.reserveLocked(payload));
  this.reservationQueue = pending.catch(() => {});
  return pending;
}

async reserveLocked(payload) {
  // ... payer/request/amount validation, idempotency (below)
  const used = [...this.operations.values()]
    .filter(row => row.status !== 'released')
    .reduce((total, row) => total + row.amount, 0);
  if (used + payload.amount > this.budget) throw new InsufficientCredits(payload.amount, this.budget - used);
  const grant = await this.identity.sign({ operation_id: payload.operation_id, request_id: this.requestId,
    payer: this.payer, provider: payload.provider, amount: payload.amount, fingerprint,
    available_before: this.budget - used });
  this.operations.set(payload.operation_id, { /* ... */ status: 'reserved', grant });
  return { grant, duplicate: false, status: 'reserved' };
}

.catch(() => {}) on the queue tail means one rejected reservation doesn't block the ones after it. The caller still receives the rejection through pending.

The competing-reservations scenario

With a 100-credit budget, research settles 5. Search and compute then each ask for 60 concurrently:

await Promise.all([
  this.execute(searchToken, [researchProof, searchProof], 'search', 60),
  this.execute(computeToken, [computeProof], 'compute', 60),
]);

Whichever reaches the queue first gets its 60. The other sees Insufficient credits: 60 requested, 35 available and is denied after passing Biscuit authorization. The decision view says so explicitly: "Biscuit allowed the call; the clearinghouse denied its credit reservation." Raise the budget to 125 and both succeed.

Idempotency: retries don't double-charge

Networks retry. The clearinghouse keys reservations by operation_id and fingerprints the full signed payload:

const fingerprint = await digest(payload);
const previous = this.operations.get(payload.operation_id);
if (previous) {
  if (previous.fingerprint !== fingerprint)
    throw new Rejected('Idempotency conflict: operation ID reused with different billing details');
  if (previous.status === 'released')
    throw new Rejected('This operation was released; create a new operation ID');
  return { grant: previous.grant, duplicate: true, status: previous.status };
}

There are three cases:

Same ID, same details. Return the existing grant. If it's already settled, the operator returns the existing result, with no new work and no new charge.
Same ID, different details. Conflict. Someone is trying to reuse an operation ID to change the amount, payer or action.
Same ID after release. Refuse. A failed operation needs a fresh ID, so a stale retry can't revive it.

The Retry scenario sends the search call twice. The ledger shows 3 operations and 40 credits settled, not 50.

Receipts: settle only what the provider claims it completed

Settlement needs evidence from the provider, bound to the specific reservation:

const receipt = await this.identities[provider].sign({
  operation_id: payload.operation_id, provider,
  grant_hash: await digest(grant), result: 'completed' });

async settle(receipt) {
  const provider = receipt.payload.provider;
  const proof = await verify(this.identities[provider], receipt);
  if (proof.result !== 'completed') throw new Rejected('Receipt does not prove completion');
  const row = this.operations.get(proof.operation_id);
  if (!row || row.provider !== provider || proof.grant_hash !== await digest(row.grant))
    throw new Rejected('Receipt is not bound to this provider and reservation');
  if (row.status === 'released') throw new Rejected('Cannot settle a released reservation');
  row.status = 'settled'; row.receipt = receipt;
}

A receipt from the wrong provider, for another reservation, or for a released reservation is rejected.

Be clear about what a receipt proves. It's the provider's signed claim that it completed the work. It doesn't prove the work was any good. That's a matter for disputes and reputation, not for cryptography.

The operation-failure scenario

Search reserves 10 credits, and then its simulated execution fails. The clearinghouse releases the reservation. Settled is 30, available is 70, and replaying the timeline shows reserved rising to 10 and falling back to 0. A test checks that every replay snapshot balances:

for (const event of run.events) {
  const ledger = event.snapshot.ledger;
  assert.equal(ledger.available + ledger.settled + ledger.reserved, ledger.budget);
}

Running it on Cloudflare Pages

The lab deploys as a single Pages project. web/_worker.js (advanced mode) handles /api/run and /api/health and passes everything else to static assets:

if (path === '/api/run' && request.method === 'POST') {
  const body = await request.text();
  if (body.length > 20_000) return Response.json({ error: 'Request is too large' }, { status: 413 });
  return Response.json(await runDemo(JSON.parse(body)));
}

Each request creates fresh keys, a new request ID and a request-local ledger. That keeps the demo stateless. It also means nothing persists between requests or across Cloudflare locations, which is fine for a lab and wrong for real money.

pnpm install
pnpm check          # node --test: real Biscuit decisions, concurrency, idempotency, release
pnpm run deploy     # wrangler pages deploy web

What a production version would need

The lab deliberately stops short of being a payment system. To make it real you would need:

Durable, centralized accounting. The serialized queue would become a transactional store, for example a Durable Object or a database row lock for each request.
Persistent issuer and operator keys, with rotation and published key sets, instead of fresh keys on every run.
Authenticated transports between operators, not in-process function calls.
Payer consent and quotes before a reservation, not a fixed price list.
Revocation. Biscuit revocation identifiers make this possible, but someone has to publish and check the list.
Reservation expiry, so abandoned reservations free their credits.
Reconciliation and dispute handling, because a receipt is a claim, not proof of quality.

Wrapping up

Across the four parts, we covered:

A Biscuit root grant whose authority block binds requester, payer, request and rights, and whose checks every use must pass.
Attenuation at each hop, narrowing what downstream operators can do without contacting the issuer.
Signed delegation envelopes that fill in what Biscuit doesn't record: who delegated to whom.
A local Datalog policy at each receiver, combining issuer facts, verified call facts and its own trust settings.
A clearinghouse that keeps money out of the token, with serialized reservations, idempotent retries, releases and receipt-bound settlement.

Try to break it. Change the trust graph, swap payers, squeeze the budget, and watch the Debug tab. If you find a way to get SearchCo to do work it shouldn't, please open an issue.

Code: github.com/darkedges/biscuit-trust-lab · Demo: biscuits.demos.darkedges.com

Local policy, shared facts: the receiver's Datalog authorizer

DarkEdges — Sun, 04 Oct 2026 06:23:03 +0000

So far in this series we've minted a root grant, narrowed it at each hop, and wrapped every delegation in a signed envelope. All of that tells the receiver what was delegated and by whom. It doesn't decide whether the receiver should do the work. That decision belongs to the receiver alone.

In Biscuit Trust Lab, each operator makes that decision with its own Biscuit authorizer.

darkedges / biscuit-trust-lab

An interactive Cloudflare Pages playground for exploring Biscuit delegation, Datalog authorization, trust between independent operators, and shared clearinghouse billing.

Relay — Biscuit network lab

Live demo: biscuits.demos.darkedges.com

Run locally

Use Node.js 22 or newer and pnpm 11:

pnpm install
pnpm dev

On Windows, ./start.ps1 starts the Pages preview and installs dependencies if needed. Use ./start.ps1 -BindAddress 10.0.0.35 for LAN access.

Deploy to Cloudflare Pages

View on GitHub

One policy, four sources of facts

Every operator runs the same policy:

allow if requester($r), accepts_requester($r),
    caller($c), service($s), trusts_caller($c, $s),
    payer($p), billing_payer($p),
    request_id($id), current_request($id),
    action($a), right($a), offers($a);

It's the same rule everywhere, but each operator evaluates it against different facts. Every predicate has a clear origin:

Fact	Comes from	Meaning
`requester`, `payer`, `request_id`, `right`	Biscuit authority block (signed by the clearinghouse)	What the original grant says
`caller`, `billing_payer`, `current_request`, `action`	Verified call (caller's Ed25519 signature checked)	What this call asks for
`service`	Receiving operator	Who I am
`accepts_requester`, `trusts_caller`, `offers`	Receiver's local policy	Whom I serve, whom I trust, what I do

Restrictions appended during delegation don't add facts. They add check if rules that must also pass (see part 2).

The policy reads almost like English. Allow the call if the original requester is someone I accept, the caller is someone I trust to send me work, the payer on the call is the payer on the grant, the call belongs to the granted request, and the action was granted and is something I offer.

Building the authorizer

Here's how the receiver assembles the authorizer in lib/relay.js:

const builder = new AuthorizerBuilder();
builder.addCode(POLICY);
// The policy is fixed source code. All added values come from validated names or JSON-quoted strings.
builder.addCode(`caller(${JSON.stringify(caller)}); service(${JSON.stringify(provider)});
  billing_payer(${JSON.stringify(payload.payer)});
  current_request(${JSON.stringify(payload.request_id)}); action(${JSON.stringify(payload.action)});
  offers(${JSON.stringify(provider)});`);
builder.merge(authorizer`time(${new Date()});`);
for (const who of this.accepts[provider]) builder.addCode(`accepts_requester(${JSON.stringify(who)});`);
for (const [source, target] of this.edges)
  if (target === provider) builder.addCode(`trusts_caller(${JSON.stringify(source)}, ${JSON.stringify(target)});`);

const built = builder.buildAuthenticated(verified);
built.authorizeWithLimits({ max_facts: 1000, max_iterations: 100, max_time_micro: 250000 });

A few things to notice:

buildAuthenticated(verified) only runs on a token that has already passed root-key verification and the chain checks from part 2.
authorizeWithLimits caps facts, iterations and time. Every authorizer that evaluates input from outside should do this.
Trust is local data. trusts_caller and accepts_requester come from each operator's own settings. In the UI you edit them in the trust graph and the requester checkboxes. The token never carries them.
The lab keeps offers simple: each operator offers exactly one action with the same name as itself (SearchCo offers search). A real operator would list its catalogue.

Reading the decision

authorize() returns allow or deny. For teaching, that isn't enough, so the lab asks Biscuit for the facts the authorizer can actually see, using a query rule for each predicate:

const rule = Rule.fromString(`inspected(${vars}) <- ${name}(${vars})`);
built.queryWithLimits(rule, LIMITS).map(fact => fact.terms());

It then compares the facts the call needed with the facts that are present, and labels each with its origin. That table is what you see when you click an operator under Granted permissions. A missing fact shows in red.

One caveat: the table is an explanation. Biscuit's own authorize() result is the only thing that decides permit or deny. The table is rebuilt from queried facts so a human can see why.

How each scenario fails

Change payer

ResearchCo signs a search call that names mallory-org as the payer:

payer("alice-org")            // authority block
billing_payer("mallory-org")  // from the verified call

This fails twice. The policy needs payer($p), billing_payer($p) to unify, and they don't. The root token's own check if billing_payer($p), payer($p) fails too. Even an operator with a careless policy would be stopped by the issuer's check. Search is denied before billing, so the ledger settles 30 instead of 40.

Forbidden operation

SearchCo receives action("delete"). The grant has no right("delete"), and SearchCo doesn't offer delete. ResearchCo's block check if action("search") also fails. Three independent reasons, one denial.

Missing caller trust

Remove the ResearchCo → SearchCo edge in the trust graph and run again. SearchCo's authorizer no longer has trusts_caller("research", "search"), so no policy matches:

{"FailedLogic":{"NoMatchingPolicy":{...}}}

ComputeCo is unaffected, because it trusts PlannerCo, which delegated compute directly. Changing trust at one operator only changes that operator's decisions.

Requester not accepted

Untick Alice for SearchCo, and accepts_requester("alice") disappears from SearchCo's authorizer. If PlannerCo stops accepting Alice, the run stops at ingress. PlannerCo runs a small authorizer of its own before delegating anything:

const planner = authorizer`allow if requester($r), accepts_requester($r);`;

When that fails, no tasks are created at all.

Untrusted issuer

As covered in part 2, a token minted with a different root key fails Biscuit.fromBase64(token, rootPublic) and never reaches Datalog. The decision view shows phase: verification rather than phase: datalog.

Two authorization boundaries

Every billable call is authorized twice: once by the receiving operator, and again on behalf of the clearinghouse before it reserves credits. The Debug tab shows them as separate entries. In the lab, the clearinghouse re-runs the same verification and the receiver's policy. In a real deployment it would hold its own policy, for example "only reserve for providers registered for this payer".

The tests check that a denied call never reaches billing:

const denied = await runDemo({ scenario: 'payer_swap' });
const search = denied.debug.filter(entry => entry.task_index === 1);
assert.equal(search.length, 1, 'Denied operator call must not reach billing');
assert.equal(search[0].outcome, 'denied');

Authorization says the call is allowed. It doesn't say the payer can afford it. In the final part we look at the clearinghouse: why the balance can't live in the token, how reservations stay safe under concurrency, how retries avoid double charging, and what a production version would need.

Code: github.com/darkedges/biscuit-trust-lab · Demo: biscuits.demos.darkedges.com

Attenuating Biscuit tokens and signing the delegation chain

DarkEdges — Sun, 04 Oct 2026 06:22:45 +0000

In part 1 I introduced the network: Alice's request flows through PlannerCo to ResearchCo, SearchCo and ComputeCo, and every billable call goes through a clearinghouse. This post covers the token side: how the root grant is minted, how each hop narrows it, and why Biscuit alone isn't enough to prove who delegated.

All code is from lib/relay.js.

darkedges / biscuit-trust-lab

An interactive Cloudflare Pages playground for exploring Biscuit delegation, Datalog authorization, trust between independent operators, and shared clearinghouse billing.

Relay — Biscuit network lab

Live demo: biscuits.demos.darkedges.com

Run locally

Use Node.js 22 or newer and pnpm 11:

pnpm install
pnpm dev

On Windows, ./start.ps1 starts the Pages preview and installs dependencies if needed. Use ./start.ps1 -BindAddress 10.0.0.35 for LAN access.

Deploy to Cloudflare Pages

View on GitHub

Minting the root grant

The clearinghouse issues one root Biscuit for each request. Its authority block holds facts about the request and checks that every later use must pass:

mint(privateKey) {
  return biscuit`requester(${this.requester}); payer(${this.payer}); request_id(${this.requestId});
    right("research"); right("search"); right("compute");
    check if billing_payer($p), payer($p);
    check if current_request($r), request_id($r);
    check if action($a), right($a);
    check if time($t), $t < ${this.expiry};`.build(privateKey);
}

The facts describe the grant: Alice is the requester, alice-org pays, the request has an ID, and three rights are granted.

The checks tie those facts to each call. The receiver supplies billing_payer, current_request, action and time from the verified call it's handling. If the call claims a different payer, a different request, an action outside the granted rights, or arrives after expiry, a check fails and Biscuit denies the call. The receiver's own policy can't override that.

The tagged template (biscuit`...`) comes from the JavaScript Biscuit bindings. Interpolated values are passed as typed parameters, not pasted into the source, so a requester name can't inject Datalog.

The keys are real Ed25519 keys:

const root = new KeyPair(SignatureAlgorithm.Ed25519);
demo.rootPrivate = root.getPrivateKey();
demo.rootPublic = root.getPublicKey();
demo.expiry = new Date(Date.now() + 15 * 60_000);
demo.rootToken = demo.mint(demo.rootPrivate);

Each operator gets the clearinghouse's public key and only accepts tokens whose signature chain leads back to it.

Attenuating at each hop

When PlannerCo delegates research, it appends a block that limits which actions the token can still be used for:

async delegate(parentToken, caller, provider, actions, parentTask = 'root', parentProof = null) {
  const check = `check if ${actions.map(action => ground('action', [action])).join(' or ')};`;
  const restriction = block``;
  restriction.addCode(check);
  const token = parentToken.appendBlock(restriction);
  // ... signed envelope, see below
}

The network makes three delegations:

Hop	Appended block
PlannerCo → ResearchCo	`check if action("research") or action("search")`
ResearchCo → SearchCo	`check if action("search")`
PlannerCo → ComputeCo	`check if action("compute")`

SearchCo's token therefore carries the authority block plus two restriction blocks. Every check in every block must pass. Even though the root grants compute, SearchCo can't use its token for compute, because ResearchCo's block forbids it.

Appending needs no private key and no call to the issuer. Each block is chained to the one before it with a fresh ephemeral key, so any block can be added but none can be removed. In part 1 I also showed that a right("delete") fact in an appended block is ignored by the authorizer. Blocks can narrow authority but can't widen it.

The gap: who appended this block?

Here is the problem. A Biscuit tells SearchCo which restrictions apply. It doesn't tell SearchCo who added them. An attenuation block isn't signed by an identity that SearchCo knows.

That matters in a delegation network. SearchCo's policy says "I accept work from ResearchCo". To enforce that, SearchCo needs proof that:

ResearchCo is the one calling.
ResearchCo got this task from PlannerCo, which got it from the original request.
Each token in the chain extends the token before it, with nothing dropped.

So the lab adds a delegation envelope at each hop, signed with the delegator's own Ed25519 identity key (via WebCrypto):

const proof = await this.identities[caller].sign({
  request_id: this.requestId,
  task_id: id('task'),
  parent_task: parentTask,
  caller, provider,
  allowed_actions: actions,
  token_hash: await digest(tokenText),
  token: tokenText,
  parent_proof_hash: parentProof ? await digest(parentProof) : null,
});

Each envelope names the delegator and the receiver, binds to the exact token by hash, and links to its parent envelope by hash. The envelopes form a hash chain alongside the token's block chain.

The signed operation request

When ResearchCo finally calls SearchCo, it signs the call itself:

const payload = { caller, provider, action, amount,
  payer: options.payer ?? this.payer, request_id: this.requestId,
  task_id: proof.task_id, operation_id: options.operationId ?? id('op'),
  token_hash: await digest(token.toBase64()) };
const call = await this.identities[caller].sign(payload);

The call states the action, the price, and the payer, and it binds to the token by hash.

Verifying the chain

Before any Datalog runs, the receiver checks the evidence in evaluateAuthorization:

const payload = await verify(this.identities[caller], signedCall);
if (payload.token_hash !== await digest(tokenText))
  throw new Rejected('Signed call does not match the presented Biscuit');

let previous = null;
let previousBlocks = this.rootToken.getRevocationIdentifiers();
for (const proof of proofChain) {
  const entry = proof.payload;
  await verify(this.identities[entry.caller], proof);              // envelope signature
  const hopToken = Biscuit.fromBase64(entry.token, this.rootPublic); // issuer signature
  const blocks = hopToken.getRevocationIdentifiers();
  if (blocks.length <= previousBlocks.length ||
      previousBlocks.some((value, index) => value !== blocks[index]))
    throw new Rejected('Child Biscuit must extend the parent token without dropping restrictions');
  // ... request binding, parent hash, caller == previous provider, chain starts at planner
  previous = proof;
}

Revocation identifiers make the "extends" check cheap. Each block has a unique identifier, so a child token extends its parent exactly when the parent's identifiers form a strict prefix of the child's.

The loop also checks that:

every envelope belongs to this request;
each envelope's parent_proof_hash matches the previous envelope;
each hop's caller is the previous hop's provider, and its parent_task is the previous hop's task_id;
the chain starts at PlannerCo, with parent root;
the final envelope matches the signed call's caller, provider, task, request and token hash.

Only after all of that does Biscuit.fromBase64(tokenText, this.rootPublic) verify the presented token and hand it to the authorizer.

The untrusted-issuer scenario

The Untrusted issuer scenario mints a lookalike token with a rogue key and delegates it to SearchCo with a correctly signed envelope:

const rogue = new KeyPair(SignatureAlgorithm.Ed25519);
[searchToken, searchProof] = await this.delegate(this.mint(rogue.getPrivateKey()), 'research', 'search', ...);

The facts are identical. The envelope is validly signed by ResearchCo. But Biscuit.fromBase64(entry.token, this.rootPublic) fails, because the token's root signature doesn't come from the clearinghouse. The call is rejected in the verification phase. No Datalog runs, and no credits are reserved.

A practical note: Biscuit WASM in Cloudflare Workers

The lab uses @smithery/biscuit, which wraps @biscuit-auth/biscuit-wasm. For Wrangler to bundle the .wasm file into a Pages Worker, the WASM package has to expose its module files in exports. The repo carries a small pnpm patch for this:

   "exports": {
-    "import": "./module/biscuit.js"
+    ".": { "import": "./module/biscuit.js" },
+    "./module/biscuit_bg.js": "./module/biscuit_bg.js",
+    "./module/biscuit_bg.wasm": "./module/biscuit_bg.wasm"
   },

It's registered under patchedDependencies in pnpm-workspace.yaml, so pnpm install applies it automatically.

The token and the chain prove what was delegated, and by whom. In part 3 we look at how each receiver decides whether to accept the call, using one Datalog policy that combines facts from the issuer, the call, and its own local trust settings.

Code: github.com/darkedges/biscuit-trust-lab · Demo: biscuits.demos.darkedges.com

Delegating authority across companies with Biscuit tokens

DarkEdges — Sun, 04 Oct 2026 06:22:28 +0000

Alice wants a piece of work done. Her organization pays for it. She hands the job to a coordinator, and the coordinator splits it between other companies. Some of those companies pass part of the job on again.

Every company in that chain has to answer the same questions before doing any work:

Who originally asked for this, and do I accept work for them?
Who is calling me, and do I trust them to send me work?
Who pays, and is that the payer who actually authorized it?
Is this action within what was originally granted, and within what each step passed on?
Is there still money left?

A plain bearer token or API key can't answer most of these. It can say "the holder may do X". It can't say "the holder may do X, on behalf of Alice, paid by alice-org, only as part of request 42, and only the search part of it". And once the token leaves your hands, you can't narrow it without going back to the issuer.

I built Biscuit Trust Lab to explore this problem with real cryptography and simulated companies. This series walks through how it works.

darkedges / biscuit-trust-lab

An interactive Cloudflare Pages playground for exploring Biscuit delegation, Datalog authorization, trust between independent operators, and shared clearinghouse billing.

Relay — Biscuit network lab

Live demo: biscuits.demos.darkedges.com

Run locally

Use Node.js 22 or newer and pnpm 11:

pnpm install
pnpm dev

On Windows, ./start.ps1 starts the Pages preview and installs dependencies if needed. Use ./start.ps1 -BindAddress 10.0.0.35 for LAN access.

Deploy to Cloudflare Pages

View on GitHub

Live demo: biscuits.demos.darkedges.com

The network

Alice (requester) / alice-org (payer)
  └─ PlannerCo (initial coordinator)
       ├─ ResearchCo [5 credits]
       │    └─ SearchCo [10 credits]
       └─ ComputeCo [25 credits]

All billable calls → shared clearinghouse

Four independent operators and a clearinghouse take part:

The clearinghouse issues the original grant and keeps the request's credit ledger.
PlannerCo accepts Alice's request and delegates research and compute.
ResearchCo does research, then delegates search to SearchCo.
ComputeCo does compute.

Each operator decides for itself whether to accept a call. No central service says yes or no to everyone. The clearinghouse only coordinates the money.

What's real and what's simulated. The Biscuit tokens, Datalog authorization, and Ed25519 signatures are real. The operators, the work, and the credits are simulated, and everything runs inside a single request. This is a teaching lab, not a payment system.

Why Biscuit?

Biscuit is a bearer token format with three properties that fit this problem.

1. Offline attenuation. Anyone holding a Biscuit can append a block that restricts it, without contacting the issuer. PlannerCo can take Alice's grant and pass ResearchCo a copy limited to research and search. ResearchCo can narrow it again to search only before passing it to SearchCo.

2. Appended blocks can't widen authority. A block can add checks that must pass. Facts it adds aren't trusted by the receiver's authorization policy. I tested this directly against the library used in the lab:

const root = new KeyPair(SignatureAlgorithm.Ed25519);
const token = biscuit`right("search");`.build(root.getPrivateKey());

// Try to grant ourselves "delete" from an appended block
const sneaky = block``;
sneaky.addCode('right("delete");');
const widened = Biscuit.fromBase64(token.appendBlock(sneaky).toBase64(), root.getPublicKey());

const auth = new AuthorizerBuilder();
auth.addCode('action("delete"); allow if action($a), right($a);');
auth.buildAuthenticated(widened).authorize();
// throws: {"FailedLogic":{"NoMatchingPolicy":{"checks":[]}}}

The right("delete") fact from the appended block is ignored. Only facts from the authority block (signed by the issuer) and from the receiver's own authorizer count.

3. Datalog policies. Each receiver writes its policy as Datalog rules. It combines facts from the token, facts about the incoming call, and its own local facts (who it trusts, which requesters it accepts, what it offers). Part 3 of this series covers the policy in detail.

What the lab adds on top of Biscuit

Biscuit handles "what is this token allowed to do?". A delegation network needs more than that:

Who appended this block? A Biscuit attenuation block doesn't identify its author. The lab wraps each delegation in a separately signed delegation envelope, so a receiver can check the whole chain: PlannerCo → ResearchCo → SearchCo. (Part 2)
Who is calling right now? The caller signs every operation request, and the receiver checks that signature against the presented token. (Part 2)
Is there money left? Biscuits are immutable and don't store balances. A request-scoped clearinghouse reserves credits, prevents double spending, and settles only against a signed completion receipt. (Part 4)

Try it

Open the live demo. It starts with an authorized run:

Authorized delegation settles 5 credits for research, 10 for search, and 25 for compute. alice-org pays 40 in total.
Open Granted permissions to see the root rights and each restriction that was appended. Click SearchCo to see the decision logic filled in with the real requester, payer, caller, action, and request values.
Remove the ResearchCo → SearchCo trust edge, or untick Alice for SearchCo, and run again. Search is denied. Compute still succeeds, because it never went through ResearchCo.
Try the other scenarios:

Scenario	What happens	Credits settled
Authorized delegation	Three operations settle	40
Change payer	Search denied by a Biscuit check	30
Forbidden operation	Search attempts `delete` and is denied	30
Untrusted issuer	Search token's signature rejected	30
Competing reservations	One 60-credit child denied at budget 100	65
Retry	Search's settlement is reused, not charged twice	40
Operation failure	Search's reservation is released	30

The Debug tab (/#debug) records the browser's real POST /api/run call, plus every internal authorization and clearinghouse step. You can filter for denials and copy a cURL command to reproduce a run.

Run it locally

You need Node.js 22+ and pnpm 11:

git clone https://github.com/darkedges/biscuit-trust-lab.git
cd biscuit-trust-lab
pnpm install
pnpm dev      # http://127.0.0.1:8795
pnpm check    # runs the test suite

The whole thing is a Cloudflare Pages project. web/ holds the UI, web/_worker.js serves /api/run, and lib/relay.js holds all the token, policy, and ledger logic in under 400 lines. Biscuit runs as WebAssembly inside the Worker.

Coming up in this series

Delegating authority across companies with Biscuit tokens (this post)
Attenuating Biscuit tokens and signing the delegation chain: minting the root grant, appending restrictions, and why each hop needs a signed envelope.
Local policy, shared facts: the receiver's Datalog authorizer: one policy, four sources of facts, and how each denial scenario fails.
Credits without a mutable token: reservations, idempotency and receipts: the clearinghouse, concurrent reservations, retries, and what a production system would still need.

The code is at github.com/darkedges/biscuit-trust-lab. Issues and PRs are welcome.

Run It, Deploy It, and What's Honestly Not Done Yet

DarkEdges — Thu, 01 Oct 2026 10:54:57 +0000

Repo: darkedges/pingfederate-graph-broker*

We've covered the problem, the PingFederate courier flow, introspection and delegations and the token vault. Here is how to run it and where it stands.

1. The zero-credential demo

docker compose -f compose.demo.yaml up --build -d   # http://127.0.0.1:8097
docker compose -f compose.demo.yaml down

Local simulators stand in for PingFederate, Entra and Graph, with a temporary encrypted store. State resets on restart.

2. Tests

go test -race -count=1 ./...
go vet ./...
go build -buildvcs=false ./cmd/broker

Go 1.26+ is required. The race detector needs a C compiler, so on Windows use WSL2 or Docker.

3. A live local stack

Terraform is split into separate states because PingFederate must exist before its provider can connect:

terraform/runtime: Docker Compose runtime
terraform/scopes: adopts PF's global OAuth scopes
terraform (root): Entra app registration, access token managers, clients, IdP connection, Reference ID adapter

make compose-pf, make compose-broker and make compose-portal start the pieces. The portal needs a local trusted certificate (for example from mkcert), and PingFederate needs Ping DevOps credentials.

For public hostnames there's a Cloudflare Tunnel guide. The one rule: never tunnel the PF admin port.

4. Kubernetes

A Helm chart in helm/broker deploys the broker and portal in one pod with a persistent volume. It uses a Recreate strategy and rejects replicas other than 1, because of the file store. Secrets come from an existingSecret.

make helm-lint
make helm-template
make helm-upgrade HELM_VALUES=my-values.yaml

What is not proven

The repo's verification log marks live PingFederate, Entra and Graph integration as not run. Mock-based tests pass; a real tenant acceptance checklist (11 steps in docs/OPERATIONS.md) is yet to be completed. Also:

Single instance only, no distributed storage or locking
No application-level rate limiting
The optional SAML on-behalf-of path (PF token exchange to SAML 1.1 to Entra OBO to Graph) is documented but not provisioned or proven
Public Microsoft cloud only, single tenant
Terraform doesn't yet cover the full PF handoff

I'd rather say this up front than have you find out in a test environment.

Roadmap

The next production milestone:

PostgreSQL transactions with per-connection advisory locks
Managed key encryption (KMS) and key rotation
Per-object authorisation policy
Metrics and rate limiting
Integration tests against a non-production PF/Entra environment
Possibly an MCP transport so agent frameworks can consume the directory tools directly

Get involved

If you work on PingFederate, Entra or agent security, I'd love feedback, especially on the broker_principal_type contract and the delegation model. Open an issue at github.com/darkedges/pingfederate-graph-broker.

Thanks for reading the series.

Securing the Token Vault: Encrypted State, Refresh Rotation and Safe Logs

DarkEdges — Thu, 01 Oct 2026 10:54:34 +0000

Repo: darkedges/pingfederate-graph-broker*

A broker that holds refresh tokens is a high-value target. This part walks through the controls that protect them, and the trade-offs the starter deliberately accepts.

One encrypted file

All state lives in a single file, DATA_DIR/state.enc:

AES-256-GCM with random nonces and version-specific additional authenticated data
Key supplied as TOKEN_ENCRYPTION_KEY (for example from openssl rand -base64 32). Lose it and the store is unreadable
Writes go to a temp file, fsync, then an atomic rename
If the directory fsync fails, the store is poisoned until restart, rather than continuing in an uncertain state
A flock prevents a second process from opening the same store

The trade-off: the whole file is re-encrypted on every mutation, and flock means no native Windows storage. That's fine for a single instance and wrong for a fleet, which is why Postgres is the next milestone.

Refresh rotation without races

Entra can rotate refresh tokens, so a naive implementation can lose the only valid one:

Tokens refresh when less than 90 seconds remain
Refreshes are serialised per connection
A new refresh token replaces the old one. If the response omits one, the existing one is preserved
Revocation takes the same connection lock as refresh, so an in-flight refresh can't resurrect a token the user just deleted
Store callbacks make no network calls, so a slow upstream can't hold the store lock

Logs that can't leak

Audit logging records only the client ID, operation, outcome and delegation ID. It never contains tokens, request bodies, reference IDs, query strings or raw upstream errors.

Even debug logging is restricted to fixed categories. For example, a malformed pickup is reported as format_shape=string_non_json instead of echoing the value. When debugging an identity flow, it's tempting to log the payload. This design makes that impossible by default.

The portal's browser-facing defences

The portal is a Go HTTPS backend with an embedded Next.js UI:

The PF token stays server-side. The browser gets an opaque Secure, HttpOnly cookie
CSRF and Origin checks on state-changing requests
TargetResource is matched exactly on the Reference ID callback
The Form POST from PF ends on a same-origin continuation page. A cross-origin POST redirect would otherwise run into the CSP form-action 'self' rule

Tests that target the dangerous paths

The broker test suite includes a full mocked lifecycle (TestCompleteLifecycle) and cases for replay, scope escalation, tamper detection, concurrency and credential-bearing redirects. The project runs go test -race, go vet and a build in GitHub Actions.

go test -race -count=1 ./...
go test -v ./internal/broker -run '^TestCompleteLifecycle$'

Known limits

This is not a hardened product. Still open: managed key encryption, key rotation, per-object authorisation policy, rate limiting, and protection against rollback by a privileged filesystem operator.

Last part: running it, deploying it and what comes next.

Introspection and Delegations: Authorising Agents Per User, Per Operation

DarkEdges — Thu, 01 Oct 2026 10:54:14 +0000

Repo: darkedges/pingfederate-graph-broker*

Once a user has linked their Entra account, how does an agent get to use it? Two things must both be true on every request: the caller holds a valid PingFederate token of the right kind, and a user-created delegation covers the call.

Introspect every request

The broker calls PF's /as/introspect.oauth2 for every protected request. There is no caching of authorisation results, so a revoked or expired token stops working immediately.

An accepted response looks like this:

{
  "active": true,
  "token_type": "Bearer",
  "iss": "https://pf.example.com",
  "aud": "https://directory-broker.example.com",
  "exp": 2000000000,
  "client_id": "directory-portal",
  "sub": "canonical-user-id",
  "scope": "broker.connect",
  "broker_principal_type": "user"
}

The broker requires an exact iss, an aud equal to its configured audience, token_type of Bearer, plus exp, client_id and scope.

Two callers, two contracts

Caller	PF scope	Fixed claim	Allowed client IDs
Portal acting for a user	`broker.connect`	`user`	`PF_PORTAL_CLIENT_IDS`
Background agent	`broker.directory.read`	`agent`	`PF_AGENT_CLIENT_IDS`

broker_principal_type is not a built-in PingFederate claim. It's a contract this broker introduces, set to a fixed value per client and flow in the access token manager. That prevents an agent token from ever being mistaken for a user token, and vice versa.

The portal uses the authorization code flow with PKCE. Agents use client credentials.

Delegations

A user (via the portal) grants an agent a delegation on one of their connections:

POST /v1/connections/{connection}/delegations
Authorization: Bearer <user token>

{
  "agent_client_id": "directory-agent",
  "operations": ["directory.find_users", "directory.find_groups", "directory.list_group_members"],
  "expires_in_seconds": 86400
}

A delegation binds owner, connection, agent client, operations and expiry. Lifetime is between 60 seconds and 7 days. It is re-validated on every request, and the owner can revoke it with DELETE /v1/delegations/{delegation}.

The agent's view

Method	Path	Operation
GET	`/v1/delegations/{delegation}/users`	`directory.find_users`
GET	`/v1/delegations/{delegation}/groups`	`directory.find_groups`
GET	`/v1/delegations/{delegation}/groups/{group}/members`	`directory.list_group_members`

curl -H "Authorization: Bearer ${PF_AGENT_TOKEN}" \
  "https://directory-broker.example.com/v1/delegations/${DELEGATION_ID}/users?prefix=Nick"

The agent never names a user or a connection. The delegation ID resolves to both, and only if the agent's PF client_id matches the one in the delegation.

Graph calls are narrow by construction

Graph v1.0 GET requests only
Fixed page size of 25
Raw $filter, $select and URLs from callers are rejected
Paging cursors are opaque, encrypted and authenticated, expire after 15 minutes and are bound to the delegation and route
Outbound redirects are disabled, so credentials can't follow a redirect

Failure semantics

The broker distinguishes "the grant is gone" from "something is down":

invalid_grant, interaction required, scope escalation or a Graph 401 mark the connection reconnect_required and clear its tokens.
Outages and client-credential errors do not erase a valid grant.
A Graph 403 does not trigger endless refresh attempts.

Silent connections with SAML Bearer Token Exchange

The browser link flow in part 2 needs the user to go through an Entra login. For cases where that interaction isn't wanted, the broker has an optional path (SAML_ENABLED=true, POST /v1/connections/saml) built on PingFederate's token exchange:

The portal supplies a PF reference token for the signed-in user.
PF's SAML Bearer Token Exchange issues a SAML 1.1 assertion for that user.
The assertion is exchanged at Entra for a token for a custom API.
Entra's on-behalf-of flow turns that into a Microsoft Graph token.

There's no browser redirect and no consent prompt per connection. The trade-off is that the resulting connection is session-limited: there is no refresh token to store, so it lasts as long as the Graph token does.

Two honest caveats. This path is not yet provisioned or proven against a live PF/Entra environment. And in the existing environment inspected, the Graph token for the demonstrated app carried a write permission, which must not be used unchanged: the broker's read-only rule applies to this path too.

Next: how the broker protects the tokens it holds.

PingFederate as a Token Courier: Linking Entra with the Reference ID Adapter

DarkEdges — Thu, 01 Oct 2026 10:53:46 +0000

Repo: darkedges/pingfederate-graph-broker*

In part 1 we said Entra tokens stay on the backend. But someone has to obtain them. Here the broker uses PingFederate as the courier: PF runs the upstream OIDC login to Entra, and the broker picks up the result server-to-server.

The moving parts in PingFederate

An upstream Entra OIDC IdP connection (authorization code with PKCE) requesting offline_access plus the two Graph read scopes.
The Reference ID SP Adapter from the Agentless Integration Kit. It hands the portal an opaque reference instead of the attributes themselves.
A pickup endpoint the broker calls with HTTP Basic auth to exchange that reference for attributes.

The attributes in the pickup contract:

Attribute	Meaning
`subject`	Canonical PF user ID
`entra_tid`	Entra tenant ID
`entra_oid`	Entra object ID
`entra_token_response`	Token endpoint response (Context → Token Endpoint Response)

The connection flow

The user signs in to the portal through PF (authorization code + PKCE). The PF token stays server-side.
The portal calls POST /v1/link-intents. The broker creates a one-use, five-minute intent.
The browser goes through the PF SP journey, which logs in to Entra upstream.
The Reference ID adapter Form POSTs REF and TargetResource to the portal callback.
The portal calls POST /v1/link-intents/{id}/complete with {"reference":"<REF>"}.
The broker performs the authenticated pickup from PF.
The broker checks that subject equals the sub of the portal's token.
The broker redeems the refresh token immediately to prove it works, then saves the connection encrypted.

The browser only ever carries an opaque reference. The Microsoft token response travels PF to broker, never through the portal or the user agent.

Binding by subject, not by email

The most important check is step 7. A pickup whose subject differs from the calling user's sub is rejected. Connections are bound to the authenticated canonical subject and never to an email address or UPN, which are mutable and attacker-influenced in many directories.

Link intents add more guardrails:

one-use and owner-bound
a new intent cancels the previous one
completion consumes the intent before pickup, so a failed or replayed attempt can't be retried

Scope allowlisting at import

When a connection is imported (and on every refresh), the broker inspects the granted scopes. Both read scopes must be present. OIDC scopes and User.Read are tolerated. Anything else, including broader reads or any write scope, is rejected, and a scope escalation marks the connection reconnect_required with its tokens cleared.

A note on honesty

The Terraform in the repo provisions most of this, but the PingFederate provider doesn't yet expose an SP token-generator resource, so part of the handoff is manual. The live PF/Entra path is also not verified end to end. Part 5 covers exactly what is and isn't proven.

Next: how the agent side works, with PingFederate introspection and the delegation model.

DEV Community: DarkEdges

Step-up MFA, attenuation, and what's honestly not done

1. Why the write was refused

The gotcha in trusting

2. Step-up: an attestation as a third-party block

The honest part: PingFederate isn't the attestor yet

3. Attenuation: narrowing without asking

4. Revocation and certificate binding

What is not proven

Back to the Trust Lab's list

Wrapping up

Configuring PingFederate token exchange with Terraform, and testing it end to end

1. The stack

2. What Terraform creates

Validating the subject token

The processor policy: what PingFederate lets through

3. The provider gap: restapi for two objects

4. Smaller things worth knowing

5. Testing it end to end

Without a browser

Next

Building a PingFederate token generator that mints Biscuits

1. The SDK contract

2. Attributes in, facts out, and never as strings

3. The fact names a minter must refuse

4. Checks that bind the token

5. Getting the output right: what I disassembled

6. Keys and rotation

7. Packaging: shading, and building against the image

8. Tests and an interop check

Next

Who mints the first Biscuit? PingFederate, token exchange and a hybrid model

Two token models, two strengths

The hybrid: JWTs at the edge, Biscuits inside

Why this works as a hybrid

Bridging back to the Trust Lab

What's inside PingFederate

What this doesn't do

Next

Credits without a mutable token: reservations, idempotency and receipts

darkedges / biscuit-trust-lab

An interactive Cloudflare Pages playground for exploring Biscuit delegation, Datalog authorization, trust between independent operators, and shared clearinghouse billing.

Relay — Biscuit network lab

Run locally

Deploy to Cloudflare Pages

Why the balance isn't in the token

Reserve → execute → settle (or release)

Serializing reservations in single-threaded JavaScript

The competing-reservations scenario

Idempotency: retries don't double-charge

Receipts: settle only what the provider claims it completed

The operation-failure scenario

Running it on Cloudflare Pages

What a production version would need

Wrapping up

Local policy, shared facts: the receiver's Datalog authorizer

darkedges / biscuit-trust-lab

An interactive Cloudflare Pages playground for exploring Biscuit delegation, Datalog authorization, trust between independent operators, and shared clearinghouse billing.

Relay — Biscuit network lab

Run locally

Deploy to Cloudflare Pages

One policy, four sources of facts

Building the authorizer

Reading the decision

How each scenario fails

Change payer

Forbidden operation

Missing caller trust

Requester not accepted

Untrusted issuer

Two authorization boundaries

Next

Attenuating Biscuit tokens and signing the delegation chain

darkedges / biscuit-trust-lab

An interactive Cloudflare Pages playground for exploring Biscuit delegation, Datalog authorization, trust between independent operators, and shared clearinghouse billing.

Relay — Biscuit network lab

Run locally

Deploy to Cloudflare Pages

Minting the root grant

Attenuating at each hop

The gotcha in `trusting`

3. The provider gap: `restapi` for two objects