DEV Community: DarkEdges

Custom ID-JAG on PingFederate, Part 4: Testing Live Issuance Without Overclaiming

DarkEdges — Mon, 07 Sep 2026 07:54:58 +0000

A successful token response is useful evidence. It is not the whole test.

For this custom PingFederate ID-JAG implementation, we wanted to know whether the server would reject the requests it should reject, whether the assertion could be verified independently, and whether Terraform still matched the running configuration afterward.

The live runner passed 27 checks on a server reporting version 12.3.3.1. This final part explains what those checks mean and what they leave open.

Code for this series: project repository.

Four kinds of evidence, kept separate

The project has four test layers:

26 Java offline checks, including signing and selected real PF parser, selector and serializer classes.
24 Node tests covering client protocol behavior and verification with local RSA fixtures.
Four Terraform tests using mocked providers to check configuration restrictions.
27 live HTTP checks against the running PingFederate token and JWKS endpoints.

The Java tests use the real 12.3.3 libraries but do not start an HTTP server. Some selected internal behavior is exercised reflectively in test code only. The deployed plugin does not use reflection.

The Node client tests include mocked responses. The Terraform tests do not configure a real server.

Only the live runner establishes that the installed plugin, configured policies, client authentication, request mappings and managed signing keys worked together on the running server.

Reproduce the issuing-side lab

The repository contains the complete implementation; the following commands assume you are running from its root.

First, build with a local PF 12.3.3 installation:

.\generator\build.ps1 -PfInstallDir C:\path\to\pingfederate\12.3.3
node --test

The build script runs the standalone Java proof suite. Maven packaging is also supported, but Maven does not execute that standalone suite automatically.

Deploy the resulting JAR to the test server's server/default/deploy directory and restart it. Wait for the Admin API to become ready and confirm that the custom generator descriptor appears.

Next, create the local subject fixture:

node scripts/create-local-fixture.mjs

This creates a disposable subject-signing key and two independent client secrets under the ignored .local/ directory. Repeat runs preserve existing keys and secrets.

The subject issuer is a reserved example-domain identifier. Its public JWKS is explicitly configured in the JWT processor. This is a controlled test fixture, not an identity provider completing a real login.

Follow the Terraform guide to supply administrator credentials, initialize the providers, inspect a plan and apply it. Do not copy administrator passwords into source files or published commands.

Then run:

node scripts/live-local-proof.mjs

The runner is deliberately restricted to the local runtime endpoint. It does not send fixture credentials to a downstream example domain.

Verify the assertion, not just the HTTP status

The positive exchange checks that the response uses the ID-JAG token-type URI and token_type equals N_A.

The runner then fetches the configured PF JWKS and verifies the compact JWS signature. It checks the expected signing algorithm, JWT type, key identifier, issuer, audience, client, resource, scope and lifetime, along with subject and replay-identifier presence.

An additional check confirms that the issued subject is the authorized fixture subject. The response expiry must be positive and no greater than 300 seconds.

These checks distinguish a parseable token from an assertion whose signature and intended bindings have actually been verified.

An example JWT is returned.

Issued ID-JAG
Header
{
  "alg": "RS256",
  "typ": "oauth-id-jag+jwt",
  "kid": "IhqVmmqnFs0necq8KJgwg-W_8UY_RS256"
}
Body
{
  "iss": "https://localhost:9031",
  "sub": "xaa-test-user",
  "aud": "https://target.example.test",
  "client_id": "target-client",
  "resource": "https://api.example.test/reports",
  "scope": "read:reports",
  "iat": 1788766854,
  "exp": 1788767154,
  "jti": "1847e9eb-b727-4372-aade-bd6b6bc10704"
}
Signature: present, not displayed

Exercise the rejection paths

The live suite sends subject tokens with the wrong issuer, wrong audience, wrong authorized party and unauthorized subject. It also tests an absent authorized party, expired tokens, missing expiry, multiple subject audiences and a modified signature.

At the request layer, it tests missing and duplicate audience, resource and scope parameters, as well as unauthorized destinations, scopes and requested token types.

At the client-authentication layer, it tests missing credentials, an incorrect secret and an authentication attempt using the disabled compatibility client.

All of those cases were rejected. The runner requires an appropriate error status and OAuth error response without an issued access token; it does not claim that every rejection came from the custom generator. Several should fail earlier in PingFederate's pipeline.

No subject token, issued assertion or client secret is printed by the runner. It reports check names and a summary. Keep server-side diagnostics protected too.

Recheck the managed configuration

After the live run, Terraform refreshed the eight managed resources and reported:

No changes. Your infrastructure matches the configuration.

The detailed exit code was zero.

That establishes a clean post-apply plan for this configuration. It does not establish import behavior, every possible drift-recovery case, or a tested disaster-recovery process.

Preserve the state and fixture inputs for the lab. Losing state and applying again to the same server is not a safe substitute for importing the existing resources.

The work that remains

This proof stops at issuing and independently verifying an ID-JAG.

Real OIDC login must still be connected to the intended issuer. Subject resolution and authorization need production policy rather than one allowed fixture user.

The downstream authorization server must be configured to trust the issuer and enforce the agreed assertion profile, authenticated client binding, resource and scope authorization, and replay handling. It must actually issue an access token before the full application-to-API path can be claimed as working.

Multi-node deployment, key rotation behavior and broader profile conformance also need testing. The target URLs in this lab are examples, not deployed services.

A useful result with a clear boundary

The result is specific and reproducible: a custom generator on the tested PingFederate 12.3.3.1 server issued an ID-JAG using PF-managed keys, its signature verified against the live JWKS, 27 HTTP checks passed, and Terraform's post-apply plan was clean.

That is enough to establish the issuing-side extension path as viable. It is not a reason to skip the remaining trust, authorization and receiving-side work.

Custom ID-JAG on PingFederate, Part 3: Managing the Integration with Terraform

DarkEdges — Mon, 07 Sep 2026 07:54:22 +0000

Once the custom ID-JAG generator worked, the next requirement was to make its PingFederate configuration repeatable.

The goal was not just to automate a sequence of API calls. We wanted Terraform to own identifiable resources, refresh their state and produce a reviewable plan.

The result manages eight resources on the local server reporting PingFederate 12.3.3.1. After apply, a follow-up plan returned no changes.

Code for this series: project repository.

Separate plugin deployment from configuration

Terraform configures the installed plugin. It does not deploy the JAR in this project.

The Java build produces xaa-id-jag-generator.jar. That file must be placed in the server's server/default/deploy directory, followed by a restart and verification that the Admin API discovers its descriptor.

The live test used a copy into the named local container. The repository also includes an optional Compose overlay for a read-only JAR mount. That overlay was syntax-checked, but it was not the deployment mechanism used for the successful live run.

Keeping these steps separate makes the dependency visible: an API resource cannot configure a plugin that the server has not loaded.

Check the provider schema, not only its examples

We pinned these provider versions:

terraform {
  required_version = ">= 1.10, < 2.0"
  required_providers {
    pingfederate = {
      source  = "pingidentity/pingfederate"
      version = "1.9.0"
    }
    restapi = {
      source  = "Mastercard/restapi"
      version = "3.0.0"
    }
  }
}

Inspection of the installed Ping provider schema confirmed that version 1.9.0 does not implement token-generator instances or token-exchange generator groups, despite references to those resources in some examples.

The provider does implement the JWT processor, exchange policy, OAuth clients and generator mapping we needed. We used it for those resources.

For the missing resources, we used the REST provider against the actual Admin API. Its object resource supports resource lifecycle operations and refresh, rather than just running a command during apply.

This split is specific to the pinned versions. Recheck the schema before assuming the same gap exists in a future release.

The eight resources

The complete configuration manages:

A JWT Token Processor 2.0 instance for the trusted subject issuer.
A Token Exchange Processor Policy with subject and azp issuance criteria.
A confidential requesting client restricted to token exchange and the approved scope.
A disabled compatibility client whose ID is the downstream issuer URL.
The custom ID-JAG generator instance.
A resource-selected generator group.
The policy-to-generator attribute mapping.
One common scope entry.

The REST provider owns the generator, generator group and individual scope entry. Everything else uses the Ping provider.

Managing the scope individually avoids taking ownership of the entire authorization-server settings object. We did not change global expression settings, global key configuration or the global default generator group.

Model the real API resources

The generator-group excerpt looks like this:

resource "restapi_object" "generator_group" {
  path                    = "/oauth/tokenExchange/generator/groups"
  ignore_server_additions = true

  data = jsonencode({
    id           = "xaaGroup"
    name         = "XAA explicit resource routing"
    resourceUris = [var.target_resource]
    generatorMappings = [{
      requestedTokenType = "urn:ietf:params:oauth:token-type:id-jag"
      tokenGenerator     = { id = restapi_object.generator.id }
      defaultMapping     = true
    }]
  })
}

The group depends on the generator's resource ID. Its mapping is the default within this group, which the live API required. The group itself is not a global default.

ignore_server_additions accommodates server-added fields. It is not ignore_all_server_changes; the configuration should still own the fields it explicitly sets. The observed post-apply result was a clean plan, not a comprehensive test of every possible drift scenario.

Keep the administrator password out of state

The administrator password is a sensitive, ephemeral input:

variable "admin_password" {
  type      = string
  sensitive = true
  ephemeral = true
}

The provider uses it for authentication. A check of the resulting state confirmed that the supplied administrator password was absent.

OAuth client secrets are different. They are resource inputs and are stored in state. Marking them sensitive hides their normal display; it does not encrypt the state file.

The local fixture files and state are ignored by Git. Shared use still needs an encrypted, access-controlled backend, appropriate secret injection and protected local files. A Git ignore rule is not a security boundary.

TLS verification defaults to enabled. The disposable localhost fixture explicitly opts into a localhost-only certificate exception. Remote configurations must use a trusted certificate or a configured CA file.

Plan before applying

From the repository root, with provider credentials supplied through the documented environment variables:

terraform '-chdir=terraform' init -input=false
terraform '-chdir=terraform' validate
terraform '-chdir=terraform' plan '-var-file=../.local/local.tfvars.json' '-out=../.local/xaa.tfplan'

Inspect the plan before applying the saved file. On our fresh test server, the initial plan contained eight additions and no existing-resource updates or deletions.

The first apply exposed server validation requirements described in Part 2. Terraform retained the successfully created resources in state, and the corrected plan completed the remaining configuration. We did not discard state and start creating duplicate objects.

After the successful apply, plan -detailed-exitcode returned zero with no changes. Four mocked Terraform tests also passed, checking the restricted configuration and rejecting remote TLS bypass, private JWKS input and shared client secrets.

Those tests do not prove token issuance. Part 4 covers the separate live runner, the evidence it produced and the work that remains before this could become a production integration.

Custom ID-JAG on PingFederate, Part 2: Building the Generator and Handling Runtime Constraints

DarkEdges — Mon, 07 Sep 2026 07:53:48 +0000

The signing code was only one part of getting a custom ID-JAG generator working on PingFederate 12.3.3.1.

The more revealing work was discovering what the token-exchange pipeline validates before calling the generator, and what it actually passes into the plugin.

This article describes the implementation that passed the live local proof. It issues an assertion for one fixed destination. It does not configure downstream redemption.

Code for this series: project repository.

Start with a small, explicit contract

The final generator receives six mapped attributes:

sub: the validated subject carried through the exchange policy.
subject_client_id: the validated subject token's audience.
subject_exp: the validated subject token's expiry in Unix seconds.
approved_scope: scopes authorized by the trusted policy.
authenticated_client_id: PingFederate's authenticated client context.
http_request: PingFederate's actual servlet request context object.

There is an important separation here. The HTTP request supplies the requested destination and scope, but it does not establish who the client is. Client identity comes from the server's authenticated context.

We also found that this 12.3.3 token-generator exchange path creates a TokenContext without populating its input parameters. Relying on getInParameters() for authentication or routing information would have been incorrect. The implementation uses explicitly mapped subject attributes instead.

Read request parameters without enabling expressions

The first configuration attempted expression-based mappings for audience, resource and scope. The running server rejected those mappings.

Instead of enabling expressions globally, the final mapping passes Context HttpRequest directly to the plugin. The generator extracts the underlying HttpServletRequest object and validates its parameters in Java.

The essential helper is:

private static String parameter(HttpServletRequest request, String name) {
    String[] values = request.getParameterValues(name);
    if (values == null || values.length != 1) {
        throw new IllegalArgumentException(
                "Missing or repeated request parameter: " + name);
    }
    return nonempty(values[0]);
}

nonempty() also rejects blank values and control characters. This is an excerpt from the plugin, not a standalone implementation.

Using getParameterValues() matters. Selecting only the first value could hide duplicate parameters. The live suite confirmed rejection of repeated audience, resource and scope parameters, including repeated identical values.

This is a deliberately strict request profile. Do not assume that accepting multiple resources or audiences can be added without revisiting the policy.

Bind the caller to the subject token

The generator compares both authenticated_client_id and subject_client_id with the configured requesting client.

The JWT processor validates the subject token's audience. The policy additionally requires azp to match the requesting client and sub to match the authorized test subject.

Our proof requires azp even when an intended real issuer might omit it. That is a restriction of this implementation, not a claim that every ID token must contain the claim. Real issuer integration needs an explicit review of those semantics.

Treat approved scope as authorization data

The requested scopes must be contained in both the generator's configured scope ceiling and the policy-provided approved_scope set.

Copying the incoming scope directly into approved_scope would defeat that check.

In this lab, the approved scope is a fixed value behind issuance criteria for one authorized subject and client. Production deployment needs a real entitlement decision for the user, client and destination.

Satisfy the audience check before the generator

The live server validates each token-exchange audience as a local OAuth client ID. An unknown value fails before the custom generator can run.

Our outgoing assertion needs the target authorization-server issuer as its audience. To preserve that value, we created a local compatibility registration whose client ID is exactly:

https://target.example.test

This is not the requesting client and not the client registration at the downstream server.

The compatibility client remains disabled. It has an independent unused secret and only the ACCESS_TOKEN_VALIDATION grant, because the Terraform provider requires a nonempty grant list.

Two live checks established the boundary: issuance succeeded with that registration disabled, and an authentication attempt using it was rejected. This is observed behavior of the tested server, not a blanket compatibility promise for every PF version.

Route by resource and sign with managed keys

The generator group maps the exact resource URI to the ID-JAG requested token type. PingFederate required one default mapping inside the group. We configured that mapping without making the group a global default.

The plugin gets the current RS256 key through the public SDK accessor:

JwksEndpointKeyAccessor.newInstance().getCurrentRsaKey("RS256")

It signs with typ set to oauth-id-jag+jwt, includes the key's kid, and creates a fresh jti. Expiry is the earlier of the configured lifetime and the validated subject-token expiry.

The compact JWT is returned as a StringSecurityToken. The live server preserved that string without an additional Base64 wrapper, and the signature verified against its published JWKS.

Generating a unique jti is not replay prevention. The receiver still needs to enforce replay handling when the assertion is redeemed.

Keep the remaining boundary visible

This implementation validated the issuing side with a locally trusted subject fixture. Real issuer login, downstream acceptance, production entitlements and multi-node behavior remain separate work.

Part 3 makes the working configuration repeatable with Terraform, including the resources that the pinned Ping provider does not expose directly.

Custom ID-JAG on PingFederate, Part 1: Can PingFederate 12.3.3 Issue an ID-JAG?

DarkEdges — Mon, 07 Sep 2026 07:52:59 +0000

PF ID-JAG: Can PingFederate 12.3.3 issue an ID-JAG through a custom token generator?

For the fixed-destination proof described here, the answer is yes. A live PingFederate server returned the assertion, and its signature verified against that server's published JWKS.

That result matters, but so does its boundary. It is not evidence that an arbitrary application can accept the assertion, that a complete Cross-App Access deployment exists, or that the implementation conforms to every requirement of the evolving specification.

This series follows the path from inspecting the extension points to applying Terraform and testing the real token endpoint.

Code for this series: project repository.

What we were trying to build

Cross-App Access, or XAA, is the pattern described by the Identity Assertion JWT Authorization Grant draft. An application obtains an ID-JAG through token exchange, then presents that assertion to a downstream authorization server to request an access token. The draft connects OAuth token exchange with the JWT authorization grant flow. This project uses draft-04 as its reference, not a finalized standard.

Our implementation focuses on the first exchange. The intended sequence is:

The requesting client authenticates to PingFederate and supplies a subject token.
PingFederate validates the token and applies an authorization policy.
A custom generator issues an ID-JAG for a fixed downstream destination.
The application would redeem that assertion at the downstream authorization server.

Only the first three steps were exercised against the live server. Step four remains integration work.

Missing native support was not the same as a missing extension path

An early assumption in this project was that a generic JWT access-token flow would be the practical substitute. That assumption did not survive inspection of the actual 12.3.3 classes.

The relevant question was more precise: could the token-exchange pipeline route a custom requested token type to a token generator and preserve its output?

The Java extension point exposes:

SecurityToken generateToken(TokenContext context)

The server also has token-exchange generator groups and mappings. Ping's generator-group documentation describes associating requested token types with generator instances and routing requests using resource URIs.

We inspected and exercised the request parser, resource selector, generator mapping and response serializer from the actual local installation. That established an offline path worth testing on a running server.

It did not establish a working deployment yet. Client authentication, plugin discovery, attribute mappings and key retrieval still had to work together.

The token processor and generator have different jobs

The implementation uses the built-in JWT Token Processor 2.0 for inbound validation and a custom Java generator for outbound issuance.

The processor validates the configured issuer, signature, audience and time claims. A Token Exchange Processor Policy then restricts the allowed subject and checks the authorized-party claim, azp.

The generator checks the authenticated client, destination, scope and remaining subject-token lifetime before signing the outgoing assertion.

This division is important. Producing a signed JWT does not establish that its subject is authorized to access another application's API. The authorization decision needs a trusted source and an explicit policy.

For the lab, that policy authorizes exactly one test subject. It is intentionally not a substitute for production entitlements.

A deliberately narrow proof

The tested setup has one requesting client, one target authorization-server issuer, one resource, one allowed scope and RS256 signing. Assertion lifetime is capped at 300 seconds and cannot exceed the validated subject token's expiry.

The build uses the PF 12.3.3 installation and SDK. The live Admin API reports version 12.3.3.1.

The inbound token is a locally signed fixture whose public key is explicitly trusted by the JWT processor. That gives us controlled positive and negative tests without pretending to have completed a real OIDC login.

The target issuer and resource use reserved example domains. No downstream authorization server or target client was provisioned by this proof.

What the live result established

The successful response contained the unchanged compact JWT in access_token, the ID-JAG URI in issued_token_type, token_type set to N_A, and a bounded expires_in value.

The runner verified the signature using PingFederate's live JWKS endpoint. It also checked the intended subject, issuer, destination, client, resource and scope.

Across the live run, 27 checks passed. Those included rejection cases, not just successful issuance. The detailed test coverage is the subject of Part 4.

The lesson

There is a useful distinction between a product feature being available out of the box and a product having extension points capable of implementing a constrained version of it.

For this server, the custom-generator path was viable. Getting it to work required understanding the validation that happens before the generator, the attributes that actually reach it and the format the server returns afterward.

Part 2 covers those runtime details, including an audience lookup that initially looked unrelated to the outgoing assertion and a way to avoid expression-based request mappings.

Building One Tap for PingFederate, Part 3: An Automated Narrated Demo Video

DarkEdges — Sun, 30 Aug 2026 10:55:36 +0000

Authentication demonstrations are difficult to record reliably. A live flow
depends on cookies, existing sessions, certificate trust, test passwords, and
network timing. It can also expose credentials or tokens in a recording.

For this project, I built a deterministic presentation that explains the real
behavior without depending on live secrets. The implementation is available at
github.com/darkedges/pingfedonetap.

The storyboard

The 16:9 tour contains six timed scenes:

A fresh visitor sees no unsolicited account popup.
The visitor starts an interactive PingFederate login.
The OIDC callback establishes the application session.
Application-only logout clears local state.
The chooser displays two remembered accounts.
Selecting the second account reuses the PingFederate session without a password prompt.

The presentation uses mock credentials and token summaries. It demonstrates
state transitions but never handles a real password, authorization code, or
token.

make demo-tour

The page supports autoplay, looping, playback speed, hidden controls, Space to
pause, and R to restart. This makes it useful both for rehearsal and automated
capture.

Generate a timed AI voiceover

The narration uses the Apache-2.0 licensed hexgrad/Kokoro-82M model from
Hugging Face. The selected af_heart voice is clear for short technical
narration.

The source script is a JSON file with a start time, scene label, and sentence
for each cue. The generator synthesizes every sentence, measures its actual
duration, and fails if it would overlap the next cue.

make voiceover

The output is:

artifacts/one-tap-demo-voiceover.wav

Solving PyTorch memory growth

An early implementation kept one Kokoro pipeline alive while generating all
six sentences. On a constrained Windows development machine, CPU memory grew
until PyTorch failed during a later cue.

The final generator starts one worker process per cue. Each worker loads the
model, writes a temporary floating-point WAV, and exits. Process termination
returns PyTorch's working memory to the operating system before the next cue
starts. The parent process then validates timing and mixes the small audio
segments into a 34-second, 24 kHz PCM WAV.

This approach is slower, but its memory behavior is predictable.

Record the browser automatically

Playwright opens a headless Chromium context with both viewport and recording
size fixed at 1280 x 720. Autoplay is disabled so the recorder controls the
exact start.

The capture process:

Opens the presentation and verifies the stage dimensions.
Waits for the page to settle.
Presses R to start the tour.
Waits until the tour marks the final scene complete.
Holds the final signed-in frame until the 34-second narration ends.
Closes the browser context so Playwright finalizes the WebM.
Trims browser setup frames.

Mux a delivery-ready MP4

The project uses imageio-ffmpeg, whose platform wheel includes an FFmpeg
executable. FFmpeg converts the silent VP8 WebM to H.264 and adds the WAV as AAC
audio.

The complete pipeline is one command:

make demo-video

It produces:

artifacts/one-tap-demo-screen.webm
artifacts/one-tap-demo-final.mp4

The final file is 1280 x 720, 30 frames per second, 34 seconds long, with H.264
video, AAC audio, and the MP4 metadata moved to the front for progressive web
playback.

Why keep the deterministic tour separate

The narrated presentation is not a replacement for integration tests. The live
demo still verifies the adapter endpoint, cookie decoding, OIDC callback, PKCE,
and session behavior. The deterministic tour has a different purpose: it makes
the explanation repeatable, safe to publish, and easy to regenerate after a UI
change.

That separation produced a better test tool and a better communication tool.

Repository: https://github.com/darkedges/pingfedonetap

Watch the published demo: https://youtu.be/KuVNjWiZrAk

Playwright #Python #AI #FFmpeg #PingFederate #DevOps

Building One Tap for PingFederate, Part 2: Docker, Terraform, and OIDC with PKCE

DarkEdges — Sun, 30 Aug 2026 10:54:04 +0000

The account chooser needs more than a widget and a Java adapter. PingFederate
must have a complete authentication policy, a credential validator, a reusable
authentication session, and an OIDC client. This article makes that environment
repeatable with Docker, Terraform, and Make.

Source: github.com/darkedges/pingfedonetap

Bake the adapter into the PingFederate image

The Maven build produces the adapter JAR. A PowerShell staging script creates a
server profile overlay with this structure:

docker/pingfederate-profile/
  instance/server/default/
    deploy/one-tap-status-adapter.jar
    conf/template/one-tap-status-template.html
    conf/language-packs/one-tap-status-template.properties

The Dockerfile copies that overlay to /opt/in/ in the official
PingFederate image. At startup, the Ping container downloads Ping Identity's
getting-started profile and merges the local overlay into the runtime under
/opt/out/instance.

The important point is that the JAR is part of the image input. It is not
copied manually into a running container.

make docker-image

Keep license credentials out of source

The container obtains its development license at startup. Put the Ping DevOps
credentials in environment variables or an ignored .env file:

PING_IDENTITY_DEVOPS_USER=replace-me
PING_IDENTITY_DEVOPS_KEY=replace-me
ONE_TAP_ALLOWED_ORIGINS=http://localhost:8080

Do not commit these values. The credentials are needed when the container
starts, not when the image is built.

make docker-up
make docker-logs

Provision the authentication chain

The Terraform configuration creates:

A Simple Username Password Credential Validator for disposable test users.
An HTML Form IdP Adapter backed by that validator.
An Identifier First Adapter that remembers up to five identifiers for 30 days.
The custom One Tap status adapter with an exact origin allowlist.
An enabled IdP authentication policy.
An authentication-session policy for the HTML Form adapter.
OAuth and OIDC mappings.
A public OIDC client restricted to Authorization Code with PKCE.

The interactive policy is intentionally simple:

Identifier First
  Success: pass subject as incoming username
    HTML Form
      Success: complete authentication
      Failure: fail
  Failure: fail

The status adapter is not part of this tree. Adding a status-only adapter to the
interactive policy would leave authentication in progress and prevent the flow
from completing.

Why the authentication-session policy matters

Remembering an identifier does not remove the password requirement. The HTML
Form adapter must also have a reusable PingFederate authentication session.

The local policy uses:

Persistent session: true
Idle timeout: 60 minutes
Maximum timeout: 480 minutes
Device type: private

After the first successful password authentication, a later OIDC request can
reuse this session. That is what lets the remembered-account selection finish
without prompting for the password again.

Configure a browser public client correctly

The demo client uses these settings:

Client ID: one-tap-demo
Grant: Authorization Code
Client authentication: none
PKCE: required
Scope: openid
Redirect URI: http://localhost:8080/callback.html

Redirect URIs are exact matches. A different port, path, or trailing slash must
be registered explicitly.

The callback validates the OIDC state and exchanges the code with the PKCE
verifier. The demo shows only a sanitized result and does not retain the code,
verifier, access token, or ID token.

Apply the configuration

Ping DevOps license credentials and Terraform administrative credentials are
different concerns. Set the provider credentials in the current shell, then
use an ignored terraform.tfvars for test users and local options.

make terraform-init
make terraform-plan
make terraform-apply
make demo-up

Open http://localhost:8080 after trusting the local development certificate
for https://localhost:9031.

Production boundaries

This environment is a local demonstration. For a real deployment:

Store Terraform state in an encrypted, access-controlled backend.
Use an enterprise credential validator rather than local test users.
Remove development TLS trust overrides.
Validate ID token signatures and claims in a backend.
Use production origins and exact redirect URIs.
Define explicit identity provider logout behavior separately from application logout.

In part 3, we will turn the working flow into a deterministic narrated video
with Kokoro, Playwright, and FFmpeg.

Repository: https://github.com/darkedges/pingfedonetap

Video demo: https://youtu.be/KuVNjWiZrAk

Terraform #Docker #OIDC #PingFederate #DevOps

Building One Tap for PingFederate, Part 1: Architecture and the Secure Account Bridge

DarkEdges — Sun, 30 Aug 2026 10:53:15 +0000

Modern sign-in experiences often remember accounts and let a returning user
continue with one click. Reproducing that pattern with PingFederate requires
more than drawing an account picker. The browser, PingFederate, and the web
application each own different state, and treating those states as one session
causes repeated password prompts, stale panels, and broken logout behavior.

This series explains a working local implementation for PingFederate 12.3.3.
The complete source is available at
github.com/darkedges/pingfedonetap.

The behavior we want

The target experience has four rules:

A new visitor with no remembered identifier should not see a popup.
The first sign-in should use the normal PingFederate authentication policy.
A valid PingFederate session should let a remembered account continue without another password prompt.
Logging out of the demo application should clear only the application session, then allow the account picker to appear again.

The important distinction is that a remembered account is not automatically a
passwordless account. The account chooser answers "who might sign in?" A valid
PingFederate authentication session answers "has this user already proved who
they are?" The application session answers "is this browser tab currently
signed in to this application?"

The three state owners

Web application
  Owns the local signed-in state and OIDC callback result

PingFederate authentication session
  Determines whether another password challenge is necessary

Identifier First adapter cookie
  Remembers identifiers that completed authentication successfully

These states must be coordinated, not merged.

When the application receives tokens, it suppresses the chooser and hides its
sign-in button. When the user selects "Log out of demo," the application clears
its own state and resumes the chooser. It deliberately does not terminate the
PingFederate session. That is why selecting a remembered account can complete
silently after application logout.

Why the browser cannot simply read the account cookie

PingFederate's Identifier First adapter owns a persistent HttpOnly cookie named
identifierFirstAdapter.previous.subjects. HttpOnly is correct because page
JavaScript should not read authentication cookies.

The demo runs at http://localhost:8080, while PingFederate runs at
https://localhost:9031. The application is also on a different origin, so it
cannot inspect PingFederate cookies directly.

The solution introduces a small status-only PingFederate adapter. It runs on
the PingFederate origin, reads the native Identifier First cookie, and returns a
sanitized list through an origin-restricted iframe bridge. The browser widget
renders the chooser only when that list contains accounts.

Demo application
  |
  | hidden sandboxed iframe with nonce
  v
PingFederate /ext/one-tap/status
  |
  | reads HttpOnly Identifier First cookie
  v
Allowed parent origin receives sanitized users via postMessage

Authentication flow

The first login uses an OIDC Authorization Code flow with PKCE:

The application sends the browser to PingFederate.
Identifier First collects or selects the identifier.
The HTML Form adapter validates the password.
PingFederate records the successful identifier and establishes its session.
The callback validates state and exchanges the code with PKCE.
The application marks itself signed in and suppresses the account chooser.

For a remembered account, the widget first attempts authorization with
prompt=none. If PingFederate can reuse its session, tokens return without a
password prompt. If silent authentication cannot complete, the widget falls
back to an interactive top-level request without forcing prompt=login.

Build the status bridge

The custom OneTapStatusAdapter registers this extension endpoint:

/ext/one-tap/status

The widget loads the endpoint in a hidden iframe. The adapter reads the cookie
server-side and renders a small Velocity template. That template sends a
sanitized account array to the parent with window.parent.postMessage().

The endpoint is status-only. It is not inserted into the interactive
authentication policy and remains separate from the Identifier First and HTML
Form sequence.

Decode the native cookie

The Identifier First cookie contains a URL-encoded, comma-separated list of
Base64-encoded identifiers. The adapter decodes each value and returns display
objects. It never returns passwords, tokens, or the raw cookie.

Supporting PingFederate's native representation was important. Inventing a
second account cookie would have created another source of identity state and
made lifecycle behavior harder to reason about.

Secure the cross-origin response

A cross-origin account bridge needs several controls working together.

Exact origin allowlist

Configured origins are normalized to a scheme, host, and optional non-default
port. User information, paths, query strings, and fragments are rejected.

The same allowlist controls CORS, CSP, and the permitted postMessage target.

Per-request nonce

The widget generates a random nonce and includes it as pfOtNonce. The adapter
accepts only 32 to 128 hexadecimal characters and echoes the value in the
bridge message.

The parent accepts the response only when the origin, source window, message
type, and nonce all match the iframe request it created.

Sandboxed iframe

The widget creates an invisible iframe with sandbox="allow-scripts". The
bridge can execute its small script, but it cannot submit forms, navigate the
top-level page, or gain broader browser capabilities.

Explicit postMessage target

The bridge never posts to "*". It checks document.referrer against the
allowlist and posts only to an accepted origin. The parent independently
validates the sender origin and nonce.

Narrow framing policy

PingFederate normally emits X-Frame-Options: SAMEORIGIN. That blocks the
intentional cross-origin iframe. The dedicated endpoint removes that header
and replaces it with a narrow policy:

Content-Security-Policy: frame-ancestors http://localhost:8080

It also returns Cache-Control: no-store so account status is not cached.

Avoid the first-request 404

An extension handler registered only when an adapter instance is first used
can return 404 when the widget calls it before any authentication flow has
initialized the adapter.

The implementation registers the handler in the adapter constructor and again
during configuration. The container also provides
ONE_TAP_ALLOWED_ORIGINS during plugin discovery so early registration has a
safe origin policy.

Give the host explicit controls

The browser widget exposes a deliberately small API:

PfOneTap.dismiss();
PfOneTap.suppress();
PfOneTap.resume();
PfOneTap.refresh();
PfOneTap.signIn(username, displayName);

The host calls suppress() after establishing its application session. On
application logout, it calls resume() and refresh() to request fresh status
with a new nonce.

Design and security lessons

Account discovery and authentication are separate concerns.
Application logout and identity provider logout should be separate actions.
A remembered identifier must never be treated as proof of authentication.
Host applications need explicit suppress, resume, and refresh controls for embedded sign-in widgets.
Authorization Code with PKCE is the correct baseline for a browser public client.
Keep the origin allowlist exact and environment-specific.
Never return credentials, tokens, or raw cookie data.
Validate both event.origin and event.source in the parent.
Bind every bridge response to a fresh nonce.
Apply frame-ancestors only to the dedicated bridge endpoint.

In part 2, we will package the adapter with Docker and provision the complete
authentication and OIDC configuration with Terraform.

Repository: https://github.com/darkedges/pingfedonetap

Video demo: https://youtu.be/KuVNjWiZrAk

PingIdentity #PingFederate #OIDC #Authentication #Identity

Trusted AI Agent Transactions, Part 5: End-to-End Proof

DarkEdges — Sun, 23 Aug 2026 23:03:55 +0000

Building and proving the complete request path

The previous articles covered the identity model, PingFederate token exchange, SPIRE workload identity, and PingAuthorize policy. This final part connects them into one testable application path.

The application flow

The browser workbench signs the user in through PingFederate with OAuth 2.0 Authorization Code and PKCE. The application never collects the user's PingFederate password.

After sign-in:

the demo agent receives the user access token
the agent obtains a JWT-SVID from SPIRE
PingFederate, acting as the TTS, exchanges the subject and actor evidence for a short-lived Txn-Token
the agent sends that token in the Txn-Token header while calling the MCP gateway over SPIFFE mTLS
the gateway validates the transaction token and immediate caller
OPA or PingAuthorize evaluates the verified target and tool request
the gateway forwards the unchanged transaction token to the MCP server over mTLS
the MCP server calls the protected API over another authenticated mTLS hop

The original user access token does not travel beyond the exchange. The Txn-Token does not become a browser session token, does not use the Authorization header for internal propagation, and is not rewritten by intermediaries.

A UI that shows evidence without exposing credentials

The workbench uses two-thirds of the screen for service interaction and one-third for a selectable audit trail. Events correlate the same transaction ID across the agent, gateway, MCP server, API, and authorization decision.

Selecting an event can show safe request and response metadata plus decoded, allowlisted token claims. It must not expose raw access tokens, JWT-SVIDs, transaction JWTs, authorization headers, cookies, authorization codes, client secrets, refresh tokens, private keys, or sensitive tool arguments.

Decoded claims are evidence for a human operator, not a new authorization input. Services authorize only after cryptographic validation.

Repository-owned product startup

Both Ping products use digest-pinned images and read-only repository-owned profile overlays.

PingFederate startup builds and tests the custom token processor plugin. Its Terraform configuration remains a separate explicit step.

PingAuthorize starts with a repository-owned deployment package selected during first setup. The package is mounted read-only, and the container joins only the expected local application bridge network.

Secrets, licenses, generated certificates, private keys, Terraform state, and discovery output remain outside Git.

Testing the security statement

The main authorization statement is:

verified transaction context
AND verified immediate caller
AND target policy

The end-to-end suite therefore needs more than a success case. It proves rejection for:

forged logical agent identity
wrong SPIFFE workload
expired transaction token
wrong audience
unapproved MCP target
stolen transaction token presented by the wrong mTLS caller
direct agent-to-API access when only the MCP server is allowed
malformed or contradictory authorization decisions

It also proves that one transaction ID appears across all expected hops and that captured logs contain no raw token material.

The PingFederate clean-bootstrap test goes further by recreating the product on an isolated volume and Terraform state, applying managed TLS, completing a live exchange, rejecting a tampered actor token, and cleaning only its randomly named resources.

The broader lesson

Agent security is not solved by adding an agent_id claim or passing a user token farther downstream. The implementation needs distinct evidence for the user, logical agent, workload, transaction, and immediate caller.

PingFederate provides the controlled delegation boundary. SPIRE proves runtime identity. PingAuthorize evaluates the verified action context. The gateway preserves the boundary between identity verification, routing, and policy enforcement.

Together, they make an agent action explainable and testable: who authorized it, which agent was approved, which workload ran it, why the transaction exists, which service made each call, and which policy allowed or denied the operation.

Previous: Making policy decisions with PingAuthorize

Return to the series index.

GitHub Repository: https://github.com/darkedges/pf-tts

Trusted AI Agent Transactions, Part 4: PingAuthorize Policy Decisions

DarkEdges — Sun, 23 Aug 2026 23:03:22 +0000

Making policy decisions with PingAuthorize

Part 3 established the transaction context and immediate caller identity. Authorization still needs to answer a separate question: may this verified combination invoke this target and tool for this purpose?

PingAuthorize is integrated as a remote policy decision point at the MCP gateway. It does not verify the transaction JWT or the mTLS connection. Those checks happen before policy evaluation.

Only verified input crosses the policy boundary

The gateway constructs a typed policy request from values it has already verified:

user identity
logical agent identity
agent instance identity
original workload SPIFFE ID
immediate caller SPIFFE ID
transaction ID and purpose
scopes
MCP target
tool name

Browser fields and MCP request fields are not trusted as identity evidence. The target and tool come from the gateway's validated route, not an arbitrary policy document supplied by the caller.

A remote `PERMIT` is not enough by itself

The adapter calls a fixed HTTPS /governance-engine endpoint with explicit connection, request, and decision timeouts. It also bounds the response size and requires an exact JSON schema.

An allow result requires all of the following:

policy status is OKAY
AND decision is PERMIT
AND authorised is true
AND no unfulfilled obligatory statement exists

Missing, contradictory, malformed, oversized, timed-out, cancelled, or unavailable responses deny. Unknown JSON fields deny. A PERMIT paired with authorised: false denies. Obligations deny until a named handler is implemented and tested.

TLS verification cannot be disabled, and the PingAuthorize hostname must match its runtime certificate. The policy package is mounted read-only and cannot be loaded from an arbitrary network location.

The policy tuple

The repository-owned deployment package permits only an exact conjunction over the trusted values:

logical agent
AND original workload
AND immediate caller
AND purpose
AND scope
AND target
AND tool

This matters for AI agent integrations because a broad statement such as "this agent may use MCP" is usually too weak. The useful decision is closer to "this approved agent workload, acting for this verified user transaction and purpose, may invoke this tool through this caller path."

OPA and PingAuthorize can share a contract

The Go gateway has a small authorization interface. An in-process OPA adapter is the default local option, while PingAuthorize implements the same typed contract through its JSON PDP API.

That makes the policy engine replaceable without moving identity validation into the policy layer. It also allows the same allow and deny matrix to be tested against both implementations.

What the tests prove

Failure coverage includes:

forged logical agent
wrong workload or immediate caller
missing or ambiguous scope
malformed and oversized decisions
policy errors and unavailable service
unsafe endpoint or disabled TLS validation
unfulfilled obligations
cancellation and timeout

The local live test has also shown an exact tuple returning PERMIT and a forged logical agent returning NOT_APPLICABLE over certificate-validated HTTPS.

Previous: Binding a logical agent to a real workload with SPIRE

Next: Building and proving the complete request path

GitHub Repository: https://github.com/darkedges/pf-tts

Trusted AI Agent Transactions, Part 3: SPIRE Workload Identity

DarkEdges — Sun, 23 Aug 2026 23:02:55 +0000

Binding a logical agent to a real workload with SPIRE

Part 2 used a SPIRE JWT-SVID as the actor token in PingFederate token exchange. That proves more than a caller-supplied agent name, but it helps to understand exactly what it proves.

A logical agent describes an approved application role. A SPIFFE ID identifies an attested running workload. They are related, but they are not interchangeable.

AgentID:  urn:agent:customer-support
SPIFFEID: spiffe://example.org/agent/customer-support

The first is a policy identity. The second is a cryptographically attested runtime identity.

Two SVID formats, two jobs

The implementation uses both SPIRE credential formats:

JWT-SVID authenticates the agent to PingFederate during RFC 8693 token exchange
X.509-SVID authenticates workload-to-workload connections with mTLS

The JWT-SVID uses an audience dedicated to the PingFederate Transaction Token Service integration. The Txn-Token audience identifies the trust domain in which the call chain is valid. The protected target and tool belong in transaction context and authorization policy. Reusing the actor-token audience for the Txn-Token would blur two distinct trust boundaries.

Immediate caller identity changes at every hop

The transaction token remains unchanged through the request path, but the immediate caller changes:

Agent -> Gateway:     caller is the agent SPIFFE ID
Gateway -> MCP:       caller is the gateway SPIFFE ID
MCP -> Protected API: caller is the MCP server SPIFFE ID

This lets the protected API reject a direct agent call even if the agent possesses a valid transaction token. The API can require the verified transaction context and the expected MCP server identity on the current mTLS connection.

Local development without making lab shortcuts production policy

The Docker lab runs a SPIRE Server and Agent and uses Docker workload attestation. Each workload has a distinct label and registration entry:

wai.workload=demo-agent
wai.workload=mcp-gateway
wai.workload=demo-mcp-server
wai.workload=demo-api

Those selectors produce separate SPIFFE IDs. Mounting the Workload API socket does not let a container choose an identity. SPIRE observes the calling workload and matches its external selectors to a registered entry.

The lab uses a join token to bootstrap the SPIRE Agent. That is explicitly a development choice. A production deployment should use a node attestor appropriate to its environment, such as cloud instance identity, Kubernetes PSAT, X.509 proof of possession, or hardware-backed attestation.

Rotation and ambiguity

SPIRE signing keys can overlap during normal rotation. The integration accepts multiple JWT authorities only when every entry is explicitly a JWT-SVID authority, uses a unique non-empty key ID, and satisfies the configured key and algorithm constraints.

Unknown key IDs, duplicate IDs, unexpected algorithms, ambiguous identities, missing audiences, and conflicting claims fail closed. The token header is never allowed to choose a newly trusted algorithm dynamically.

The binding rule remains the same throughout: a workload cannot become another logical agent by changing request data.

Previous: Using PingFederate token exchange as the delegation boundary

Next: Making policy decisions with PingAuthorize

GitHub Repository: https://github.com/darkedges/pf-tts

Trusted AI Agent Transactions, Part 2: PingFederate Token Exchange

DarkEdges — Sun, 23 Aug 2026 23:01:49 +0000

Using PingFederate as a Transaction Token Service

Part 1 separated the user, logical agent, runtime workload, agent execution, and transaction identities. This part shows where they are joined safely.

In the Tokenetes architecture, a Transaction Token Service, or TTS, uses the RFC 8693 token exchange protocol to mint a Txn-Token. This implementation assigns that logical role to PingFederate.

The agent sends:

subject_token      = the user's access token
subject_token_type = access token
actor_token        = the agent workload's JWT-SVID
actor_token_type   = JWT
requested_token_type = urn:ietf:params:oauth:token-type:txn_token
audience           = the transaction trust domain
scope              = the narrow purpose of this transaction

The subject token answers who authorized the external invocation. The SPIRE actor token is an agent-specific extension that proves which attested workload is requesting the exchange. Neither token is accepted as a substitute for the other. The base Transaction Tokens profile relies on authenticated TTS clients; this design additionally carries explicit actor evidence so PingFederate can bind a logical AI agent to its runtime workload.

Example subject and actor tokens

The following payloads are illustrative decoded claims. In the implementation, claims are used only after the complete token has passed signature, issuer, audience, algorithm, key ID, and time validation. Raw tokens are never written to application or audit logs.

The subject token is the user's OAuth access token:

{
  "iss": "https://pingfederate.example",
  "sub": "user-123",
  "aud": "wai-agent-token-exchange",
  "scope": "openid profile mcp:invoke",
  "client_id": "wai-browser",
  "iat": 1770000000,
  "exp": 1770000300,
  "jti": "subject-token-id"
}

It represents the authenticated user. It does not prove which agent workload is presenting it, and it is not forwarded to the MCP gateway or downstream services.

The actor token is a JWT-SVID issued by SPIRE to the running agent workload:

{
  "iss": "https://spire.example.org",
  "sub": "spiffe://example.org/agent/demo",
  "aud": [
    "urn:pingfederate:wai:token-exchange"
  ],
  "iat": 1770000000,
  "exp": 1770000060
}

It proves the SPIFFE workload identity to PingFederate. It does not identify the user, and it does not let the workload choose a logical AgentID.

The agent submits both tokens to PingFederate using a form-encoded RFC 8693 request:

POST /as/token.oauth2 HTTP/1.1
Host: pingfederate.example
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=REDACTED_USER_ACCESS_TOKEN
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&actor_token=REDACTED_SPIRE_JWT_SVID
&actor_token_type=urn:ietf:params:oauth:token-type:jwt
&requested_token_type=urn:ietf:params:oauth:token-type:txn_token
&audience=example.org
&scope=mcp:invoke
&request_details=%7B%22target%22%3A%22mcp-gateway%22%2C%22tool%22%3A%22customer.read%22%7D

The values are redacted here intentionally. Tokens belong in the protected request body over validated TLS, never in a URL, log message, audit event, or error response.

What PingFederate validates

The PingFederate Token Exchange Processor Policy validates both sides of the delegation:

the user token processor validates the subject token
the SPIRE processor validates the JWT-SVID signature, issuer, audience, time, key ID, and algorithm
trusted configuration maps the verified SPIFFE ID to a logical AgentID
the policy issues a small, short-lived transaction JWT for the requested audience

The caller never supplies an authoritative logical agent identity. A workload such as spiffe://example.org/agent/demo is mapped to a configured logical agent such as urn:agent:demo inside the trusted policy boundary.

The result is a Txn-Token

After validating the subject and actor independently, PingFederate should issue a short-lived signed JWT conforming to the Transaction Tokens profile. Its protected header identifies it as a Txn-Token:

{
  "typ": "txntoken+jwt",
  "alg": "ES256",
  "kid": "pingfederate-transaction-signing-key"
}

The body carries the immutable transaction context:

{
  "iss": "https://pingfederate.example/transaction-token-service",
  "sub": "user-123",
  "aud": "example.org",
  "scope": "mcp:invoke",
  "txn": "019...",
  "req_wl": "spiffe://example.org/agent/demo",
  "tctx": {
    "target": "mcp-gateway",
    "tool": "customer.read",
    "agent": {
      "id": "urn:agent:demo",
      "instance_id": "019..."
    },
    "workload": {
      "id": "spiffe://example.org/agent/demo"
    }
  },
  "rctx": {
    "authn": "urn:ietf:rfc:6749"
  },
  "iat": 0,
  "exp": 0
}

The response uses the normal OAuth token response shape:

{
  "access_token": "REDACTED_TRANSACTION_JWT",
  "issued_token_type": "urn:ietf:params:oauth:token-type:txn_token",
  "token_type": "N_A"
}

The Txn-Token is not sent in the OAuth Authorization header between internal workloads. It uses its dedicated header:

Txn-Token: REDACTED_TRANSACTION_JWT

The token is not replay resistant, so TLS, its very short lifetime, trust-domain audience validation, and immediate-caller SPIFFE mTLS are all required. The same Txn-Token remains unchanged through the MCP gateway, MCP server, and protected API. Each service validates it before using any decoded claim.

Arbitrary claims are not copied from either input token. The original user access token and actor JWT-SVID stop at the exchange boundary and are not propagated to MCP servers or downstream APIs.

Current implementation status

The repository already implements the difficult security boundaries: RFC 8693 exchange, independent subject and actor validation, workload-to-agent binding, short lifetime, immutable propagation, strict issuer and audience checks, SPIFFE mTLS at each hop, target authorization, and correlated audit.

It currently represents the result with application-specific transaction claims and bearer-token transport. To claim Tokenetes-style Transaction Tokens conformance, it still needs to emit typ: txntoken+jwt, request and return the Transaction Token type URN, map the context to txn, scope, tctx, rctx, and req_wl, use the trust domain as aud, and propagate the JWT in the Txn-Token header. Validation must reject the older application token shape once that migration is enabled.

Terraform and plugin discovery

The reference implementation manages PingFederate with the official Terraform provider. Terraform owns the token processors, token exchange policy, access token manager, mapping, scope, and OAuth client.

Plugin field names are discovered from the running PingFederate version before configuration is generated. This avoids guessing descriptor fields or weakening validation when product versions differ.

Startup and configuration are separate trust operations. The profile starts the pinned product and installs the tested custom plugin. Scope creation and Terraform apply remain explicit operations, so starting a container cannot silently rotate an OAuth client secret or mutate token policy.

Clean bootstrap without committed secrets

The repository-owned profile overlay is mounted read-only. A local generator creates short-lived bootstrap TLS material, datastore credentials, and system keys with cryptographically secure randomness. Those values are written to an ignored local file and never committed.

The clean-volume test then:

starts PingFederate with random test-owned names and ports
validates the bootstrap certificate
applies managed TLS first
reconnects using the new trust anchor
applies the complete Terraform configuration
performs a live token exchange
proves that a tampered actor token is rejected
removes only the exact test-owned resources

This is important because a configuration that only works against a long-lived developer volume is not a reproducible security control.

Previous: The identity problem behind AI agents

Next: Binding a logical agent to a real workload with SPIRE

References: CNCF Tokenetes and the IETF Transaction Tokens draft.

GitHub Repository: https://github.com/darkedges/pf-tts

Trusted AI Agent Transactions, Part 1: The Identity Problem

DarkEdges — Sun, 23 Aug 2026 23:00:58 +0000

The identity problem behind AI agents

An application that calls an API for a user normally answers one identity question: who is the user?

An AI agent introduces several more:

Which user authorized the work?
Which logical agent is acting?
Which running workload actually made the call?
Which agent execution is involved?
Which transaction and purpose does the call belong to?
Which service made the current network hop?

Putting every answer into a single sub claim creates a dangerous illusion. A logical agent name is not cryptographic proof of the running process. A workload identity is not the user. A transaction identifier is not a caller identity.

This implementation keeps five values separate:

UserID: the authenticated human or upstream principal
AgentID: the approved logical agent definition
AgentInstanceID: one execution of that agent
SPIFFEID: the attested runtime workload
TransactionID: the immutable identifier for the delegated action

Why a user access token is not enough

Passing the original user token through every service has three problems.

First, downstream services cannot reliably distinguish the user from the agent acting for the user. Second, a broadly scoped user token may reach systems that never needed it. Third, the token usually says little about the purpose of this specific transaction.

The safer model is the Transaction Tokens architecture implemented by Tokenetes. An external endpoint exchanges the incoming authorization at a controlled Transaction Token Service boundary. The result is a short-lived signed Txn-Token containing immutable identity and authorization context for one call chain.

Why an `agent_id` field is not proof

An HTTP request can claim any agent name. If the server authorizes that value directly, one workload can impersonate another by changing a string.

The logical AgentID must instead come from trusted policy that maps a cryptographically verified workload identity to an approved agent. The caller can request an operation, but it cannot choose its identity.

Immutable context and authenticated hops

The Txn-Token carries immutable delegated context:

user + logical agent + original workload + transaction + purpose

Each network connection independently proves the immediate caller through SPIFFE mTLS:

verified transaction context
AND verified immediate caller
AND target policy

The token is not rewritten at every hop. That avoids giving intermediate services the power to remove or forge earlier context. The same transaction ID can be correlated across the agent, gateway, MCP server, and protected API.

The target flow

User OAuth token
  -> AI agent
  -> PingFederate RFC 8693 token exchange
  -> short-lived transaction JWT
  -> MCP gateway
  -> MCP server
  -> protected API

In this design, PingFederate fills the logical Transaction Token Service role. SPIRE supplies a JWT-SVID as agent workload evidence during exchange and X.509-SVIDs for mTLS between workloads. PingAuthorize evaluates the verified Txn-Token context at the gateway.

Tokenetes is the reference point for the call-chain model: a Txn-Token is minted once for the external invocation, remains immutable as it moves downstream, and is accepted only inside its trust domain. The immediate network caller is still authenticated separately.

The result is not a new identity system. It is a way to combine existing user, workload, delegation, transport, and policy controls without confusing their responsibilities.

Next: Using PingFederate token exchange as the delegation boundary

GitHub Repository: https://github.com/darkedges/pf-tts

DEV Community: DarkEdges

Custom ID-JAG on PingFederate, Part 4: Testing Live Issuance Without Overclaiming

Four kinds of evidence, kept separate

Reproduce the issuing-side lab

Verify the assertion, not just the HTTP status

Exercise the rejection paths

Recheck the managed configuration

The work that remains

A useful result with a clear boundary

Custom ID-JAG on PingFederate, Part 3: Managing the Integration with Terraform

Separate plugin deployment from configuration

Check the provider schema, not only its examples

The eight resources

Model the real API resources

Keep the administrator password out of state

Plan before applying

Custom ID-JAG on PingFederate, Part 2: Building the Generator and Handling Runtime Constraints

Start with a small, explicit contract

Read request parameters without enabling expressions

Bind the caller to the subject token

Treat approved scope as authorization data

Satisfy the audience check before the generator

Route by resource and sign with managed keys

Keep the remaining boundary visible

Custom ID-JAG on PingFederate, Part 1: Can PingFederate 12.3.3 Issue an ID-JAG?

What we were trying to build

Missing native support was not the same as a missing extension path

The token processor and generator have different jobs

A deliberately narrow proof

What the live result established

The lesson

Building One Tap for PingFederate, Part 3: An Automated Narrated Demo Video

The storyboard

Generate a timed AI voiceover

Solving PyTorch memory growth

Record the browser automatically

Mux a delivery-ready MP4

Why keep the deterministic tour separate

Playwright #Python #AI #FFmpeg #PingFederate #DevOps

Building One Tap for PingFederate, Part 2: Docker, Terraform, and OIDC with PKCE

Bake the adapter into the PingFederate image

Keep license credentials out of source

Provision the authentication chain

Why the authentication-session policy matters

Configure a browser public client correctly

Apply the configuration

Production boundaries

Terraform #Docker #OIDC #PingFederate #DevOps

Building One Tap for PingFederate, Part 1: Architecture and the Secure Account Bridge

The behavior we want

The three state owners

Why the browser cannot simply read the account cookie

Authentication flow

Build the status bridge

Decode the native cookie

Secure the cross-origin response

Exact origin allowlist

Per-request nonce

Sandboxed iframe

Explicit postMessage target

Narrow framing policy

Avoid the first-request 404

Give the host explicit controls

Design and security lessons

PingIdentity #PingFederate #OIDC #Authentication #Identity

Trusted AI Agent Transactions, Part 5: End-to-End Proof

Building and proving the complete request path

The application flow

A UI that shows evidence without exposing credentials

Repository-owned product startup

Testing the security statement

The broader lesson

Trusted AI Agent Transactions, Part 4: PingAuthorize Policy Decisions

Making policy decisions with PingAuthorize

Only verified input crosses the policy boundary

A remote PERMIT is not enough by itself

The policy tuple

OPA and PingAuthorize can share a contract

What the tests prove

Trusted AI Agent Transactions, Part 3: SPIRE Workload Identity

A remote `PERMIT` is not enough by itself

Why an `agent_id` field is not proof