Ping Identity Developer Portal Blog

How expensive is a token exchange, really?

Tue, 06 Oct 2026 00:00:00 GMT

This post was originally published on Federico Carbone’s blog site.

Context

Token exchange is gaining popularity as a way to cross trust boundaries in agentic architectures, and I have described the pattern in earlier posts on SPIFFE workload identity and on centralizing MCP authorization with PingAuthorize.

Whenever I propose it, the same performance concern comes up: every extra exchange adds a hop to the authorization server, and a chatty agent could multiply that hop many times. The concern is reasonable, so I measured the token exchange performance against a two-engine PingFederate cluster on Kubernetes.

The result: At 500 exchanges per second the p95 latency was 9.5 milliseconds, with zero failures across the whole campaign. CPU consumption scaled approximately linearly with the exchange rate across the tested range, corresponding to about 5 CPU-ms of aggregate PingFederate engine CPU per completed exchange.

The test stops at 500 exchanges per second by choice. The goal was to establish a representative baseline rather than determine the cluster’s saturation point. The tests were also run in a shared environment without dedicated infrastructure.

The scenario

The deployment is a standard Ping Identity Kubernetes topology: one administration Pod and two PingFederate engine Pods behind a single Kubernetes Service. The test assumes an agentic workload where the agents and PingFederate run within the same Kubernetes environment. The measured path therefore reflects the expected production service-to-service path and intentionally excludes external ingress and user-to-cluster network latency.

Accordingly, load is generated by ten k6 agent Pods running inside the same cluster. Everything runs in an Amazon EKS cluster in eu-west-1: six worker nodes, all r5.xlarge instances (4 vCPU and 32 GiB each), running Amazon Linux 2023.

%%{init: {'flowchart': {'curve': 'linear'}}}%%
flowchart TB
    subgraph CL["Amazon EKS cluster — eu-west-1 (6 nodes, r5.xlarge)"]
        direction TB

        subgraph LB["Load generation"]
            K1["k6 agent-0"]
            K2["k6 agent-1"]
            KM["…"]
            K9["k6 agent-9"]
            JB["Kubernetes Job<br/>10 indexed completions"]
        end

        subgraph PF["PingFederate — namespace pf-perf"]
            direction TB
            ADM["pf-admin<br/>1 Pod, 2 CPU / 4 GiB limit"]
            ENG1["pf-engine-0<br/>2 CPU req / 4 CPU lim"]
            ENG2["pf-engine-1<br/>2 CPU req / 4 CPU lim"]
            SVC["Kubernetes Service<br/>port 9031"]
        end

        JWKS["perf-jwks-server Pod<br/>nginx, serves subject-key JWKS over TLS"]
    end

    JB --> K1 & K2 & KM & K9
    K1 & K2 & KM & K9 -->|"token exchange<br/>POST /as/token.oauth2"| SVC
    SVC --> ENG1 & ENG2
    ENG1 -.->|"JWKS fetch"| JWKS
    ENG2 -.->|"JWKS fetch"| JWKS
    ADM -.->|"config replication"| ENG1
    ADM -.->|"config replication"| ENG2

k6 agent Pods: The load generators generate a new JWT subject token at every iteration and exchange it exactly once — no token is reused, no two requests carry the same token. The 10 Pods simulate 10 independent agent instances acting on behalf of one pool of 100 synthetic user identities, rotating round-robin. In PingFederate each Pod authenticates as its own OAuth client — perf-agent-0 through perf-agent-9 — and the subject token’s audience is the calling agent’s client id.
Kubernetes Service: Load-balances across both engine Pods on port 9031; admin traffic is not part of the test.
PingFederate engines: Run the measured path — JWKS fetch and caching, JWT validation, token-exchange policy, output-token signing.
PingFederate admin: Configures the engines through cluster replication and stays idle.
perf-jwks-server: A small nginx Pod serving the subject-token verification JWKS over HTTPS (self-signed cert imported into the engines’ JVM truststore); the engines fetch and cache it.

Each exchange is an RFC 8693 request where the clients authenticate with client_secret_basic (no actor token) and exchange a self-contained JWT subject token. The engines authenticate the client, validate the subject token’s signature (using the keys obtained from the JWKS pod), the issuer, the audience, and the expiry and issue a new token.

I deliberately excluded:

User authentication (subject tokens are self-signed by the generator — no IdP round-trip)
Persistent-grant storage (the client is grant-only TOKEN_EXCHANGE, so the store is never touched)
Any external policy calls.

Token exchange

Here is one measured exchange — every k6 iteration performs exactly this (secrets are redacted and tokens are truncated).

Request (the subject token is signed by the load generator, RS256):

POST /as/token.oauth2 HTTP/2
Host: pf-pingfederate-engine:9031
Authorization: Basic cGVyZi1hZ2VudC0zOjxwZXJmX2NsaWVudC1zZWNyZXQ+
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&subject_token=eyJhbGciOiAiUlMyNTYiLCAidHlwIjogIkpXVCIs…[611 chars]
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token
&requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token
&resource=https%3A%2F%2Fmcp.example.internal%2Fmcp
&scope=mcp%3Atools%3Ainvoke

The subject token’s claims (decoded):

{
  "iss": "https://pf-perf-subject",
  "sub": "perf-user-042",
  "aud": "perf-agent-3",
  "iat": 1789978138,
  "exp": 1789978438,
  "jti": "mcp-final-1"
}

The issued access token is an RS256 at+jwt signed with PingFederate’s centralized signing key. Header (decoded):

{
  "alg": "RS256",
  "kid": "ejOM-MOWkc272nB1UwDyUGPasY4_RS256",
  "pi.atm": "8dzf",
  "typ": "at+jwt"
}

Payload (decoded):

{
  "scope": "mcp:tools:invoke",
  "authorization_details": [],
  "client_id": "perf-agent-3",
  "iss": "https://pf-pingfederate-engine",
  "iat": 1789978138,
  "sub": "perf-user-042",
  "aud": "https://mcp.example.internal/mcp",
  "act": {
    "sub": "perf-agent-3"
  },
  "exp": 1789978438
}

sub is the subject user, taken from the subject token’s sub through the token-exchange processor policy; act.sub is the authenticated client id, built by the access-token mapping from context.ClientId; aud is the requested resource URI, so the token is audience-restricted to the target MCP server; scope carries the requested scope, registered in the OAuth server settings — here mcp:tools:invoke; exp - iat is the token manager’s 5-minute lifetime.

The PingFederate side is fully declarative: a server profile carries all required objects as bulk-config JSON that the image imports at startup, and both engines are guaranteed identical configuration through cluster replication.

Test stages and environment

The campaign ran three reference stages — 100, 250, and 500 exchanges per second — and repeated the whole ascending ladder three times (100 → 250 → 500, ×3) against the same continuously warmed engines. Each run is five minutes at a constant arrival rate with a 30-second warmup excluded from the measured series; a throwaway sanity run before the first round is discarded by protocol, so every counted run starts from the same warmed state.

Each agent Pod drives total-rate/10 arrivals per second — at the 500 stage, 10 Pods × 50 = 500. The constant-arrival-rate executor opens each request on schedule regardless of response time, so it measures latency under controlled arrival, not throughput at saturation. All nine runs delivered their configured rates with zero dropped iterations and a 100% success rate.

Cluster

Amazon EKS, region eu-west-1, Kubernetes 1.35 (EKS build)
Six worker nodes, Amazon Linux 2023
All nodes r5.xlarge: 4 vCPU and 32 GiB each (roughly 24 vCPU of total capacity)

PingFederate sizing

Deliberately modest, close to a small production starter:

Pod	CPU request	CPU limit	Memory request	Memory limit
pf-admin (1)	1	2	2 Gi	4 Gi
pf-engine (2)	2	4	3 Gi	6 Gi

The Kubernetes scheduler is configured to place the two engines on different nodes when it can.

Load generation: 10 k6 Pods requesting 100m each.

How the test is run

Everything is driven by the following scripts, run from the client machine (my laptop):

Deployment: Installs the stack into Kubernetes
Verification: Checks the deployment is healthy and the engines landed on different nodes
Smoke test: Performs a single real token exchange before any load, proving the chain works
Run test: Runs the actual load test and collects the results
Reporting: Builds the dashboard

Alongside them, the monitoring script samples Pod and node resource usage into a CSV while the test runs. The scripts are not part of the measured path: they only observe the cluster through kubectl and collect results. Everything that generates or serves load runs inside Kubernetes; everything that coordinates, copies, and computes runs outside.

The run itself, step by step:

Before anything starts, one terminal is started to watch the cluster. Every 5 seconds it asks Kubernetes what the PingFederate Pods are consuming — CPU, memory — and writes each answer into a CSV. This runs the whole time, in the background (Monitoring).
The test starts. 10 k6 Pods begin firing token-exchange requests at PingFederate, 5 minutes per run, three ascending rounds per campaign. While each Pod works, k6 writes down every single request it made — timestamp, how long it took, whether it was warmup or real measurement — into a file inside its own container.
The 5 minutes end. Each k6 prints one final summary into its Pod’s log (e.g. “I sent 15,000 requests, p95 was 9 ms, everything passed.”) and then k6 quits.
The k6 Pods stay alive for 2 extra minutes after k6 quits and the run-test script collects all the results from the Pods — copying each agent’s per-request file out of its container; the summaries need no copying, they are already in the logs.
Finally, the reporting script combines everything: the per-request file from each agent, the printed totals from each log, and the resource samples from the CSV — all merged into one HTML dashboard on a shared time axis, which is where every number in this article comes from.

The results

Across the nine runs of the campaign (3 stages × 3 rounds): 780,072 token exchanges, 100% success, zero dropped iterations, all thresholds passed in every run. Not one failed or malformed OAuth response in the entire campaign.

Latency by stage

Median run of the three rounds per stage, measured phase only, warmup excluded. Every column comes from the same measured window, pooled across all ten agents:

Stage	Target rate	Requests	avg	median	p90	p95	p99
100/s	100.0% achieved	30,008	5.4 ms	5.1 ms	6.9 ms	7.5 ms	9.7 ms
250/s	100.0% achieved	75,007	5.2 ms	4.8 ms	6.6 ms	7.4 ms	10.8 ms
500/s	100.0% achieved	150,008	5.9 ms	5.3 ms	7.7 ms	9.5 ms	15.3 ms

Each stage’s reported row is the median run of its three, selected by measured p95; the per-run p95s were 100/s: 7.23/7.54/7.72 ms · 250/s: 7.31/7.44/8.09 ms · 500/s: 9.03/9.51/10.01 ms — tight spreads that indicate the numbers below are not an artifact of a single lucky run.

Latency remained within a narrow range: p95 ranged from 7.4 to 9.5 milliseconds between 100 and 500 exchanges per second.

Latency and CPU over time at 500 exchanges per second

The two charts below are the Report Generator’s time-series output for the 500 tps run (the first of the three rounds at that level).

Response time (in ms): Response time p90 over the five-minute run at the 500-per-second stage

Combined CPU load of the PingFederate engines (in millicores): Combined engine CPU over the five-minute run at the 500-per-second stage

Combined engine CPU holds steady at about 2.5 cores.

Resource consumption

Median run of the three rounds per stage:

Stage	Engine CPU avg	Engine CPU peak	Engine CPU per exchange
100/s	0.56 cores	0.62 cores	5.6 CPU-ms
250/s	1.28 cores	1.36 cores	5.1 CPU-ms
500/s	2.62 cores	2.72 cores	5.2 CPU-ms

The last column is the CPU-per-exchange figure: it is derived by dividing the aggregate CPU consumed by the PingFederate engines by the achieved exchange rate. It should therefore be interpreted as an observed CPU-efficiency metric for this workload and environment, not as a direct measurement of the incremental CPU cost of a single token exchange. Fixed JVM and platform CPU overhead is included in the figure.

Memory consumption is low: the two engine Pods together sat at a flat 2.8 GiB across all stages.

Key takeaways

In this test configuration, the token-exchange step remained in the single-digit-millisecond range at p95 for most of the tested range, reaching 9.5 ms at 500 exchanges per second. In agentic workflows where LLM reasoning and multi-step execution operate on much longer timescales, this makes the measured identity hop small relative to the overall interaction.

Resources

pingfederate-token-exchange-perf — the full project: Helm charts, k6 script, monitor and report tooling, the per-run evidence files behind every number in this article, and the HTML reports for all nine runs of the 3×3 campaign.
OAuth 2.0 Token Exchange — RFC 8693.
PingFederate OAuth configuration — token-exchange processor policies and access token managers.
k6 documentation — constant-arrival-rate executor and thresholds.
Securing agentic workflows with token exchange and workload identity — the identity pattern this test measures the cost of.

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community.

Centralizing MCP Authorization with PingAuthorize - Part 1

Thu, 01 Oct 2026 00:00:00 GMT

This post was originally published on Federico Carbone’s blog site.

Context

Large organizations often adopt multiple cloud platforms, modern AI services, and distributed applications, which leads to increasingly fragmented authorization. A single enterprise, for example, may expose MCPs through Azure, AWS, and on-premises servers.

Each platform introduces its own authorization mechanism, and over time, business rules become scattered across gateways, serverless functions, middleware, and application code. The result is duplicated policies, inconsistent decisions, difficult audits, and expensive maintenance.

PingAuthorize addresses this problem by separating policy enforcement from policy decision making. Gateways and applications remain responsible for enforcing decisions as Policy Enforcement Points (PEPs), while PingAuthorize acts as the centralized no-code Policy Decision Point (PDP).

This is the first article in a series exploring how PingAuthorize can centralize authorization decisions across different platforms and MCP environments.

I start with Azure API Management (APIM) protecting an MCP server, while future articles will apply the same model to other enforcement points such as AWS AgentCore Gateway.

What problem PingAuthorize solves: sprawl across hybrid environments

As enterprises expand across cloud providers and AI platforms, these challenges emerge:

Inconsistent authorization: Business policies become embedded in platform-specific implementations. The same rule may be implemented differently across gateways, clouds, and applications, producing inconsistent decisions.
Policy duplication: Authorization logic is copied into multiple enforcement points. Every policy change must then be implemented several times, increasing the risk of drift.
Authorization logic in code: Without a dedicated policy engine, teams implement authorization rules directly in application code or middleware. This consumes development cycles and ties every policy change to code reviews, testing, and deployments.
Limited governance: Authorization decisions are distributed across platform-specific logs, making it harder to understand why access was granted or denied and increasing the effort required for auditing and compliance.

PingAuthorize solves those challenges by centralizing policy evaluation: it evaluates the business policy and returns the authorization decision. This allows organizations to:

Keep business authorization rules outside applications and MCP servers
Update policies without redeploying APIs
Use contextual and attribute-based authorization
Centralize authorization decisions and audit information
Reuse the same authorization model across different platforms
Gain visibility and improve auditability by logging every authorization decision

The solution

The first implementation in this series implements an APIM Policy Fragment that delegates the authorization decisions to PingAuthorize. The fragment forwards the original MCP request to the PingAuthorize Sideband API, and then either forwards the call to the MCP server or relays the authorization denial to the caller.

The following diagram depicts the components in the implementation and their interactions:

%%{init: {'flowchart': {'curve': 'linear'}}}%%
flowchart LR
    C["Agent"]
    MCP["Protected MCP"]

    subgraph AZURE["Azure APIM"]
        APIM["Azure API Management\nMCP endpoint"]
        FRAG["APIM Policy Fragment\nSideband PEP"]
    end

    subgraph PING["PingAuthorize"]
        SB["Sideband API\n/sideband/request"]
    end

    C -->|"MCP tools/call\n(Agent Access Token - delegated)"| APIM
    APIM --> FRAG
    FRAG -->|"Sideband request\n(method, URL, headers, body)"| SB
    SB -->|"200 without response object\nPERMIT"| FRAG
    SB -->|"200 with response object\nDENY (status + WWW-Authenticate)"| FRAG
    FRAG --> APIM
    APIM -->|"tools/call if PERMIT\n(JSON/RPC payload)"| MCP

Agent: Invokes MCP tools through APIM using an Agent Access Token (typically obtained via Token Exchange).
Azure API Management: Acts as the Policy Enforcement Point (PEP). Receives the MCP request, runs the policy fragment, and either forwards the call to the backend MCP or relays the denial.
APIM Policy Fragment: A reusable APIM policy artifact that preserves the original request, wraps it in a Sideband request envelope, calls the PingAuthorize Sideband API with a shared secret, and enforces the returned decision. It performs no OAuth flows of its own.
PingAuthorize Sideband API: Acts as the Policy Decision Point (PDP). Receives the original request, evaluates policy over the full HTTP context, and either allows the call through (no response object) or returns a complete denial response for the PEP to relay.
Protected MCP: The protected MCP server (in our context a demo Mortgage MCP), receives requests only after APIM allows them through.

The important aspect is that APIM does not contain the business authorization logic. It forwards the request context required for policy evaluation and enforces the resulting authorization decision.

Scope note: This article focuses on the authorization integration between APIM and PingAuthorize. Token validation, token exchange, and backend MCP server security are outside the scope of this article. In a production setup, APIM could exchange the inbound token for a backend-scoped token before calling the MCP server. For simplicity, the demo MCP server is left open and no token exchanges have been configured in APIM.

The Sideband integration model

With this model, APIM constructs a Sideband representation of the incoming request containing the HTTP context required by PingAuthorize. PingAuthorize evaluates policy against the full HTTP context: request method, URL, headers (including the Authorization bearer token and its claims), query parameters, client IP, and the request body.

The integration follows three rules:

Permit: The PDP returns HTTP 200 with no top-level response object. The PEP continues to the backend.
Deny: The PDP returns HTTP 200 with a top-level response object containing a complete response to hand back to the client: status code, reason, headers (including WWW-Authenticate), and body. The status in that object is the PDP’s choice, not the PEP’s: 401 with a WWW-Authenticate header when the token is invalid or a step-up is required, 403 when the request is authenticated but not authorized. The PEP relays it verbatim.
Fail closed: Any transport failure or non-200 result is an integration error, not an authorization decision. The PEP does not continue and returns 502 Bad Gateway (sideband-unavailable for a failed call, sideband-error for a non-200 reply) — an unreachable PDP never becomes implicit access.

For an MCP call such as:

{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
        "name": "get_mortgage_summary",
        "arguments": {
            "customerId": "CUST-10001"
        }
    }
}

the fragment sends to the PingAuthorize sideband endpoint the following request:

{
  "source_ip": "203.0.113.10",
  "source_port": 5034,
  "method": "POST",
  "url": "https://apimid4ai.azure-api.net/mortgage-mcp/mcp/mortgage",
  "http_version": "1.1",
  "headers": [
    { "Accept": "application/json" },
    { "Content-Type": "application/json" },
    { "Host": "apimid4ai.azure-api.net" },
    { "Authorization": "Bearer <agent-access-token>" }
  ],
  "body": "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"get_mortgage_summary\",\"arguments\":{\"customerId\":\"CUST-10001\"}}}"
}

A PERMIT returns HTTP 200 with no response object; a DENY returns HTTP 200 with one:

{
  "response": {
    "response_code": 403,
    "response_status": "Forbidden",
    "headers": [
      { "Content-Type": "application/json" }
    ],
    "body": "{\"jsonrpc\":\"2.0\",\"id\":2,\"error\":{\"code\":-32003,\"message\":\"Forbidden\"}}"
  }
}

The APIM policy fragment

The integration with PingAuthorize is implemented directly as an APIM policy fragment. The fragment performs four operations:

Preserve the MCP request.
Build the Sideband request envelope.
Call the PingAuthorize Sideband API.
Enforce the returned decision.

The fragment is driven by three APIM Named Values:

AuthorizeSidebandRequestEndpoint (Plain): Base URL of the Sideband API without /sideband/request.
- PingAuthorize (software): https://paz.example.com:7443
- PingOne Authorize (cloud): The gateway Service URL, such as https://http-access-api.pingone.eu/v1/environments/{environmentId}
AuthorizeSidebandClientToken (Secret): The sideband shared secret — the Sideband API shared secret configured on PingAuthorize, or the gateway credential on PingOne Authorize.
AuthorizeSidebandDebug (Plain): false by default. Set to true temporarily to return a redacted Sideband request and the complete authorization response to the API client for diagnostics.

1. Preserve the MCP request

The Sideband API requires the original body as a string, so the fragment reads it before anything else and preserves it for later forwarding:

<set-variable
    name="authorizeOriginalRequestBody"
    value="@(context.Request.Body == null
        ? string.Empty
        : context.Request.Body.As<string>(preserveContent: true))" />

2. Build the Sideband request envelope

The envelope mirrors the original request. APIM rebuilds the full request URL (scheme, host, optional port, path, query string), and collects the headers as an array of single-entry objects — the shape the Sideband API expects. The Authorization header carries the agent’s bearer token unchanged, which is what lets PingAuthorize validate and inspect the caller’s token.

<set-variable name="authorizeSidebandRequestBody" value="@{
    var originalUrl = context.Request.OriginalUrl;
    var scheme = originalUrl.Scheme.ToLowerInvariant();
    var includePort = (scheme == "http" && originalUrl.Port != 80) ||
                      (scheme == "https" && originalUrl.Port != 443);
    var requestUrl = originalUrl.Scheme + "://" +
                     originalUrl.Host +
                     (includePort ? ":" + originalUrl.Port.ToString() : string.Empty) +
                     originalUrl.Path +
                     originalUrl.QueryString;

    var sidebandHeaders = new JArray();
    sidebandHeaders.Add(new JObject(new JProperty("Accept", "application/json")));
    sidebandHeaders.Add(new JObject(new JProperty("Content-Type", "application/json")));
    sidebandHeaders.Add(new JObject(new JProperty("Host",
        originalUrl.Host +
        (includePort ? ":" + originalUrl.Port.ToString() : string.Empty))));
    sidebandHeaders.Add(new JObject(new JProperty("Authorization",
        context.Request.Headers.GetValueOrDefault("Authorization", string.Empty))));

    var serializedBody =
        (string)context.Variables["authorizeOriginalRequestBody"];

    if (!string.IsNullOrEmpty(serializedBody))
    {
        try
        {
            serializedBody = JToken.Parse(serializedBody)
                .ToString(Newtonsoft.Json.Formatting.None);
        }
        catch
        {
            // Preserve a non-JSON body exactly as received.
        }
    }

    var payload = new JObject(
        new JProperty("source_ip", context.Request.IpAddress ?? string.Empty),
        new JProperty("source_port", 5034),
        new JProperty("method", context.Request.Method),
        new JProperty("url", requestUrl),
        new JProperty("http_version", "1.1"),
        new JProperty("headers", sidebandHeaders),
        new JProperty("body", serializedBody)
    );

    return payload.ToString(Newtonsoft.Json.Formatting.None);
}" />

APIM policy expressions cannot access the originating TCP source port, but the Sideband API requires a source_port value between 1 and 65535. The fragment therefore uses a fixed synthetic value (5034).

3. Call the Sideband API

The fragment posts the envelope to {endpoint}/sideband/request, authenticating with the shared secret in the PDG-TOKEN header. The call is wrapped in an APIM retry policy because APIM pools keep-alive connections to the Sideband endpoint, and a pooled socket that the server has already closed fails instantly — under rapid traffic this surfaced as intermittent 502 responses even though PingAuthorize was healthy. The decision probe is idempotent (a pure policy evaluation with no side effects), so retrying is safe: the first retry is immediate, the second follows a 1-second gap:

<retry condition="@(context.Variables["authorizeSidebandResponse"] == null)"
       count="2"
       interval="1"
       first-fast-retry="true">

    <send-request
        mode="new"
        response-variable-name="authorizeSidebandResponse"
        timeout="20"
        ignore-error="true">

        <set-url>@("{{AuthorizeSidebandRequestEndpoint}}".TrimEnd('/') + "/sideband/request")</set-url>
        <set-method>POST</set-method>

        <set-header name="PDG-TOKEN" exists-action="override">
            <value>{{AuthorizeSidebandClientToken}}</value>
        </set-header>

        <set-header name="Content-Type" exists-action="override">
            <value>application/json</value>
        </set-header>

        <set-header name="Accept" exists-action="override">
            <value>application/json</value>
        </set-header>

        <set-body>@((string)context.Variables["authorizeSidebandRequestBody"])</set-body>
    </send-request>
</retry>

The credential header name is part of the Sideband API configuration, so it must match what your PingAuthorize Sideband API endpoint expects — PDG-TOKEN here.

4. Enforce the decision

First, fail closed on transport problems. If every retry fails, the response variable stays empty:

<choose>
    <when condition="@(!context.Variables.ContainsKey("authorizeSidebandResponse")
        || context.Variables["authorizeSidebandResponse"] == null)">
        <return-response>
            <set-status code="502" reason="Bad Gateway" />
            <set-header name="Content-Type" exists-action="override">
                <value>application/json</value>
            </set-header>
            <set-body>@{
                return new JObject(
                    new JProperty("error",
                        new JObject(
                            new JProperty("code", "sideband-unavailable"),
                            new JProperty("message",
                                "Authorization Sideband service is unavailable")
                        )
                    )
                ).ToString();
            }</set-body>
        </return-response>
    </when>
</choose>

A non-200 status is also an integration error — not an authorization denial — and returns 502 with a sideband-error code. With HTTP 200, the semantics are simple: a top-level response object means DENY; its absence means PERMIT.

<set-variable
    name="authorizeSidebandBody"
    value="@(((IResponse)context.Variables["authorizeSidebandResponse"])
        .Body.As<JObject>(preserveContent: true))" />

<choose>
    <when condition="@(((JObject)context.Variables["authorizeSidebandBody"])["response"] is JObject)">
        <!-- DENY: extract the relay fields from the response object -->
    </when>
</choose>

<!-- No response object means PERMIT; continue to the backend unchanged. -->

On denial, the fragment extracts response_code, response_status, the response headers (looking for content-type and www-authenticate), and the body, then relays them to the caller. The status is PingAuthorize’s decision — 401 when the token is invalid or missing, 403 when the caller is authenticated but not authorized (including the MCP insufficient_scope challenge):

<set-variable name="authorizeDenyStatus" value="@{
    var denial = ((JObject)context.Variables["authorizeSidebandBody"])["response"];
    int status;

    return Int32.TryParse((string)denial["response_code"], out status)
        && status >= 100 && status <= 599
            ? status
            : 403;
}" />

<set-variable name="authorizeDenyReason" value="@{
    var denial = ((JObject)context.Variables["authorizeSidebandBody"])["response"];
    return (string)denial["response_status"] ?? "Forbidden";
}" />

Finally, the denial is returned with the authorization service’s status, reason, and WWW-Authenticate header when one was supplied.

The fragment also supports a temporary diagnostics mode: when AuthorizeSidebandDebug is true, denials and integration errors return the redacted Sideband request (with Authorization, Cookie, and Proxy-Authorization headers masked) and the complete authorization response to the API client, which makes endpoint and payload mistakes obvious during setup. Set it to true only for debugging.

Policies

To test the fragment, I used a demo mortgage MCP server. In sideband mode, PingAuthorize receives the original request and exposes its full HTTP context to policies — including the JSON-RPC body. The policies extract the attributes needed for authorization evaluation (the method, the tool name, risk-relevant arguments such as changeType), and the claims of the bearer token in the Authorization header.

The following controls are evaluated in order (first applicable wins), after a global Token Validation policy has already rejected expired, badly signed, or wrong-issuer tokens with a 401:

Token validity: An inactive token never reaches the policy set. The global Token Validation policy denies it with a 401 before any MCP logic runs.
Allow Delegated Token by VIP Users Only: When the call is delegated (the token carries both a subject and an actor subject, act.sub, meaning an agent is acting for a user), it’s permitted only if the subject is a VIP user. A standard user behind the same agent is denied with delegation_not_permitted; direct, non-delegated calls are untouched by this gate.
Allow read operations: The read tools (get_mortgage_summary, calculate_affordability, generate_rate_quote) are permitted for tokens carrying the mortgage:read scope.
Allow low risk changes: changeType = PAYMENT_DATE (moving a due date, in this demo defined as low risk) is permitted on the mortgage:write scope with no human involvement.
Deny High Risk Changes Without HITL: Economically risky changes (RATE_SWITCH, TERM_CHANGE, OVERPAYMENT) are denied with a machine-readable approval_required challenge unless the token carries a matching approval. Nothing is executed; the denial is the challenge.
Allow High Risk Changes with HITL: A risky change is permitted when the token carries an approval whose transaction context mirrors this exact payload, claim by claim, and whose txn claim matches the transaction id in the payload (validated with the HITL mechanism described below).
Default Deny: anything else: Unknown tools, wrong scopes, anything unmatched.

Scopes act as capability classes (mortgage:read, mortgage:write), so adding a tool never requires reconfiguring scopes. Risk is derived from the tool call payload, not the tool: the same submit_mortgage_change_request call results in permit and challenge based on its changeType argument.

When a policy denies a request because the token lacks the required scope, the denial is MCP-compliant. PingAuthorize composes the challenge defined by the MCP authorization specification: HTTP 403 with a WWW-Authenticate header carrying error="insufficient_scope", the required scope, and the resource_metadata URL of the Protected Resource Metadata document that the MCP server exposes. The fragment relays the decision, and a compliant client parses the challenge, discovers the authorization server through the metadata document, and can run a step-up authorization for a token with the missing scope.

For example, a token carrying only mortgage:read calling submit_mortgage_change_request triggers the challenge:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="mortgage:write", resource_metadata="https://apimid4ai.azure-api.net/.well-known/oauth-protected-resource/mortgage-mcp/mcp/mortgage", error_description="This operation requires the mortgage:write scope"
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32003,
    "message": "Forbidden"
  }
}

The human-in-the-loop path works as a deny-then-challenge loop. A PDP decision is synchronous — it cannot pause and wait for a human — so a risky change is first denied with the approval_required challenge. The human is redirected by the agent to the authorization server to obtain a short-lived transaction token whose claims mirror the approved transaction exactly (with the transaction context carried inside the access token itself):

{
  ... standard claims ...
  "approved_for": "submit_mortgage_change_request",
  "tctx": {
    "tool": "submit_mortgage_change_request",
    "changeType": "TERM_CHANGE",
    "mortgageId": "MORT-90001",
    "requestedValue": "30 years"
  },
  "txn": "TXN-8f3c1a90-4d2e-4b7a-9c1f-2e5d6a8b3c4d"
}

The txn claim is the transaction identifier minted by the authorization server. When the agent retries the identical call with that token, the approval policy validates the HITL by comparing every tctx claim against the parsed payload, attribute to attribute (the mirror):

tctx.tool against the MCP tool name
tctx.changeType against the parsed change type
tctx.mortgageId against the mortgage in the request
txn in the token against the transaction id in the payload

Any drift — a different change type, a different mortgage, a mismatched transaction id — breaks the mirror and the call is denied again.

The transaction id included in the payload and in the token helps the backend to protect against token replays: the backend records the first execution against the transaction id and, for any subsequent request with the same id, returns the recorded outcome without re-executing the business logic.

The following picture shows the policy set in the policy designer: The mortgage MCP policy set in the PingAuthorize policy designer

The following two pictures show how the Decision Visualizer depicts the evaluation: a PERMIT (a read tool permitted by the mortgage:read scope), and a DENY (a risky change denied for missing approval): A read tool permitted by the mortgage:read scope

A risky change denied for missing approval

Key takeaways

This article explained how PingAuthorize provides centralized dynamic authorization for Azure API Management. APIM acts as a Policy Enforcement Point for MCP servers without embedding business authorization rules in the gateway or in the protected MCP servers themselves. The policy fragment is the only integration artifact needed, and because it speaks the Sideband API — shared between PingAuthorize software and PingOne Authorize in the cloud — the same artifact enforces the same policies against either deployment.

This pattern is most useful when:

Multiple teams or platforms maintain separate authorization policies that express the same business rules, making drift and inconsistency inevitable.
Policy changes require coordinated redeployments across gateways, functions, or application code.
Compliance or audit requirements need a centralized, queryable record of every authorization decision regardless of where it was enforced.
Authorization rules depend on contextual or dynamic attributes — user roles, risk scores, time constraints — that must evolve independently of the applications that enforce them.

The next articles will apply the same pattern to additional enforcement surfaces such as AWS AgentCore Gateway, further showing how authorization decisions can be centralized and standardized across platforms.

Resources

PingAuthorize Sideband API — how the Sideband API proxies authorization decisions.
Sideband API configuration — configuring Sideband API endpoints and services on PingAuthorize.
Azure API Management policies — reference for APIM inbound policy expressions and send-request.
Source code — APIM policy fragment and configuration guidelines, including the mortgage policy set and its end-to-end test suite (azure-apim/test/policy-e2e-tests.sh).

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community.

Decentralized Identity on iOS: What Happens When Your App Becomes a Digital Wallet

Thu, 01 Oct 2026 00:00:00 GMT

A QR code, a camera, and a question

You’ve seen the flow, maybe without thinking about it: a kiosk or a web page shows a QR code, the user opens a mobile app, points the camera at it, and a moment later the app asks, “Do you want to share proof of employment with this organization?”

That moment looks like magic, but it is a protocol conversation. Inside those few seconds, a verifier has stated exactly what it needs, the user’s device has found a credential that satisfies the request, the user has decided to share it, and a signed response has gone back for verification.

This article walks through that conversation from the side developers actually ship: an iOS application that is the wallet. We’ll look at what a digital wallet really is under the hood, and then integrate the PingOne Wallet SDK for iOS step by step — pairing, credential issuance, and handling an OpenID4VP presentation request. By the end, the QR-code moment should feel less like magic and more like a state machine you can debug.

Decentralized identity: Proof moves into the user’s hands

For most of the history of digital identity, proof lived on servers. A login produces a token; a token is checked by another server. The user never holds anything — they hold a session at best. Every “proof of who you are” depended on a central party being online and agreeing to vouch for you, again and again.

Decentralized identity inverts this. Trust no longer flows through a central service at verification time; it is carried in cryptographically signed data that the user holds. Two building blocks make that possible:

Verifiable Credentials (VCs): A W3C standard format for tamper-evident statements — “this organization asserts this person is an employee with this title,” signed by the issuer. A credential in a wallet is a verifiable credential (or a closely related format), plus the cryptographic material that proves it belongs to the device presenting it.
Decentralized Identifiers (DIDs): A W3C standard for identifiers the user controls, resolvable to public keys without a phone home to a central identity provider. Wallets and issuers use DIDs as the signing and addressing layer: the issuer signs with its DID, the wallet proves possession of its DID’s private key, and the verifier checks signatures against the DID documents. The iOS SDK this article uses ships a DID SDK for exactly this layer.

Put together, the model looks like this: the user’s device holds a credential — issued once by an organization the user trusts — and presents it to whoever needs verification, when it is needed. Ping’s framing puts it well: a credential is like a long-lived SAML assertion or OIDC ID token that doesn’t have to be reissued on every sign-on. An “Employee” credential might carry your employer and job title; an application verifies it and acts on what it says.

Three roles make this work, and it is worth naming them because they map to real products:

Issuer: The organization that vouches for the claims and signs the credential (for example, an employer issuing an Employee credential).
Holder: The user, whose wallet app stores and guards the credential.
Verifier: The application or service that requests and checks the credential.

%%{init: {'flowchart': {'curve': 'linear'}}}%%
flowchart LR
    I["Issuer"]
    H["Holder\n(wallet)"]
    V["Verifier"]

    I -- "1. issues & signs credential" --> H
    H -- "2. presents proof (when asked)" --> V
    V -. "3. checks signature against issuer DID" .-> I

The decentralized identity trust triangle: the issuer signs once, the holder presents on demand, and the verifier checks the signature without calling the issuer.

Notice what is absent: No server needs to be online to vouch for the user at step 2. The verifier can check the issuer’s signature on its own, from the credential and the public key material. That is the “decentralized” in decentralized identity — trust travels with the credential instead of being mediated live by an identity provider.

The credentials move over open standards. OpenID4VP (OpenID for Verifiable Presentations) defines how a verifier states what it needs and how the wallet answers. PingOne supports OpenID4VP-based credentials, which means a PingOne-issued credential can be verified by other standards-compliant products, along with a PingOne-proprietary format that adds capabilities inside the Ping ecosystem. Knowing which format you’re working with matters for interoperability decisions, and we’ll return to that in the limitations.

What a wallet actually is

Before the code, a mental model. A digital wallet is two things:

A key store: Credentials are cryptographically bound to the device. On iOS this means keys live in the Secure Enclave and data in the keychain — which is also why a wallet doesn’t run on a simulator. The wallet signs challenges with these keys, which is how a verifier knows the credential is being presented by the device it was issued to.
A state machine: The wallet moves through a small number of states — unpaired → paired → receiving → presenting — and every interesting event (a pairing request, a new credential, a verification request) is a message that arrives from the outside and pushes the machine to its next state.

That second point is the one that saves you debugging time. When your integration misbehaves, the question is almost never “which of fifty settings is wrong?” It is “which message arrived, and what state did it move us to?” The SDK’s design makes this visible, as the walkthrough shows.

The walkthrough: Integrating the Wallet SDK on iOS

We’ll build this in four stages:

Instantiate the wallet client and get an identity for the wallet instance.
Pair the wallet with a user in a PingOne environment.
Receive credentials (issuance and revocation).
Handle a verification request: match, consent, present.

The snippets below are illustrative, adapted from the PingOne Wallet SDK sample app. They show the shape of the integration; the sample app in the SDK repository is the complete, tested reference.

Stage 1: Instantiate the client and get the wallet’s identity

The wallet SDK instance in your app has an applicationInstanceId — a UUID that uniquely identifies it on the PingOne platform. Your app creates the client with a builder, then reads that identifier:

let clientBuilder = PingOneWalletClient.Builder(forRegion: PingOneRegion.NA)
// Set a storage manager for encrypted local storage
if let storageManager = storageManager {
    clientBuilder.setStorageManager(storageManager)
}
clientBuilder.build()
    .onError { error in
        // handle initialization failure
    }
    .onResult { client in
        // The applicationInstanceId identifies this wallet instance
        let applicationInstanceId = client.getApplicationInstance(
            forRegion: PingOneRegion.NA)?.getId()
        // Send it to a trusted backend service (next stage)
    }

Two things are happening that are worth noticing. First, the builder pattern gives you async success and failure paths (onResult / onError) — this convention runs through the whole SDK. Second, the applicationInstanceId is not a user identifier. It identifies this wallet instance on this device. Connecting it to a user is the next stage, and it is deliberately not the app’s job to do that directly.

Stage 2: Pair the wallet with a user

A wallet only becomes useful when it is bound to a user in a PingOne environment. The design principle here matters: your mobile app should not call PingOne OAuth APIs directly. Instead, the app sends the applicationInstanceId to a backend service it already trusts, and the backend performs the pairing:

Your app authenticates the user with whatever mechanism it already uses.
The app sends the applicationInstanceId to your trusted backend.
The backend calls the PingOne API to create a digital wallet for the user, passing the applicationInstanceId in the request body.
PingOne sends a pairing request to the wallet.

The pairing request itself is a nice example of the security model. It arrives as an end-to-end encrypted message containing a cryptographically random challenge string. The wallet signs the challenge with its device keys and returns the signature — proving, without any shared secret having crossed the network, that the request reached the device it was meant for.

Your app learns about the pairing request through a callback:

func handleCredentialRequest(_ presentationRequest: PresentationRequest) {
    guard let pairingRequest = presentationRequest.getPairingRequest() else {
        return // not a pairing request; handle as a presentation (Stage 4)
    }
    pingoneWalletClient.pairWallet(for: pairingRequest)
        .onResult { _ in
            // wallet paired with the user
        }
        .onError { err in
            // pairing failed
        }
}

From here on, the wallet is paired: it is bound to a user and ready to hold credentials.

Stage 3: Receive credentials

Credentials reach the wallet over the PingOne Mailbox service, and the delivery model explains most issuance questions before they become support tickets:

When a user’s attributes change, PingOne’s credential lifecycle manager evaluates whether a credential should be issued or revoked, stages the change, and a periodic process issues or revokes accordingly. Issuance is scheduled, not real-time — if you’re testing and don’t see a credential arrive, check whether the next processing cycle has run.
Issued and revoked credentials travel to the wallet as end-to-end encrypted mailbox messages.
The SDK polls the mailbox (every 3 seconds by default) and calls your app through the callback handler when something arrives.

The callbacks mirror the lifecycle:

func handleCredentialIssuance(issuer: String,
                              message: String?,
                              challenge: Challenge?,
                              claim: Claim,
                              errors: [PingOneWallet.WalletException]) -> Bool {
    // Persist the credential to your secure storage
    dataRepository.saveCredential(claim)
    return true
}

func handleCredentialRevocation(issuer: String,
                                message: String?,
                                challenge: Challenge?,
                                claimReference: ClaimReference,
                                errors: [PingOneWallet.WalletException]) -> Bool {
    // Remove or mark the revoked credential
    dataRepository.saveCredentialReference(claimReference)
    return true
}

Note what the SDK does not do here: it doesn’t decide where credentials live in your app. Storage is yours — the sample app uses a DataRepository backed by Secure Enclave keys, and the protocol it implements is designed to be replaced with your own implementation.

Stage 4: The verification request — the heart of the flow

Now the QR-code moment. A verifier shows a code (or sends a deep link, or a push notification); the SDK parses it, fetches the presentation request, and calls the same handleCredentialRequest callback you saw in Stage 2. This time it is not a pairing request, and your job is to answer three questions in order:

What is being asked? The presentation request describes the claims the verifier needs — a job title, an employment status, a date of birth — in the language of the OpenID4VP presentation exchange.

Do we have it? Matching happens locally, on the device, before the user is involved:

let matcherResults = pingoneWalletClient
    .findMatchingCredentialsForRequest(presentationRequest)
    .getResult()
let matchingCredentials = matcherResults.filter { !$0.claims.isEmpty }

guard !matchingCredentials.isEmpty else {
    // Tell the user what is missing rather than failing silently
    return
}

This ordering is deliberate and it is the privacy core of the design: the request is evaluated against the wallet’s contents on-device. Only after a match exists does the user see anything.

Does the user consent? This is your app’s moment. If multiple credentials match, the app lets the user choose. Then the app presents:

pingoneWalletClient.presentCredentials(credentialPresentation)
    .onResult { result in
        switch result.getPresentationStatus() {
        case .success:
            // Verified. The verifier accepted the presentation.
        case .failure:
            // The presentation was rejected
        case .requiresAction(let action):
            // The verifier sent a follow-up action to handle
        }
    }
    .onError { err in
        // transport-level failure
    }

The three-way status is worth designing your UI around. success closes the loop; failure usually means the verifier’s policy rejected what was presented; requiresAction means the conversation isn’t over — the verifier has replied with another step the wallet needs to perform.

The whole flow on one page

sequenceDiagram
    participant V as Verifier
    participant P as PingOne
    participant W as Wallet app (your iOS app)

    V->>P: QR code / deep link
    P->>W: Presentation request (encrypted mailbox)
    W->>W: Match credentials (on-device)
    W->>W: User selects + consents
    W->>P: Signed presentation
    P->>V: Result

The verification flow end to end: the request arrives over the encrypted mailbox, matching and consent happen on-device, and only the signed presentation leaves the wallet.

Pairing and issuance follow the same mailbox pattern: a message arrives encrypted, the SDK decrypts and verifies it, the app gets a callback, and the user’s data stays on the device until the user acts.

Limitations and what to know before you build

Device, not simulator: The wallet uses the Secure Enclave, the keychain, and (in the sample app) the camera for profile creation. Plan for on-device testing from day one.
Scheduled issuance: Credential issue and revoke run on a processing schedule, not instantly. When your test credential doesn’t appear and you’re sure the polling is fine, the schedule is the suspect.
Two credential formats: OpenID4VP-based credentials interoperate with other standards-compliant verifiers; PingOne’s proprietary format offers additional capabilities within the Ping ecosystem. Choose deliberately, because it decides who can verify what you issue.
Verifier-side setup: A verifying environment needs an issuer profile configured before it can verify credentials — a detail that surprises teams testing cross-environment verification.
The snippets are illustrative: They are adapted from the sample app and simplified for length. Treat the sample app as the source of truth, and validate against the product documentation for your SDK version.

Takeaways

A digital credential is a long-lived, signed set of claims the user holds — the decentralized identity answer to “prove this about me” without a fresh token exchange every time.
A wallet is a key store plus a state machine. Debugging your integration means asking which message arrived and what state it produced.
Integration has exactly four stages: instantiate and get the wallet’s identity, pair through a trusted backend, receive lifecycle events via encrypted mailbox messages, and answer presentation requests with match → consent → present.
Matching happens on-device before consent. That ordering is not an implementation detail — it is the privacy property that makes the pattern worth adopting.

Where to go next

Explore the PingOne Wallet SDK for iOS sample app, which contains the complete, runnable version of every snippet in this article.
Read the PingOne Credentials product documentation for issuance rules, credential formats, and verifier configuration.
Read the OpenID4VP specification if you want to understand what is actually inside a presentation request.

Join the discussion on the Ping Identity developer community.

Login Widget Customization, from CLI to Chat Prompt

Fri, 25 Sep 2026 00:00:00 GMT

We spend a lot of our time in the Ping Login Framework, the Svelte-based toolkit behind our Login Widget. Building a custom login screen is always the same task at heart, but lately we’ve watched our own process for doing it evolve through three distinct stages.

Each stage streamlines things a bit more than the last, and by the third one we’re barely writing any code ourselves. We want to walk through that evolution, and why building each tool led us straight to building the next one.

One thing up front: everything past the first section is experimental. The APIs might change as we refine things, and none of it is officially supported yet.

If you like seeing where things are headed before everyone else, though, read on.

Building custom components

The Login Framework ships with a full set of built-in Svelte components that render every stage and callback type out of the box, so most apps built with the Login Widget never need to touch any of this. But sooner or later you’ll want to break away from the defaults.

Maybe you need a different look and feel: your own branding, layout, or validation messaging. Or maybe you need functionality the built-ins just don’t offer, like an extra field on a login form, or a bespoke UX for a particular callback type. That’s what custom components are for.

Implementing a custom callback component for boolean attributes

The framework supports two kinds:

Stage components: Replace an entire form layout for a specific stage.

Think a fully custom DefaultLogin screen with your own branding, layout, and validation messaging.
Callback components: Override how a specific callback type renders, globally, wherever it shows up in any journey.

To build either one, you drop a .svelte file into experimental/custom/stages/ or experimental/custom/callbacks/.

It has to start with a metadata header that the framework’s Vite plugin uses to auto-register it during the build:

<!--
@component
Type: stage
Name: DefaultLogin
-->

<script>
  export let form, journey, step;
</script>

<main>
  <!-- your custom layout -->
</main>

The framework reads that header at build time to auto-register the component, so no manual wiring needed.

This is still the most powerful option. You get full control over markup, styling, and behavior, and it’s where we still land for anything with unusual design requirements.

Scaffolding with the ping-lf CLI

The thing is, the header syntax has to be exact. A typo or a missing field, and the build fails without much to tell you why.

Add in the directory conventions and the prop contract for each component type, and it’s the kind of detail you tend to get right the second time, not the first.

So we wrote a CLI, ping-lf, to take care of the boilerplate.

You can install the ping-lf tool as follows:

npm install -g @forgerock/login-framework-cli

Note: You must be running Node 20 for the following ping-lf commands to work.

After installing the CLI, you’ll have the following tools available:

init: Initialize a new project from a published framework release or a local framework directory.
generate callback: Scaffold a new custom callback component under experimental/custom/callbacks/.
generate stage: Scaffold a new custom stage component under experimental/custom/stages/.
releases: List the framework releases available on GitHub.
update: Update an existing project to a newer framework version while preserving your custom components and configuration.

For example, you can initialize a new Login Widget project as follows:

ping-lf init ./MyCustomWidget
cd MyCustomWidget
pnpm install

Now you’re ready to scaffold your custom stage component:

ping-lf generate stage MyCustomLogin

That one command creates the file in the right directory, with a correctly formed metadata header, matching the naming convention the framework expects.

The generate command also scaffolds Storybook stories, a mock journey step, utility functions, and a unit test.

Best Practice: Over time you’ll want to keep your project up to date, and again the ping-lf tool can help.

Use ping-lf update to pull in framework changes while leaving your custom components and config alone.

What we like about the CLI isn’t that it saves keystrokes. It’s that it removes an entire category of mistakes.

You can’t misspell Type: in the header if the CLI writes it for you. You get the directory structure right by construction. It turns “read the docs carefully” into “run a command”, which is a much better place for a team to be once you’ve got more than one or two people touching custom components.

Still, at this point you’re the one driving. You decide what to build, you run the command, and then you go write the actual component logic and layout by hand. The CLI just clears the path to that part.

Supercharged components: adding an MCP for use by LLMs

Once the CLI existed with a clean set of typed commands behind it, it was a short step to ask: why not expose those same commands as tools an AI assistant can call directly? So ping-lf can also run as an MCP server, the same protocol that tools like Google Gemini and Claude Code use to call out to external tools.

Pass ping-lf the mcp parameter to run it in MCP mode. Point your AI assistant at it, and every one of those CLI commands becomes something the assistant can call directly, in the middle of a conversation, without you touching a terminal.

Wiring it up is just a config entry:

{
  "mcpServers": {
    "ping-lf": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@forgerock/login-framework-cli",
        "mcp"
      ]
    }
  }
}

After connecting to an assistant, you’ll have the exact same operations the CLI exposes, just callable directly from your assistant instead of typed as a CLI option.

In practice, that means we can describe what we want in plain language, something like:

Using the ping-lf MCP server, add a custom component for BooleanAttributeInputCallback that has a nice toggle effect between the two options, where a pill moves left or right to highlight the option and dim the unselected one.

The assistant scaffolds the component and fills in a first pass at the markup, using the framework’s own conventions, because it can see and call the same tools we would.

The interesting part isn’t that it saves typing. What it actually does is collapse the whole loop, by giving the LLM a declarative way to create the scaffolded code, rather than guessing at making the files directly.

You describe the outcome, get a working starting point, and iterate in conversation instead of switching between docs, terminal, and editor.

It doesn’t replace the first section of this post. You still need to understand stages and callbacks to know what to ask for, but you can focus on the result you want, rather than the details of how to build it.

It turns the CLI usage from earlier into something closer to “just tell it what you want”.

Where this leaves things

This is early-access, experimental tooling, and it’ll keep changing shape as we get feedback. But the trajectory is clear enough that we think it’s worth sharing now: from hand-writing metadata headers, to a CLI that writes them for you, to an AI assistant that can use that CLI on your behalf.

If you’re building on the Login Framework and want to try any of this, especially the MCP piece, grab the CLI and give it a spin!

Join the discussion on the Ping Identity developer community.

Token Exchange with Delegation in the Agentic Era

Thu, 06 Aug 2026 00:00:00 GMT

This post was originally published on Gwiz Kid.

Introduction

If you’re familiar with OAuth, you’ve likely come across RFC 8693 - Token Exchange. An often-overlooked capability within the OAuth specification, token exchange gives us the ability to communicate between multiple services and applications, re-scope requested tokens, and delegate authority to services downstream.

Delegation in particular has become a hot topic as of late due to the rise of agentic systems. With the rise of AI tooling deciding to perform actions in a non-deterministic manner, it is becoming more and more important to delegate those actions instead of giving them broad overarching permissions without auditability.

If some — or all — of that went over your head, you’re not alone and you’re in the right place.

This Guide aims to give you a high-level overview of what Token Exchange is, how Delegation applies, and what that means in agentic systems. We’ll do that by taking a closer look at what Delegation means in the context of application, and then agentic, identity.

It’s split into the following parts:

Understanding
Application

By the end of this Guide you should have a high-level understanding of what Token Exchange is, why it and delegation is important, and how it applies to both an agentic and non-agentic system. You’ll also gather a deeper understanding of why identity is so important to this system.

What is token exchange with delegation?

Overview

We use OAuth to secure access to resources. It allows us to define who owns what and what permissions they have.

OAuth also allows us to share access to resources securely. Given what we know about ownership and permissions, we can permit others access — forever or temporarily (lifetime) and with specific permissions (scopes).

When we share resources, we want to be very specific about what we share and with whom we share that resource with. We also likely want to know, once we’ve shared, who is doing what and who are they doing that action for.

Token Exchange with Delegation provides us that detail.

Let’s define some key players in exchange: the Subject, the Actor, and the Authorization Server.

The Subject is the primary entity that owns the resource. This could be an end-user, a microservice, an embedded system, or otherwise — it’s the primary identity that this exchange is for.
The Subject passes their token to the Actor, who is the entity that exchanges the token. This could be an application, secondary microservice, or even another identity who will receive the exchanged token and (likely) perform an action on behalf of the Subject.
The Authorization Server (AS) performs the exchange. There could be more than one AS depending on if the exchange is occurring cross-domain with trusted systems or all be performed on a single AS if the Subject and Actor live in the same domain. The AS will ultimately decide what scopes the Actor is able to receive based on the request that they made.

At the end of the day, the Actor exchanges the Subject’s Token with the Authorization Server to get a new token modified to perform the specific task the Actor wants to take. And exchanges can be chained — some services may call additional services, and along the way their permissions and Subject/Actor detail updates accordingly.

Token Exchange is the process of transforming the scope. Delegation is the “on behalf of” relationship tied to the exchange itself. While you can perform Token Exchange without Delegation, it’s critical to delegate when we want a clear audit trail of who performed the action and who they performed it for.

Example

Getting clearer? Let’s break this down with a non-technical example: paying someone from your bank account.

In this example, you want to pay your friend $10. You could go to your bank, give them your ID and PIN, withdraw $10, and then give it to your friend.

Let’s say you can’t get to the bank. Instead, you could give your friend your ID and PIN, have them go to the bank, and have them withdraw the $10.

But wait! If they have your ID and PIN, who’s to say they won’t transfer more than $10, change your PIN, or close your account? By sharing your credentials directly you’ve given your friend far too many permissions.

So instead, you issue a temporary PIN that lets your friend go to the bank and withdraw only $10. To make that PIN you had to prove yourself to your bank and because the PIN is tied to the $10 transaction its blast radius has been significantly reduced (one might even say “downscoped”). But that PIN is missing some key information — we have no idea who withdrew the $10. In fact, in the eyes of the bank, YOU withdrew it. We just performed Token Exchange without delegation.

So let’s clear this up further. Rather than a temporary PIN you give your friend a check. That check has your bank routing number on it, the exact amount your friend will get from your account, AND (notably) your friend’s information on it. In fact, before depositing that check the friend is going to have to validate themselves by endorsing the check and the bank will validate the transaction before letting your friend cash it.

You are the Subject, your friend is the Actor, and the bank is the Authorization Server. You validated yourself by using a valid check, you have downscoped your access to withdrawal only and for a specified amount, and your friend is acting on behalf of you to withdraw using the permissions that they exchanged at the bank who approved the whole thing.

In the case of chaining requests, we are going to be a little imaginative with this example.

Let’s say that your friend employed a couple other people to help with your task. You don’t know who they are but you do know that you owe your friend $10. Chaining exchanges lets your friend create an invoice that pays their employees from the $10 you gave them access to in your bank account. This would let you, the bank, and your friend be able to see that your friend’s employees got paid through your friend using your money. A chained token exchange gives you full visibility into each actor before it interacts with the resource.

Applying token exchange with delegation

Now that we’ve a good baseline, let’s apply this to a non-agentic system and then evolve it into an agentic one.

Delegation in a non-agentic system

A common system may look like what you see here.

A basic, non-agentic system

A user uses an application to interact with a service or resource.

In the most traditional sense, this could be an employee logging into a document site to edit a presentation, or a customer listing their previous orders. But an application is really an interface to the service — it could just as easily be a telephony product embedded in a helpdesk system or an embedded system receiving and interacting with analytics data relevant to the end user.

At the end of the day, your infrastructure likely relies on something — be it a person, system, or otherwise — interacting with something else to receive or act upon a service.

And in all reality, your application is likely communicating with more than one service. Microservice architectures, SaaS platforms, and specified tools have given rise to the implementation of an API Gateway that receives, validates, and routes requests to the appropriate service given the context of the user’s — and the application’s — request.

Adding an API Gateway

So how does identity play into all of this?

Layering an Identity Provider over a non-agentic system

Your identity layer sits on top of every stage in the flow from a user down to the resource.

Your user authenticates
The application exchanges the user’s token with the appropriate scope to perform an action for the user
The API Gateway introspects the exchanged token to ensure its validity and optionally exchanges again to provide additional context and scoping on the call.

In short, the identity provider helps you answer the following questions:

Who is this request for?
Who is performing the request?
If they’re able, What can they do?

Questions an Identity Provider answers

Let’s break this down in more detail:

Who is this request for? In this example, it’s your end-user. Not only do you want to know who this action should be performed on, but you want to ensure that they approved this action to have taken place. In our flow we have this level of assurance because your user authenticated with their identity provider and initiated the request with their valid access token.
Who is performing the request? Your application, upon receiving the user’s token, exchanged it for their own. This tied the application to the request as the actor — they are performing an action on behalf of the user. Ultimately, this gives you a clear audit trail of who is doing what and for who. The API gateway can also exchange the request from the Application to scope the request to themselves and track that the gateway is acting not only on behalf of the application but also the user.
If they’re able, What can they do? Now that you have all of this information — the actions being requested (the scopes), the resources they want to access, the user that requested and the applications that are acting on behalf of that user, you can use an authorization engine to strongly verify that all of this data matches what you expect.

Your identity provider plays a part in all of these interactions: It authenticates the user, exchanges the tokens, and validates the requests based on the policies you’ve defined.

Delegation in an agentic system

Securing an Agentic interface isn’t too different from the concepts you just reviewed.

An agentic system

That same application you were using before now likely contains an interface to interact with your agent. Your agent is listening to that interface. The agent isn’t the reasoning engine: it is a deterministic system that surfaces common, repeatable actions you want your non-deterministic system to take.

That agent can be plugged into one, or many, LLMs — Large Language Models (like Claude, ChatGPT, etc.) which use the context of the user interface and the actions surfaced by the agent to make decisions based on what it is understanding and learning from.

But an agent by itself isn’t particularly useful. It, like your application, needs to interact with services and resources based on the actions it’s been told to do. You could surface the raw API calls directly but there are common interfaces, like MCP (Model Context Protocol) that have defined standards for how to surface tools for your Agent to discover and subsequently use.

Just like before, you likely have more than one set of services and as such likely have more than one MCP server. To easily surface all tools, and make it simple to interact with them, you probably have an MCP Gateway to field and route those requests.

And, as we saw in the first example, your identity lives across the entire operational flow. The only difference is since we’ve added an additional layer of action, we’ve added an additional layer of exchange.

Layering an Identity Provider over an agentic system

This answers the exact same questions as before — Who is this request for, Who is performing the request, and if they’re able, What can they do?

Questions an Identity Provider answers in an agentic system

And that token exchange, that delegation, is key to this approach — we are now tracking, auditing, and validating that the application, the downstream agent, and optionally the gateway have the appropriate permission to perform the actions they’ve been instructed to do.

Conclusion

You should now have a high-level understanding of Token Exchange with Delegation, along with a view into how to apply it in both non-agentic and agentic use cases. You should understand the importance of knowing who is performing what and for whom, and that this relationship can be chained through more than one identity. Finally, you should recognize the incredible importance of identity in managing this system.

This guide is your primer, 101 course into the architectural basics. With it, you can begin designing authorization strategies that utilize the information provided by the delegating parties in your identity stack.

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community.

Custom Node Tips, Tricks, and Utilities

Wed, 05 Aug 2026 00:00:00 GMT

This post was originally published on Gwiz Kid.

Custom Nodes in PingOne Advanced Identity Cloud and PingAM enable the creation and management of flexible, reusable Journey Nodes. Unlike Scripted Decision Nodes, custom nodes let us define input parameters and output values so that we can templatize and genericize common actions we find ourselves scripting (and re-scripting) over and over.

As I’ve been building out Custom Nodes, I’ve collected some common reusable patterns that make development more consistent, easier to manage, and faster to implement.

This guide will walk you through some tips and tricks when building Custom Nodes as well as provide you functionality to help kickstart your next Node design. It’s broken down into the following sections:

When to Use a Custom Node
When Not to Use a Custom Node
How to Structure a Custom Node
Useful Functionality
Gotchas

This guide expects a level of familiarity with Scripting in PingAM/PingOne Advanced Identity Cloud as well as an understanding of Journeys.

When to Use a Custom Node

Reusability and Traceability

If you find yourself using the same Scripted Decision Node across multiple Journeys, Realms, or Tenants, it may be time for you to build a Custom Node.

Custom Nodes make reusing custom code significantly easier, for a few reasons:

Custom Nodes are available cross-realm — meaning you can design and maintain the node in one place and use it across all of your PingAM realms.
Custom Nodes detect and show usage and cannot be deleted when in use. Ever accidentally deleted a script that was used in a Journey? Custom Nodes prevent that issue as well as give you broader visibility into how it’s being implemented.

Sharability

If you find yourself creating custom capabilities that help your broader team, you’ll likely save a ton of time down the line if you convert your script into a Custom Node.

Custom Nodes show up in the Node selector in the Journey Canvas — meaning your designers don’t have to know what script to pick or configure and can organically find your node as they build their Journeys.
Custom Nodes have preset outcomes — saving your Journey designers the step of reviewing your Scripted Decision Node code to find the right outcomes and hopefully spell them correctly in the Node configuration.
Custom Nodes have built-in import and export utilities — meaning you have a preconfigured bundle that can be stored (locally, remotely, in git, etc), tracked, and imported using both API and UI.

Parametrization

If you find yourself creating copies of the same Scripted Decision Node but with different starting values (e.g. gathered from state, ESVs, set in constants), you should probably consider building a Custom Node.

Custom Nodes support parametrization of inputs, including ESV support, meaning that you can build a genericized structure that supports dynamic data retrieved from ESVs, state values, and/or user input to determine its outcomes. Why create a scripted node that returns an access code from one service, for example, when you can create a custom node that returns an access code from any service given the provided client credentials and secret?

Atomic Actions

Custom Nodes (and Journey Nodes in general) are meant to be atomic actions. This means that an individual node should do one thing and do that one thing well. As an example, take a look at the Platform Username Node — it collects a username and puts that value into Shared State. For a more complex version, there’s the Attribute Collector — it collects attributes found in the IDM schema and stores those in objectAttributes.

If you find yourself making a Scripted Decision Node or Custom Node that performs a wide range of diverse actions, consider breaking it down into smaller Custom Nodes. You’ll likely find that each component you’ve designed has its own utility outside of the larger node and, while more nodes are on your canvas, your Journey may become easier to follow since each action is explicitly shown on-screen.

TL;DR

Custom Nodes provide you the following benefits:

Cross-Realm availability (primarily useful for PingAM)
Display of all usage of the node within the UI and prevention of deletion while in use
Node availability within the Journey Canvas Node Selector
Preset, static outcomes
Built-in import and export utilities
Parametrization, including passing of ESVs
Atomic, generic, templated patterning

When Not to Use a Custom Node

Hyper-Specificity

If your created node performs an extremely specific, likely one-off, action it is probably best to keep it a Scripted Decision Node. Creating many one-off nodes has the unintended consequence of cluttering your Custom Nodes viewer and your Node selection list within your Journey canvas and may also result in designers unfamiliar with your node using it in unexpected (likely incorrect) ways in their Journeys.

Hyper-Generalization

There’s a reason we want our nodes to be self-contained with well-defined boundaries of use: it means that our users who will be building with these nodes will understand exactly what the node does and how to manipulate the inputs in that node to perform the actions they want to take. A super-duper do-it-all node will likely become too complicated to set up (or maintain!) for anyone other than the designer of the node.

Libraries

Since Nodes are meant to be atomic, their functionality must be self-contained to what is defined in the Node itself. As such, Custom Nodes do not have access to Library Scripts within their scripts.

If you are looking to create a Custom Node whose functionality would normally leverage a Library Script, see if you can place the necessary functions within the Node’s script editor without bloating the scope of that node too much (see Hyper-Generalization). Otherwise, a Scripted Decision Node may be more effective in this use case.

TL;DR

Custom Nodes come with the potential watch-out-fors:

Explosion of one-off nodes within the Journey Canvas
Creation of overly vague “super nodes” that are difficult to use and maintain
Lack of Library Script support

How to Structure a Custom Node

As more and more Custom Nodes are designed, it’s important to adopt a common design practice to ensure that maintainers can easily learn from, adopt, modify, and improve each other’s designs. The provided structure was designed with portability, clarity, and consistency in mind for Custom Nodes as well as Scripted Decision Nodes.

Below is an example structure for Custom Nodes, including comments detailing what each section does.

/**
 * Title: 
 * Provide the name of the node here. Makes searching for the node easier in Scripts
 * 
 * Description:
 * Explain what your node does. How does it work, what does it interact with?
 * Make this multi-line as needed.
 *  
 * Outcomes:
 * - Success   Description of this outcome
 * - Error     Description of this outcome
 *
 * Author(s):
 * - Author Name
 */

//// CONSTANTS
/**
 * Use this section to define constant values that will be used throughout your script.
 * These values should not change during execution of the script.
 * Placing constants at the top of the script makes it easy to find and modify them if needed.
 */
var CONSTANTS = {
    ERROR_TAG: "Example Node Name"
};

var NODE_OUTCOME = {
    SUCCESS: "Success",
    ERROR: "Error"
};

//// UTILITIES
/**
 * Use this section to define utility functions that will be used throughout your script.
 * These functions should be generic and reusable, helping to keep the main logic of your script clean and focused.
 * They can include tasks like data manipulation, callbacks definitions, APIs, etc.
 * Ideally, define these functions in a way that they can be reused in other scripts and nodes as well.
 */


//// MAIN
(function() {
    // Initial (default) outcome. This may be updated based on logic in the try/catch block.
    outcome = NODE_OUTCOME.SUCCESS;

    try {
        /**
         * Main logic of your script goes here.
         * Ensure to handle any potential errors gracefully and update the outcome accordingly.
         * Minimize the amount of code in this section by leveraging utilities defined above.
         */
        
        //// PARAMETERS
        /**
         * Get parameters defined for this node
         * Default values should be set in the node configuration and in the CONSTANTS section above.
         */
        // Example parameters
        var exampleBoolean = !!properties.exampleBoolean;
        var exampleString = properties.exampleString ? properties.exampleString : "defaultValue";
        var exampleNumber = properties.exampleNumber ? Number(properties.exampleNumber) : 42;
        var exampleArray = properties.exampleArray ? properties.exampleArray.toArray() : [];
        var exampleObject = properties.exampleObject ? properties.exampleObject : {};
        
        //// LOGIC
    } catch(e) {
        //// ERROR HANDLING
        logger.error(`${CONSTANTS.ERROR_TAG} ERROR: ${e}`);
        outcome = NODE_OUTCOME.ERROR;
    }
    action.goTo(outcome);
}());

A template not including the comments and examples is found below:

/**
 * Title: 
 * 
 * Description:
 *  
 * Outcomes:
 * - Success   The node completed successfully
 * - Error     The node encountered an error. Check the logs for more details.
 *
 * Author(s):
 * - 
 */

//// CONSTANTS
var CONSTANTS = {
    ERROR_TAG: "Example Node Name ERROR"
};

var NODE_OUTCOME = {
    SUCCESS: "Success",
    ERROR: "Error"
};

//// UTILITIES

//// MAIN
(function() {
    outcome = NODE_OUTCOME.SUCCESS;

    try {      
        //// PARAMETERS
        
        //// LOGIC
    } catch(e) {
        //// ERROR HANDLING
        logger.error(`${CONSTANTS.ERROR_TAG}: ${e}`);
        outcome = NODE_OUTCOME.ERROR;
    }
    action.goTo(outcome);
}());

Useful Functionality

Retrieving, Concatenating, and Traversing Values from State

Use Case

Very commonly we interact with data retrieved from Node State. In many cases, we may need to retrieve nested data stored in an object and/or array, and may want to concatenate that data with other static (or dynamically-retrieved) data.

The utility function resolveHandlebars(element, replaceUnresolvedHandlebarsWithString) provides you a way to do that. It supports nested objects and arrays using JSON Pointer Notation as well as string interpolation using handlebars {{}} syntax.

To use the function within your Custom Node:

Paste the below Utility Functions into your node.
Reference the resolveHandlebars function against one of your parameters. I like to also set replaceUnresolvedHandlebarsWithString as a parameter so that the user can decide if the node should do something different if any of the state values are missing.

// Within your MAIN, in the PARAMETERS section

var replaceUnresolvedHandlebarsWithEmptyString = !!properties.replaceUnresolvedHandlebarsWithEmptyString;
var message = properties.message ? resolveHandlebars(properties.message, replaceUnresolvedHandlebarsWithEmptyString) : null; // use whatever property here

Examples

Simple State Values

Use Handlebars to reference state keys directly. This will return the value as stored in state.

{{errorMessage}} — retrieves the value from nodeState.get("errorMessage")
{{username}} — retrieves the value from nodeState.get("username")
{{objectAttributes}} — retrieves the value (object) from nodeState.get("objectAttributes")

Nested Objects with JSON Pointer Notation

For nested objects and arrays, use JSON Pointer Notation within the handlebars. JSON Pointer starts the value with a forward slash (/) and uses that slash as a delimiter to traverse objects (using the keys) or arrays (using the indices).

{{/objectAttributes/mail}} — retrieves mail from the objectAttributes object
{{/results/0/name}} — retrieves the name from the first element of the results array

You may be wondering why period or bracket notation isn’t used here. There are three main reasons:

Existing nodes, such as the Query Filter Decision Node, as well as IDM use this approach natively.
Unlike period notation, JSON Pointer supports Objects and Arrays and requires less characters than bracket notation (supporting readability and easier debugging).
Some Node State keys use periods inside their key (I’m looking at you, PingOneProtectEvaluationNode.RISK — Protect Evaluation Node).

String Interpolation

Combine state values with other values and/or plaintext.

"Welcome {{/objectAttributes/givenName}} {{/objectAttributes/sn}}, your risk score is {{/risk/0/score}}"

Utility Functions

Add the following constants into the CONSTANTS section of your Custom Node:

var CONSTANTS = {
    OBJECT_DELIMITER: "/",
    HANDLEBAR_REGEX: /\{\{(.*?)}}/g,
    HANDLEBAR_OPENER: "{{",
    HANDLEBAR_CLOSER: "}}"
};

Add this code into the UTILITIES section of your Custom Node:

/**
 * Traverse a nested object path within a base object
 * @param {object} baseObject The base object to traverse
 * @param {Array<string>} pathArray An array of strings representing the path to traverse
 * @returns {any} The value at the end of the path, or null if not found
 */
function getNestedValue(baseObject, pathArray) {
    if (pathArray.length === 0) {
        return baseObject;
    } else {
        // Check if the baseObject is a valid object and if not try to parse it as JSON
        if (typeof baseObject !== "object" && baseObject !== null && baseObject !== undefined) {
            try {
                baseObject = JSON.parse(baseObject);
            } catch (e) {
                return null;
            }
        }
        var currentKey = pathArray[0];
        if (baseObject && baseObject[currentKey] !== undefined) {
            return getNestedValue(baseObject[currentKey], pathArray.slice(1));
        } else {
            return null;
        }
    }
}

/**
 * Stringifies the element only if necessary
 * @param {any} element The element to stringify
 * @returns {string} The stringified element
 */
function stringifyIfNeeded(element) {
    var type = typeof element;

    if (type === 'string') {
        // Already a string, return as is
        return element;
    } else if (type === 'undefined' || type === 'function') {
        // Return null or an empty string as a consistent fallback for undefined or functions
        return null;
    } else {
        // For everything else (objects, arrays, numbers, booleans, null), stringify.
        return JSON.stringify(element);
    }
}

/**
 * Given an element containing handlebar values, retrieve those values from state and replace them in the element.
 * If the entire element is a single handlebars value, return the value as-is without stringifying.
 * If the value contains JSON pointer notation, traverse the nested object to retrieve the value.
 * If the value cannot be found in state, either replace with an empty string or throw an error based on the flag.
 * @param {string} element The element containing handlebars. This will always be a string
 * @param {boolean} replaceUnresolvedHandlebarsWithEmptyString Flag to replace unresolved handlebars with an empty string. If false, an error will be thrown for unresolved handlebars.
 * @returns {any} The resolved element.
 */
function resolveHandlebars(element, replaceUnresolvedHandlebarsWithEmptyString) {
    if (element) {
        var newElement = element;
        var matches = element.match(CONSTANTS.HANDLEBAR_REGEX);

        if (matches && matches.length > 0) {
            // Check if the entire element is a single handlebars value
            var isSingleHandlebar = matches.length === 1 && element === matches[0];
            
            matches.forEach(function(match) {
                // Extract the key inside the handlebars
                var handlebarsKey = match.replace(CONSTANTS.HANDLEBAR_OPENER, "").replace(CONSTANTS.HANDLEBAR_CLOSER, "").trim();
                
                // First, check if the element exists as-is in state
                // This accounts for non-nested values with dots inside the key like "PingOneProtectEvaluationNode.RISK"
                var resolvedValue = nodeState.get(handlebarsKey);
                
                // If not, check if it's a nested object using JSON pointer notation
                if ((resolvedValue === null || resolvedValue === undefined) && handlebarsKey.indexOf(CONSTANTS.OBJECT_DELIMITER) === 0) {
                    var stateValuePath = handlebarsKey.split(CONSTANTS.OBJECT_DELIMITER);
                    if (stateValuePath.length > 1) {
                        var baseObject = nodeState.get(stateValuePath[1]);
                        if (stateValuePath.length > 2) {
                            // Traverse the nested object path
                            resolvedValue = getNestedValue(baseObject, stateValuePath.slice(2));
                        } else {
                            resolvedValue = baseObject;
                        }
                    }
                }

                if (resolvedValue !== null && resolvedValue !== undefined) {
                    if (isSingleHandlebar) {
                        // If the entire element is handlebars, return the value as-is without stringifying
                        newElement = resolvedValue;
                    } else {
                        newElement = newElement.replace(match, stringifyIfNeeded(resolvedValue));
                    }
                } else if (replaceUnresolvedHandlebarsWithEmptyString) {
                    newElement = newElement.replace(match, "");
                } else {
                    throw(`Unable to resolve value for key: ${handlebarsKey} within element: ${element}`);
                }
            });
        }
        return newElement;
    } else {
        throw('Element is null or undefined');
    }
}

Storing Results and Errors in State

Use Case

It’s incredibly common for a node to return a result of an operation into state — either a successful response of data (e.g. the PingOne Verify Completion Decision Node returning the transaction in pingOneVerifyTransactionId) or a failure response with reasoning (e.g. the PingOne Verify Evaluation Node capturing failures in pingOneVerifyEvaluationFailureReason).

The great part about a Custom Node is that we not only can perform the same utility but we can enable the user to specify where that data should be stored. That way:

If this node is being used in multiple places for different reasons, we can store and reference each result separately without fear of overriding an existing value.
We enable users to standardize where all of their nodes return values (for example, specifying that all error messages get stored in the errorMessage Shared State Key for easy referencing later).

To enable storage of results and errors in state within your Custom Node:

Paste the below Utility Functions into your node.
Add the following two properties to the end of your property list (I like to keep them at the end since they aren’t directly tied to functionality and are placed in a consistent way for users to find):

Name	Label	Description	Type	Default Value
resultSharedStateKey	Result Shared State Key	The location in which the result will be stored in Shared State.	String	result
errorMessageStateKey	Error Message State Key	If an error occurs, the location in Shared State where the error message will be stored.	String	errorMessage

Tip: If you always want a result or error message to be pushed to state, enforce the parameter to be required from within the parameter configuration.

Examples

Let’s say you have a Configuration Provider that displays a message containing the results of a Custom Node’s evaluation.

You could set up your Custom Node to push the results and error messages to output. Then, the config provider would display the resulting information regardless of whether it’s a result or failure without any additional logic.

You could set up your Custom Node to push the results to myResults and error message to myErrors. That way, the config provider could display results or errors with different text depending on what it receives.

You could set up your Custom Node to push results to myResults and leave error messages empty — resulting in only results and no error messages being passed to the config provider. The same could be said the other direction — you could leave results empty and then the config provider could only get error messages.

Utility Functions

Paste this within the PARAMETERS section of your MAIN within your Custom Node:

var resultSharedStateKey = properties.resultSharedStateKey ? properties.resultSharedStateKey : null;
var errorMessageStateKey = properties.errorMessageStateKey ? properties.errorMessageStateKey : null;

After your node has performed its action successfully, add this line to your MAIN:

// change `result` to the result you want to store
if (!!resultSharedStateKey) {
    nodeState.putShared(resultSharedStateKey, result);
}

Replace the ERROR HANDLING section of your MAIN within your Custom Node:

catch(e) {
    //// ERROR HANDLING
    logger.error(`Error during object creation: ${e}`);
    if (!!errorMessageStateKey) {
        nodeState.putShared(errorMessageStateKey, e);
    }
    outcome = NodeOutcome.ERROR;
}

Gotchas

Below are some common gotchas encountered when working with Custom Nodes.

Property Gotchas

Multi-Value Properties

If your property is multivalued, you’ll need to convert that property to an array before using it in your function (e.g. properties.exampleArray.toArray())

Enumerated Properties

Enumerated Values are defined in the Node property configuration as the Key being the value that returns to the script and the Value as the label that is used in the selector within the node.

Additionally:

The Key has restrictions on what characters it can support — consider using CONSTANT_CASE.
The Value supports most characters — consider using human-readable, Title Case with spaces.
The Default Value matches the Keys in the Enumerated Values.

As an example, if you wanted to create a dropdown list in which a user selected the “Message Type” when displaying a message to the user, your property configuration might look something like this:

{
  "messageType": {
    "title": "Message Type",
    "description": "The type of Message to display to the user.",
    "type": "STRING",
    "required": true,
    "defaultValue": "INFORMATION",
    "options": {
        "INFORMATION": "Information",
        "ERROR": "Error",
        "WARNING": "Warning"
    },
    "multivalued": false
  }
}

In this setup, the user will see and be able to select the options “Information”, “Error”, and “Warning”.

When selected, the value “INFORMATION”, “ERROR”, or “WARNING” is passed into the script.

The default value is “INFORMATION”, meaning that the user will see “Information” by default and if unchanged the value “INFORMATION” will be passed into the script.

It is to your advantage to define the dropdown values as a dictionary (JSON object) in your script in which your passed value is mapped to a static value or state.

Outcome Gotchas

Outcomes are static and case-sensitive. If your code returns an outcome of Success that outcome should be defined as Success (not success or SUCCESS).
On a similar topic, you should make your outcomes Title Case with spaces to match the outcomes in a standard Journey Node. It’ll make your node look and feel like the rest on the canvas.
You can configure a Custom Node to return an error outcome automatically. If you do, the outcome is set as Script Error. Any error outcomes (Error, Script Error, etc) defined in code must still be defined in the configuration separately as the Script Error outcome is only returned on an error that isn’t handled. With this in mind, I suggest choosing either the built-in error or defining your own: not using both.

Node Management Gotchas

If you attempt to import a Custom Node with the same name or id into your tenant the import will fail. To fix, you must change the name and id within the JSON export prior to importing.
If you change a Custom Node, the new version of that custom node will be applied to all Journeys using it immediately.
Descriptions support the same basic HTML formatting as the content in Page Nodes. Use that functionality to add greater detail like <code> blocks, links, and paragraph/list formatting. Markdown is not supported.

Gotchas as of This Article

Object Parameter types do not support HTML formatting in their descriptions.
Custom Nodes do not support versioning. Consider storing exports in an external git repository.
The UI forces Multi-Valued and Enumerated values to be required even though they technically don’t need to be. To get around this, use the API to update the node config with required set to false and the UI will work as normal.

Conclusion

Through this guide we have:

Learned when and when not to use Custom Nodes
Worked through a standard structure to designing Custom Nodes and Scripted Decision Nodes
Learned of some common utility functions to kickstart Custom Node development
Walked through common “gotchas” when working with Custom Nodes

Custom Nodes are an incredibly powerful tool that massively improves collaborative Journey development. Knowing when and how to leverage them for your team will make you all the more effective in your IAM journey.

Join the discussion on the Ping Identity developer community.

Introducing macOS Platform SSO in PingID Desktop 2.0

Wed, 29 Jul 2026 00:00:00 GMT

macOS Platform SSO in PingID Desktop 2.0 gives developers and identity architects a way to connect the native Mac sign-on experience to PingFederate and extend that trust into browser-based applications and native apps that rely on system web authentication. This isn’t just a desktop UI update. It’s an end-to-end flow built from an MDM-delivered Platform SSO profile, PingID Desktop 2.0, PingOne for Workforce (PingID), and PingFederate 13.1 or later.

In this first release, PingFederate is the supported identity provider (IdP), the Platform SSO extension is installed as part of PingID Desktop 2.0, and the supported authentication method is Secure Enclave-backed keys.

This post focuses on the implementation side of the release: prerequisites, architecture, PingFederate configuration, MDM profile requirements, and the main flow boundaries you should understand before rollout.

Prerequisites

Before you start, make sure the deployment baseline is in place.

Requirement	Details
macOS	macOS 15.4 or later
Hardware	Apple Silicon Mac
Device management	MDM is required, and unattended Automatic Device Enrollment (ADE) is supported
Desktop client	PingID Desktop 2.0 or later
Ping service	PingOne for Workforce (PingID) is required, and users must exist there before registration
Identity provider	PingFederate 13.1 or later
PingFederate component	Mac Platform SSO adapter

If you are already using PingID Desktop 1.0, the client-side change is straightforward: upgrade to PingID Desktop 2.0. No additional configuration is required in the installer or in the running application itself to enable macOS Platform SSO. The configuration is delivered through MDM and the PingFederate-side setup.

Why Platform SSO matters

Platform SSO is Apple’s framework for binding the local macOS sign-on experience to an enterprise identity provider. In Ping’s implementation, the model combines device identity, user identity, cryptographic trust, token issuance, and application single sign-on (SSO) in a single flow.

Platform SSO is also different from browser-session-based SSO. It doesn’t rely on an existing browser cookie to create the SSO experience. Because trust is established through the platform and the identity provider integration, even a newly installed supporting browser (based on Apple’s WebKit) can participate in SSO right away. The same model can also benefit native applications that use the same PingFederate login domain through supported system web authentication flows.

From a technical point of view, that matters because the trust does not begin in the browser. The device is registered first, the user is registered second, and only then does the system use that registered state to satisfy later authorization requests. That is what makes the experience feel native while still keeping PingFederate in control of policy and token issuance.

What we are releasing

This release adds macOS Platform SSO support to the new PingID Desktop application, starting with version 2.0. The Platform SSO extension is installed as part of PingID Desktop and works with PingFederate as the supported identity provider for this release.

At a high level, the solution has three major phases:

Device registration
User registration
Login and application authorization

Those phases matter because Platform SSO is not just a browser shortcut. The flow establishes trust in the device, binds a user credential to that device, and then uses that trust to support later sign-on requests.

How it works

The architecture includes four collaborating parts: the MDM profile that delivers the required configuration, the macOS Platform SSO engine, the PingID SSO extension, and PingFederate as the identity provider runtime layer.

The MDM profile is what turns the feature on for the device and tells macOS where to send matching authentication traffic. At the profile level, developers should expect a com.apple.extensiblesso payload with values such as the Ping extension identifier, the Ping team identifier, the list of URLs that should be handled by the extension, and ExtensionData that carries the Platform SSO configuration. Inside that configuration, the important values are the client identifier, base URL, audience, and PingFederate instance identifier that the extension uses when talking to PingFederate. For this first release, the Platform SSO authentication method is UserSecureEnclaveKey.

The macOS Platform SSO engine handles platform-native behavior, such as key generation, authentication, token refresh, and secure token storage. The PingID SSO extension handles device registration, user registration, token and login configuration, and the interception of supported SSO requests. PingFederate receives the Platform SSO-augmented requests, validates tokens, Secure Enclave signatures, nonce and replay protections, and device binding, then issues the client-specific result for the application or browser flow.

From an implementer’s point of view, the flow looks like this:

The device is enrolled and receives the required Platform SSO profile through MDM.
The device completes registration and establishes a cryptographic device identity.
The user completes registration and binds a user credential to that device.
When a supported authorization request arrives, macOS routes it to the Platform SSO extension.
The extension adds the required Platform SSO material and forwards the request to PingFederate.
PingFederate validates the request and continues the authentication policy.
The application receives the result of the PingFederate flow without forcing the user to manually repeat sign-on.

What you need to configure

To roll out macOS Platform SSO, there are three technical control planes to configure: device management, PingOne for Workforce, and PingFederate. You can find full details in Configuring Platform SSO for macOS (Workforce only) in the PingOne documentation.

1. Device management and MDM profile

The device must be Apple Silicon, run macOS 15.4 or later, and be managed by MDM so it can receive the Platform SSO configuration profile. Unattended ADE is also supported, which is useful for zero-touch provisioning of managed Mac fleets.

The MDM profile is where you define the full Platform SSO behavior for the device, not just the redirect target. The exact values depend on your environment, but the key structure should look like this (keys can also change according to needs):

{
  "Type": "Redirect",
  "URLs": [
    "https://<pingfederate-host>"
  ],
  "PlatformSSO": {
    "Account": {
      "DisplayName": "My Org Name"
    },
    "UserCreation": {
      "EnableAtLogin": true,
      "TokenToUserMapping": {
        "FullName": "name",
        "AccountName": "preferred_username"
      },
      "EnableFirstUserDuringSetup": true,
      "EnableRegistrationDuringSetup": true
    },
    "RegistrationToken": "<registration-token taken from the PingFederate Adapter>",
    "UseSharedDeviceKeys": true,
    "AuthenticationMethod": "UserSecureEnclaveKey",
    "AllowDeviceIdentifiersInAttestation": true
  },
  "ExtensionData": {
    "AppPolicy": {
      "AppAllowList": [
        "<bundle-id-1>",
        "<bundle-id-2>"
      ],
      "AppBlockList": [
        "<blocked-bundle-id-1>",
        "<blocked-bundle-id-2>"
      ],
      "AllowManagedAppsOnly": false
    },
    "PSSOConfiguration": {
      "BaseURL": "https://<pingfederate-host>",
      "Audience": "https://<pingfederate-host>",
      "ClientID": "<oauth-client-id>",
      "InstanceID": "<pingfederate-instance-id>"
    }
  },
  "ExtensionComposedIdentifier": "com.pingidentity.pingid.desktop.pingssoe (6U3RF4C84N)"
}

The ExtensionComposedIdentifier (in Declarative Device Management as in the example above) or ExtensionIdentifier and TeamIdentifier (in a regular configuration profile) will always hold com.pingidentity.pingid.desktop.pingssoe and 6U3RF4C84N respectively.

Platform SSO deployments also need a separate associated domains payload. This payload authorizes Safari and system authentication services to route authentication traffic to the PingID Desktop SSO extension. Each entry should use the authsrv: prefix followed by the host name only. Do not include https://, a port, or a trailing slash. For example, if your PingFederate base URL is https://pf.example.com, the associated domain value should be authsrv:pf.example.com. Add one entry for each domain your deployment uses. ApplicationIdentifier will always be 6U3RF4C84N.com.pingidentity.pingid.desktop.

A placeholder associated domains payload can look like this:

{
  "PayloadType": "com.apple.developer.associated-domains",
  "Configuration": [
    {
      "ApplicationIdentifier": "6U3RF4C84N.com.pingidentity.pingid.desktop",
      "AssociatedDomains": [
        "authsrv:<your-pingfederate-host>"
      ]
    }
  ]
}

A few fields are especially important during implementation. The URLs list and the associated domains payload work together to determine which login traffic the extension can handle. The TokenToUserMapping section controls how claims from the identity response (OIDC ID Token) map to the local macOS account. The EnableFirstUserDuringSetup and EnableRegistrationDuringSetup flags are useful when you want registration to happen during Setup Assistant, especially in unattended ADE deployments. The PSSOConfiguration block must align with the PingFederate-side client, audience, base URL, and instance configuration.

Note about EnableFirstUserDuringSetup: If you enable this field as part of ADE, macOS shows a native username and password screen that prompts the user for IdP credentials. The system authenticates the user against the IdP using the Password grant type. macOS then carries the response into the next screen, where it creates the local account. In the local account creation screen, the account name and full name fields are pre-populated, and the user only needs to create the local account password. This prevents the possibility of users giving their own account and machine names.

2. PingOne for Workforce presence

PingOne for Workforce is part of the solution. Users participating in the flow must exist in PingOne for Workforce before registration starts. That presence is what enables device registration, user registration, and strong authentication during the Platform SSO journey.

The Platform SSO flow also supports PingOne for Workforce as the MFA layer, including methods such as push notifications to the PingID mobile application and passkeys.

Note about created users in PingOne for Workforce: To support the use of the MDM profile key TokenToUserMapping - Account Name, the admin must create a custom User Attribute named preferred-username in PingOne for Workforce that will map the username to the PingFederate field inserted into the preferred_username field in the ID Token. Each user must have this Custom Attribute.

Admins can check if the user is registered to the Platform SSO in the User -> Services -> Authentication section under Sessions & Devices.

3. PingFederate 13.1+ configuration

Customers should use PingFederate 13.1 or later, and in practice the latest supported PingFederate deployment is the best starting point.

The PingFederate configuration should include the following components and they should be aligned as one end-to-end Platform SSO flow:

Import the Apple Enterprise Attestation Root CA so PingFederate can validate the attestation chain presented during registration.
Add the urn:apple:platformsso scope.
Configure an OAuth client for the desktop app. The required grant types are Authorization Code, Refresh Token, and Assertion Grant.
Make sure the client can complete the OIDC flow and issue both an access token and an ID token.
Create an access token manager for the Platform SSO flow.
Create or update the OpenID Connect policy used to issue and validate the required claims.
Create a Mac Platform SSO adapter in PingFederate.
Create a Mac Platform SSO JWT Bearer Grant Processor.
Create the IdP connection used by that grant processor.
Add the Platform SSO adapter to the authentication policy.

Treat these as connected configuration objects rather than isolated tasks. The OAuth client, tokens, adapter, grant processor, IdP connection, and authentication policy all need to agree on the same Platform SSO flow so registration and sign-on behave consistently.

A few implementation details are especially important:

Platform SSO must be the first step in the PingFederate authentication policy. If another adapter appears before it, the flow is not supported.
Customers can use PingFederate HTML Adapters or a DaVinci flow later in the authentication experience. This way, admins can take the advantage of different MFA options (such as number matching push notifications to PingID mobile app or passkeys etc.), PingOne Verify, and so on.
The OAuth client, access token manager, adapter, and IdP connection should be configured consistently so the same client and token context are used across registration and SSO.

Troubleshooting

If registration or sign-on does not behave as expected, collect logs from all three layers of the flow: macOS, PingID Desktop, and PingFederate. Looking at only one layer usually gives you only part of the story.

1. Stream macOS unified logs

Use macOS unified logging when you want to watch the flow in real time while reproducing the issue.

log stream --predicate 'process == "AppSSOAgent"' --info --debug
log stream --predicate 'process == "pingssoe" AND subsystem BEGINSWITH "com.pingid.passwordless"' --info --debug

Or for the ADE flow, in addition to the above (Terminal can be opened by using ⌃+⌥+⌘+T):

log stream --predicate 'process == "Setup Assistant" AND subsystem == "com.apple.macbuddy"' --info --debug

In practice, the most useful predicates are the ones that narrow the stream to the PingID Desktop app, the SSO extension, or Apple AppSSO activity. If you already know the process name, subsystem, or category you want to follow, add it to the predicate and reproduce the registration or sign-on flow again.

2. Collect PingID Desktop logs

For PingID Desktop, the fastest way to gather diagnostics is the built-in CLI.

sudo pingiddesktop logs --time 30m

The output path is /tmp/pingid-desktop-logs.zip.

3. Review PingFederate server logs

On the server side, review the PingFederate logs while reproducing the same registration or sign-on attempt. This is especially important when you need to confirm adapter execution, token issuance, attestation validation, policy progression, or failures in the JWT Bearer Grant Processor or IdP connection.

For Platform SSO issues, it is a good practice to collect PingFederate logs in DEBUG during testing so you can correlate the server-side event with the device-side and desktop-side activity.

Current scope

This first release is intentionally focused.

Today, the supported authentication method is Secure Enclave-backed keys. In the current design, Phase 1 support is limited to the Secure Enclave approach, and the configuration examples use UserSecureEnclaveKey for the authentication method.

That limitation is important because the registration and assertion model depends on hardware-backed keys and attestation as part of the trust chain.

It is also important to understand what the extension does and does not intercept. The PingID SSO extension supports browser-based authentication flows and system web authentication sessions. It does not intercept direct API traffic such as cURL, Postman, background service calls, URLSession requests, or JavaScript fetch() calls, because those do not go through the OS-level browser authentication path.

Why this matters for developers and implementers

For engineering teams standardizing on managed Macs, this release creates a clean separation of responsibilities:

MDM delivers the Platform SSO profile.
PingID Desktop 2.0 hosts the extension.
PingOne for Workforce provides the user and MFA context.
PingFederate enforces policy and issues the final authentication result.

That split makes the system easier to reason about during rollout and troubleshooting. The device and user are enrolled once, and later authorization requests can be evaluated using signed proofs tied to that registered state instead of forcing the user through repeated sign-ons.

It also means troubleshooting gets easier when you keep the layers separate. If registration is failing, start with MDM profile delivery, the PingID Desktop logs, and the PingFederate debug logs. If sign-on works in the browser but not through Platform SSO, check whether the request is actually using a supported browser or system web authentication path and whether Platform SSO is the first step in the PingFederate policy.

Looking ahead

This is the beginning of the Platform SSO journey in PingID Desktop. The current release focuses on PingFederate as the supported identity provider and on Secure Enclave-backed authentication. Support for additional authentication types and broader coverage will follow in future releases.

If you are planning a rollout now, the best place to start is with PingID Desktop 2.0, the latest PingFederate deployment, the Mac Platform SSO adapter, PingOne for Workforce, and an MDM-managed device fleet. That gives you the baseline you need to validate registration, confirm policy behavior, and test browser and native application sign-on with the supported architecture.

macOS Platform SSO in PingID Desktop 2.0 is a practical step toward a more native and lower-friction sign-on experience on managed Macs. For developers and identity teams building passwordless and device-aware experiences around PingFederate, this is the right place to start.

Join the discussion on the Ping Identity developer community.

Mapping the landscape for AI-first headless identity

Tue, 28 Jul 2026 00:00:00 GMT

As we continue to enhance AI-first headless methods of working with Ping Identity systems, we want to know more about your experiences and needs. If you’re exploring headless IAM workflows that enable agentic operations or wondering how AI can streamline the administrative experience with Ping’s platform, we’d love your feedback.

We’re running a short survey to better understand how teams think about using AI agents for IAM admin, where current experiences fall short in terms of headless capabilities and context for agents, and which problems matter most to solve next. Your input will help us prioritize both product direction and follow-up research in this space.

We’re especially interested in feedback on questions like:

What makes headless admin valuable or challenging in real-world environments?
What guardrails and contextual guidance would best support agents in safely designing, configuring, and operating your specific identity infrastructure?
Which admin workflows feel most important to improve first?
What signals help you trust and adopt new approaches in identity administration?

AI-first headless identity isn’t just about removing UI: it’s about giving teams and their AI tools and agents more flexible, intelligent ways to manage identity workflows, reduce manual effort, and contextually adapt administration to the needs of their environment. Your feedback can tell us where that vision is already resonating and where more clarity, capability, or support is needed.

If you’re willing to go a step further, the survey also includes options for more engagement beyond the survey and the blog.

Take the survey

If you are a PingOne user, you might find a version of the survey in the Research section of Help & Resources in the top nav bar.

If we get at least 30 complete responses, we’ll share the survey results in a future post.

Thanks in advance for helping us shape the future of AI-first headless identity admin at Ping Identity.

Join the discussion on the Ping Identity developer community.

React Native SDK 1.0 Release!

Fri, 24 Jul 2026 00:00:00 GMT

The problem we set out to solve

Cross-platform development promises one codebase for both iOS and Android, but authentication is usually where that promise gets complicated. A production app needs more than a login screen. It has to handle token lifecycle, secure storage, biometrics, push, external identity providers, and multi-step orchestration, all from a single codebase.

The existing options usually forced a trade-off. Thin wrappers left the hard parts to the developer, browser-only flows limited how native the experience could feel, and custom bridges meant maintaining native code separately for both platforms. That’s why we’ve built our Ping Orchestration React Native SDK to close the gap: a TypeScript API that exposes the real capabilities of the underlying native SDKs without abstracting away the complexity you still need access to.

What’s in the toolbox

The SDK is a Yarn monorepo of independent packages. That means applications can install what they actually need instead of pulling in a single oversized package.

The SDK supports both Journey orchestration and standard OIDC flows. It handles the flow from the initial challenge through token handling, including redirect handling, PKCE, refresh, and session management. Those pieces are already built in, so the app doesn’t need to wire them up separately.

useJourney returns a [node, actions] tuple. node is a discriminated union for the current Journey state. Loading and error states live on actions. If the flow needs to be shared across screens, JourneyProvider can hold that state at the navigator level instead of passing it through props.

useJourneyForm is an optional hook for normalizing the callback array returned by a Journey step. It maps callbacks into typed fields with kind, prompt, and executionMode, covering regular inputs, background callbacks, and native handoffs like FIDO. That lets the UI decide whether to render an input, run work automatically, or delegate to a native capability. It also exposes canSubmit, issues, and a prebuilt form.input object that can be passed directly to actions.next().

MFA is part of the same model. Passkeys, TOTP, push MFA, and device binding are implemented as dedicated packages that plug into the flow rather than forcing a separate native project or a second bridge layer.

Token storage uses the native secure store on each platform. Device signals and device-bound features are separate packages, so apps can add them only if they need them.

The TypeScript surface is intentionally strict. Nodes, fields, config, and errors are typed unions, so application code can narrow correctly.

What the SDK covers is only part of the story. The other part is how those capabilities are exposed to application code.

How we designed the API

A big part of the work was making sure the API stayed predictable from the React Native side, while still exposing the native capabilities underneath.

Factory functions, not classes

Every client is created with a factory function that returns a plain object. There is no new, no inheritance, and no this. Configuration is validated at creation time, and the native instance initializes lazily on the first call. The result composes cleanly into a context, ref, or module-level singleton.

A consistent client contract

All authentication clients, such as OIDC and Journey, share the same surface: start, next, user, refresh, revoke, and dispose. Return types are discriminated throughout, so TypeScript narrows correctly at every call site.

React hooks, standalone or with a provider

useJourney and useOidc return a [state, actions] tuple. A client can be passed directly, or the argument can be omitted, and the hook will read from the nearest provider.

A screen can use a client directly when the flow is local:

const [state, actions] = useJourney(journeyClient)

Or the application can provide the client higher in the tree and let screens read it from context:

// Root component
<JourneyProvider client={journeyClient}>
  <App />
</JourneyProvider>

The bridge: New Architecture and Classic, transparently

Every package supports both TurboModules and the classic bridge. The TypeScript layer resolves the correct native module at runtime, so application code does not need to handle either case. Moving an app to the New Architecture doesn’t require any changes to how the SDK is called.

In practice, that means the packages follow the same general patterns, while still allowing the app to work closer to native behavior when needed.

What developers can build with the SDK

The SDK is not prescriptive about your app’s structure. Because it covers the entire identity surface area, you have the flexibility to build:

Passwordless sign-on: Implement passkeys and biometrics, with a Journey fallback for seamless enrollment or account recovery.
Software TOTP: Enable users to enroll and generate verification codes directly inside the app instead of forcing them to switch to a separate authenticator.
Push MFA approval flows: Design custom approval flows that match the app’s design system rather than dropping users into a generic web view.
Device-bound sessions: Securely tie user credentials directly to a specific physical device.
Social and external IdP handoff: Let the SDK manage the browser steps, token exchange, and resulting session states.
Background device signal collection: Gather silent device signals as part of a Journey flow for real-time risk evaluation.

The following table maps those capabilities to the documented use cases and usage guides available today:

Use case or guide	Description
FIDO and passkeys	Passwordless sign-on with passkeys and biometrics
Push notifications	Push-based MFA approval flows
OATH one-time passcodes	Software TOTP enrollment and verification
Social sign-on	External IdP handoff and token exchange
Device binding	Binding credentials to a specific physical device
Device profiling	Background device signal collection for risk evaluation
Device management	User-facing device self-service flows
User self-service	Profile management and account recovery
Magic links	Resuming journeys via deep-linked magic links
Journey orchestration	Configuring, starting, and navigating authentication journeys
SDK customization	Logging, storage, and network request customization

How to get started

All packages are published to npm under the @ping-identity scope, so there’s nothing to configure beyond the standard registry.

The documented baseline targets React Native 0.80.1 and supports iOS 16.0+ and Android API 29+. For more information, refer to supported operating systems and browsers.

Install the packages the app needs. It is recommended to include the core package alongside the auth packages:

yarn add @ping-identity/rn-oidc @ping-identity/rn-journey @ping-identity/rn-core

ℹ️ Note: For teams evaluating the SDK, the sample app is one of the most useful starting points. The repository includes PingSampleApp, and the documentation positions it as the place where the SDK packages are exercised together. Follow our tutorial to get started!

What’s next

Version 1.0 targets teams building on PingOne Advanced Identity Cloud and PingAM — Journey orchestration, OIDC flows, token management, and MFA are all tested and supported against both platforms. If you’re running on either, this release is ready to use today.

The OIDC package also supports standard redirect-based flows against any OIDC-compliant authorization server, so teams not yet on a Ping Identity platform or that want an in-app browser redirect experience can use the React Native SDK.

Up next are:

React Native SDK agent skills: The goal is to make common setup work less repetitive: scaffold an authentication flow, wire Journey callbacks, configure OIDC, and generate a sample integration from a single prompt.
DaVinci support: The plan is to bring the same client and hook model used elsewhere in the SDK to PingOne DaVinci orchestration as that integration expands.

Resources

Securing agentic workflows with token exchange and workload identity

Tue, 21 Jul 2026 00:00:00 GMT

This post was originally published on Federico Carbone’s blog site.

Context

Agentic systems change the identity problem. The user can start the request, but the agent decides how to complete it. It can call tools, invoke other services, inspect intermediate results, and change the plan as the session progresses. That means the important question is no longer only “who is the user?” It is also “which agent or workload acted, on behalf of whom, and why was that action allowed?”

Traditional identity models typically divide identity into two categories: human users and workloads. Workloads often authenticate with service accounts, API keys, or client credentials. That works for simple automation, but it becomes weak for agentic flows that are delegated, dynamic and non-deterministic. Furthermore, if every downstream call only shows a generic service identity, the audit trail loses the real story. A protected API could see “the agent service called me,” but not that a specific agent acted for a specific user after a specific tool decision.

That is unsafe because accountability becomes partial. Security teams need to answer who did what, when, and why. Downstream systems need enough context to enforce fine-grained policies. Incident responders should not have to reconstruct a session by stitching together disconnected logs from the browser, portal, agent, and tools. The identity context should travel with the flow. The architecture needs a way to propagate both user identity and actor identity across hops, without collapsing everything into one broad user token or one generic service account.

This blog uses a dummy telco customer-support chatbot to show how Ping Identity can support a safer model. The business behavior is intentionally simple. The important part is the identity chain across the browser, the web application, the agent, the MCP server, PingFederate, and SPIRE.

The pattern is:

Use OAuth 2.0 Token Exchange to mint a new access token at each service boundary.
Use SPIFFE/SPIRE to give each workload an attested identity.
Use the workload JSON Web Token SPIFFE Verifiable Identity Document (JWT-SVID) as the token exchange actor token.
Let each receiving service validate a token minted for its own audience.

That gives us user delegation and workload identity in the same flow.

Why token exchange

RFC 8693 defines OAuth 2.0 Token Exchange. It describes a protocol for requesting and obtaining security tokens from OAuth authorization servers, including tokens that support delegation.

The important part for this demo is the request model. A client sends a subject_token, an actor_token, and asks for a token with a target audience and scope. The subject_token represents the party on behalf of whom the token is requested, while the actor_token represents the party receiving delegated rights. That maps naturally to agentic systems.

The user remains the subject. The portal and agent are actors. Each actor gets only the token it needs for the next hop. The receiving service can validate the audience, scopes, subject, and actor chain instead of guessing intent from a token minted for another resource.

This matters for three reasons:

Auditability: If an agent reads payment data, we want logs and tokens to show the user and the workload path, not just a generic service account.
Policy: PingFederate can allow the portal workload to request only an agent-audience token, and allow the agent workload to request only an MCP-audience token. The customer scopes can travel across the chain, but each token is still minted for the next workload. That is more precise than giving a backend service account broad standing access.
Containment: Reusing a user token across services spreads a bearer credential beyond its intended audience. Using a generic service account loses the user delegation context. Token exchange avoids both problems by minting a new, constrained token for the next resource.

Why SPIFFE and SPIRE

SPIFFE gives software components a standard way to identify themselves. A component can be an API, an agent, a worker, or any service running in the platform. Instead of saying “this is some pod” or “this is some service account,” SPIFFE gives it a stable identity string called a SPIFFE ID, for example spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/portal.

SPIRE is one implementation of SPIFFE. Its job is to check what a workload really is and then issue a short-lived credential for it. That check is what “attestation” means. In Kubernetes, SPIRE can look at platform facts such as the namespace, pod labels, and service account. If those facts match the configured rules, SPIRE gives the workload a credential.

That credential is called an SVID, or SPIFFE Verifiable Identity Document. In simpler terms, it’s a signed identity document for the workload. When the portal gets a JWT-SVID, it’s getting a signed token that says “this workload is the portal service” and includes the portal SPIFFE ID. When the agent gets one, it says “this workload is the agent service.”

In this project, the portal and agent request JWT-SVIDs from the SPIFFE API. Those JWT-SVIDs are short-lived workload credentials. The services send them to PingFederate as actor_token values during token exchange.

That gives PingFederate two independent facts:

The subject_token is the incoming OAuth access token representing the user.
The actor_token is the SPIFFE JWT-SVID proving which workload is asking for the next token.

No shared secret is needed between the workload and PingFederate. The trust is based on PingFederate validating the JWT-SVID issuer, signature, audience, and SPIFFE subject.

Demo architecture

The browser uses Authorization Code + PKCE with PingFederate. After that, the server-side path uses token exchange with SPIFFE JWT-SVID actor tokens.

Each token exchange produces a new access token targeted at the next service in the chain, with a different audience while preserving the delegated user identity.

%%{init: {'flowchart': {'curve': 'linear'}}}%%
flowchart LR
    B["Browser SPA"]
    P["Portal API"]
    A["Agent"]
    M["MCP Server"]
    PF["PingFederate"]
    S["SPIRE / SPIFFE"]

    B -->|" authorize + PKCE "| PF
    PF -->|" User Token<br/>sub=User<br/>act=-<br/>aud=Portal API "| B
    B -->|" API call (User Token) "| P
    P -->|" fetch JWT-SVID "| S
    P -->|" token exchange<br/>subject=User Token<br/>actor=Portal JWT-SVID "| PF
    PF -->|" Agent Token<br/>sub=User<br/>act=Portal API<br/>aud=Agent "| P
    P -->|" A2A call (Agent Token) "| A
    A -->|" fetch JWT-SVID "| S
    A -->|" token exchange<br/>subject=Agent Token<br/>actor=Agent JWT-SVID "| PF
    PF -->|" MCP Token<br/>sub=User<br/>act=Agent<br/>aud=MCP Server "| A
    A -->|" MCP tool call (MCP Token) "| M

The main components are:

Browser SPA: Signs the user in with PingFederate and calls the portal API.
Portal API: Validates the browser token, exchanges it for an agent token, and forwards the user request to the agent.
Agent: Validates the agent token, chooses MCP tools, exchanges the token again for the MCP audience, and calls the MCP server.
MCP server: Validates the MCP token and enforces tool scopes before returning customer data.

PingFederate: issues the User Token, Agent Token, and MCP Token, and validates the SPIFFE JWT-SVID actor token during token exchange.

SPIRE: Issues JWT-SVIDs to Kubernetes workloads through the SPIFFE Workload API.

Expected flow

A normal support request follows this path:

The user signs in through the Browser SPA.
PingFederate issues a User Token for the Portal API to the Browser SPA.
The Browser SPA calls POST /api/chat on the Portal API with the User Token.
The Portal API validates the User Token.
The Portal API fetches a portal JWT-SVID from SPIRE / SPIFFE.
The Portal API sends a token exchange request to PingFederate with the User Token as the subject token and the portal JWT-SVID as the actor token.
PingFederate issues an Agent Token to the Portal API for the Agent audience.
The Portal API calls POST /a2a/message on the Agent with the Agent Token.
The Agent validates the Agent Token and chooses MCP tools.
The Agent fetches an agent JWT-SVID from SPIRE / SPIFFE.
The Agent sends a token exchange request to PingFederate with the Agent Token as the subject token and the agent JWT-SVID as the actor token.
PingFederate issues an MCP Token to the Agent for the MCP Server audience.
The Agent calls the MCP Server with the MCP Token.
The MCP Server validates audience and scopes before returning profile or payment data.

The video below shows the demo from the application point of view. It starts with a signed-in user invoking the chatbot, then opens the token flow view where the tokens are surfaced for demo purposes:

At each hop, the subject remains the user who initiated the action.
Each exchange uses the current access token as the subject token and the workload JWT-SVID as the actor token.
Scopes are reduced as the request moves from the Portal API to the Agent and then to the MCP Server.

Your browser does not support the video tag.

Workload identity model

The Kubernetes manifest defines service accounts for the three workloads and ClusterSPIFFEID resources that map pods to SPIFFE IDs:

spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/portal
spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/agent
spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/mcp

The portal and agent mount the SPIFFE Workload API socket:

volumeMounts:
  - name: spiffe-workload-api
    mountPath: /spiffe-workload-api
    readOnly: true
volumes:
  - name: spiffe-workload-api
    csi:
      driver: csi.spiffe.io
      readOnly: true

After the socket is mounted, the application can call the SPIFFE Workload API from inside the pod and ask for a JWT-SVID. The requested JWT-SVID audience is the value PingFederate expects for token exchange validation.

The client IDs intentionally match the SPIFFE IDs:

API_OAUTH_CLIENT_ID=spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/portal
AGENT_OAUTH_CLIENT_ID=spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/agent
SPIFFE_JWT_SVID_AUDIENCE=pingfederate-token-exchange

That gives PingFederate a direct mapping between the OAuth token-exchange client and the attested workload identity.

Fetching the JWT-SVID

The software fetches a JWT-SVID before calling the PingFederate token endpoint. The important request fields are the SPIFFE ID and the audience. In the demo, this is done with the SPIFFE/SPIRE Python SDK through WorkloadApiClient:

from spiffe import WorkloadApiClient
from spiffe.spiffe_id.spiffe_id import SpiffeId

socket_path = "unix:/spiffe-workload-api/spire-agent.sock"
audience = "pingfederate-token-exchange"
portal_spiffe_id = "spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/portal"

# Retrieve the JWT-SVID from the SPIFFE Workload API using the SPIFFE/SPIRE SDK.
with WorkloadApiClient(socket_path=socket_path, default_timeout=5.0) as client:
    svid = client.fetch_jwt_svid(
        audience={audience},
        subject=SpiffeId(portal_spiffe_id),
        timeout=5.0,
    )

portal_jwt_svid = svid.token

Decoded, the portal JWT-SVID looks conceptually like this:

{
  "iss": "https://oidc-discovery.ping.demo",
  "sub": "spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/portal",
  "aud": ["pingfederate-token-exchange"],
  "exp": 1782774000
}

The agent gets its own JWT-SVID with its own SPIFFE ID:

{
  "iss": "https://oidc-discovery.ping.demo",
  "sub": "spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/agent",
  "aud": ["pingfederate-token-exchange"],
  "exp": 1782774000
}

These are not API access tokens. They are workload identity documents used as proof of the actor during token exchange.

Building the token exchange request

The two server-side exchanges use the same RFC 8693 request shape:

Portal to agent: the subject token is the browser access token and the actor token is the portal JWT-SVID.
Agent to MCP: the subject token is the agent access token and the actor token is the agent JWT-SVID.

For example, the portal-to-agent exchange is a form post to the PingFederate token endpoint. The incoming browser access token becomes the subject_token, and the portal JWT-SVID becomes the actor_token:

from urllib.parse import urlencode

import httpx

token_endpoint = "https://pingfederate.example.com/as/token.oauth2"
portal_client_id = "spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/portal"
agent_resource = "spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/agent"
agent_scopes = "customer:profile:read customer:payments:read"

body = urlencode({
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": browser_access_token,
    "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "actor_token": portal_jwt_svid,
    "actor_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "scope": agent_scopes,
    "resource": agent_resource,
    "client_id": portal_client_id,
})

headers = {
    "accept": "application/json",
    "content-type": "application/x-www-form-urlencoded",
}

async with httpx.AsyncClient(timeout=20) as client:
    response = await client.post(token_endpoint, content=body, headers=headers)
    response.raise_for_status()

agent_token = response.json()["access_token"]

Exchange one: portal to agent

The browser starts with a user token for the portal API:

{
  "iss": "https://pingfederate.example.com",
  "aud": "customer-support-agent-portal-api",
  "sub": "user-123",
  "scope": "openid profile customer-support-agent:portal-api:chat customer-support-agent:customer:profile:read customer-support-agent:customer:payments:read",
  "customer_id": "cust-1001"
}

Before the portal calls the agent, it exchanges that browser token for an agent token. The request uses:

subject_token=<browser access token>
actor_token=<portal JWT-SVID>
audience=spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/agent
scope=customer-support-agent:customer:profile:read customer-support-agent:customer:payments:read
client_id=spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/portal

The issued token is for the agent:

{
  "iss": "https://pingfederate.example.com",
  "aud": "spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/agent",
  "sub": "user-123",
  "scope": "customer-support-agent:customer:profile:read customer-support-agent:customer:payments:read",
  "client_id": "spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/portal",
  "act": {
    "sub": "spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/portal"
  }
}

The agent validates this token against its own SPIFFE ID audience and rejects any token not minted for the agent.

Exchange two: agent to MCP

When the agent needs customer data, it exchanges the agent token for an MCP token. The request uses:

subject_token=<agent access token>
actor_token=<agent JWT-SVID>
audience=spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/mcp
scope=customer-support-agent:customer:profile:read customer-support-agent:customer:payments:read
client_id=spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/agent

The issued token is for the MCP server:

{
  "iss": "https://pingfederate.example.com",
  "aud": "spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/mcp",
  "sub": "user-123",
  "scope": "customer-support-agent:customer:profile:read customer-support-agent:customer:payments:read",
  "client_id": "spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/agent",
  "act": {
    "sub": "spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/agent",
    "act": {
      "sub": "spiffe://ping.demo/ns/spiffe-token-exchange-demo/sa/portal"
    }
  }
}

The MCP server is now seeing a token that was minted for the MCP resource, not a reused portal or agent token. The token also preserves the actor chain: the user is still the subject, the agent is the immediate actor, and the portal remains visible as the previous actor. That chain can be used for audit logs and for fine-grained policy decisions such as “allow payment data only when this user delegated through this agent workload.”

The MCP server still enforces authorization at the tool boundary. The profile tool requires customer-support-agent:customer:profile:read. The payment tool requires customer-support-agent:customer:payments:read. Token exchange gets the request to the right resource with the right scopes; the resource server still validates and enforces them.

Token exchange logic in PingFederate

PingFederate is the authorization server that validates the incoming user token, validates the workload actor token, maps the relevant attributes, evaluates token-exchange policy, and issues the next access token. One important point is that the subject token and actor token can come from different issuers. In this demo, the subject token is a PingFederate access token and the actor token is a SPIRE JWT-SVID. PingFederate can validate each token independently, then combine the resulting user and workload context in the token exchange policy.

%%{init: {'flowchart': {'curve': 'linear'}}}%%
flowchart LR
    ST["<b>Subject token validator</b><br/>(validates user token<br/>issuer, signature, audience, scopes)"]
    AT["<b>Actor token validator</b><br/>(validates workload JWT-SVID<br/>issuer, signature, audience, SPIFFE ID)"]
    POLICY["<b>Token Exchange Processor Policy</b><br/>(maps validators<br/>and inbound attributes)"]
    ACCESS["<b>Access token mapping</b><br/>(sets claims, scopes<br/>and actor chain)"]
    ISSUER["<b>Token issuer</b><br/>(issues next-hop<br/>access token)"]

    ST -->|" user claims "| POLICY
    AT -->|" workload claims "| POLICY
    POLICY -->|" inbound claims "| ACCESS
    ACCESS -->|" token contract "| ISSUER

At a high level, the demo needs three OAuth clients:

A browser SPA client for Authorization Code + PKCE.
A portal token-exchange client whose client ID is the portal SPIFFE ID.
An agent token-exchange client whose client ID is the agent SPIFFE ID.

The GitHub repository will contain the PingFederate configuration details. The main PingFederate OAuth configuration area is documented in the PingFederate OAuth configuration guide.

When to use this pattern

This pattern is useful when a user-facing app calls an intermediate service, and that service calls more protected backend tools or APIs. It is especially useful when those intermediate services are workloads running in Kubernetes and can receive SPIFFE identities automatically.

Use it when you want:

Resource-specific access tokens at every service boundary.
Workload identity without distributing static client secrets to pods.
A visible actor chain for delegated calls.
Tighter control over which workload can request which downstream audience and scopes.

Do not use it as a substitute for API authorization. The final resource server still needs to validate tokens and enforce scopes, claims, and object-level rules. Token exchange gives the resource a better token to validate; it does not remove the need to validate it.

Key takeaways

The point of the demo is not that an agent can call a tool. The point is that every call crosses the boundary with the right identity material.

The browser token is for the portal. The portal proves its workload identity with a SPIFFE JWT-SVID and gets an agent token. The agent proves its workload identity with its own JWT-SVID and gets an MCP token. The MCP server receives a token minted for its audience and enforces tool scopes before returning data.

That is the core pattern: user delegation travels through OAuth token exchange, workload identity travels through SPIFFE, and each service validates only the token meant for itself.

One thing this article does not solve is proof of possession. The exchanged tokens are still bearer tokens. A follow-up article should explore binding issued tokens to a key or mTLS channel so possession of the token string alone is not enough to use it.

Ping CLI 1.0: A Command Line Utility for the Ping Platform

Thu, 09 Jul 2026 00:00:00 GMT

We’re excited to share that Ping CLI has reached version 1.0, a long-term supported, generally available release. Ping CLI is a command-line tool that connects to multiple Ping Identity services simultaneously, allowing you to manage them through one consistent, developer-first terminal interface.

Ping Identity has a broad platform, and Ping CLI enables standard management patterns through a generalized, consistent terminal interface. Use it to promote configuration from staging to production, validate that your apps are set up correctly before a release, script a repeatable setup, or explore an API interactively with common conventions. For developers who live in the terminal, it means one management interface across your configured services, a logical set of commands, and configuration you can export, version, and share.

This article is an introduction and will highlight what Ping CLI is, what you can do with it right now, and where it’s headed.

Where we’ve come from

CLIs at Ping have taken many forms and have evolved incrementally for their individual use cases. As our platform capabilities have expanded and become better integrated, we saw the need for a single terminal experience that allows developers to manage configuration from the terminal, as well as bundle configuration into configuration-as-code packages and reliably deploy those packages to higher environments.

We started the unified CLI journey with Ping CLI in late 2024 as an evolution of pingctl and, in its initial experimental releases, you gave us valuable feedback that helped us steer toward our current milestone release.

Version 1.0 represents our commitment to our developer community: to meet developers where they’re at, whether that’s in the terminal, the web admin consoles, or using agents. The CLI is now fully supported and can be built into workflows with confidence.

What it is used for

The CLI serves three main use cases:

Developers in the terminal
Deterministic automation and CI/CD
Headless, AI-first use cases

Here we briefly discuss all three, but keep an eye out for future deep-dive articles.

Developers in the terminal

The CLI is designed to be intuitive and easy to use for developers that live in the terminal. If you prefer the terminal to the browser for quick (or extensive) configuration changes and shell scripting for rapid prototyping and personal automation, then the CLI presents an efficient alternative to administration in the web console.

Tip: use the CLI’s shell completion to quickly build commands with Tab autocomplete.

Deterministic automation and CI/CD

GitOps-based CI/CD is an industry standard method of promoting configuration between environments in an automated, auditable, and highly governed way. Where customers have invested in GitOps CI/CD pipelines, there has to be a repeatable, idempotent way to:

Export Ping Identity configuration as code.
Organize exported configuration as code within the filesystem.
Version control within source control (such as Git).
During CI/CD workflow execution, apply that versioned configuration to the next environment in the deployment pipeline.

There is no one-size-fits-all approach to CI/CD, but there are industry-standard patterns of use, so the CLI provides the toolkit to natively integrate with a wide range of CI/CD workflow orchestrators, with both imperative (“these are the actions to take to get to the end state”) and declarative (“this is the end state I want, take whatever actions are needed”) methods of configuration management with the ability to integrate with OpenTelemetry collectors for deep observability.

Headless, AI-first use cases

Ping CLI is designed to be natively understood by coding and configuration agents. The ability to understand and use CLIs is inherent in the training of many large language and small language (LLM and SLM) models, meaning they know how to read and run CLIs and interpret the output, to determine the actions to take.

By logically laying out the command structure with brief but effective --help text, agents can crawl the CLI to be able to compose commands to achieve an outcome. When paired with developer documentation (such as the Developer Use Cases), the agent can compose commands, with data payloads, to accelerate the development of use cases.

Tip: Use the bundled ping-cli-usage Agent Skill so the agent doesn’t need to crawl the --help texts to understand how to use the CLI.

Agents can use the Ping CLI to augment the CI/CD and configuration promotion workflows, by exporting configuration, raising requests to change the configuration-as-code within the GitOps pipeline with Pull Requests (as coding agents do today), and orchestrating the CI/CD workflows to reduce repetitive work by DevOps developers and administrators.

Refer to Build with AI developer documentation for more information on how agents can use the Ping CLI alongside Agent Skills and documentation for agents.

What you can do today

We’re on our journey to build out the CLI capability and build a truly unified CLI experience that allows rich management features covering all of Ping Identity’s product capabilities. We’ve started by releasing a solid foundation, with configuration management features for PingOne and universal services:

DaVinci
PingOne MFA
PingOne Protect
PingOne Verify
PingOne Authorize
PingOne Credentials

Let’s take a look at some of the new features available in 1.0!

Interactive guided setup

The Ping CLI now provides a guided setup process. Use pingcli init to walk you through first-time configuration, including connecting products and services and setting some initial preferred settings.

Tip: If you’re looking to just connect one set of products, each platform has its own guided setup process. To specifically connect PingOne with the guided setup interface, use pingcli pingone init

The pingcli init command

Authenticate across multiple services

We’ve streamlined the login process for developers using interactive logins using the browser. After connecting products to the CLI through the interactive setup, login for all can be performed with a single command.

The pingcli auth login command

The simplicity of managing admin sessions, as one CLI session, allows developers to spend less time authenticating and more time getting the job done.

Ping CLI supports the login methods you’d expect:

Service accounts for automation: for use with CI/CD pipelines and fully automated workflows.
Interactive login flows with silent token refresh: where supported, interactive logins are for developers using the CLI directly in the terminal. IAM administrators can apply strong policies to CLI users, including the use of admin MFA.

Where available, the CLI stores tokens safely in your OS keychain, or ephemerally where keychains are not available (such as when running in an OCI container).

Tip: Each platform has its own auth management. If you’re looking to just manage PingOne without any other connected product, use pingcli pingone auth login.

Manage configuration across products and services

Each product and service gets its own command namespace. PingOne lives under pingcli pingone, and each resource exposes a consistent set of verbs:

create: to create new resources within an environment
apply: an idempotent way of maintaining a resource’s configuration
get: to return the full configuration of a resource by its identifier
list: to return multiple resources of the same type (with a filter, where the API allows)
replace: to overwrite a resource with new configuration
delete: to remove a resource from the environment
template: generates a JSON body skeleton as a starting point for manual configuration-as-code development

Tip: Most commands have aliases to make life easier, giving users and agents command patterns that suit them best. For example, pingcli p1 is an alias of pingcli pingone. The create verb also has an alias of new, the update verb has an alias of replace, list has an alias of ls, among others. Try out what suits you. If we miss an obvious command alias, tell us with the pingcli feedback command.

The pingcli pingone application example commands

The universal services (MFA, Verify, Protect, Credentials, Authorize, and DaVinci) are addressable directly by service, or as part of their platform for convenience:

Example showing how DaVinci flows are managed

The same command shapes carry across resources, services, and products, so the muscle memory you build in one place transfers everywhere. Resources deep-nest naturally too:

pingcli pingone applications sop-assignments list --environment-id $ENVIRONMENT_ID --application-id $APPLICATION_ID
pingcli pingone groups group-nestings list --environment-id $ENVIRONMENT_ID --group-id $GROUP_ID

Profiles for every environment

Real workflows span sandboxes, development, testing, staging, and production. Some users will need to be operating on multiple environments, or switching contexts depending on what is needed in the moment.

Configuration profiles let you keep those configurations side by side and allows quick switching between them globally or per command:

Example showing configuration profile use

Configuration is persisted in (and can be loaded by) a readable YAML file, and every setting can be overridden by an environment variable, which is ideal for easily injecting configuration and secrets into CI/CD pipelines at runtime.

Make raw API calls when you need them

The managed resources cover the common cases and are being built out over the next few releases, but sometimes you need the full surface of an API. This is especially useful if you’re using a prerelease product feature that’s not yet built in as a native command, or you need more control than a native resource command can provide.

Each product exposes an api command giving you a cURL-like experience with authentication, base URL, and environment details filled in for you automatically:

Example showing custom API commands

Output built for scripting

Ping CLI speaks both human and machine. Every command accepts -O/--output-format with four modes:

text: The default, formatted for reading at the terminal.
json: A single structured document, ideal for jq or JMESPath queries using the --query parameter.
ndjson: Newline-delimited JSON (one record per line), ideal for jq, grep, awk, and for streaming and sending to log pipelines.
ndjson-typed: Newline-delimited JSON with type metadata per record, ideal for jq and sending to log pipelines that need a consistent structure.

For extracting exactly the fields you need, --query takes a JMESPath expression directly rather than piping to another tool. For transformations that go beyond what JMESPath supports, pipe to jq.

Using the --query parameter and piping output to jq example

For pipelines that must react to results, --no-color keeps logs clean, while --detailed-exitcode distinguishes success (0), error (1), and success-with-warnings (2) so a CI step can branch on the outcome as well as text.

Quality-of-life extras

Shell completion: pingcli completion zsh (also bash, fish, powershell).
AI agent skills: pingcli agent-skills install / list for teams building agent-assisted workflows.
OpenTelemetry integration: For deep observability into CLI actions.

Getting started

Ping CLI ships as a signed release for macOS, Linux, and Windows across common architectures, and as a Docker image. To get started for PingOne:

Follow the PingOne getting started guide in the CLI documentation
Run the guided initialization walkthrough (which authenticates you at the end): pingcli init
List the environments you’re able to view: pingcli pingone environments list

Full installation instructions, the complete command reference, and configuration guides live on the Ping Identity Developer Portal.

What’s next

Version 1.0 is a commitment to stability: a foundation you can build automation on with confidence. But it’s a milestone, not a destination. The vision is a genuinely universal tool, one that speaks to every Ping service and platform with the same fluency it speaks to PingOne today.

As a preview, in the pipeline we have:

Advanced Identity Cloud configuration management.
PingFederate configuration management (for both private tenant and software).
Defined declarative import/export tools.
Refined processes for exporting and generating configuration-as-code (as an evolution of the experimental platform export command in Ping CLI version 0.8).
Enhanced headless AI features, enabling more streamlined use with configuration agents.
The ability to introspect environments and debug issues.
The ability to extend with custom plugins. And more to come.

Can we improve? Your feedback matters

Keep an eye out for future releases that enhance the capabilities of the CLI even further. Your real-world feedback matters. As you use the Ping CLI, tell us what you need.

Is there a command alias you’re finding is missing? Is there a feature you’d like included? Is there a use case we can improve upon?

Run pingcli feedback to reach us directly, or open an issue on GitHub to track a request or vote on features.

And finally

Look out for upcoming articles where we deep dive into Ping CLI with headless, AI-first configuration using agents, building a CI/CD workflow with Ping CLI, and generating configuration-as-code. Welcome to Ping CLI 1.0!

Used the CLI to build something great? Tell the community! Join the discussion on the Ping Identity developer community.

Multi-Brand administration in PingOne with new group-level role assignments

Mon, 06 Jul 2026 00:00:00 GMT

As you scale PingOne to support richer, multi-brand experiences, a familiar question tends to pop up: how do you delegate administration cleanly when the same end user belongs to many different business lines?

In this post, we’ll walk through what group-level assignments of administrative roles are, how they behave in PingOne, and the kinds of real-world problems they’re designed to solve.

Background: How PingOne administration worked before group level assignment

PingOne uses a hierarchy of organization → environment → population / environment → application to determine administration over different resources as shown below, before the new group-level assignment type.

PingOne administration hierarchy — role assignments before group-level support

A few important concepts:

Administrator environment: Each organization comes with a pre-created “administrators” environment. This is where we recommend managing platform administrators, separate from end users. (There are cases where delegated admins should live alongside end users)
Built-in vs custom roles: Built-in roles cover common platform responsibilities (for example, Identity Data Admin and Help Desk Admin), while custom roles let you combine granular permissions to reach least privilege.
Levels: Roles can be assigned at different levels (organization, environment, population, and — now — groups) so that an admin’s power is limited to exactly what they should manage. This can be done across environments so that a single admin identity has roles over other environments.

Today, population-level roles are the main way to segment administrator access to different user communities (for example, employees and contractors, or region A and region B) where a user can only exist in a single population. That works well for many B2B and workforce scenarios, but it starts to show its limits in some high-scale consumer use cases.

Learn more in Delegated Administration in PingOne for a full background on delegated admin and a breakdown of Populations and Groups in PingOne.

The customer problem: shared identity, many brands

If a large media company runs many consumer applications under different sub-brands, each brand has its own app and each app has its own help desk, but end users sign on with a single shared credential across all of them.

They need to:

Let each brand’s help desk reset passwords, manage MFA devices, and troubleshoot issues only for their brand’s users.
Avoid creating separate identities per brand, because the user experience should be “one login, many apps”.
Avoid duplicating users into separate populations just to drive administration, because users commonly span multiple brands and populations aren’t designed for this overlap.

In other words, they need delegated administration segmented by groups, not just by populations.

How group-level roles behave

With group-level assignment, the goal is for the model to feel predictable and intuitive:

If an admin has a role over a population, and a user belongs to that population, the admin can manage that user — just like today.
If an admin has a role over a group, and the user is in that group, the admin can manage that user — even if the user is also in other groups or populations.
If the admin has both population and group-level assignments, the effective access is the union: if the user matches either level, the admin can manage them.

Practically speaking: it’s enough for the admin to have an assignment at either the population level or group level to manage a given user.

This is exactly what customers like the multi-brand help desk scenario need: “if this user is in any of my brand groups, I should be able to help them, even if they also belong to other brands.”

PingOne administration hierarchy with group-level role assignment support added

Tackling user creation

Group-level assignments introduced a chicken and egg problem: how can an admin create a user and then manage them when in PingOne you cannot assign a user to a group at creation time?

To solve this problem, we’ve introduced the ability to assign a user to a static group when creating them. This ensures that if an admin needs to create a user manually, they can do so and still manage them afterwards.

There are some caveats to keep in mind:

If an admin creates a user in a group (given that they have a role assignment over that group) that is associated with a population, the user is created in that population.
If an admin created a user in a group not associated with a population, then the user is created in the default population if there is one.
- If there is no default population (not recommended) and the admin is in the same environment, the user is created in the same population as the admin.
- In the event the admin is not in the same environment, user creation will fail.

In most cases the above isn’t a problem, but it is important to understand in more complex organizations.

Some example scenarios

With group-level assignments, you can model administration much more closely to how your business is structured.

1. Brand help desks

Scenario

A media company runs multiple fan sites and apps under different artist or label brands. Each brand has its own help desk team, but fans use the same account everywhere.

The multi-brand identity problem — one user identity, multiple brand help desks, separate support boundaries needed

How to set it up

Create a group for each brand (or set of brands) your support team owns. For example, Brand A Users, Brand B Users, VIP Fans, and so on.
Assign a Help Desk Admin (or equivalent custom role) at the Brand A Users Group level and so on.

Brand Help Desk access via group roles — Help Desk A can manage Alex through a group-scoped role; Help Desk B has no assignment and cannot

What it does

The Brand A help desk can:
- Reset passwords
- Manage MFA devices
- Perform recovery actions
only for users in the Brand A group — even if those users also belong to other brands or global groups.

This lets you keep a single, clean user identity while still giving each support team exactly the access they need.

2. Specialized admin teams

Scenario

You have a small, expert team that handles high-risk operations, such as managing MFA devices for executives or handling escalated recovery flows.

How to set it up

Create groups like Executives, High-Risk Accounts, or Escalated Support.
Build a narrow custom role focused on the operations this team is allowed to perform (for example, MFA device management and account recovery only).
Assign that custom role at the high-risk group level.

What it does

The specialized team can perform sensitive operations only for the users you’ve explicitly grouped, without granting those permissions over the entire population or environment.

Designing your model with group-level assignments

When you’re planning how to use group-level assignments, a few guiding questions help:

How do I delegate based on my organizational structure? Think of your organizational structure and goals first, then align administration to it using groups and populations for finer delegation and environment or organization for those needing full visibility and control.
What’s the “home” for my admins? Generally continue to use the administrators environment as the home for admin identities, and then assign roles over the right mix of environments, populations, and groups from there. If your delegated admins are also end users, consider keeping them in the production environment rather than separate. Think about how you want to separate or combine the administrative responsibilities for a person from their end user identity.

The end result is an administration model that reflects how your teams actually work day to day, while still keeping a single, consistent identity for every user.

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community!

Securing ChatGPT apps with OAuth 2.0 and CIBA

Wed, 24 Jun 2026 00:00:00 GMT

This post was originally published on Federico Carbone’s blog site.

Context

Enterprises are now building apps and tools for personal agents, and those agents rarely operate in a single trust model. Some capabilities need access to public or low-friction resources. Others need the agent to act on behalf of a signed-in user to reach private data or protected APIs. Some actions go further and require explicit user approval before the agent can complete them.

In this blog, I describe how the PingOne platform can be used to secure a personal agent through a demo ChatGPT hotel booking app that uses OAuth 2.0, PingOne Authorize, Token Exchange, and CIBA to move from public access to authenticated access and then to transaction approval.

MyHotels demo

MyHotels is a demo ChatGPT app built with the OpenAI Apps SDK. It lets a user search for hotels, ask for member-only pricing, and start a booking that requires end-user approval before it completes. I use this demo application to show how Ping Identity can protect a ChatGPT personal agent when that agent needs to move across different trust levels.

The following diagram shows the high-level logical architecture for the demo.

%%{init: {'flowchart': {'curve': 'linear'}}}%%
flowchart LR
    U["User"] --> CG
    U --> P1

    subgraph CG["ChatGPT Host Runtime"]
        direction TB
        CORE["ChatGPT"]
        WR["Widget Runtime\n(runs Widget UI)"]
    end

    subgraph MCP["MCP Server"]
        direction TB
        TOOLS["Tools"]
        RES["Resources\n(publishes Widget UI)"]
    end

    API["Backend API"]
    P1["PingOne"]

    CORE --> TOOLS
    CORE --> RES
    CORE --> WR
    CORE --> P1

    MCP --> API
    MCP --> P1

MyHotels logical architecture

User: interacts with ChatGPT and the mounted widget to search hotels, request member rates, and approve or finalize booking actions. The user also signs in and completes approval prompts through PingOne.
ChatGPT Host Runtime: discovers MCP tools, resources, and authentication requirements; calls MCP tools on behalf of the user; reads widget resources; mounts the widget in its sandboxed runtime; and uses PingOne during the OAuth flow for protected MCP tools.
Widget Runtime: runs the MyHotels widget UI inside ChatGPT and calls tools back through ChatGPT.
MCP Server: exposes the hotel tools, publishes the widget HTML as an MCP resource, calls PingOne Authorize for policy decisions, exchanges tokens for backend API access, starts CIBA approval when policy requires end-user consent, and calls the backend hotel API.
Backend API: owns the demo hotel business surface, including the hotel catalog, member-rate access, booking quotes, booking intents, and mocked booking confirmation.
PingOne: provides the identity and authorization services used by the demo, including agent registration, user authentication, token exchange, policy decisions, and CIBA-based end-user approval.

End user experience

The following videos demonstrate the end-user experience. First, the no-session journey shows what happens when the user starts from a fresh ChatGPT conversation and crosses from a public flow into a protected one. Second, the existing-session journey shows the same general flow when the user already has an authenticated session and can move more quickly into protected actions:

For this demo, payment details are assumed to already be on file with MyHotels. ChatGPT does not collect or submit card data. After the required authorization checks are satisfied, the backend booking service is the component that completes the mocked payment and confirms the booking.

No-session journey:

Your browser does not support the video tag.

Existing-session journey:

Your browser does not support the video tag.

The following video shows the booking flow when the policy uses transaction thresholds: bookings below 200 EUR proceed without additional approval, bookings above 200 EUR require user approval, and bookings above 1000 EUR are denied.

Your browser does not support the video tag.

How ChatGPT apps work

At a high-level, ChatGPT is the host runtime, and the demo app exposes capabilities through MCP tools and resources. When ChatGPT decides to call a tool such as hotel search, it sends the tool request to the MCP server. When a tool response includes an output template, ChatGPT reads the matching resource and mounts the widget UI inside its own runtime.

The tool surface is small and intentional:

search_hotels
search_hotels_member_rates
prepare_booking
finalize_booking

The widget is delivered as the MCP resource ui://widget/myhotels-widget.html. The widget is not just a public web page that ChatGPT opens. It is a resource served through MCP and mounted by ChatGPT when a tool response references it through openai/outputTemplate.

After mounting, the widget uses the window.openai bridge to interact with ChatGPT. In this project, that bridge is used in two different ways:

sendFollowUpMessage(...) to ask ChatGPT to call the protected member-rates tool
callTool(...) to invoke booking-related tools directly from the widget

That gives the app a useful split:

ChatGPT remains the orchestrator
the widget becomes the interactive UI surface
the backend systems stay behind the MCP boundary

The Identity Provider

At a high-level, Ping Identity plays four different roles in this demo. First, PingOne supports user authentication for ChatGPT when the app crosses into protected functionality. Second, the MCP server uses PingOne Authorize to evaluate each tool call against policy. Third, the MCP server uses OAuth token exchange to obtain a backend API token with the correct audience and scope. Fourth, PingOne supports the CIBA approval flow used by the MCP server for booking approval:

PingOne handles user sign-in
PingOne Authorize decides whether the tool call should be allowed
token exchange gives the backend API a token minted for its own resource
CIBA handles higher-friction approval when policy requires it

PingOne Authorize

The current demo does not rely only on OAuth scopes at the MCP layer. Every tool call is sent to PingOne Authorize with a payload that identifies the MCP service, the requested tool, selected request parameters, and the inbound ChatGPT bearer token, so that PingOne Authorize can decide whether the tool call should be allowed.

That lets the MCP server enforce a mixed model:

search_hotels remains available to unauthenticated users so the public hotel catalog can be searched without sign-in
search_hotels_member_rates is allowed only when the request is initiated by a user who is allowed to access ChatGPT, the actor context shows the ChatGPT connector acting on behalf of that user, the token is intended for the MCP resource, and the token carries the correct scope
prepare_booking is allowed only when the same user, actor, audience, and MCP booking-scope checks pass, and the decision also evaluates quote attributes such as totalPrice and currency
finalize_booking is allowed only when the same protected-user, actor, audience, and scope checks pass
any MCP request that does not satisfy one of those allowed patterns is denied

For booking, the important point is that policy is not binary. The quote amount changes the outcome:

below 200 EUR: permit
above 200 EUR: permit with a human-in-the-loop obligation
above 1000 EUR: deny

So in the current design, PingOne Authorize decides whether booking is allowed immediately, requires explicit user approval, or should be blocked entirely.

Token exchange

The ChatGPT-facing token is meant for the MCP surface. The backend API is a different protected resource with its own audience and scopes. Instead of forwarding the original token and overloading its meaning, the MCP server exchanges it for a backend API token.

This gives us clearer boundaries:

ChatGPT gets a token for the MCP resource
the MCP server gets a token for the backend API resource
the backend validates a token that was actually minted for it

In the current configuration, the ChatGPT-facing MCP token can look like this:

{
  "aud": "myhotels-hotelmcp",
  "sub": "user-123",
  "given_name": "Alice",
  "groups": ["ChatGPT User"],
  "act": {
    "sub": "chatgpt-client-id"
  }
}

In this demo, the exchanged backend token can look like this:

{
  "iss": "https://auth.pingone.../as",
  "aud": "myhotels-hotelapi",
  "sub": "user-123",
  "scope": "my-hotels:api:member_rates",
  "client_id": "mcp-token-exchange-client-id",
  "act": {
    "sub": "mcp-token-exchange-client-id",
    "act": {
      "sub": "chatgpt-client-id"
    }
  }
}

There are two important things in these tokens.

First, the token audiences and scopes stay separated. The ChatGPT-facing token is for the MCP resource. The exchanged token is for the backend API and carries one of the backend API scopes such as my-hotels:api:member_rates or my-hotels:api:book.

Second, the token preserves an actor chain. The first token already identifies the ChatGPT client as the acting party. After exchange, the subject is still the user, user-123, but the token now also shows that the MCP token-exchange client acted on behalf of the original ChatGPT client. That is exactly the kind of traceability we want when a personal agent triggers downstream API calls through an intermediary service.

CIBA

In many architectures, the client is the component that initiates CIBA. In this demo, we moved it to the MCP server rather than the ChatGPT client. We still wanted approval to be bound to a concrete business transaction, but we do not control the ChatGPT runtime like a conventional first-party client. The MCP layer is therefore the practical control point: it has the user context, it receives the policy obligation from PingOne Authorize, it can initiate approval with PingOne, and it can coordinate the protected call path to the backend API.

The backend still owns the booking intent and its lifecycle. The MCP server starts CIBA, stores the auth_req_id, and maps it to the server-side transaction ID returned by the backend. The widget only knows the transaction ID and polls for status updates.

The user journeys in detail

1. Public hotel search

The simplest journey starts with a natural-language request such as “show me hotels in Milan”.

ChatGPT calls search_hotels on the MCP server. The MCP server first asks PingOne Authorize for a policy decision. If the decision is PERMIT, it returns hotel results and the widget template reference. ChatGPT then reads ui://widget/myhotels-widget.html, mounts the widget, and passes the tool output into the widget runtime.

The widget then renders:

a map
hotel markers
hotel cards
standard nightly rates

No authentication is required for this part of the experience.

sequenceDiagram
    participant U as User
    participant CG as ChatGPT
    participant MCP as MCP Server
    participant PDP as PingOne Authorize
    participant W as Widget

    U->>CG: Search hotels in a city
    CG->>MCP: tools/call(search_hotels)
    MCP->>PDP: PDP decision(search_hotels)
    PDP-->>MCP: PERMIT
    MCP-->>CG: hotels + outputTemplate
    CG->>MCP: resources/read(ui://widget/myhotels-widget.html)
    MCP-->>CG: widget HTML resource
    CG->>W: instantiate widget runtime
    CG->>W: provide toolOutput / globals
    W->>W: render hotels and map

Public hotel search flow

2. Member-rate search

The second journey starts from the rendered widget. The user clicks Show Member Rates.

The widget does not fetch pricing directly from the backend. Instead, it asks ChatGPT to call search_hotels_member_rates. That tool is protected. If the user is not signed in or does not have the required scope, the MCP server returns an OAuth challenge. ChatGPT handles the sign-in flow and retries the tool call with a valid bearer token.

After that:

the MCP server asks PingOne Authorize for a decision using the inbound bearer token
PingOne Authorize verifies that the caller is a ChatGPT user and that the MCP token has the required scope
it performs token exchange to obtain a backend API token
it calls the backend API with the exchanged token
it returns hotel results with member pricing

The widget updates in place and shows:

discounted member rates
savings compared to the standard rate
the authenticated user display name in the UI

This is a good example of progressive authentication. The user can explore first and authenticate only when the value of signing in is obvious.

sequenceDiagram
    participant U as User
    participant W as Widget
    participant CG as ChatGPT
    participant MCP as MCP Server
    participant P1 as Ping Identity
    participant PDP as PingOne Authorize
    participant API as Backend API

    U->>W: Show member rates
    W->>CG: window.openai.sendFollowUpMessage(...)
    CG->>MCP: tools/call(search_hotels_member_rates)
    MCP->>PDP: PDP decision(search_hotels_member_rates)
    alt token missing or insufficient
        MCP-->>CG: OAuth challenge
        CG->>P1: OAuth flow
        P1-->>CG: access token
        CG->>MCP: retry tools/call(search_hotels_member_rates)
        MCP->>PDP: PDP decision(search_hotels_member_rates)
    end
    PDP-->>MCP: PERMIT
    MCP->>P1: token exchange
    P1-->>MCP: backend API token
    MCP->>API: GET /hotels?memberRates=true
    API-->>MCP: member-rate hotels
    MCP-->>CG: member-rate hotels
    CG->>W: provide updated toolOutput

Member-rate search flow with OAuth and token exchange

3. Booking with approval

The booking journey starts when the user clicks Book on a hotel card and submits check-in date and number of nights.

The widget calls prepare_booking. That tool is also protected, but the logic is now more nuanced than a simple authenticated-or-not check.

The MCP first exchanges the token for a backend API token and asks the backend for an authoritative booking quote. It then sends the inbound bearer token, the tool name, and the quote attributes such as totalPrice and currency to PingOne Authorize. If policy returns PERMIT, MCP creates the booking intent. If policy also returns a human-in-the-loop obligation, MCP starts CIBA. If no such obligation is returned, MCP can confirm the booking immediately.

This is a useful design choice because the approval threshold is policy-driven rather than hard-coded into the app.

Across the MCP and backend layers, the system stores:

the transaction ID
the booking owner
the CIBA auth_req_id
the quote and approval state

The widget receives either an immediate confirmation or a pending booking status. For approval-driven bookings, it starts polling finalize_booking.

From there the flow is:

The MCP server asks PingOne Authorize for each finalization attempt.
It verifies that the caller still matches the booking owner.
It polls PingOne using the stored auth_req_id.
When approval reaches approved, the MCP server exchanges the token again if needed and confirms the backend booking intent.
The widget reflects the current state in ChatGPT.

So the user interaction is conversational at the start, visual in the middle, and approval-driven at the end.

sequenceDiagram
    participant U as User
    participant W as Widget
    participant CG as ChatGPT
    participant MCP as MCP Server
    participant PDP as PingOne Authorize
    participant API as Backend API
    participant P1 as Ping Identity

    U->>W: Book hotel
    W->>CG: window.openai.callTool("prepare_booking", ...)
    CG->>MCP: tools/call(prepare_booking)
    MCP->>MCP: parse token sub for demo owner state
    MCP->>P1: token exchange
    P1-->>MCP: backend API token
    MCP->>API: POST /booking-quotes
    API-->>MCP: quote with nightlyRate + totalPrice
    MCP->>PDP: PDP decision(prepare_booking with quote)
    PDP-->>MCP: PERMIT, optional USER-AZ-REQUIRED
    MCP->>API: POST /booking-intents
    API-->>MCP: bookingIntent pending
    alt USER-AZ-REQUIRED returned
        MCP->>P1: POST cibaAuthorization
        P1-->>MCP: auth_req_id + expires_in + interval
        MCP-->>CG: bookingApproval pending
        CG->>W: provide updated tool result
        loop while pending
            W->>CG: window.openai.callTool("finalize_booking", ...)
            CG->>MCP: tools/call(finalize_booking)
            MCP->>PDP: PDP decision(finalize_booking)
            PDP-->>MCP: PERMIT
            MCP->>MCP: parse token sub and verify ownerSub matches
            MCP->>P1: POST token (CIBA poll)
            P1-->>MCP: pending or final state
            opt approved
                MCP->>P1: token exchange
                P1-->>MCP: backend API token
                MCP->>API: POST /booking-intents/:transactionId/confirm
                API-->>MCP: bookingIntent confirmed
            end
            MCP-->>CG: bookingApproval update
            CG->>W: provide updated tool result
        end
    else no human-in-the-loop obligation
        MCP->>API: POST /booking-intents/:transactionId/confirm
        API-->>MCP: bookingIntent confirmed
        MCP-->>CG: bookingApproval approved
        CG->>W: provide updated tool result
    end

Booking flow with CIBA-based approval

Conclusion

MyHotels is a compact but realistic example of how Ping Identity can secure a ChatGPT personal agent across different trust boundaries. In this demo, PingOne provides the main identity capabilities that make the flow work safely:

user authentication when the agent crosses into protected functionality
centralized MCP authorization through PingOne Authorize
audience and scope-specific token issuance for the MCP layer
OAuth 2.0 Token Exchange so the backend API receives a token minted for its own protected resource
actor-chain visibility that preserves how the request moved from ChatGPT to MCP to the backend
CIBA-based approval for higher-risk actions such as booking
policy-based thresholds that can allow, step up, or deny booking actions based on amount

Taken together, those capabilities let the personal agent move from public access to authenticated access and then to explicit transaction approval without collapsing everything into one token or one client-side flow.

Help us shape the future of Ping Identity's documentation

Mon, 22 Jun 2026 00:00:00 GMT

If you use Ping Identity documentation to build, configure, troubleshoot, or learn, we’d love your feedback. Our 2026 Annual Documentation Feedback Survey takes 5 – 10 minutes to complete and is designed to help us prioritize improvements that will make the biggest difference for you.

This year’s survey asks about the full documentation experience: how easy it is to find content, whether information is easy to apply, how well the docs help you resolve issues, and whether they help you discover new ways to use the products.

It also asks what kinds of content you want more of, including developer content such as code samples, example apps, and SDK or API docs. In addition, we’re asking how you use AI tools to find Ping Identity information and what you want those tools to do better for you.

For developers and technical implementers, that matters. Good documentation should help you get started faster, find the right configuration details, connect information across pages, and turn examples into something you can actually use in your environment. Your feedback helps us see where we’re doing that well and where we still need to improve.

If you’re willing to go deeper, the survey also includes an option to volunteer for a 30-minute follow-up interview or other research activities. That gives us a chance to understand the story behind the scores and comments, not just the numbers.

Take the survey

Take the Annual Documentation Feedback Survey

Thanks in advance for helping us improve the documentation experience for builders, admins, and everyone else who depends on Ping documentation to get work done.

Docs for Agents: making Ping Identity documentation work with AI

Fri, 19 Jun 2026 00:00:00 GMT

Developers increasingly build with AI coding agents, and one of the first things those agents do when working on an identity integration is try to pull in your docs. If your documentation isn’t structured for that, the agent either gets noisy HTML it has to parse, or it gives up and hallucinates the API surface instead.

There are ways to make your docs more agent-friendly, and we recently implemented a number of these solutions for Ping Identity’s documentation. The result: our docs are now much easier for agents to discover and consume, which means better accuracy and a smoother experience for developers building with AI.

The problem: great docs, invisible to agents

Ping Identity has extensive technical documentation — thousands of pages across docs.pingidentity.com and developer.pingidentity.com. But “extensive” doesn’t automatically mean “agent-friendly.”

Before this work, an AI agent trying to use our docs would hit a few walls:

HTML noise: Documentation pages are built for browsers. Navigation chrome, scripts, and hundreds of lines of HTML overhead are irrelevant for an agent — and they’re expensive in terms of tokens. Stripping HTML to get to the actual content is possible, but imperfect, since the agent has to guess which parts are content and which parts are noise.

Well-structured, semantic HTML does carry useful context, but in practice most HTML pages aren’t very well-structured or semantically rich — and even when they are, the signal-to-noise ratio rarely justifies the token cost.
No discovery mechanism: Even if an agent knew our docs existed, there was no structured way for it to find the right page. It would have to either crawl the entire site or guess at URLs.
No machine-readable product metadata: Pages described products in natural language, but nothing told a search engine or agent in structured terms which product a page was about.

On top of all this, AI-driven traffic already accounts for a significant percentage of site visits. We were already being crawled; we just weren’t giving those crawlers what they needed.

To make matters more complex, there isn’t really a single “right” way to solve these problems. Best practices and specifications are still evolving, and it may be a while before an approach that works across most agents solidifies into a standard. Any solution we implemented had to be flexible enough to evolve as the ecosystem does, while still providing immediate value to developers building with AI today.

What we built

Because of the evolving landscape, we took a multipronged approach, implementing several complementary features to make our docs more agent-friendly. Our goal was to make it easy for agents to discover the docs they need, give them a clean, efficient way to fetch the content, and provide structured metadata to help them understand what they’re looking at, all without diminishing the experience for human readers.

Markdown alternates for every page

The most significant single change: every documentation page now has a Markdown alternate at the same URL, with .html swapped for .md, which lives parallel to the HTML version. For example:

https://docs.pingidentity.com/pingam/8/setup/am-admin-interface-tools.html
→
https://docs.pingidentity.com/pingam/8/setup/am-admin-interface-tools.md

Markdown alternates strip out navigation, scripts, and all the browser-facing overhead, leaving just the content. Pulling Markdown instead of HTML can eliminate a significant portion of the data an agent would otherwise have to process as noise. That’s a dramatic drop in token cost and a meaningful improvement in accuracy. Taking a random sampling of pages across our docsets, the Markdown version is typically between 85% and 95% smaller than the HTML version, while still retaining the content an AI agent actually cares about.

To improve discovery of the Markdown alternates, we also added a <link rel="alternate" type="text/markdown"> element in the <head> of every HTML page, pointing to the corresponding Markdown URL. This way, an agent that starts with the HTML page can easily find the Markdown version without having to guess the URL structure. To help humans discover it too, we also added a link to the Markdown version at the top of each page.

We generate the markdown versions based on the published HTML, rather than just exposing our raw files. This is because we write our documentation using AsciiDoc. While most agents are perfectly happy to handle AsciiDoc, we do enough post processing during our build pipeline that it wasn’t feasible to just expose the raw AsciiDoc, and if we were going to have to process the files anyway, we may as well align with what has become an unofficial standard for AI-oriented docs. The Markdown generation happens at build time via an extension to our Antora build pipeline. Building the Markdown and the HTML from the same source content keeps them in sync — you can’t accidentally publish docs that have one without the other.

llms.txt indexes

Markdown alternates solve fetching a known page. But how does an agent know which pages exist?

The answer is llms.txt, an emerging standard for giving AI models a curated, structured index of a site — similar in spirit to robots.txt, but designed for context consumption rather than crawling control.

We generate llms.txt files as part of the same Markdown build pipeline, at two levels:

Per-docset: https://docs.pingidentity.com/pingam/llms.txt lists every page in the PingAM docset with its title and Markdown URL. An agent working on a PingAM integration can load this file to get a full inventory of available content, then selectively fetch the pages relevant to its task.
Site-wide: https://docs.pingidentity.com/llms.txt and https://developer.pingidentity.com/llms.txt aggregate the per-docset files into a single index organized by product.

JSON-LD structured data

In parallel with the Markdown and llms.txt work, we added JSON-LD structured data to every documentation page. JSON-LD is a machine-readable format for expressing things like “this page is a TechArticle about PingAM, published on this date, by Ping Identity.”

Search engines and AI knowledge graphs already know how to consume this. Adding it to our pages helps both SEO and agent context — an agent parsing a docs page can read the JSON-LD block and immediately understand the product, product version, and content type rather than having to infer it from the natural language text. For a first pass, establishing the product/content-type relationship cleanly was the highest-value thing to ship, with room to iterate as needs evolve.

A “Docs for Agents” landing page

To tie all of this together for humans and agents alike, we published a Docs for Agents page explaining how everything fits together: where the Markdown alternates are, how the llms.txt files are structured, and recommended patterns for loading focused context on a specific product vs. discovering what’s available across the full site.

This isn’t necessarily a standard, but it’s a useful resource, and one that others in the industry have also opted to do (Cloudflare has a similar page, for instance). It’s a way to signal to developers that “yes, we know you’re using AI agents, and yes, we have features in place to support that.”

`Accept: text/markdown` content negotiation

Some agents send an Accept: text/markdown header with their requests, expecting the server to return Markdown if it’s available. We’ve recently added support for this, including a fallback to the HTML version if the Markdown version isn’t available for some reason.

This approach is gaining a lot of traction as a more elegant way to handle Markdown alternates, since it doesn’t require the agent to manage two separate URLs for each page. The agent can just request the normal URL and let content negotiation handle the rest. It’s still early days for this pattern, and not all agents support it yet, but we wanted to be ready for it as it becomes more common. You can learn more about this approach at Accept: text/markdown.

Try it out

If you’re building an integration and want to give your AI coding agent focused context on a Ping product:

Point the agent at the product’s llms.txt: For example, https://docs.pingidentity.com/pingam/llms.txt for PingAM. The agent can scan the titles and selectively fetch the pages most relevant to what you’re building.
Fetch Markdown instead of HTML: Swap .html for .md on any page URL, or extract the <link rel="alternate" type="text/markdown"> URL from the page <head>. If your agent supports it, you can also just send an Accept: text/markdown header and let content negotiation do the work.
Not sure which product docset you need? Start at https://docs.pingidentity.com/llms.txt or https://developer.pingidentity.com/llms.txt for an index of everything available.

What’s next

Enriched page descriptions for llms.txt entries: Right now each entry in an llms.txt file is just the page title and URL. The spec recommends a short description (≤150 characters) alongside each link. We’re updating all of our docs pages to include these descriptions, which should help make the llms.txt indexes even more useful.

Docs MCP server: The longer-term vision is a Docs MCP server that exposes our documentation as callable tools rather than just static files. An agent using MCP would be able to search across products, retrieve specific sections, and get structured answers without having to manage the llms.txt/Markdown workflow manually. This is in active development and should be launching soon.

Monitoring and iteration: We’re actively monitoring how agents are using these features and gathering feedback from developers. The AI ecosystem is evolving rapidly, so we’re committed to iterating on our approach as best practices and standards emerge.

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community!

Resources

Specifications

“Docs for Agents” Examples

Securing the PingOne DaVinci Widget with the Backend-for-Frontend (BFF) Pattern

Wed, 17 Jun 2026 00:00:00 GMT

Web application architecture has gone through several major evolutions over the last 30 years - and I’m old enough to have lived through most of them. Thankfully, we’ve largely moved on from the era of server-rendered UI frameworks like Java Servlets, PHP, and ASP applications that rebuilt an entire page on every interaction. In their place, single page applications (SPAs) have become the dominant model for modern web experiences.

SPAs dramatically improve responsiveness and usability by moving much of the application control logic into the browser, where JavaScript can interact directly with backend APIs without requiring constant full-page refreshes. From a user experience perspective, the benefits are undeniable.

For identity architects and security practitioners, however, this shift introduced a new set of challenges. Traditional authentication and session-management patterns were designed around trusted server-side applications. As applications moved toward increasingly “pure” SPA architectures, those patterns became harder to apply safely and consistently.

In my opinion, the challenge of building a truly secure browser-only SPA remains largely unsolved. While modern OAuth and browser security standards have improved significantly, exposing sensitive OAuth tokens directly to browser code still creates risks that many teams underestimate. That’s why I continue to believe that a secure backend following the Backend-for-Frontend (BFF) pattern is a critical component of any security-sensitive SPA architecture.

In this article, we’ll walk through an approach for securing the PingOne DaVinci embedded widget using a BFF architecture that prevents sensitive OAuth tokens from ever being exposed to the browser client. The core idea is simple: keep the widget in the browser for the user experience, but keep the trust decisions, token handling, and application session establishment in the backend.

What is a widget anyway (and why would we use one?)

As a modern identity orchestration platform, DaVinci provides multiple integration models that allow applications to consume orchestration flows in the way that best matches their architecture and UX goals.

For modern web applications, embedded authentication experiences have become increasingly popular. Rather than redirecting users to a hosted login page, authentication journeys are rendered directly within the application itself, creating a more seamless user experience. While there are certainly security tradeoffs worth discussing, the approach is now common enough that identity platforms need to support it well.

DaVinci offers two primary approaches for embedded authentication experiences:

Headless integration using APIs and SDKs. Applications can use DaVinci APIs and SDKs to implement the entire authentication experience directly in client-side code. This gives development teams maximum control over UI and UX behavior, but also requires them to own and maintain the interaction logic themselves.
The embedded DaVinci widget. The pre-built DaVinci widget provides a faster and more flexible way to embed authentication flows directly into a web application while allowing DaVinci to handle the orchestration and flow-rendering logic. The result is a seamless embedded experience with significantly less implementation effort.

In this article, we’ll focus specifically on securing the embedded DaVinci widget integration itself rather than exploring every possible DaVinci deployment model. In particular, we’ll concentrate on two key security objectives. First, we’ll show how the widget can rely on a trusted backend service to securely initiate DaVinci flows without exposing sensitive DaVinci API credentials to browser-based JavaScript. Second, we’ll show how to complete the authentication process without returning OAuth tokens, DaVinci session tokens, or other sensitive handoff artifacts through the browser front channel.

To demonstrate the approach, we’ll use a deliberately simple reference architecture consisting of two components. The frontend application is implemented as a lightweight HTML and JavaScript SPA that runs entirely in the browser and hosts the embedded DaVinci widget. Supporting this is a minimal backend service implemented in Node.js using the Express framework. By keeping the architecture intentionally straightforward, the example focuses on the core security concepts without introducing unnecessary framework complexity.

Why this pattern is worth the extra work

With an embedded authentication widget, there is an unavoidable architectural tension. The browser needs to host the user experience, because that is the whole point of embedding the widget. But the browser is not where we want to handle API credentials, OAuth tokens, refresh tokens, or durable authentication state.

The pattern in this article draws a clean boundary. The widget still renders in the browser, but the BFF creates the authentication transaction, DaVinci binds the completed flow back to that transaction, and the tokens are delivered directly from DaVinci to the backend over a server-to-server callback. The browser is responsible for the interactive experience and for asking the BFF to finalize the local application session. It is not responsible for transporting token material.

That is why this pattern works well. It preserves the embedded login experience, keeps OAuth tokens out of frontend JavaScript, avoids exposing DaVinci API credentials, gives the BFF a server-side transaction to validate, and lets the BFF regenerate the application session only after it has verified signed token claims that match the transaction it originally created.

Full code for the sample implementation described below is available in GitHub.

Note: The code in this article is provided as a sample for educational purposes and is not intended for direct production use without review and adaptation for your specific environment.

Step 1: Securely obtaining a DaVinci SDK token

The first challenge when embedding the DaVinci widget into a browser-based SPA is securely obtaining the SDK token required to initiate a flow. Normally, generating this token requires a DaVinci API key - a highly sensitive credential that should never be exposed to browser JavaScript or embedded into frontend source code.

To avoid this, the browser never communicates directly with the DaVinci /sdktoken endpoint. Instead, the frontend calls a trusted backend endpoint (/dvtoken) implemented in our Express-based BFF service. The backend securely stores the DaVinci API key using environment variables and uses it to request a short-lived SDK token from the DaVinci orchestration API.

In this pattern, /dvtoken does one more important thing. Before requesting the SDK token, the BFF creates a short-lived authentication transaction. This transaction includes a transactionID, a cryptographically strong nonce, and two time windows: one for starting the DaVinci flow and one for completing the overall authentication transaction.

function createAuthTransaction() {
  const issuedAt = Date.now();

  return {
    transactionID: crypto.randomUUID(),
    nonce: crypto.randomBytes(32).toString('base64url'),
    issuedAt,
    startBy: issuedAt + AUTH_FLOW_START_TTL_MS,
    completeBy: issuedAt + AUTH_TRANSACTION_TTL_MS,
    status: 'pending',
  };
}

These two time windows are intentionally different. Starting the widget should happen quickly, so startBy can be short. Completing the journey could take longer, especially if the flow includes MFA, identity verification, or any other user interaction that takes time, so completeBy should be longer.

The BFF stores this transaction server-side and also stores a copy in the pre-auth Express session associated with the browser. It then passes selected values into the DaVinci flow as SDK token parameters:

body: JSON.stringify({
  policyId: WIDGET_POLICY_ID,
  parameters: {
    transactionID: authTransaction.transactionID,
    nonce: authTransaction.nonce,
    expiresAt: authTransaction.startBy
  }
})

The browser doesn’t need to know these values. They’re generated by the BFF and delivered directly to DaVinci as flow input parameters. The browser receives only the widget SDK token and the minimal configuration needed to render the widget.

return res.json({
	token: data.access_token,
	companyId: COMPANY_ID,
	policyId: WIDGET_POLICY_ID,
	apiRoot: API_ROOT
});

Step 2: Invoking the login flow with the widget

With the SDK token in hand, the frontend can initialize the DaVinci widget and invoke the login flow. The widget is configured to use runFlow, along with the apiRoot, companyId, policyId, and short-lived SDK token returned by the BFF. At this point, the browser has everything it needs to render and execute the embedded DaVinci experience, but still doesn’t have access to any long-lived credentials, OAuth tokens, or BFF transaction secrets.

const tokenRes = await fetch('/dvtoken', {
	method: 'POST',
	headers: { 'Content-Type': 'application/json' },
	body: JSON.stringify({})
});

const { token, companyId, policyId, apiRoot } = await tokenRes.json();

const props = {
	config: {
    	method: 'runFlow',
    	apiRoot: apiRoot,
    	accessToken: token,
    	companyId: companyId,
    	policyId: policyId
	},
	useModal: false,
	successCallback: async () => {
    	const result = await finalizeLogin();
    	showAuthenticatedState(result.user);
	}
};

davinci.skRenderScreen(UI.widget, props);

The important nuance is in the DaVinci flow design. Here’s an example of a flow, with details below:

DaVinci flow overview showing the full authentication orchestration

The flow should validate that the BFF-supplied transaction context is present and fresh before continuing with authentication. At minimum, the flow should check that transactionID, nonce, and expiresAt are present, that expiresAt is numeric, and that the current time is not later than expiresAt. Our flow input schema validation takes care of the first three and we use a simple A<B function node for the fourth.

Flow input validation step 1 - checking transactionID, nonce, and expiresAt fields are present

Flow input validation step 2 - schema validation configuration

Flow input validation step 3 - additional schema validation

Flow input validation step 4 - A less than B expiry check

This validation doesn’t prove that the transaction is valid by itself. The BFF remains the source of truth because it created the transaction. But it gives the DaVinci flow a clean way to reject stale or malformed starts before asking the user to authenticate.

Step 3: Generating tokens without returning them to the browser

After the user completes the embedded journey, DaVinci needs to generate the OAuth tokens. The critical design rule is that those tokens must not be returned to the widget success callback. Instead, DaVinci should deliver them directly to the BFF using the HTTP Connector’s “Make REST API Call” capability. The key flow design choice here is to ensure that the “PingOne Authentication Return Success Response (Widget Flows)” node is not the final one in the flow.

To bind the generated token response to the BFF transaction, the ID token should include the BFF-generated nonce and transaction identifier. In the sample implementation, the custom transaction claim is bff_transaction_id.

These claims need to be in the ID token. The BFF verifies the signed ID token and uses the claims in that token as proof that the token response is bound to the transaction it originally created.

ID token custom claims configuration showing bff_transaction_id and nonce fields

Step 4: Delivering tokens to the BFF server-to-server

After DaVinci generates the token response, it calls the BFF directly. This is the key architectural boundary in the design. The browser is never responsible for carrying an authentication artifact from DaVinci to the backend.

The DaVinci HTTP connector calls /auth/davinci/complete with a shared callback secret and a JSON body containing the transaction binding values and token response:

POST /auth/davinci/complete
Content-Type: application/json
X-DaVinci-Callback-Secret: <shared callback secret>

{
  "transactionID": "bff-generated-transaction-id",
  "nonce": "bff-generated-nonce",
  "completedAt": 1717000012345,
  "interactionId": "optional-davinci-interaction-id",
  "tokens": {
    "access_token": "eyJ...",
    "refresh_token": "optional-refresh-token",
    "id_token": "eyJ...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

HTTP connector callback configuration step 1 - Make REST API Call setup

HTTP connector callback configuration step 2 - request body mapping

HTTP connector callback configuration step 3 - full connector setup

The BFF route is intentionally registered before the browser-origin middleware, because this request is not coming from the browser and will not have the same Origin and Fetch Metadata headers. Instead, the route is protected using the callback secret, token signature validation, and transaction binding checks.

app.post(
	'/auth/davinci/complete',
	callbackRateLimit,
	express.json({ limit: '20kb' }),
	requireDavinciCallbackSecret,
	async (req, res) => {
    	const { transactionID, nonce } = req.body || {};
    	const transaction = authTransactions.get(transactionID);

    	if (!transaction || transaction.status !== 'pending') {
        	return res.status(409).json({ error: 'Unknown or invalid transaction' });
    	}

    	if (!safeEqual(nonce, transaction.nonce)) {
        	return res.status(403).json({ error: 'Invalid transaction binding' });
    	}

    	const claims = await verifyIdToken(tokens.id_token);
    	const tokenTransactionID = getTransactionIDFromClaims(claims);

    	if (!safeEqual(tokenTransactionID, transactionID)) {
        	return res.status(403).json({ error: 'Invalid token transaction binding' });
    	}

    	if (!safeEqual(claims.nonce, transaction.nonce)) {
        	return res.status(403).json({ error: 'Invalid token nonce binding' });
    	}

    	transaction.status = 'tokens_delivered';
    	transaction.idTokenClaims = claims;
    	transaction.tokens = tokens;

    	return res.json({ received: true });
	}
);

The code above is intentionally abbreviated, but the validation order is important. The BFF first finds the pending transaction by transactionID, then checks the nonce supplied in the body, then verifies the signed ID token and checks that the signed claims contain the same transactionID and nonce. This gives us both a server-to-server delivery channel and a signed token-level binding to the transaction.

Step 5: Finalizing the BFF application session

The server-to-server callback cannot set the browser’s application session cookie because the browser is not involved in that request. That final step still needs to happen from the browser, but the browser doesn’t need to send any sensitive token material.

When the DaVinci widget completes successfully, the frontend calls /auth/finalize with an empty JSON body:

async function finalizeLogin() {
	const finalizeRes = await fetch('/auth/finalize', {
    	method: 'POST',
    	headers: { 'Content-Type': 'application/json' },
    	body: JSON.stringify({})
	});

	if (!finalizeRes.ok) {
    	throw new Error(`Finalize failed with HTTP ${finalizeRes.status}`);
	}

	return finalizeRes.json();
}

This route uses the pre-auth Express session cookie to find the pending transaction that was created when /dvtoken was called. It then checks that DaVinci has already delivered tokens for that transaction. If the token delivery is complete and all bindings match, the BFF regenerates the Express session and promotes it into an authenticated application session.

await regenerateSession(req);
req.session.authenticated = true;
req.session.user = user;
req.session.subject = transaction.subject;
req.session.access_token = tokens.access_token;
req.session.refresh_token = tokens.refresh_token;
req.session.id_token = tokens.id_token;
req.session.id_token_claims = idTokenClaims;
await saveSession(req);

This session regeneration step is important. The pre-auth session exists only to bind the browser to the pending authentication transaction. After authentication is complete, the BFF discards that pre-auth session identifier and creates a fresh authenticated session. This reduces session fixation risk and gives the application a clean transition from unauthenticated to authenticated state.

The browser receives only a normal application response and a secure application session cookie. It never sees the OAuth tokens, the DaVinci API key, or a DaVinci sessionToken.

Step 6: Hardening the browser-facing routes

The BFF also includes browser-origin checks for the routes that are intended to be called by the frontend. CORS is useful here, but it is important not to overstate what CORS does. CORS is enforced by browsers; it doesn’t authenticate arbitrary non-browser HTTP clients.

For that reason, the BFF uses origin checks as a browser-side protection layer, not as the only security control. The server-to-server DaVinci callback uses different protection because it is not a browser request.

For the browser session cookie, the implementation uses an application-scoped cookie with the HttpOnly, Secure, SameSite=Strict attributes:

const sessionCookieOptions = {
	httpOnly: true,
	secure: true,
	sameSite: 'strict',
	path: '/',
	maxAge: SESSION_TTL_MS
};

The cookie is named __Host-acme_session. The __Host- prefix gives the browser additional constraints: the cookie must be Secure, must use Path=/, and must not include a Domain attribute. This helps keep the session cookie tightly scoped to the application host.

This doesn’t eliminate bearer cookies. A BFF application still needs a browser cookie to represent the application session. The point is that the cookie is now an app-local session handle controlled by the BFF, not an OAuth token, refresh token, DaVinci session token, or DaVinci token reference.

Putting it all together

The full end-to-end flow now looks like this:

The browser calls /dvtoken.
The BFF creates transactionID, nonce, startBy, and completeBy.
The BFF requests a DaVinci SDK token and passes the transaction context into the flow.
The browser renders the embedded widget using the returned SDK token.
DaVinci validates the transaction context and authenticates the user.
DaVinci generates OAuth tokens and includes nonce and bff_transaction_id in the ID token.
DaVinci calls /auth/davinci/complete server-to-server and delivers the tokens to the BFF.
The BFF validates the callback secret, pending transaction, body nonce, ID token signature, ID token audience, ID token issuer, ID token nonce, and ID token transaction claim.
The widget success callback fires in the browser.
The browser calls /auth/finalize with no token material.
The BFF validates the browser session binding and promotes the transaction into an authenticated application session.
The browser receives only the application session cookie.

End-to-end flow diagram showing all 12 steps of the BFF authentication pattern

While there are a few moving parts, the responsibility boundaries are straightforward. The browser is responsible for rendering the embedded DaVinci widget and collecting the user’s interaction. DaVinci is responsible for executing the identity journey and generating tokens. The BFF is responsible for protecting credentials, validating token delivery, binding the transaction, and establishing the application session.

A few practical caveats

The sample implementation deliberately keeps the architecture simple, but there are a few production considerations worth calling out.

The sample stores pending authentication transactions in an in-memory Map. That is fine for a single demo service, but production deployments should use Redis, a database, or another shared server-side store.
The sample uses the default express-session store. That is not suitable for production scale. A production BFF should use a real session store.
The DaVinci callback currently uses a shared static secret. A stronger version would use an HMAC signature over the request body and timestamp, mTLS, or another stronger server-to-server authentication mechanism where available.
Origin and CORS checks are useful for browser-based protection, but they do not authenticate non-browser clients. The critical protection for token delivery is the combination of callback authentication, signed ID token validation, and BFF transaction binding.

Over to you

It would be great to hear how others are approaching this pattern in their own environments.

Are you already using a BFF-style architecture to protect OAuth tokens in SPA applications, or are your teams still comfortable managing tokens directly in the browser? When embedding authentication journeys with tools like the DaVinci widget, where do you draw the line between user experience convenience and token-handling risk? And have you found other patterns that preserve the seamless embedded login experience without exposing long-lived credentials or OAuth tokens to frontend code?

Drop a comment and join the discussion on the Ping Identity developer community with your thoughts, questions, or your own lessons learned from building secure modern web applications in the identity trenches.

Understanding the Org Model

Thu, 28 May 2026 00:00:00 GMT

This post was originally published on Gwiz Kid.

Introduction

PingOne Advanced Identity Cloud (AIC) and PingIDM (Ping’s self-managed Identity Management) provide a powerful model called Organizations which enables out-of-the-box extensible, inherited relationships between users and associated groups of users. In short, Organizations give you the ability to match your IAM strategy to your business strategy, and not the other way around - they are a means to unify, simplify, and standardize your process across your internal, external, and partner identities.

Considering its flexibility and scalability, starting with an empty tenant and the base Organization model can feel a bit daunting.

This Guide intends to teach you the key information you need to know when interacting with AIC/PingIDM’s Organization model. It is split into the following sections:

Introduction
Object Modeling Definitions
- What’s the Deal with RDVPs?
What is the Organization Model?
- A Quick Analogy
Utilizing the Organization Model
Referencing the Organization Model in the Platform
Extending the Organization Model
Conclusion

By the end of this Guide you’ll have a medium-level understanding of Organizations and how they operate generically within AIC and PingIDM.

This Guide expects a beginner level of familiarity with AIC or PingIDM. Certain topics covered here will be specific to the AIC platform: when this happens, we’ll call it out. If you do have a tenant or deployment available, feel free to follow along however it is not necessary.

Object Modeling Definitions

Before we define Organizations, we need to understand the underlying infrastructure that surrounds it. Let’s start broadly and then narrow down as we go.

The Organization model is a part of Identity Management (IDM). PingIDM is the self-deployed instance and is a core feature set within AIC. Identity Management’s job is to represent, control, connect, and map identity data in and out of the Ping platform. Regarding Organizations, we care most about representing and controlling its data - what does the template look like, and ensuring that the data within it is managed appropriately (think CRUDPAQ - Create, Read, Update, Delete, Patch, Action, Query).

Managed Objects are a templatized instance of data in IDM that contains Properties. In essence, they are the representation of identities within IDM. By default, your instance comes with Users, Roles, Assignments, Groups, and Organizations, but you can create as many as you’d like. Managed Objects store data within a Directory, with each Managed Object being categorized separately.

Properties (sometimes called Attributes) are the individual data fields within a Managed Object that represent the data types stored within that object. They define the specific pieces of information each instance of that Managed Object will hold. As an example, a User is a Managed Object, and their Username is one of their Properties. Properties can be booleans, numbers, arrays (called multivalues), objects (including nested objects), strings, Relationships, and Virtual Properties. You can also create custom types as needed. Properties have their own unique indexing¹, validation, hashing or encryption, and triggers which can be performed on actions such as validating, retrieving, or storing an instance of this Property.

Relationships are a type of Property that creates a linkage between instances of Managed Objects. Relationships can be one-to-one, one-to-many, many-to-one, and many-to-many, and can be linked to different Managed Objects or the same Managed Object. Common examples of relationships include Manager to Employees, Parent to Children, or Department to Teams. Relationships can contain their own data within the link itself, can return their data alongside either end of the link in a query, and can be used as a means to notify the connected Managed Objects that changes have occurred on opposite ends of the link (Relationship-Derived Virtual Property).

Virtual Properties are a powerful Property type that can dynamically calculate its own data on the fly, either on time of retrieval or based on notifications received from a Relationship tied to this Managed Object (Relationship-Derived Virtual Property). This significantly simplifies data and queries as well as improves performance because the complex calculations are handled for you dynamically at run time or statically at storage time - for example, you could have a virtual property that dynamically returns the “Full Name” of a User as a combination of their First and Last name without actually having to store and update that value separately.

Relationship-Derived Virtual Properties (RDVPs) are a type of Virtual Property that update based on notifications from the Relationships linked to its Managed Object. An RDVP has access to content from the Object’s Relationships and can travel the chain of relationships to create a composite value of the chain. Relationships and RDVPs are the two components of IDM that make Organizations so flexible and capable.

What’s the Deal with RDVPs?

RDVPs are an insanely powerful tool for reducing complexity and increasing performance.

As an example, let’s say that you have a business structure of Managers to Employees like we mentioned in the Relationships section. In most companies, you’re not going to have one layer of Managers - you’ll probably have at least 3 and each of those layers may have tens to hundreds of Managers who then manage their own number of Employees.

If I wanted to get a list of all of the Managers above an Employee, how would I go about it? Normally, it would likely be a series of queries that would look something like this:

Get the Employee
Find the Employee’s Manager
Get the Manager
Find the Manager’s Manager
Get the Manager’s Manager
Find the Manager’s Manager’s Manager
…
Manager X has no Manager, return

Think about this the other way, too. If I wanted to get all of the Employees under a Manager, and each Manager has more than one Employee, how many operations do I have to take? Now what if I had to perform this action every time I entered an application? This is starting to sound a lot like one of those classic graph traversal interview questions!

The deeper or wider you go, with the more connections you have, the more operations you would normally have to take. This makes your code complex and significantly increases the number of queries you need to make to get the data you and your users need to be successful. RDVPs solve this problem.

RDVPs travel the Relationships for you and update a static result on the object directly at time of change from anywhere in the Relationship.

If we looked at the previous example, if I wanted to get a list of the Employee’s Managers, or a list of the Manager’s Employees, the data is on the User directly. If the Employee is promoted, or switches teams, and the managerial hierarchy changes, the data on the User updates automatically.

RDVPs proactively updates relevant aggregate data so that you only have to look at one Object to understand what’s going on with everything it’s linked to.

What is the Organization Model?

Organizations are a Managed Object that contain multiple Relationships both to Users and to other Organizations. These Relationships store RDVPs that define the linkages that the Organization has with other Organizations and Users. Since Organizations are a Managed Object, they are adherent to the same scale as Users, meaning that AIC is rated for hundreds of millions of Organizations while PingIDM is hypothetically as scalable as your hardware will allow.

Organizations, at their core, build a hierarchy of templatized data. Due to the Relationships between Organizations and Users, this data can be inherited up and down the hierarchy.

Visualized, the Organization model often looks like a tree.

The Organization Model

Organizations enable hierarchical, inherited data templates, allowing you to standardize and represent complex structures such as families, business partnerships, and supplier/distributor models.

But just having this data is only one part of what makes this model special. Organizations don’t just represent Parent/Child relationships between other Organizations: they also by default contain 3 different Relationship types with Users - and Users can retrieve and inherit information from the hierarchy as well. Due to the RDVPs already on the Organization, and the permission model in place on the Organization, elevated Relationship types (i.e. Owners and Admins) have the ability to manage aspects of both the Organization, its related Users, and any Organizations and Users that they’ve inherited - both via REST API and (in the case of AIC) hosted UI.

The Organization Model with Users

Organizations enable hierarchical, inherited delegated administration, allowing you to scale administration alongside your platform by delegating operational management of the hierarchy and its Users to the Users within the Organization (or its Parent).

Additionally, these Relationship types are many to many, meaning that a single User can be a Member, Admin, and Owner of as many different Organizations and Hierarchies as they need.

Universal Identity in Organizations

Organizations enable a Universal Identity, where one Identity has one User account for all Services.

So, why Organizations?

Organizations let you:

Templatize grouping of content so that you can build a standard that the platform adheres to
Delegate the content so that the platform can be managed at scale without having to hire thousands of admins to keep up
Link the content so that it and its users can inherit information and administration for quicker time-to-value

A Quick Analogy

Think of the Organization Model as a Condominium.

As the Tenant Administrator, you’re the owner of the Building itself. You dictate what services are available, how the condos are laid out, and the keycard system for how the residents get into the building. You can also add floors and rooms to the Condo at any time.

The people in your Condo (Users) could be Residents (Admins) or Staff (Owners). Everyone must use their keycard to get into the building, and that same keycard may give them access to different rooms or Condos in the building. A Resident, for example, may have access to their Condo as well as to a friend’s Condo. Staff may have access to all Condos on a given floor, and may have access to systems like plumbing and electrical which the Residents don’t interact with.

Residents can modify their Condo, but how they can change it must adhere to the rules and regulations defined by the Building. To the benefit of the Resident, ongoing maintenance of the Condo and its services are managed by the Building and not by them.

If the Resident decides to rent out their Condo, their Tenants (Members) will have access to the Building and to the Condo but won’t be able to modify the Condo at all. They can only use the facilities given to them by the Resident.

As your Building grows, you may need more staff to run it. As such, you can appoint Floor Managers (Owners of a Parent Org) who also have the ability to create new Condos and manage the Floors, Residents, and Tenants within.

Additionally, some of your Maintenance Staff and Floor Managers live in your Building. That means they are also Residents, and have different capabilities and responsibilities depending on what Condo they’re currently in.

Utilizing the Organization Model

So let’s put this all together and see how the Organization Model works in practice. Note that the platform screens shown below are taken from the built-in Hosted Pages within AIC, however each and every action is available in PingIDM via the Native UI or REST API.

Our goal today will be to create a basic business hierarchy. We’ll take the Supplier/Distributor model for this example.

Supplier/Distributor Example

In our example we have a Manufacturing vertical named BX Manufacturing. BX Manufacturing has partnerships with Suppliers, who provide goods and services, and Distributors, who purchase BX Manufacturing’s products to then be sold elsewhere. Both Suppliers and Distributors need to give their employees access to BX Manufacturing’s systems but what they ultimately do with those systems is very different.

To start, let’s create the Root Organization. As the Tenant Admin, we can select “New Organization”, enter in the Name, and then we’re ready to go.

Creating the Root Organization

Now, an Organization is only as useful as its Relationships. With that in mind, let’s assign an Owner to this Organization so that we can delegate management of the Manufacturing Vertical and its subdivisions.

Underneath the “Owner” section, we can assign a User to our Organization. In my example, the user “Owner” has already been registered. Note that while we are assigning manually here, you can always automate this assignment during provisioning, user registration (likely via a Journey/Tree in AIC/PingAM), or (if you have Governance features in your AIC tenant) during Access Request or with a Form submission that triggers a Workflow or Approval.

Assigning the Owner

Let’s log in as the Owner User. You’ll find that you have access to update and delete BX Manufacturing and its users and can create new Organizations underneath the Organization you’re an Owner of.

Default Owner Permissions

While you have very similar capabilities to the Tenant Administrator by default, you won’t have access to manage other Owners - that’s the job of the Tenant Administrator.

Default Owner Permissions - No Owner Management

Since we’ve been delegated ownership of BX Manufacturing, let’s set up the Suppliers and Distributors suborganizations and assign some people to manage them. We’ll create a new Organization and assign that Organization to BX Manufacturing as a Parent.

Creating the Sub-Organizations (Children)

We’ll repeat the same action for the Distributors Organization.

Creating the First-Level Children

Currently, our Organizations don’t have any Users in them. Let’s fix that. As an Owner, we can create a new User and assign them as a Member and/or an Administrator to any and all Organizations that we own and have inherited ownership to.

Creating the Suppliers Administrator

If we log out as an Owner, and log in as the Suppliers Admin, we’ll see that we only have access to the Organization that we were assigned, and unlike the Owner can’t manage other Administrators of our Organization(s).

Default Administrator Permissions

We can, however, manage our Users and create and manage new Organizations. Let’s create Supplier A and Supplier B now as children of Suppliers.

Creating the Suppliers

Additionally, let’s create some Users who are Members of the different Suppliers.

Assigning Members

Log back in as the Owner. You’ll see that you have inherited permissions to the Suppliers and the Users made by your delegated Administrator.

Inheritance at Work

Owners and Admins inherit permission to all of their sub-Organizations and its Users. Members inherit context from all of their Parent Organizations. Owners and Admins permission goes down the tree, Members context goes up.

We mentioned before that Users can have more than one Relationship to one or more Organization. Let’s say, for example, that Supplier B interacts with Distributor A to sell OEM add-ons to a customer, like a spoiler on a car. Since BX Manufacturing is the creator and owner of the finished product, they must be intrinsically involved in the linkage between this Supplier and Distributor. Here we’re dealing with a B2B2C scenario, or Business-to-Business-to-Consumer.

Unified Identity

In this situation, our User is an Admin to Supplier B and is also a Member to Distributor A. At the end of the day, this is the same person with the same account and the same login but with different relationships to each Organization. One person is tied to one identity, but the Relationships that they have to the Organizations give them different permissions to Organizations and Users and give others different permissions to them.

In practice, as the user Supplier B Admin I can see Supplier B and the Members associated with Supplier B. As Distributor A Admin, I can see and manage Supplier B Admin because they’re a Member of my Organization.

My Supplier received the context they needed to interact with Distributor while still being able to manage their own Users and Supplier information. My Distributor cannot receive the context of the Supplier but can manage the suppliers associated with their Organization.

B2B2C Using Organizations

Referencing the Organization Model in the Platform

Advanced Identity Cloud takes the Organization Model one step further and incorporates it throughout its platform. That way, actions and interactions can reference the context and relationships to make unique experiences and define specific permissions defined by each individual user.

To start, the openidm binding allows you to access and manage any IDM data throughout AIC. This gives you the flexibility to interact with your Organization throughout the User journey, for example:

An Event Hook that auto-assigns Organization membership based on a Property or Group they’re a member of (for example, a specific AD OU)
A Custom Endpoint that returns Relationship information for decentralized Policy Enforcement
User Journeys where things like branding, MFA, and risk policies are dictated by the configuration on the Organization
Access Token Modification where the token includes context of what Organizational privileges the User has

To give you a sense of what actions are useful in the context of Organizations, take a look at this Library Script that you can use wherever Next-Gen scripting is available.

If you have Governance enabled within your AIC Tenant, Organizations appear in the following places:

Owners and Admins can request access to Applications, Entitlements, and Roles on behalf of their Members.
Identity Certification Campaigns can be filtered to Users in specific Organizations
Scopes can be filtered to specific Organizations and Relationships (e.g. Owner/Admin/Member)
Forms allow a dynamically enumerated list of Organizations as a Multi-select option

Just like with the rest of the platform, you can utilize the same bindings to interact with the Organization in actions such as Workflows.

Extending the Organization Model

So where do we go from here?

Organizations give us a template with pre-built relationships that can be referenced throughout Ping’s platform. And that’s just it: it’s a template upon which we can extend and expand to meet the needs of our organization.

As a start, add Properties to your Organization - things you see your business units and partnerships doing over and over again that could (and should) be standardized.

Once you’ve built that model the way you like it, connect the model to your platform. It could be a way to control branding, extended support capabilities, or something completely different - work with your stakeholders to decide what is important for them and their users to have and to manage.

When you’ve got the model in a place you like, delegate administration to the capabilities you’d like to share with your partnerships. You own the model, and you delegate the controls.

If you see that the parent organizations need more control than the children, consider applying inheritance rules.

And, as you expand, keep changing it! The beauty of this template is that it grows with you: you can enable the right experience, security, lifecycle, and overall IAM strategy for each and every use case without having to rebuild your entire platform every time a new business requirement comes along.

Conclusion

Through this Guide we have:

Learned about the key elements of IDM that make up the Organization model
Learned how the Organization model applies these concept
Created, delegated, and managed Organizations and Users
Learned how to connect Organizations throughout AIC
Learned about common approaches in extending the Organization model to meet our business needs

The Organization model provides you the bricks to build dynamic, magical experiences for your Administrators and your Users. And with this foundation the only limit you have is your imagination.

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community.

Footnotes

Note that AIC provides general purpose extension attributes for cases in which you need to index additional values as a means to protect tenant response time. This is not a limitation in PingIDM. ↩

PingOne DaVinci Primer: Creating Dynamic Experiences with PingOne Populations

Fri, 22 May 2026 00:00:00 GMT

This post was originally published on Gwiz Kid.

Introduction

As part of creating a User in PingOne that User will need to be assigned to a Population. Populations in PingOne create logical segments of user identities, which not only define administrative boundaries for Users and Groups with elevated permissions (Admin Roles) but also provide additional metadata that can be used to cater the User’s experience to fit their unique use cases.

This How-To will teach you how to create dynamic user experiences using PingOne’s built-in Populations coupled with PingOne DaVinci. Along the way you’ll learn common strategies and design decisions when building out PingOne DaVinci flows.

The level of detail here is meant for beginners to PingOne and PingOne DaVinci. If you are just looking for, or want to follow along with, the pre-built example, download the DaVinci flow using the link here.

There are DaVinci tips and tricks interspersed throughout this document. Search for the ⭐ emoji to jump between them.

This How-To is broken down into the following sections

Introduction
Initial Setup
- Creating the Forms
- Creating Your DaVinci Flow
Retrieving the Population
- Retrieving the Population based on the User
- Retrieving the Population based on the Alternative Identifier
  - Parsing the Email Domain
  - Selecting a Population from a List
Changing the Theme based on the Population
Enforcing Password Policies based on the Population
Enforcing Login with an External IdP based on the Population
Dynamic Registration
Connecting the Flow to Your Application(s)
Conclusion
Other Helpful Tricks
- Variables
- Parsing Objects from a Teleport

By the end of this How-To you’ll have a DaVinci flow that gathers Population metadata based on the User and Population context and applies that metadata during the User’s login and registration experience. Along the way, you’ll learn a wide variety of DaVinci capabilities such as (but not limited to):

Navigating the DaVinci canvas
Building and using Forms within the page
Interacting with Connectors, Triggers, and Action Decision Nodes
Passing data between nodes
Branching and teleporting during the user’s journey
Finding and using nodes and flows from the Marketplace

This How-To expects a beginner level of familiarity with DaVinci and the PingOne console. Since Managing Populations is well-defined in the documentation, we won’t be discussing that here.

Initial Setup

This How-To requires an Environment with PingOne SSO and PingOne DaVinci. Make sure you have the appropriate Environment, licenses, and permissions before continuing.

You can use the Default Population for this How-To, or you can create a new one: just make sure you have at least one User in that Population so that you can test your flows. The name of my Population is “Example” and my user is “Example User” with the username “example@bxretail.org”.

Fortunately for us, importing and exporting experiences like the one in this document is trivial in PingOne. If you’d like to start with the pre-built example, download the DaVinci flow using the link here and then import into your Environment to get going.

That being said, if you’re looking to get a better understanding of how to construct flows like this, it’s worth the time to follow along with this How-To.

Creating the Forms

Since we are going to be capturing some user information to log in and are going to be branding them based on our Population, we should create some Forms. Forms provide a drag-and-drop editor for building user interfaces that we can then reuse throughout our DaVinci Flows.

Go to “User Experience” - “Forms” in your PingOne navigation bar. You’ll see a series of example forms that can be used in your flows - feel free to click each of them to see what capabilities they provide in the preview.

Our experience is going to collect the user’s username and then use that information to figure out what Population they are associated with either for registration or authentication. We can quickly create that form by duplicating the Example - Sign On form already made for us.

Select the form entitled Example - Sign On, click on the three-dot menu (fun fact: those are called Kebab Menus) and select Duplicate. You’ll see a new version created called something like Example - SignOn1 - select it, hit the three dots and this time click Edit.

Creating Your First Form

The Editor view gives us access to a bunch of different capabilities, but we’re not going to need to make a whole lot of changes for our use case.

First, under Properties (in the left bar) change the Form Name to Email-First Authentication. Then, select the Password field and click on the trash can icon in the left window to delete it. Optionally, select the Username field, change the validation type to “Custom”, the Regex to ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ and the Error Message to the translation key forms.fields.user.email.errorMessage (which is the phrase “Invalid Email Address”).

The Email-First Authentication Form

When you’re done, make sure to save the form by hitting the “Save” button in the top-right of the page.

Creating Your DaVinci Flow

We’re going to be retrieving and responding to our Users’ inputs within a DaVinci flow.

On your left navbar, click on the DaVinci button. If it’s not there, make sure you’re in an Environment with DaVinci enabled.

A new tab will open in your browser to DaVinci. Click on the “Flows” button on the left navigation bar and the “Add Flow” in the top right corner of the page. If you’re using the example flow, feel free to select “Import Flow” otherwise click the “Blank Flow” option from the dropdown, giving it the name Dynamic Experiences with Populations. Once you hit “Create”, you’ll be taken into the DaVinci editor, which is where we’ll spend the majority of this How-To.

Retrieving the Population

Our Population contains important information about our user - things like their password policy, their branding, and if they log in using an external identity provider. To use that information accordingly we need a way to figure out what population our user (or new user) is related to.

Retrieving the Population based on the User

Collecting the Username

First off, let’s pull Population data based on the User that we’ve identified in our DaVinci flow. Think of this use case as the initial login page for your customers into your business: based on who we see, we’ll dynamically change their experience accordingly.

⭐ DaVinci Learning: Connectors, Capabilities, and Triggers

To start, click the “+” button in the bottom-left corner of your Canvas (that’s the editor window), click “User Interface”, and click on your “Email-First Authentication” form. A little node will snap to your mouse which you can then click on the canvas to add.

Adding a New Form

The form is a Connector and is using the “Show Form” capability - you can check this out by clicking the back error at the top of the form editor screen. You’ll also see that you can select the forms you created previously from the “Form” dropdown that appears.

Selecting the “Show Form” Capability

At this point you have a single node that collects the username and stores it under the key user.username. To test, hit the “Deploy” button in the top right corner and then the “Try Flow” button to open up the form in a new tab.

A rendered Form

Nice! In one node you have a log in form. Now, let’s figure out what Population this user is from based on their username.

Finding the User

Click and drag from the black dot on the right side of the Form connector - a little line should show up. When releasing that line, you’ll be prompted to add a new connector. This time, select the PingOne connector.

Connecting Connectors

You’ll see that your Form is now connected to a new node with a little grey bubble and a blue line with the word “True” on it. Those bubbles are called Action Decision Nodes and they allow us to branch decisioning logic based on the results of the prior connectors. Right now, that blue “True” is saying that if All Triggers are True, then the Form will continue to the PingOne connector. You can have multiple responses come from the same action decision node, which we’ll use later when handling actions like a user not existing in our Environment. If you ever need to change a trigger, you can right-click the word (in that case, “True”) or click on the Action Decision Node directly.

Action Decision Nodes

Now that these two connectors are connected, let’s configure the PingOne node to lookup the user. Click on the PingOne connector and select the “Find User” capability.

⭐ DaVinci Learning: Passing Data with Handlebars

We are going to be looking up our user based on their username, using the username inputted by the form. To do so, under the PingOne Attributes field type the word username and hit enter. Then under the identifier, select the “{}” icon in the right side of the input and click on your Form. Any time you see the “{}” icon means that you have access to data collected along the course of your DaVinci flow.

Collecting Input Data

Once you’ve clicked on your Form connector, you’ll see that the output values include the username keyed based on the defined key we set in the Form Connector. Go ahead and select user.username as the Identifier.

Selecting the specific value

If you’re curious why the icons for these values are curly braces, it’s because the data is actually being referenced using handlebars notation - if you hover on the value you selected you can see what the reference looks like. For the most part, you’ll probably not have to work with the handlebars directly, but it’s useful to know in cases that you want to ensure a specific value is being used in connectors downstream.

Seeing the Handlebars representation of the data

⭐ DaVinci Tip: Flows can get quite large quite fast. Consider putting unique titles and descriptions on each connector (you can find that in the “Settings” tab within the action’s editor view) as well as annotations (right-click on the canvas and select “Annotation”) to help you reference the correct values in inputs as well as better understand what a flow is doing when maintaining/editing.

Hit “Apply” to save your changes.

Retrieving the Population Details

If a User is found, we know their Population.

From the “Find User” connector, add an “All Triggers True” action connection to an Http connector with the capability “Custom HTML Message”. The message should say “Your population ID is” with the added variable of the matchedUser.population.id.

Displaying the Population ID

Apply, Deploy, and then Try your new flow. If you use a pre-existing user, you should see their Population ID.

The matched user’s Population ID

A Population ID isn’t too useful by itself. Let’s pull data on the Population directly using the ID we’ve retrieved.

⭐ DaVinci Learning: Disabling Nodes

Move the Display Population ID connector out of the way, right click, and Disable the connector. This lets us keep the connector in our editor if we want to use it later without it being considered by DaVinci as a valid path. The node will turn semi-transparent to indicate that it’s disabled.

Disabling a Node

From the same Action Decision Node, connect a PingOne Connector with the capability “Read Population”. In your input, add the same population ID from your matched user that you used in the Display Population step.

Reading a Population

Now, if the Population can be found, we can pull more metadata from that Population. Connect a new Http connector with the “Custom HTML Message” capability, toggle on “Show Continue Button”, and add the Message “Your Population data:” with the additional value of the population output that came from the Read Population node. If you want to add an object or array, rather than a single piece of data, into an input click the “+” button next to the specific object value.

Adding an Object as an Input Value

Apply, Deploy, and Try your flow. This time, you should see all of the metadata that came back from your user’s population.

The User’s Population

Retrieving the Population based on the Alternative Identifier

Next, let’s get the Population based on an Alternative Identifier we’ve been provided during the flow. Alternative Identifiers are custom values that you can set on a Population and are used to help you identify what Population should be selected during a flow. Think of this as a domain (possibly in a redirect URL or in the user’s email address), an ID (in a query parameter or body of a REST call), or any other value you’d like to use to help you recognize what Population matches. This is a great approach when you want specific users to be registered into particular populations as you can identify them even before they have created an account in PingOne.

In fact, registering by context is exactly what we want to add into our flow. Currently, if you enter in a user that doesn’t exist in PingOne, the flow returns an error. Instead, let’s try to find the right population for this user: falling back to our Default population if nothing matches.

Parsing the Email Domain

We are going to attempt to match the email domain extracted from our user’s username to an Alternate Identifier within our Population.

⭐ DaVinci Learning: Ping Marketplace

You probably noticed that when you got the user information, the domain isn’t extracted by default. If you wanted, you could always write a custom function in a Functions Connector to do this for you: but rather than build from scratch, Ping provides a Marketplace of Nodes and Flows pre-configured to handle the heavy-lifting for you. In this case, let’s use the Parse Domain from Email Address node.

Log into the Marketplace with your PingOne admin credentials, hit the “Copy to clipboard” button in the top right corner of the Marketplace listing, and then in your DaVinci canvas right-click an empty area and select “Paste Nodes”. You’ll now have the connector ready to go in your flow.

Pasting Nodes

As a rule of thumb: if there’s functionality you want but you can’t find a trigger that does it, a custom page in HTML that you want designed, or a more complicated flow that you don’t know how to start on, go to the Marketplace. It’s likely there’s something there that will either do or help you get to the solution you’re looking for.

Some notable Marketplace listings include:

Nodes:
- User Registration Node Group: A set of nodes that complete a registration process. Useful when learning how to design HTML in DaVinci, action on button presses with the A Equals Multiple B trigger, and interacting with teleports.
Styling:
- Ping UX - DaVinci CSS: A set of CSS files to help you quickly stylize and brand your custom HTML pages, compatible with Bootstrap formatting.
- DaVinci Design Studio: A Chromium web plugin that lets you quickly create custom themes in CSS that you can add as a custom style to your DaVinci flows. If you’re using custom HTML rather than a Form, and don’t have your own CSS to use, this is a great starting point.
Flows:
- DaVinci DNA Workforce Solution and DaVinci DNA CIAM Solution: A comprehensive set of modular functionality built out in reusable subflows, including PingOne MFA, PingID, PingOne Protect, and PingOne Verify. This is the gold standard for how to design flows and should get you 90% of the way there when building out your own designs
- Verified Trust for Workforce: A flow that enables a helpdesk user to confirm someone’s identity before performing sensitive actions. These flows are also built on the DNA methodology.

Alright: enough about the Marketplace. Let’s wire up this new node.

Connect the Action Decision Node off of your Find User node to the Parse Email Domain node, right-click the “True” action connection and switch it to “Any Trigger False”. In other words, we’re telling DaVinci to parse the email domain when the user does not exist in PingOne. Finally, within the Parse Email Domain node set the value of the variable email to the username you collected within the form.

Parsing the Email Domain

Hit “Apply”, and then drag and create a new PingOne Connector off of your Parse Domain node. From the new node select the “Read Population” trigger again but this time change the Population search to “Use Alternative Identifier” and pass in the domain that was parsed in the prior node.

Reading the Population from the Alternate Identifier

Now that we have queried Populations based on the identifier, let’s display the resulting selection. Unlike reading the Population based on ID, though, the same alternative identifier could exist in multiple populations - meaning our response could return more than one population!

⭐ DaVinci Learning: Cloning, Copying, and Pasting Nodes

To see this in action, we’ll display that result in a message like we did before. But rather than build a brand new node, right-click and Clone the existing HTTP node with our population’s message. Cloning a node, or copy/pasting a selection of nodes (highlighted by holding and dragging your mouse), makes building larger DaVinci flows faster and easier.

Cloning a Node

Wire the response of Read Population to the cloned node, and then update your cloned node to look at the populations response from the query rather than a single population. An important note - the population value in your cloned node is still pointing to the original connector it was connected to (i.e. Read Population by ID). When cloning, make sure your references are matching the correct nodes.

Displaying all Populations

With this all connected, applied, and deployed, add an alternative identifier to a Population that matches an email domain you can test. In this example, I’m using “bxretail.org”.

Setting the Alternative Identifier on the Population

Now, when I try the flow and enter a user who doesn’t exist using that email domain, the population (or populations) with that alternative identifier show up.

Retrieving Populations on Email Domain

Selecting a Population from a List

When the User does not exist and we query Populations based on the email domain, there are a series of outcomes we need to account for:

The email domain is associated to one Population
The email domain is associated to more than one Population - in which we let the user select their Population
The email domain isn’t associated with any Population - in which we fall back to the Default Population

To do so, we will implement some Function Connectors to branch our path. Function Connectors let us compare values and make decisions based on what we find, or run JavaScript to do things like modify or create values to pass into downstream connectors.

Right-click and Delete your HTTP node that displays populations. We won’t be needing it anymore.

⭐ DaVinci Learning: Functions Connectors**

In its place connect a “Functions” Connector and select the “A > B” Trigger, adding the title “Any Pops Found?”. Set the Type to “Number”.

In A, add the “rawResponse” field from your Read Populations node, hover over the field, and copy the handlebars reference that appears. It’ll look something like {{local.68dcy1mtem.payload.output.rawResponse}}.

Getting the Raw Response

The triggers within the PingOne connector are making API calls behind the scenes, and if you know the Read Populations request you’re aware that there’s an additional field that’s hidden in this result set: the size - which informs you how many results have been returned from the request.

⭐ DaVinci Learning: Accessing Hidden Fields

Just because the field doesn’t show up in the schema selector doesn’t mean that the field is missing - it just means that the connector didn’t define that value in its output schema. To get access to size, modify your copied handlebars to include size as a key, something like {{local.68dcy1mtem.payload.output.rawResponse.size}} and then copy/paste that change as Value A in your A > B node. Value B, then, should be set to 0.

Accessing Hidden Fields

⭐ DaVinci Tip: That seemingly arbitrary string of values after local is your Node ID - and it’s how each node is being referenced throughout your flow. You can find the Node ID under the header of the Node editor or by toggling “Show Node IDs” in your flow settings (top-right menu).

We now have a True/False branch we can use. Connect an “All Triggers True” response to the Function Connector with the Trigger “A > B”, the Title “More than One Pop Found?”, A set to the handlebars you used in the prior node, B set to 1, and the Type set to Number.

Checking for Many Populations

From that same Action Decision, wire an “Any Trigger False” to a PingOne Node with the Trigger “Read Population” and the selector set to “Default”.

Getting the Default Pop When None are Found

⭐ DaVinci Learning: HTML Templates and Custom CSS/JavaScript

If more than one Population is found, we want the User to select their preferred Population. To do this, we are going to go back to the marketplace to insert the Dynamic Dropdown node. This node pack is a bit different than our forms as it uses the HTTP Connector’s Custom HTML Template to render content, which gives us a great opportunity to review a more complex node.

First off, connect an “All Triggers True” trigger from the “More than One Pop Found?” node to the “Form Options Array” node that you just imported. Then, in that node you just connected, add the “populations” array gathered from your “Read Pop(s) by Alt ID” Node, setting the optionLabelKey to name and the optionValueKey to id.

Connecting the Populations List

Create a new Population (I named mine “Example 2”) with the same alternative identifier, and then Apply, Save, Deploy, and Try the Flow. When you enter in a new User with that domain, you should see a dropdown with the associated Populations. But what gives - the page looks terrible!

The Unformatted HTML Page

The HTTP Node you imported lets you serve custom HTML, CSS, and JavaScript - it’s great in cases when you require heavier customization, interactivity, or interaction with an external CMS. In this case, our template that we imported relies on Ping UX - DaVinci CSS: so let’s import that into the flow.

To do so, click on the menu (three dots) in the top right corner and select “Flow Settings”, and then in the “Customizations” tab under “Page Customization” enable “Use Custom CSS”. There you can add in the Custom CSS Rules and the Custom CSS files provided in the Marketplace (or, for your own use cases, the custom assets you have from your own system).

Adding the Custom Ping CSS

⭐ DaVinci Tip: Want a starting off point? Add the DaVinci Design Studio Chrome extension to get custom css that can be used in tandem with the Ping CSS provided.

Apply, Save, Deploy, and Try the Flow again. You’ll see the form shows up with the formatting matching the baseline branding in your form editor, with one exception: the Logo isn’t showing up.

The Properly-Formatted Dropdown

If you read through the Dynamic Dropdown node, you’ll see that it also (optionally) expects the DaVinci Branding Variables Node. This node lets you quickly and easily set the name of your company and the URL of your logo to be used across all HTTP nodes. Copy that node and place it at the beginning of your flow, connected to the first form in which you show the username.

Set Company & Logo Node

You know the drill. Apply, Save, Deploy, Try. Now your logo shows up on the page too.

⭐ DaVinci Learning: Input and Output Schema

Both the Functions Connector and the HTTP Connector we just added have an Input and an Output schema. These schemas exist so that you can add specific data requirements on what data is needed for this node to function and what data will be returned for use in downstream nodes.

Let’s take a look at how the schemas are defined and what they look like in practice, starting with the “Form Options Array” Custom Function Node.

Clicking into this node, you’ll see that some JavaScript is being executed to parse an array of objects and format that array into something that the HTML node can use when building the dropdown. At the top of the node you’ll see a Variable Input List - this is where the variables that are being passed in the params object you can see referenced in line 3 of the script are coming from. These variables are given a name, a value, and a data type, which helps inform the script how to parse and interact with that params value.

Underneath the hood, these variables are being defined with an Input Schema using JSON Schema formatting. In the case of the Custom Function Node, how those parameters are passed into the JavaScript is handled for you.

At the other end of the JavaScript function, you’ll see that you’re returning an object with the key options). This contains the key/value pairs that are being referenced in the HTML node. But while this data is being returned, the JavaScript by itself doesn’t inform the downstream nodes what the data looks like. The Output Schema provides that definition.

Scrolling to the bottom of the node definition, you’ll see an Output Schema section with the following JSON:

{
  "output": {
    "type": "object",
    "properties": {
      "options": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string"
            },
            "value": {
              "type": "string"
            }
          },
          "required": [
            "label",
            "value"
          ]
        }
      }
    }
  }
}

You’ll see that the output of this node is expected to return a property of name options, which is an array that contains objects whose properties are label and value: both strings.

When you click on the “Dynamic Dropdown” HTTP Node, you’ll see that the options array is passed and that you can reference it within the output of the Form Options Array node. Since the Label and Value were also defined, you can see that you can select that option directly from that object, to do things like target a specific element in the array.

The Resulting Output

Since we are in the HTTP node, let’s take a look at how the inputs are formatted - since all of the input elements up to the HTML template are special to just this created node. Instead of an input editor like we saw in the Function Node, the Inputs are defined in an Input Schema halfway down the page - right next to the Output schema and just below the Form validation rules.

⭐ DaVinci Tip: If you are making your own HTML template, toggle the “Switch View” button to view the template using a classic code editor. When you’re adding variables, toggle back and use the “{}” button like you’ve done in other inputs.

The Input Schema here defines not only what values are expected to be available, but also how the inputs should be formatted for the user to fill in (preferredControlType) and whether or not the user can dynamically pass parameters from other nodes (enableParameters). The type and displayName indicate how the input is used and how it shows up for the user in this node. When editing the Input Schema, it’s important to know:

Your inputs should be put within the properties object.
The only preferredControlType available is textField.
Your inputs must use unique keys.
If you define a propertyName, the propertyName must match the key.
It’s best to edit the Input Schema in a separate text editor. It makes editing and validating the schema easier.

Try adding another input - let’s call it example. It should look something like this:

"example": {
"type": "string",
"displayName": "My New Example Input",
"preferredControlType": "textField",
"enableParameters": true
}

Apply your changes. You’ll see the new input ready to go with the key example available for use in your HTML, CSS, and JavaScript via handlebars.

The New Input

There’s no need to keep that input. You can remove or leave it in, your call.

The Input and Output Schema shows up throughout DaVinci - you’ll see it in Teleports (we’ll get to that later) and the overall Input Schema for your flow. These definitions allow you to strongly define what is being passed in and out of each node, from one flow to another, or from another application into the DaVinci flow.

⭐ DaVinci Learning: Output Fields

While looking at the HTTP Node you probably noticed that there was nothing defined in the Output Schema but that node needs to return some data to the next node - in this case, what was selected and what button was pressed. Custom HTML Templates reference output data defined directly in the HTML itself and use the Output Fields list to link that data back to the node’s output.

In the Output Fields List section you should see two properties: one called select and one called buttonValue. Now, take a look in the HTML Template: you’ll see that our select has the id of select and our submit button has the data-skbuttontype of form-submit and the data-skbuttonvalue of CONTINUE.

For standard inputs, the id of that input is referenced in the Output Fields List. For buttons, that definition is handled by the sk attributes that live on it - in particular, that skbuttonValue is holding the value that you can reference later, and that “buttonValue” output field is referring to it.

For a list of SK Attributes, head to the documentation here. For a list of standard components that can be added to HTML (called SK-Components), such as polling, camera, recaptcha, and filepickers, go here.

You’ve also probably noticed that both the button and the select have a Data Type of String and a Control Type of Text Field. For all intents and purposes, those two fields should be left as-is: the conversion from your HTML to the other options may not work as expected.

⭐ DaVinci Tip: When working with forms, make sure that the id of your form matches the data-skform html tag on your submission buttons - otherwise, your DaVinci flow won’t receive the results of your form data.

Changing the Theme based on the Population

You now have a means to identify the Population based on an existing User or a new User with the added capability for the User to select their Population if their username matches more than one. Let’s cater the experience based on the context that their Population provides.

Each Population can be assigned its own Theme. This Theme can then be referenced within DaVinci to stylize your user’s experiences.

⭐ DaVinci Learning: Teleports

We have two different experiences that we will want to present to our user, a Login experience and a Registration experience, and more than one place in which we need to surface it. In the case of Registration, for instance, we both will need to perform the registration process if a population was selected by the user, if there was only one population found, or if the default population was selected instead. You could duplicate functionality, but if you want to change something later you’re going to have to find and change each implementation one at a time, which could lead to some pretty hard to troubleshoot errors. You could wire up each node to the same path, but not only does that get visually confusing you’ll have to handle all of the different outputs per node. This is where Teleports come in.

From a coding sense, think of a DaVinci flow as a module. It likely performs a series of things in combination with each other to enact a larger action - like registration and login. Within that module are functions - little bits of smaller atomic actions that are invoked for the module to do its thing. Teleports are these functions. Teleports allow you to break out smaller pieces of functionality into reusable segments that can be called on, looped from, and reused without any copy/pasting or complex wiring.

As a rule of thumb, if you are reusing the same nodes over and over again, consider putting them in a Teleport.

To start, scroll below the flow you’ve built so far and add an annotation to indicate what this teleport is for (I’m using “Login”). It’s best practice to write flows horizontally and individual teleports vertically, ideally with the teleports in execution order (for example, if you have a teleport that returns a session or an error, it should probably be at the bottom) - that way, you can read through the content of a flow similar to how you would read a flowchart or diagram.

Next, add in a Teleport connector with the trigger “Define a Start Node”. Once you do, you’ll see something pretty familiar - an Input schema! Teleport Start Nodes tell the flow where a new section begins and what data can be passed into that section: think of it like a function definition.

First off, change the name of your Teleport in the Settings tab - you’ll use that name to identify the Teleport later. I’m naming mine “Login”.

The Input Schema should look something like this:

{
    "type": "object",
    "properties": {
        "p1UserId": {
            "type": "string",
            "displayName": "PingOne User ID",
            "preferredControlType": "textField",
            "enableParameters": true,
            "propertyName": "p1UserId"
        },
        "p1UserName": {
            "type": "string",
            "displayName": "PingOne Username",
            "preferredControlType": "textField",
            "enableParameters": true,
            "propertyName": "p1UserName"
        },
        "populationId": {
            "type": "string",
            "displayName": "Population ID",
            "preferredControlType": "textField",
            "enableParameters": true,
            "propertyName": "populationId"
        },
        "populationThemeId": {
            "type": "string",
            "propertyName": "populationThemeId",
            "displayName": "Population Theme ID",
            "enableParameters": true,
            "preferredControlType": "textField"
        },
		"populationIdPId": {
            "type": "string",
            "propertyName": "populationIdPId",
            "displayName": "Population IdP ID",
            "enableParameters": true,
            "preferredControlType": "textField"
        }
    }
}

This allows us to pass our PingOne User’s ID and Population Details into the Teleport.

⭐ DaVinci Tip: Teleports stringify the data that comes into it and as a result, won’t be able to handle nested object definitions. Either define your required fields individually in the input schema, set them in a Flow Instance Variable, or write a custom function to parse the values from the stringified object.

In our case, since we only need two values from our Population it’s easiest to define them at the top level.

Now connect a Form Connector with the Show Form Trigger to your Teleport Start Node, selecting the “Password Authentication” form. Change the Form Theme to “Use Theme ID” and pass in the Theme ID from your parsed Population.

Passing Parsed Object Variables into a Form

You probably noticed that your variables list looked different inside this new section. That’s because the Teleport only has access to the data that was passed into it or variables set at the Global or Flow Instance level. Just like a function, the teleport can only see its parameters, top level constants, or run-time variables.

Back up to your Read Population by ID node (the one called after you discover an existing user), replace your HTTP node with a Teleport but this time use the Go to Start Node trigger and select your Login teleport as the start node.

Your variables for a PingOne User ID and Population Details will appear. Add in your PingOne User from your Find User node and the PingOne Population Details from the Find Population node.

Go to Teleport

You’ve now set up a way to pass data into a teleport - basically, execute a function in your module. Apply, Save, Deploy, and Try the flow with a user that does exist. You should now hit the Password page.

The Password Page

But the theme looks just like the last page! Let’s change that.

Back in PingOne, under User Experience → Branding and Themes, go ahead and create a new theme. I’m using the base “Slate” theme for this example.

When you’re feeling good about the theme, under Directory → Populations select your Population and under Configuration assign your new theme.

The next time you go through the flow, you’ll see the theme change to your selected theme.

The Updated Theme

Enforcing Password Policies based on the Population

You can set a unique Password Policy per Population so that each User segment can meet the security requirements set by their organization.

Since a User can only be a part of a single Population, the default node already knows their password policy during login. From the Password Authentication Node, connect a PingOne Connector with a Check Password Trigger, adding the teleported p1UserId and the password you collected from the form.

The Check Password Node

A password can be in more than one state - it’s valid, invalid, or it needs to be updated in some way (e.g. it’s expired, doesn’t meet the new password policy requirements). If you wanted to just check if the password is/isn’t valid, creating responses using the “All Triggers True” and “Any Trigger False” responses works just fine. But, if you’d like to perform additional branches on validation you can use an A == B (Multiple Conditions) Function Node to compare the status of the Check Password response to the response options shown in the Check Password API reference.

For the sake of this example, we’ll create an outcome only on success - the error response will be handled for us.

Wire up the Check Password Node to an HTTP connector with the Custom HTML Message trigger and give it the message “Password Status:” including the status variable from your Check Password node. If you want to see all status information, set the path to be “Any Trigger Completes”.

Now, when you log in with the correct password you’ll see the status information that you’d likely branch from in a more robust flow.

Returned Password Check Status

Enforcing Login with an External IdP based on the Population

Some of your business groups and partnerships may have their own established Identity Provider that they’ll want to bring rather than having their users create and manage a separate account. Populations let you assign a default provider that, when a user federates with it, will associate them with the right Population (and as such the appropriate theming and managed administration).

Your teleport has already been configured to pull in the external IdP ID tied to your population - we’ll just need to add the branching path that decides whether to log in with that IdP instead of locally.

Connect your Teleport Start Node to a Function Connector with the “A is Empty” trigger and enable “Check undefined/null”. Connect the “All Triggers True” outcome to the Password Authentication node you made in the last section.

Check for Local Login

Next, connect the “Any Trigger False” outcome to a PingOne Authentication Connector with the trigger “Sign On with External Identity Provider”, using the populationIdPId, the populationId, and the p1UserName (in the Login Hint) you collected in the teleport.

⭐ DaVinci Tip: If you don’t want users to be able to link to an existing account or create a new account from an external IdP, uncheck the “Link with PingOne User” checkbox.

External IdP Login

To test, add an HTTP Connector with a custom HTML Message of your choosing - I’ve added the statusCode from the external IdP Login. When you Log in with a Population that doesn’t have an External IdP configured, you should see the password page as you did before. But in the case you have an External IdP configured, you’ll redirect to their login page and then come back with your login status.

A Successful External IdP Login

Dynamic Registration

We’ve created the Teleport for Logging in, but we haven’t handled the users who don’t exist yet. Hold and drag with your mouse to highlight all of your login teleport nodes and Duplicate the selection. Next:

Rename the Annotation and the Teleport Start node to “Registration”.
In the Teleport Start Node, remove p1UserId since a user doesn’t exist yet.
Change the Password Authentication form to “Example - Registration” and pass in the p1UserName into the username and email field values.
Change the Check Password Trigger to the Create User Trigger and pass in the Username, Email, Password, and Population ID.

Finally, wire up the following connections in your New User branch at the top of your flow to the Go To Teleport for Registration:

Using an “All Triggers True” after the “Get Default Pop” node, using the population details from the Get Default Pop and the Username from the Username form.
Using an “Any Triggers False” after the “More than One Pop Found?” node, using the top Population result from the “Read Pop(s) by Alt Id” node and the Username from the Username form.
Connecting from the Dynamic Dropdown node (replacing the HTTP node), connect a PingOne Connector with a Find Population trigger using the selected population ID, and then wire the true outcome to the Registration teleport using the newfound population details. Alternatively, replace the Get Population node with a Custom Function that returns the appropriate population details from the previous call.

Now, when you enter a new user you are taken to the appropriate registration page depending on your Population preferences, automatically using the appropriate password policy and external IdP.

New User Registration

Connecting the Flow to Your Application(s)

Up to this point we have used the “Try Flow” button to test out our DaVinci flow. While this approach is great for testing or for flows that execute actions without the need for returning user context, in the real world it’s highly likely that your flows will complete with a user logging into an Application with an active session from PingOne.

To start, let’s make two more Teleports: one to return an authentication success and the other to return a failure.

Duplicate just the annotation and the Start Teleport Node from your Login section and then change the Input Schema for your Login Success Teleport to only have the p1UserId - that’s all we need to authenticate the user. Name the new section and teleport “Login Success”.

From that node connect a PingOne Authentication Connector with the trigger “Return Success Response (Redirect Flows)”. Configure this node to use the User ID from the Teleport and leave the Authentication Method as “pwd” since we aren’t performing any additional form of risk or multifactor-based authentication. You’ll see in this node you can optionally decorate the ID and Access Tokens with custom claims as needed by your downstream application.

The Success Route

Duplicate the nodes and annotations, renaming the new section and teleport “Login Failure”. Inside the teleport, change the input schema to capture the Error Message:

{
	"type": "object",
	"properties": {
		"errorMessage": {
			"type": "string",
			"displayName": "Error Message",
			"preferredControlType": "textField",
			"enableParameters": true,
			"propertyName": "errorMessage"
		},
		"errorDescription": {
			"type": "string",
			"displayName": "Error Description",
			"preferredControlType": "textField",
			"enableParameters": true,
			"propertyName": "errorDescription"
		},
		"errorReason": {
			"type": "string",
			"displayName": "Error Reason",
			"preferredControlType": "textField",
			"enableParameters": true,
			"propertyName": "errorReason"
		}
	}
}

Then, change the PingOne Authentication Connector’s trigger to “Return Error Response” with a custom error message that uses the inputs you just provided in the Teleport’s Input Schema (I set the Error Message to invalid_request).

The Success and Failure Teleports

Now that you have a means to inform the downstream applications of a success or failure, let’s wire it up to the appropriate paths in the flow.

From Node	Connect Go To Teleport	With Variables
Check Password, Inside Login	Login Success (All True)	`p1UserId` from the teleport, or the `id` returned from Check Password
Check Password, Inside Login	Login Failure (Any False)	The error details from Check Password
External IdP Node, Inside Login	Login Success (All True)	`p1UserId` from the teleport, or the `id` returned from External IdP Login
External IdP Node, Inside Login	Login Failure (Any False)	The error details from External IdP Node
Create User, Inside Registration	Login Success (All True)	The `id` returned from Create User
Create User, Inside Registration	Login Failure (Any False)	The error details from Create User
External IdP Node, Inside Registration	Login Success (All True)	The `id` returned from the External IdP Login
External IdP Node, Inside Registration	Login Failure (Any False)	The error details from External IdP Node

The Connected Teleports

⭐ DaVinci Learning: PingOne Flows

In order for our DaVinci flow to be connected to an application in PingOne, we will need to make it a PingOne Flow.

PingOne operates with DaVinci via an OIDC redirect. When a user attempts to log in to an application in PingOne, and DaVinci is protecting that application (via a Flow Policy), PingOne will redirect the user to DaVinci to perform its actions upon which it redirects back to PingOne to generate a user session and log the user in. The handoff looks something like this:

DaVinci with PingOne

Underneath your Flow Settings (click the three dots in the top-right, select Flow Settings and under the General tab) enable PingOne Flow. This converts the flow to run for either OIDC or SAML authentication with PingOne.

Enabling a PingOne Flow

Once you do this (and deploy!) you’ll notice that a little “P1” icon appears next to your title and if you try to use the “Try Flow” button you’ll be redirected to an error page that indicates that this flow requires PingOne to run.

Hitting “Try Flow” with a PingOne Flow

DaVinci connects flows to PingOne applications using Flow Policies. Flow Policies let us define what flows and flow versions run, when they run, and what statistics we’d like to gather when users are driven through the flows (say, a successful outcome or a failure).

On the DaVinci sidebar, click on “Applications”. You should see a page that includes a PingOne SSO Connection. You can add more Flow Policies to the existing PingOne Connection or create a new one - this lets you create bundles of Policy categories, making it easier to identify when selecting the Policy in PingOne.

DaVinci Applications

Create “Add Application” and name it “Dynamic Populations”, then click on the created Application. You’ll see that this application is its own OIDC client with a unique client ID and client secret, and that the “Company ID” is actually the ID of the PingOne environment that this instance of DaVinci is tied to. This lets you take that same application and use it with non-PingOne systems you want DaVinci to interact with.

Select the “Flow Policy” tab and click on “Add Flow Policy”. Make sure you add a name in the first step (in my case I’m doing “Population Login and Registration”) and select “PingOne Flow Policy” since we will be interacting with a PingOne application. An option to Bypass flows will appear - skip that section and click Next.

Adding a Flow Policy - Step 1

You’ll now see a picker of PingOne-configured flows that you have created. Select the flow you’ve been working on (Dynamic Experiences with Populations) and click on “Latest Version”.

⭐ DaVinci Tip: DaVinci holds up to 100 past versions of your deployed flows - meaning that you can “lock” an application down to a specific version of a flow while you develop a new one without impacting your users’ experience.

Adding a Flow Policy - Step 2

Next, set your selected flow to 100% distribution and set the PingOne Authentication (Login Success) node as your Success Node.

⭐ DaVinci Tip: DaVinci Flow Policies let you select multiple flows and flow versions in the same policy and then set a distribution to each instance within that policy. That, coupled with the success node definitions, allows you to A/B test and gather feedback on different approaches with your users simultaneously.

Adding a Flow Policy - Step 3

At this point you have defined an Application and a Flow Policy within that Application. Let’s assign that policy to PingOne to be evaluated when a user attempts to login.

Back in PingOne, click on the “Applications” tab and submenu. Feel free to use a custom SAML or OIDC application, but for the sake of simplicity I’m going to use the “PingOne Self-Service - MyAccount” application.

Clicking on your application, select the “Policies” tab and click “Add Policies”. You’ll see a DaVinci tab in the subsequent editor - click on that tab and then check the new policy you just made.

Assigning a Flow Policy to a PingOne Application

By assigning this policy you have informed PingOne that for a user to successfully authenticate into this application they are required to first go through the DaVinci flow you created.

On the Overview tab, click on the Home Page URL of the Self Service Application (or in the case of your OIDC/SAML App, the appropriate calling URL) and open in an incognito tab. You’ll be greeted with a familiar sight - your DaVinci flow! Successfully complete login and you’ll be redirected to your My Account page (or wherever your app completes).

A Logged-In User

Conclusion

You now have a way to dynamically branch login and registration experiences based on contextual data supplied by the User and Population. You’ve also built a toolbox of relevant skills in DaVinci to build more complex, interesting, and incredible flows confidently.

DaVinci is an incredibly powerful tool, and coupling it with the strong capabilities and services within PingOne you can design the most secure and seamless experiences for your users.

For a copy of the completed flow, go here.

Other Helpful Tricks

There are some other capabilities in PingOne that may prove useful as you work your way through more complicated flows.

Variables

Variables allow us to set data that can either be stored and referenced at a particular instance of a running flow (that’s a Flow Instance Variable, like a module-level constant) or globally across all executions (that’s a Global Variable or Company Context, and it’s exactly what you think).

You can set variables within nodes in Flows (you actually did that in the “Set Company & Logo” node) as well as via the “Variables” tab on the left menu. It’s likely that you’ll set Flow Instance Variables dynamically within a Flow and Global Variables from within the menu (as those are normally static for all flow executions). A great example use case of Global Variables is the DNA Flows mentioned before - check out their configuration guide for an example of what you can store.

Parsing Objects from a Teleport

If you had a complex object that you wanted to pass directly into a teleport, it’s useful to parse that object in a subsequent Custom Function Connector.

The function within that connector should be incredibly simple - return the name of the object you want to return and parse the passed object into JSON.

As an example, if you wanted to pass the Population object into a teleport directly you could create a script that looks something like this:

module.exports = async ({params}) => {
	return {'population': JSON.parse(params.populationString)}
}

In a production use case you may want to add some parametrization and checking to validate that your object has all of the values you’re looking for.

Next, set your Output Schema to map to the object you want to reference.

Using the same use case, your output schema may look something like this:

{
	"output": {
		"type": "object",
		"properties": {
 			"population": {
				"type": "object",
				"propertyName": "population",
				"displayName": "Population",
				"properties": {
					"id": {
						"type": "string",
						"displayName": "Population ID",
						"propertyName": "id"
					},
					"name": {
						"type": "string",
						"displayName": "Population Name",
						"propertyName": "name"
					},
					"preferredLanguage": {
						"type": "string",
						"displayName": "Preferred Language",
						"propertyName": "preferredLanguage"
					},
					"passwordPolicy": {
						"type": "object",
						"displayName": "Password Policy",
						"propertyName": "passwordPolicy",
						"properties": {
							"id": {
								"type": "string",
								"displayName": "Password Policy ID",
								"propertyName": "id"
							}
						}
					},
					"theme": {
						"type": "object",
						"displayName": "Theme",
						"propertyName": "theme",
						"properties": {
							"id": {
								"type": "string",
								"displayName": "Theme ID",
								"propertyName": "id"
							}
						}
					},
					"defaultIdentityProvider": {
						"type": "object",
						"displayName": "Default Identity Provider",
						"propertyName": "defaultIdentityProvider",
						"properties": {
							"id": {
								"type": "string",
								"displayName": "Default Identity Provider ID",
								"propertyName": "id"
							},
							"type": {
								"type": "string",
								"displayName": "Default Identity Provider Type",
								"propertyName": "type"
							}
						}
					}
				}
			}
		}
	}
}

This approach gives us a parsed object we can reference in later nodes.

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community.

Introducing the DaVinci MCP Server

Thu, 14 May 2026 00:00:00 GMT

As the market moved toward AI assistants and agent-based workflows, I kept coming back to one question:

What does this mean for identity orchestration platforms?

More specifically, what should identity orchestration look like when AI assistants become part of the developer workflow?

Identity journeys are not just pieces of code. They represent onboarding, authentication, MFA, recovery, fraud checks, and access decisions. They are the product of decisions made by architects, developers, product managers, and security teams, often over many months, sometimes by people who have since moved on. If AI assistants are going to help teams build and operate software, they also need a better way to understand the identity journeys behind those experiences.

That realization came to me through a very ordinary scenario.

Life Before AI-Assisted Orchestration

When a Simple Support Ticket Becomes an Identity Investigation

Silvia is a support agent at ACME Corp. She has received several tickets from users who cannot register their FIDO2 device during account creation. She knows that MFA device onboarding runs through DaVinci, but she does not know which flow is involved, where the failure is happening, or who to ask first.

Traditionally, her path forward looks like this: escalate to the flow development team, wait for someone to pick up the ticket, have them identify which application and flow policy is in scope, inspect the connector configuration, review execution logs, and determine whether the failure is in the flow logic, the MFA connector, a policy decision, the user’s device, or something upstream in PingOne.

The customer issue is simple to describe. The investigation is not.

Silvia does not need to become a DaVinci expert. But she does need a faster way to ask operational questions: Which flow handles this onboarding journey? Where does FIDO registration happen? Which connector is used? What did the last ten failed executions look like? What should I check first?

Right now, those questions require a specialist. They do not have to.

Need of the Hour

These are situations where the need for an MCP server becomes imminent, as a practical way to make DaVinci administration and troubleshooting easier.

If an AI assistant can securely access the structure of a DaVinci environment, it can help people like Silvia understand flows faster, identify dependencies, validate configuration, and troubleshoot failures without starting from scratch every time.

A Quick Word on MCP

Before we go further, MCP, or the Model Context Protocol, is an open standard introduced by Anthropic that allows AI assistants to connect to external tools and data sources through a common interface. Instead of fragmented, custom integrations between AI tools and every system a team uses, MCP provides a standard protocol for connecting AI assistants to the systems where context actually lives.

For identity orchestration, that context lives in flows, applications, connectors, variables, forms, flow versions, validation results, and execution history.

MCP is the bridge. The DaVinci MCP Server is what sits on the other side of it.

For a deeper look at MCP’s architecture, workflow, and security model, see the Ping Identity MCP documentation.

The DaVinci MCP Server

Today we are introducing the DaVinci MCP Server, an open-source MCP server that gives MCP-compatible AI assistants secure, structured access to your DaVinci environment.

This is our first step toward making DaVinci context available to AI. The current release focuses entirely on read access; exploration, inspection, validation, and execution monitoring. The goal for this first release is to help teams understand their DaVinci environments faster, and then gradually move towards automating changes to DaVinci resources.

The MCP server includes tools organized into two collections:

davinci_admin: Core administrative tools for exploring your environment:
- List and inspect flows, flow versions, and full flow definitions including node graphs
- List applications and application flow policies
- Discover available connectors and deployed connector instances
- Get details on variables and forms
davinci_flow_troubleshooting: Specialized tools for validation and debugging flow configurations and troubleshooting flow executions

Life After AI-Assisted Orchestration

The first time this becomes useful is not some dramatic moment where an AI agent fixes an entire identity journey by itself.

It is a moment where support agents like Silvia can directly ask, “Where are users failing during FIDO registration?” and getting a place to start instead of an escalation queue.

It is an architect asking, “Is this flow ready to deploy?” and seeing validation errors and warnings explained in plain language, not buried in a UI they have to navigate manually.

The exact time savings will vary by environment, flow complexity, and familiarity with DaVinci. But the difference in the starting point is consistent. With the DaVinci MCP Server, an AI assistant can surface the relevant flows, dependencies, validation results, and execution details at the start of the conversation, not at the end of a multi-hour investigation.

Persona	Situation	Without DaVinci MCP Server	With DaVinci MCP Server
New developer / architect	Inherited an onboarding journey, needs to improve drop-off rates	Days to weeks: learn DaVinci concepts, inspect flows and identify dependencies manually.	Hours: ask the assistant to explain the flow, identify dependencies in business terms
Support / operations team	Production issue reported, team does not know which flow or node is responsible	Hours or days of back-and-forth between support and identity admins, starting with no context	Faster first response: provide user and approximate timelines and get details on point of failure
Identity architect	Review whether a flow is production-ready	Hours of manual review across the flow ecosystem, and known best practices	Minutes: the assistant validates the flow configs and highlights blockers
Developer	Make changes to a flow	Hours of manual inspection of the flow and its references	Minutes: the assistant generates a flow dependency summary before the developer touches anything
Product manager / business owner	Onboarding conversion dropped, wants to understand why	Days or weeks: Wait for technical teams to manually explain flows and correlate behavior	Hours: Get understanding of the onboarding journey in business terms and ask more focused follow-up questions

Once teams see how much time is spent on context discovery and first-triage work, the natural next question becomes: which of these workflows can we automate? The read-only tools in this release are the foundation, but once you understand what your AI assistant can see and reason about, you start seeing which repetitive, manual, and rule-based investigation tasks are candidates for automation.

The key takeaways are:

start with simple things,
build confidence in how AI interacts with your DaVinci environment,
and progressively hand off more of the first-response and review work to AI-assisted or fully automated workflows.

Getting Started

The DaVinci MCP Server runs locally on your machine. Before you begin, make sure you have:

Local Prerequisites

Node.js v22.0.0 or higher (Download & Install)
An MCP-compatible AI client such as Claude Code, VS Code with Cline, Cursor, Gemini CLI, or Claude Desktop

PingOne Prerequisites

A PingOne subscription (licensed or free trial)
DaVinci enabled on your PingOne environment (Admin Console → Environments → Services → DaVinci)
A PingOne Worker Application configured with:
- Authorization Code + PKCE
- redirect URI http://127.0.0.1:7474/callback
- Token Endpoint Authentication Method set to None
A PingOne user with at least DaVinci Admin Read Only role assigned

Configuration Values You’ll Need from PingOne Admin Console

Variable	Where to find it
DAVINCI_MCP_ENVIRONMENT_ID	Settings → Environment Properties
AUTHORIZATION_CODE_CLIENT_ID	Applications → your Worker App → Overview
ROOT_DOMAIN	pingone.com (NA), pingone.eu (EU), pingone.asia/pingone.au (APAC), or your custom domain

Add the Server to Your AI Client

For Claude Code CLI:

claude mcp add --transport stdio davinci \
  --env DAVINCI_MCP_ENVIRONMENT_ID="your-environment-id" \
  --env AUTHORIZATION_CODE_CLIENT_ID="your-client-id" \
  --env ROOT_DOMAIN="pingone.com" \
  -- npx -y @ping-identity/davinci-mcp-server start

For other clients (Claude Desktop, Cursor, VS Code Cline, Gemini CLI), add the equivalent JSON block to your MCP client configuration:

{
  "mcpServers": {
    "davinci": {
      "command": "npx",
      "args": ["-y", "@ping-identity/davinci-mcp-server", "start"],
      "env": {
        "DAVINCI_MCP_ENVIRONMENT_ID": "your-environment-id",
        "AUTHORIZATION_CODE_CLIENT_ID": "your-client-id",
        "ROOT_DOMAIN": "pingone.com"
      }
    }
  }
}

VS Code and Cursor users can also use the one-click install deeplinks in the GitHub repository. For advanced configuration, filtering which tools or collections are exposed to the AI assistant, see the full setup guide.

Security

OAuth 2.0 with PKCE Every tool call is authenticated using OAuth 2.0 Authorization Code flow with PKCE. Your password is never stored. The resulting access token is saved in your OS-native keychain, the same place your browser stores credentials.

Read-only operations The current release is entirely read-only. No flow mutations, no deployments, no configuration changes are possible through these tools. There is nothing to audit because nothing is written.

Least privilege The agent has the same permissions as your authenticated PingOne user. Use the DaVinci Admin Read Only role. Do not authenticate with an account that has write or admin-level access unless you have a specific reason and have reviewed the implications.

Trust your client Only run this server with AI clients you trust. Review agent prompts and tool calls before deploying AI-assisted workflows to production.

What to Do Next

Try it in a real scenario. Think about something you or a teammate spent too long on recently, understanding a flow, diagnosing a failure, preparing for a review. Try it again with the MCP server connected to an AI assistant.

Think about your workflows. Where does your team spend time rediscovering context? Where are the first-triage steps that are repetitive and rule-based? Those are the candidates for AI-assisted or eventually automated workflows.

Share what you find. The Ping Identity developer community is where use cases get refined. What worked, what did not, what you wish the server could do, that feedback shapes the roadmap.

Raise issues on the repository. If you hit a bug, a gap, or if you have an enhancement request open an issue. We are listening.

References

Delegated Administration in PingOne

Tue, 12 May 2026 00:00:00 GMT

This post was originally published on Gwiz Kid.

Introduction

Your business is likely not just one set of users. In today’s world, identity stretches beyond the borders of siloed Internal (Workforce Employee) or External (Customer) user engagement and relationships. And as that line blurs, so does the process of user administration.

PingOne, Ping’s Multi-Tenant SaaS solution, provides a robust means to delegate and manage administrative capabilities across the platform.

This Guide will teach you how you can create and manage delegated administration of Policies and Users within the PingOne Platform. It is broken down into the following parts:

Defining Key PingOne concepts
Delegating Administration
Extending Delegated Administration

By the end of this Guide you’ll have configured multiple Environments with their own Applications, Populations, Groups, and Users. Additionally, you’ll have assigned Delegated Administrators to oversee capabilities within these Environments.

This Guide expects a beginner level of familiarity with the PingOne administrative console. If you haven’t set one up yet, be sure to get access to a PingOne instance (register for a trial here) so that you can follow along.

But before we get into the details, let’s go over some quick platform definitions.

Definitions

Delegated Administration in PingOne will primarily interact with Environments, Populations, Groups, and Admin Roles.

An Environment is a subdivision of your instance of PingOne. It contains the core resources you’ll use to build your IAM services, including your Users, the Applications they’ll single-sign-on (SSO) into, and the Services and Policies you’ll use to secure the access activities of those Users.

A Population is a unique administrative set of Users and Groups. Populations contain their own configuration such as their own Password Policies, Branding, default Identity Provider, and/or “alternative identifiers” used to easily look up a Population in things like REST APIs and DaVinci Flows.

A Group is a collection of Users. Groups can both be assigned dynamically and statically and can be nested inside one another. Groups are used as a way to assign permissions and membership for Users, including Application access and Admin Roles.

Groups can be created one of two ways:

External Groups come from an external connection, either by an Identity Provider (IdP) or LDAP Gateway. They are provisioned either via just-in-time or through synchronization and cannot be modified manually in PingOne.
Internal Groups are created manually within the PingOne portal like a Population and are a construct represented entirely in PingOne.

A Admin Role is a collection of permissions that you can assign to Users and Groups. Admin Roles allow Users (and Users within the Groups) to interact with the PingOne platform at a higher level of privilege, such as managing the Users within a particular Population. Only Users and static Groups can be assigned Admin Roles.

When to Create Multiple Environments

A popular use case of Environments is for building a promotion pipeline (e.g. development/staging/production/etc.), but additionally Environments are subdivided from one another in data and configuration - meaning that while they share the same hosting resources they do not share the same PingOne Service Selection (e.g. one Environment can have PingOne MFA while another can have PingID for multi-factor), Policy Configuration (e.g. password policies, risk policies, mfa policies, DaVinci policies, etc.), Branding (e.g. theming, forms, localization), and user data (e.g. Populations/Groups/Users and their user information).

Environments are great when you have requirements for Users, Applications, and Policies that strongly differ from one another. Let’s look at an example of managing Employees vs Customers:

Requirement	Employee	Customer
Multi-Factor Authentication	Desktop and Mobile Authenticator	Passkeys and Biometric
Risk Profiles	High Risk for New Device	Low Risk for New Device
Localization	English-Only (US Office)	English, Spanish, and French Support
User Onboarding	Provisioning from an on-premise Directory	Social Login with Google and Facebook with progressive profiling

The same can be said with business relationships. Perhaps you have a grouping of Suppliers who interact with your internal services - if so, it’s likely you’ll be securing and provisioning them in a way more similar to your internal (employee) population. On the other hand, if you are working with Distributors that are then interacting with end-customers, those individuals may be purchasing your products more similarly to an external (customer) population. These B2B2E and B2B2C relationships require drastically different interactions, and as such may benefit from separated Environments.

Populations Vs. Groups

At a first glance, Populations and Groups look kind of similar. However, they differ in some meaningful ways, namely:

Users must be part of a Population. Groups do not.
Users and Groups can be a part of ONLY ONE Population. Users and Groups inside a Population can only be a part of Groups in that Population.
Users and Groups can be a part of MORE THAN ONE Group.
Groups can have Admin Roles assigned to them, Populations cannot.
Admin Roles can be scoped to Populations, but not to Groups.

Think of Populations as a representative set of Users and Groups as a categorization of Users. In the real world:

A Population could be a Business Partner, while a Group inside that population could be one of their Departments.
If you had a shared Application (let’s call it Partner Hub) that all of your Business Partners use, a Group that spans multiple Populations could dynamically contain the Users that need access to that app.
If you had Support personnel that aided your Business Partners, they could be in a group that has Admin Roles tied to the different Populations.

Universal vs Segmented Identity

Depending on your business case your users may require a Universal Identity or a Segmented Identity.

A Universal Identity is where one Identity has one User account for all Services. This approach is advantageous in tightly-coupled partnerships such as a family of brands, a sports conference/league, a dealership, or a franchise. Universal Identities create seamless login experiences and greatly reduce your identity management footprint.

A Segmented Identity is where one Identity has multiple User accounts for different Services.This approach is advantageous in distinct relationships such as a supplier, branded enterprise application, an affiliate, or a distributor. Segmented Identities allow finer-grained control and administrative delegation into different levels of secure Applications and Users.

Using Environments, Populations, and Groups, PingOne enables us to create both Universal and Segmented Identities. Consider the following table when setting up PingOne:

Identity Type / Service Type	Separated Services	Interconnected Services
Segmented Identity	Different Environments, Populations, and Groups	Same Environment and Group, Different Populations
Universal Identity	Same Environment and Population, Different Groups	Same Environment, Population, and Group

Given the top-level “unique-set” structure of Environments and Populations, PingOne is best suited for Segmented Identity at scale. Please review the Standard Platform Limits to understand what approach fits your implementation and size.

Delegated Administration

Now that we have a grasp on the different segmentations of identity and configurations within PingOne, let’s set up our instance to take advantage of it.

Our example in this guide will start with an out-of-the-box instance of PingOne. Feel free to work from an existing instance - our work here won’t override any of what you’ve done already.

Your PingOne instance comes pre-loaded with a dedicated Administrators Environment. This environment is where your “super-user” account lives and where you’ll add in most of your Administrators. Let’s leave this Environment alone for now while we set up some basic use-cases.

Your PingOne Instance and Administrators Environment

Example Setup

To start, we are going to configure an example for each of the 4 different Service and Identity scenarios we defined in the prior section. To do so, let’s set up two Environments with some Populations, Groups, and Users in them.

From your Environments View, select the plus “+” icon at the top of the page (or the “Create Environment” button in the “Manage Environments” modal if it’s still on your page).

Creating an Environment

Creating The Customer Environment

First off, let’s create the Customer Environment. On the next page, select the “Customer solution” option. This will come pre-bundled with a variety of services that are common for CIAM deployments, such as Single-Sign-On, Multi-Factor Authentication (PingOne MFA), Risk Profiling (PingOne Protect), Identity Verification (PingOne Verify), and Orchestration (PingOne DaVinci).

The Environment Type and Services

In Step 3, where you set the deployment options, input the following values and select “Finish”:

Name	Value
Environment Name	Customer Example
Description	A testing Environment containing sample flows, policies, and users.
Environment Type	Sandbox
Generate sample populations and users in this environment	True (checked)
Region	The closest region to you. I’m using North America (US)
License	The default license that comes with your instance.
Include a solution designer to easily design and test experiences	True (checked)
Choose your Industry	Default

The Environment Deployment Options

While this Environment is deploying, let’s create the Workforce Environment.

Creating the Workforce Environment

Head back to the Environments view by clicking the Home icon or your Organization name in the top tab on your page just to the right of the Ping Identity logo. Mine is that internal_davidgwizdala text you saw earlier.

Heading Home

Back at the Environments view, create another new Environment like you did last time but rather than selecting “Customer solution” we’ll be selecting “Workforce solution” instead. You’ll notice that the services deployed will be slightly different, most notably that PingOne MFA has been replaced by PingID and PingOne Verify has been removed.

The Workforce Environment Type and Services

In Step 3, where you set the deployment options, input the following values and select “Finish”:

Name	Value
Environment Name	Workforce Example
Description	A testing Workforce Environment containing sample flows, policies, and users.
Environment Type	Sandbox
Generate sample populations and users in this environment	True (checked)
Region	The closest region to you. I’m using North America (US)
License	The default license that comes with your instance.
Include a solution designer to easily design and test experiences	True (checked)
Choose your Industry	Default

Workforce Environment Deployment Options

Now that we’ve created some example Environments to play with, let’s see what samples we are starting with.

Reviewing the Setup

After setup is complete for both your Customer and Workforce Environments, you’ll see that the steps you’ve taken have set up a few things for you. Click into each of the Environments to check for the following samples:

Under Directory → Users, a series of Users have been added to your Environment.
Under Directory → Groups, two Groups have been added: Sample Group and Another Sample Group. If you click into the Group Details (by clicking the Group) you’ll see that Sample Group is not tied to any Population while Another Sample Group has been tied to the More Sample Users Population.
Under Directory → Populations, you’ll have been given two Populations: Sample Users and More Sample Users. These Populations come pre-loaded with their Users and, in the case of the More Sample Users Population, their own Group.
Under Applications → Applications, you’ll see that you have some Applications already created:
1. The Getting Started Application, which is the example application you saw created in the “Getting Started” tab of your Environment and is what is attached to the Solutions Designer you enabled earlier.
2. The PingOne Admin Console, which is where your administrators created in this Environment will go to manage configuration and identity data for this Environment.
3. The PingOne Application Portal, which is where your Users can go to access their applications (think of this as an Application Dock)
4. The PingOne DaVinci Connection, which links the Environment to orchestration in PingOne
5. The PingOne Self-Service - MyAccount, which is where your Users can go to manage their own profile details, passwords, and MFA devices.
6. Under the Workforce Environment, you’ll also have the PingID Desktop and PingID Mobile applications, which allow your workforce to use the PingID authenticator for Multi-factor authentication. We’ll leave these be for the sake of this example.

With this setup, we have a working demonstration of both how Customers and Employees can interact with PingOne. Now let’s delegate some permissions to it.

Since this guide is focused on Delegated Administration, we’re going to specifically use the PingOne Admin Console Application. Copy and save the Admin Console URL from the Administrators Environment, either from the Applications page, the Environment Properties (Settings → Environment Properties), or Environment Summary tab (on the Environments List page).

Finding the Admin Console URL

Creating the Delegated Administrators

Remember the Administrators Environment we mentioned earlier? This Environment is the hub where we’ll be assigning permissions for Users to Environments, Populations, and Applications.

Select the Administrators Environment from your Environments list, copying the Self Service URL on the details tab before entering, and then click on Directory → Users.

Saving the Admin Environment Self-Service URL for Later

We are going to be creating a couple different users to administer the Environments we created. Click the Plus “+” icon next to the Users header, enter in each of the following User details, and hit “Save” when done. You’ll be creating two users in total.

Name	User 1	User 2
Given Name	Customer	Workforce
Family Name	Admin	Admin
Username	customerAdmin	workforceAdmin
Email	An email you can access	An email you can access
Require Email to be Verified	True (checked)	True (checked)
Population	Administrators Population	Administrators Population
Authoritative Identity Provider	PingOne (default)	PingOne (default)
Password	Ch4ngeIt!	Ch4ngeIt!

NOTE: Email Addresses for all admin accounts (i.e. accounts with delegated roles) must be verified.

Next, let’s verify these accounts so that we can perform delegated administration. In an incognito, guest, or separate browser window, go to the Self-Service URL for the Admin Environment that you copied earlier. Enter in the username and password of your administrators - you’ll then be presented with a change password prompt.

The Change Password Prompt

Enter in the current password and then a new password of your choice. You’ll then be requested to enter in the verification code that was sent to your User when you created their account.

Entering in the Verification Code

Repeat the above steps for the Workforce Administrator. When you return to your Administrator Environment and check the Users, you’ll see that the status of their email address is “Verified”.

The Verified Admin Email Address

Delegating Administration by User

Right now, these Administrators are a part of the Administrators Environment but don’t have any specific permissions. Remember the Console URL we copied earlier? Paste it into its own separate browser (or guest account) window and try to log in as either of the admins you just created. You’ll encounter an “Incorrect username or password. Please try again.” message.

Trying to Log In without Permissions

Now, let’s give these users some permissions. Starting with the Customer Admin, select the “Roles” tab in their user profile and then “Grant Roles”.

Granting Admin Roles to a User

From here, you’ll see a wide variety of permissions available to assign. Let’s start at the highest level and work our way down.

First, set your Customer Admin to be an Environment Admin of the Customer Example Environment and hit Save. This gives your admin permission to View, Create, Update, and Delete configuration within the Environment. More details can be found in the info “i” icon next to the title, but for all intents and purposes think of the Environment Admin the manager of Environment Configuration.

Adding Environment Permissions

If you try logging in again, you’ll see that you’re now prompted with MFA enrollment (a default setting for Admin Users). Go ahead and enroll in a device of your choice.

Enrolling MFA as an Admin

You’ll see that your Customer Administrator has access to configuration details such as Monitoring, Applications, Policies, Roles, and Experience but doesn’t have the capability to see or manage Users directly.

The Environment Admin’s Capabilities

Most Admin Roles give us the capability to assign by Organization or Environment (see DaVinci Admin, Application Admin), but let’s get a bit more granular. Back in the Administrators Environment view, update the Customer Admin so that they don’t have the Environment Administrator Admin Role and do have the Identity Data Admin Role specifically for the “Sample Users” Population. To do that, select the Identity Data Admin Role, 1) click the Filter icon (next to the checkbox) and 2) select the Sample Users Population. When you’re done, you should see “Limited Access” next to the Population and then the specific population after saving in the User summary.

Limiting Access to the Sample Users Population

Now go back to your customerAdmin’s dashboard. After refreshing the page, you’ll see that most of your access has been revoked to Read-Only but now you can manage the Users within the Sample Population.

Identity Data Admin View

Using what you just learned, assign the same Admin Role to your Workforce Admin but with their permission pointed to the Sample Users Population in the Workforce Environment.

Delegating Administration by Group

So right now we have a User that can manage the Identity Data of one Population in one Environment. Likely, as your organization expands, it’ll become unwieldy (and error-prone) to assign these permissions one at a time. Rather than assigning on a User level, let’s assign to a Group instead.

Inside the Administrators Environment, under Directory → Groups, select the Plus “+” icon and give it the Group Name “Helpdesk”. This group is going to be able to manage all of the identities for both the customer and workforce environments.

Creating the Group

This Group is assigned outside of a Population so we can add any Users that are in this Environment to it. With that in mind, go to the Users tab in the Helpdesk group and select “Add Individually”. We mentioned this before, but to protect from accidental overpermissioning Administrative Groups Permissions CANNOT be assigned via a filter.

Adding Individual Users to the Helpdesk Group

On the next screen, select the customerAdmin and the workforceAdmin Users to this Group.

Next, go to the Roles Tab and select “Grant Roles”. This screen will look very familiar to you: it’s the same screen we used when assigning Admin Roles to Users!

This time, let’s give this Group the Identity Data Admin Role across both the Customer Example and Workforce Example Environments.

Assigning the Identity Data Admin Roles

When you hit Save, and go back to your customerAdmin or workforceAdmin User, you’ll see that their permissions have been “Granted By Group” to the two Environments.

The User’s Assigned Admin Roles, Direct and Group

You probably also saw an error message pop up - we’ve just tried to assign the same Admin Role twice to our Admin Users. The highest amount of permission will win here: in this case, the Helpdesk Identity Data Admin Role that grants access to all Users in both Environments.

Go ahead and refresh the admin portal for either your customerAdmin or your workforceAdmin. Not only will you see all 40 users in your current Environment, you’ll additionally be able to navigate into and see the other Environment too.

The Assigned Group Permissions to the End User

Putting it to Practice

So now you know how to assign Admin Roles to a User and to a Group - let’s try some common combinations that will help you and your Users best interact with the platform. If you want a challenge, try to assign the right roles before reading which options you need.

Managing Data about Users

Identity Data Admin

Creating New Applications and Managing Specific Applications

Client App Developer
Application Admin

Defining Authentication Policies and Experiences

Environment Admin
DaVinci Admin

User Experience Tester

DaVinci Admin
Identity Data Admin (you need a test user to test a flow!)

Extending Delegated Administration

We’ve barely scratched the surface for what Delegated Administration can do within PingOne. To give you some jumping off points, take a look at common ways the Delegated Administration model is extended within the platform.

In-Environment Admins (Partner Admins)

Remember when we first looked at the Administrators Environment and said that most delegated administrators would be in this environment? Let’s talk through the scenarios in which you may want to assign delegated administration in a non-admin Environment instead. Think of this section as the Universal Identity vs. Segmented Identity (which we did in the last section) scenario.

The delegated administrator utilizes the same policies (e.g. password, MFA, DaVinci, Risk) as the environment or identities that they manage (e.g. service user)
The delegated administrator requires a distinct login experience (e.g. UI/Branding/Flow) indicative of the partnership or brand they are coming from (e.g. branding director)
The delegated administrator accesses the same Applications that their users are managing, perhaps with a different authorization policy (e.g. Application manager)
The delegated administrator Federates from the same IdP as their users (e.g. external helpdesk, business owner)

In these cases (and more!) ensure that your delegated administrators are Grouped in meaningful ways - the more that the Admin Roles are defined at a Group level the easier it will be to track what permissions each of your Users have.

Custom Admin Roles

While PingOne provides a series of Admin Roles out of the box for you and your administrators to utilize, you can create more catered Admin Role permissions through the use of Custom Admin Roles. These allow you to set CRUD-based permissions on the same set of Administrative Roles we were working with in the other section.

Since the Documentation contains Custom Admin Role Scenarios for you to look at, I’m not going to provide a walkthrough here. That being said, combining Custom Admin Roles with your Groups and Users gives you the ultimate level of control across your Environments.

Conclusion

Through this Guide we have:

Learned about the key definitions and differences between structures within PingOne
Created our own unique example Environments containing these structures
Delegated administration to external users to manage the different structures.

Additionally, we have looked at ways that Ping extends this capability through the user of assigning Admin Roles within non-Admin Environments (“Partner Admins”) and through the creation of Custom Admin Roles.

With what you have learned today you should be able to confidently create and assign complex Admin Role relationships for your internal and external administration.

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community.

Using the new Use Case Library for fast onboarding with PingOne APIs

Wed, 06 May 2026 00:00:00 GMT

Introduction

PingOne APIs pull back the curtain to reveal precisely how PingOne sign-on flows work. From application configuration and user registration to calling the PingOne authorization server to initiate a flow, the APIs show you the detailed request and response data for each step. Whether you want a simple username/password flow, a passwordless flow, or something more intricate, the PingOne APIs are a powerful tool for getting the job done and for understanding how PingOne works.

Syncing the Postman collections

The PingOne API developer doc library contains two key resources to fast-track your API journey: Getting Started and Use Case Library. The three tasks in Getting Started walk you through the process of getting a PingOne admin access token and using that token to call PingOne APIs.

First, use the admin console to create the PingOne admin Worker application needed to issue an admin access token that gives you permission to run PingOne APIs. With an admin access token, you can then create a test environment, configure a web application, and define a test user, which are essential resources for running sign-on flows.

Exploring the use cases

The use cases align with PingOne best practices and give you steps to configure and run a wide range of sign-on flows. Building on the assets you created in Getting Started, the use cases streamline the environment and runtime endpoint configurations. For example, PingOne supports five methods for authenticating the token request. To explore how the flow differs based on token authentication method, the Use Case Library Postman collection contains a simple PUT request that operates on the asset you created in Getting Started to set the app configuration for your chosen method.

In addition, the Postman collection includes runtime endpoints precisely configured to test the flow based on your application settings. You can see the parameters required by the authorization request to initiate the flow based on your application’s configuration, and the properties needed in the token request to return an access token.

The Use Case Library contains a diverse collection of flows, including:

Device authorization for OAuth-enabled devices, such as smart TVs.
Consent agreement to obtain a user’s agreement to a policy.
Progressive profiling to add data to a user’s profile.
Multifactor authentication flows for greater security.
Passwordless authentication flows.
Proof Key for Code Exchange (PKCE) authentication flows.
DaVinci sign-on and registration flows.

These use cases show you how the configuration and runtime endpoints work together to build the flow. Think of them not only as a hands-on tutorial but also as a starting point for further development and experimentation with PingOne APIs.

Let us know what you think

Download the Postman collections for your favorite use cases and give it a try. If you have ideas about use cases that we haven’t covered in the updated content, let us know by clicking the feedback icon in the top-right corner of any page.

Enjoy the ride!

Next steps

Try Getting Started.
Try Use Case Library.
Check out the Developer Portal.
Check out the Ping Identity Developer Community.

App-to-web session transfer: the security perspective

Wed, 06 May 2026 00:00:00 GMT

This post was originally published on Medium.

This post is the third in a series; in the first, we discuss the app-to-web session transfer problem and propose a secure approach using OAuth 2.0 Pushed Authorisation Requests (PAR). In the second, we walked through a detailed implementation blueprint using the PingOne platform. This third part will dive specifically into the security implications of this approach and a number of potential enhancements we could consider. Familiarity with the previous two parts is recommended before diving into this one.

Understanding the risks

First, a disclaimer. What follows is not exhaustive — nor could it ever be. I urge anyone reading and following this advice to remember that what I’m providing here is certainly not meant to be iron-clad security guidance, however well-reasoned I like to think it may be!

Nothing that we implement in any scenario should ever be considered 100% secure anyway (not in a world where we have integrated systems with boundaries — not to mention real-life users!) Our challenge is always to do what we can to predict the threats we might face, assess the likelihood and impact of each such risk and then critically assess our proposed solution against both aspects.

If we consider the pattern end-to-end, we should be able to identify a number of potential weak points where a motivated and skilled adversary could compromise security. The first is not a new or additional risk factor, given that we are using OAuth 2 to secure a native mobile application since it relates to the usage of an access token as a bearer token to allow API access. This implies that the utmost care must be taken within the end-to-end system architecture (but particularly within the client app itself) to protect this access token from unauthorised access or exfiltration.

We can argue that our PAR-based approach does not create any additional risk of access token exposure beyond what is already present anyway. When our application makes an authenticated call to a backend API, it initiates an HTTPS request and includes the access token in an authorisation header. The PAR approach includes the access token as a POST body parameter over HTTPS to our authorisation server and since we trust the server and the orchestration logic it executes, this should not materially affect our exposure risk.

Additional controls

We have added a number of additional controls to guard against specific risks, including the following:

We use a dedicated session transfer client to initiate the PAR process and intentionally restrict this client’s capabilities with the “web-session-only” scope. By configuring this client with a meaningless scope, an invalid redirect_URI and by including a PKCE Code Challenge we add a number of layered obstacles to prevent misuse of this client — that is in addition to specific orchestration logic to prevent the successful issue of any access token to this client.
The PAR response contains a request_uri parameter and this, while inherently single-use and short-lived, does create a potential security risk since it could be exfiltrated and copied to a different device in order to hijack the web session that it creates. We mitigate this risk by further constraining the useful life of the request (via our 10-second exp claim window) and by performing an IP check ahead of creating the web session.

The missing piece: device binding

One significant risk that we have not adequately addressed is that of access token exfiltration followed by a spoofed PAR request from a different client. Given that the access token itself is all that conveys the authenticated user context, we need to ensure that should an attacker obtain a valid access token by some nefarious means, they would not be able to use this token to create a valid web session on a different device.

Our remaining challenge is thus to implement some mechanism to ensure that PAR request is initiated (and completed) on the same device that obtained the access token initially.

We should, at this point, look critically at the decision to use IP address as the mechanism for binding the backend and front-end requests. While it is arguably the simplest thing to implement, IP address is typically a rather weak proxy for real device identity since it can be almost trivially replicated via proxy.

It is tempting to consider binding the access token to the device IP address at the time of initial login and this approach certainly would be more secure than simply echoing the current IP at the time of the PAR call. As a counter, though, the nature of mobile devices means that we should expect that a device’s IP address could change during the course of a session as the user moves from one network to another. We could end up restricting our application to a single IP address for the duration of the session if we were to follow this approach.

Extending the solution with PingOne MFA

Within our toolkit, we have the PingOne MFA service, Ping Identity’s strong authentication solution and one simple way for us to further improve our security posture here would be to use the Automatic Device Authorisation capability offered by the PingOne MFA Mobile SDK. This approach allows us to do the following:

identify a device through a cryptographic payload
bind that device to a user record
perform ad-hoc verification of that device based on a provided payload

Let’s revisit the end-to-end process description from two posts back — looking at how PingOne MFA is used to extend and further secure the flow.

When Alice first registers her account with the Acme Inc native application, the app code embeds the PingOne MFA SDK, which generates a cryptographic device payload (bound to a private key in Alice’s key-store). This payload is passed to the PingOne backend as part of Alice’s registration request where the associated public key is paired with Alice’s user profile. The device is thus bound to Alice’s account.
Alice opens the Acme Inc native application and clicks the “Login” button. The app uses the PingOne MFA SDK to generate a signed payload and includes this payload with the authentication request sent to the PingOne backend.
She is authenticated via a native authentication experience (no browser pop-up) that uses DaVinci flow logic to collect Alice’s user credentials, validate these against the user directory and then calls the PingOne MFA backend to validate the payload from the device and ensure that the extracted device ID is bound to Alice’s account.
The flow completes successfully and includes the device ID as a claim in the access token that is sent to the app. The app responsibly and securely stores this access token (which is bound to her device via the device_ID claim) on Alice’s behalf.
Alice clicks the “Manage my profile” button in the app. The app code starts the PAR process using the client_id of the dedicated Session Transfer Client. It includes a scope such as “session_transfer” in the request, and generates a PKCE Code Challenge that it includes with the request. Note that the corresponding Code Verifier can be discarded at this point since this flow is not intended to ever result in an access token issuance.
The app code makes a call to the PingOne MFA SDK to generate a fresh device payload. It then includes this payload, along with the access token that it already holds for the user, and the URL of the profile management application, in the PAR body that it constructs.
It sends the PAR request to the authorisation server and obtains a response that contains a request_uri, which it appends to the AS’s authorization endpoint URL before opening a browser tab to initiate the front-channel flow.
When the front-channel request hits the Authorisation Server, the request is validated (to ensure it has not expired or already been used) before being handed to the identity orchestration engine for further processing.
The DaVinci orchestration engine must introspect or validate the provided access token to ensure that it is valid, has not expired and was indeed issued to the expected client (the mobile app). It should also extract the device_ID claim from the token. It then calls the PingOne MFA backend to validate the payload from the device and ensure that the extracted device ID is bound to Alice’s account. It also ensures that the device ID extracted from the device payload matches the device_ID claim extracted from the access token.
Should the above checks succeed, the orchestration engine extracts the “sub” claim from the access token to determine the appropriate user, and sets a session cookie in the browser for that same user.
At this point, the orchestration logic simply redirects the browser to the URL of the profile management application (the same URL that was provided via the PAR back-channel initiation in step 6). This is the step that interrupts the flow started by the Session Transfer Client and ensure that no auth code or access token is ever issued.
The profile management application now receives the browser redirect and is responsible for initiating its own OAuth/OpenID Connect Auth Code flow, just as it would had a browser opened the app URL directly. It should generate its own redirect to the AS, including its own client_id and redirect_uri, its own appropriate scopes and its own PKCE Code Challenge. The AS will start a user authentication process that should complete with no further user interaction required, based on the presence of the session cookie set in step 10.
The browser is thus redirected back to the profile management application with everything that is needed to display logged-in user content.

The above approach certainly closes a number of potential security loopholes; however the lift is admittedly rather heavy as a result. I would advise a comprehensive review of your own risk landscape (in consultation with your security team) in order to decide whether the additional overhead is warranted in your specific scenario.

In conclusion

This has been quite the journey — from a frustrated user staring at a “Contextual Cliff” to a high-assurance architecture that even a cynical CISO could love.

To wrap up this series, let’s look at the path we’ve carved out:

Part 1: The Blueprint. We defined the “Session Transfer Problem” and why relying on the “serendipitous” creation of browser cookies is no longer a viable strategy in a privacy-first, sandboxed world.
Part 2: The Implementation. We got our hands dirty with Kotlin and DaVinci, moving sensitive session data off the URL and into the secure back-channel via OAuth 2.0 Pushed Authorization Requests (PAR).
Part 3: The Hardening. We moved from “making it work” to “making it resilient,” exploring the nuances of IP binding and the “gold standard” of cryptographic MFA Device Binding to ensure the session stays where it belongs.

The reality of modern digital products is that hybrid architectures aren’t going anywhere. Our job as identity professionals isn’t to fight the existence of web-views, but to ensure that the transition between native and web remains invisible to the user and invincible to the attacker.

Identity orchestration gives us the tools to build these “bridges” without compromising on either side of the UX-Security trade-off.

Over to You

I’d love to hear from the community:

How are you currently tackling session bridging in your own environments?
Is the “heavy lift” of MFA-backed device binding a non-starter for your product teams, or has it become a non-negotiable requirement for your security auditors?
Are there other “Contextual Cliffs” in your applications that you’re struggling to smooth over?

Drop a comment in the developer community with your thoughts, questions, or your own battle stories from the IAM trenches!

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community.

Implementing secure session transfer: a field guide using the PingOne platform

Wed, 22 Apr 2026 00:00:00 GMT

This post was originally published on Medium.

In my previous article, I established the conceptual blueprint for a hardened, standards-based mobile session transfer pattern. We identified that relying on shared browser cookies is a fragile strategy, often breaking under the weight of modern tracking prevention like Apple’s ITP or Google’s Privacy Sandbox. The alternative is a robust “bridge” architecture, moving beyond basic OAuth flows to integrate Pushed Authorization Requests (PAR, RFC 9126) with Identity Orchestration for a secure session transition.

In this field guide, I am moving beyond the “why” and deep into the “how, to provide a technical, domain-by-domain breakdown of the actual implementation.

Pre-requisites

This article is designed as a direct sequel, moving straight into the implementation mechanics. As such, I am assuming you have:

A fundamental understanding of the PAR and IP binding concepts established in part 1.
Access to a PingOne environment with SSO and DaVinci enabled.
A basic proficiency with Kotlin/JetPack Compose (Android) although what is described here could be implemented in any other mobile platform with little difficulty

Initial PingOne configuration

For this setup, we need the following to be configured in PingOne:

A Native Application client (this represents our mobile app and allows that app to obtain an access token using the SDK)
A Session Transfer Application client (a stripped down client that exists only to trigger the PAR process)
Some other “OIDC Web App” (I will be using the preconfigured “PingOne Self Service — MyAccount” application that is automatically bootstrapped with any environment)
A user account for testing

The Native Application client (1) should be configured as follows:

Note here that “API” is a custom Resource defined in PingOne with a corresponding “application_api” scope. This represents access to native application backend API’s that will be granted via the application access token.

We configure a “Simple U+PW” DaVinci flow to enable native user authentication using the Ping SDK. This flow will be described later.

The Session Transfer Application client (2) should be configured as follows:

This client is also a public client (hence Token Endpoint Authentication Method = None) but note that here we specify an invalid/unused Redirect URI since this client will only be used for PAR initiation, not token issuance. We require a Pushed Authorization Request with a short timeout and also define a custom scope of web_session_only. The combination of the invalid Redirect URI, the custom scope and the PKCE enforcement should provide sufficient (and redundant) protection against this client being misused for token issuance.

The “Session Transfer” DaVinci Flow will be described later.

The first DaVinci flow

In order to deliver a fully-native login experience within our application, we will implement the PingSDK with the DaVinci Client module. This approach requires us to define a PingOne DaVinci authentication flow for initial authentication of the user within our application (the step that allows us to obtain an access token).

For this example we will use a trivially simple DaVinci flow, shown below. We use the bootstrapped “Example — Sign On” form from the PingOne Forms service.

A more detailed explanation of how to use DaVinci to enable authentication is well beyond the scope of this discussion, but should the above prove insufficient, help is always available via the comments section!

Using the Ping SDK to get a user access token

Paul Simon told us that there are 50 ways to leave your lover — what I will add to this insight is that there are at least twice as many ways to obtain an access token within a native application! I’m going to provide some very simple sample code below showing just one of these, using Android with Kotlin and JetPack Compose. Here, we use the PingSDK to trigger the above DaVinci flow to perform simple username and password authentication.

class MainActivity : ComponentActivity() {

    sealed class DaVinciState {
        object Idle : DaVinciState()
        data class Waiting(val text: String) : DaVinciState()
        data class ShowForm(val collectors: List<Collector<*>>) : DaVinciState()
        data class Error(val message: String) : DaVinciState()
        data class Success(val user: User?) : DaVinciState()
    }

    var currentState by mutableStateOf<DaVinciState>(DaVinciState.Idle)
    var userID: String? = null
    var username: String? = null
    var accessToken: String? = null

    val CLIENT_ID = "<PingOne Client ID for Native Application Client>"
    val P1_BASE_URL = "https://auth.pingone.eu/<PingOne Environment ID>/"


    val daVinci = DaVinci {
        module(Oidc) {
            clientId = CLIENT_ID
            discoveryEndpoint = P1_BASE_URL + "as/.well-known/openid-configuration"
            scopes = mutableSetOf("openid", "application_api")
            redirectUri = "com.example.myapp://oauth2redirect"
        }
    }

    var node: Node? = null;

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent {
            SessionTransferTheme {
                MainLayout()
            }
        }
    }

    suspend fun startNativeLogin() {
        node = daVinci.start()
        handleNode()
    }

    suspend fun submitCreds() {
        val submitCollector = ((node as ContinueNode).collectors[3]) as SubmitCollector
        submitCollector.value = submitCollector.key
        currentState = DaVinciState.Waiting("")
        node = (node as ContinueNode).next()
        handleNode()
    }

    suspend fun handleNode() {
        when (node) {
            is ContinueNode -> {
                currentState = DaVinciState.ShowForm((node as ContinueNode).collectors)
            }

            is ErrorNode -> {
                currentState = DaVinciState.Error("Login Error")
            }
            is FailureNode -> {
                currentState = DaVinciState.Error("Login Failure")
            }
            is SuccessNode -> {
                val user = daVinci.user()
                val userInfo: Result<JsonObject, OidcError>? =
                    user?.userinfo(true)
                if (userInfo is Result.Success) {
                    userID = userInfo.value["sub"]?.jsonPrimitive?.content
                    username = userInfo.value["username"]?.jsonPrimitive?.content
                }
                val tokenResponse = user?.token()
                if (tokenResponse is Result.Success) {
                    val token = tokenResponse.value
                    accessToken = token.accessToken
                    currentState = DaVinciState.Success(user)
                }
            }
            else -> {}
        }
    }


    @Composable
    fun MainLayout(modifier: Modifier = Modifier) {
        val scope = rememberCoroutineScope()
        Column(
            modifier = modifier
                .fillMaxSize()
                .padding(24.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center
        ) {
            when (val state = currentState) {
                is DaVinciState.Idle -> {
                    // LOGGED OUT STATE
                    Text(
                        text = "Secure Session Transfer",
                        style = MaterialTheme.typography.headlineMedium
                    )
                    Spacer(modifier = Modifier.height(8.dp))
                    Text(
                        text = "Authenticate to begin the app-to-web flow.",
                        style = MaterialTheme.typography.bodyMedium,
                        color = MaterialTheme.colorScheme.onSurfaceVariant
                    )
                    Spacer(modifier = Modifier.height(32.dp))
                    Button(
                        onClick = {
                            scope.launch {
                                startNativeLogin()
                            }
                        },
                        modifier = Modifier
                            .fillMaxWidth()
                            .height(56.dp)
                    ) {
                        Text("Login with PingOne")
                    }
                }
                is DaVinciState.Waiting -> {
                    CircularProgressIndicator()
                }
                is DaVinciState.Error -> {
                    Text(
                        text = "Error",
                        style = MaterialTheme.typography.headlineMedium
                    )
                    Spacer(modifier = Modifier.height(8.dp))

                    Text(
                        text = "$state.message",
                        style = MaterialTheme.typography.bodyMedium,
                        color = MaterialTheme.colorScheme.onSurfaceVariant
                    )
                    Spacer(modifier = Modifier.height(8.dp))
                    Button(onClick = { currentState = DaVinciState.Idle}) {
                        Text("Restart")
                    }
                }
                is DaVinciState.ShowForm -> {
                    Text(
                        text = "Secure Session Transfer",
                        style = MaterialTheme.typography.headlineMedium
                    )
                    Spacer(modifier = Modifier.height(8.dp))
                    Text(
                        text = "Enter your login details.",
                        style = MaterialTheme.typography.bodyMedium,
                        color = MaterialTheme.colorScheme.onSurfaceVariant
                    )
                    val collectors = state.collectors
                    // USERNAME
                    val textCollector = collectors[1] as TextCollector
                    val usernameText =
                        remember() { mutableStateOf(TextFieldValue(textCollector.value)) }
                    TextField(
                        value = usernameText.value,
                        modifier = modifier
                            .wrapContentWidth(Alignment.CenterHorizontally)
                            .fillMaxWidth()
                            .padding(top = 14.dp),
                        shape = RoundedCornerShape(8.dp),
                        onValueChange = {
                            usernameText.value = it
                            textCollector.value = it.text
                        },
                        label = {
                            Text(
                                text = textCollector.label,
                            )
                        }
                    )
                    // PASSWORD
                    val passwordCollector = collectors[2] as PasswordCollector
                    val passwordText =
                        remember { mutableStateOf(TextFieldValue(passwordCollector.value)) }
                    TextField(
                        value = passwordText.value,
                        modifier = modifier
                            .wrapContentWidth(Alignment.CenterHorizontally)
                            .fillMaxWidth()
                            .padding(top = 4.dp),
                        onValueChange = {
                            passwordText.value = it
                            passwordCollector.value = it.text
                        },
                        label = {
                            Text(
                                text = passwordCollector.label
                            )
                        },
                        visualTransformation = PasswordVisualTransformation(),
                        keyboardOptions =
                            KeyboardOptions(
                                keyboardType = KeyboardType.Password,
                            )
                    )
                    // BUTTON
                    Button(onClick = { scope.launch { submitCreds() } }) {
                        Text("Submit")
                    }
                }
                is DaVinciState.Success -> {
                    Text(
                        text = "Logged in",
                        style = MaterialTheme.typography.headlineMedium
                    )
                    Text(
                        text = "Hi $username",
                        style = MaterialTheme.typography.bodyMedium,
                        color = MaterialTheme.colorScheme.onSurfaceVariant
                    )
                    Spacer(modifier = Modifier.height(32.dp))           
                }
                else -> {}
            }
        }
    }
}

The code above should be “more or less” directly usable to build an example application, as long as you first follow the prerequisites required by the Ping SDK. It is, of course, provided with no warranties of any kind and must be used for your own education only. Right now, our app is pretty simple, as shown below.

Extending the app to launch web content

Before we dive into the magic of the DaVinci flow that makes our final goal achievable, let’s extend the app code from above to launch the PingOne MyAccount web console in a browser view.

First, we add a button to the UI by modifying the MainLayout compose function as below

@Composable
    fun MainLayout(modifier: Modifier = Modifier) {
/* SNIP */
            when (val state = currentState) {
/* SNIP */
                is DaVinciState.Success -> {
                    Text(
                        text = "Logged in",
                        style = MaterialTheme.typography.headlineMedium
                    )
                    Text(
                        text = "Hi $username",
                        style = MaterialTheme.typography.bodyMedium,
                        color = MaterialTheme.colorScheme.onSurfaceVariant
                    )
                    Spacer(modifier = Modifier.height(32.dp))
//Start of new code 
                    Button(
                        onClick = {
                            scope.launch {
                                launchUserProfileInBrowser()
                            }
                        },
                        modifier = Modifier
                            .fillMaxWidth()
                            .height(56.dp)
                    ) {
                        Text("View User Profile")
                    } 
// End of new code 
                }
                else -> {}
            }
        }
    }

Next we add a function to perform the PAR initiation and launch the browser with the received request_uri value.

suspend fun launchUserProfileInBrowser() {
        val client = HttpClient(Android) {}
        val verifier = PkceGenerator.generateVerifier()
        val challenge = PkceGenerator.generateChallenge(verifier)
        val myIP = getPublicIp(client)
        val requestTimestamp = System.currentTimeMillis()
        val expiresAt = requestTimestamp + 10000 // 10 seconds leeway
        val response: HttpResponse = client.submitForm(
            url = "https://auth.pingone.eu/<PingOne Environment ID>/as/par",
            formParameters = parameters {
                append("client_id", "<PingOne Client ID for Session Transfer Application Client>")
                append("response_type", "code")
                append("scope", "openid web_session_only")
                append("redirect_uri", "https://unused")
                append("request_token", accessToken ?: "")
                append("code_challenge", challenge)
                append("code_challenge_method", "S256")
                append("ip_address", myIP?:"")
                append("exp", "$expiresAt")
                append("application_URL", "https://apps.pingone.eu/<PingOne Environment ID>/myaccount/")
            }
        )

        if (response.status.isSuccess()) {
            val responseBody = response.bodyAsText()
            val jsonResponse = JSONObject(responseBody)
            val requestUri = jsonResponse.getString("request_uri")

            val authorizeUrl = Uri.parse("https://auth.pingone.eu/<PingOne Environment ID>/as/authorize")
                .buildUpon()
                .appendQueryParameter("client_id", "<PingOne Client ID for Session Transfer Application Client>")
                .appendQueryParameter("request_uri", requestUri)
                .build()

            val customTabsIntent = CustomTabsIntent.Builder().build()
            customTabsIntent.launchUrl(this, authorizeUrl)

        } else {
            // Handle HTTP errors (e.g. 400 Bad Request)
            println("PAR Error: ${response.status}")
        }

    }

Lastly, we need a bit of utility code, as below:

// A utility method to figure out our own IP
suspend fun getPublicIp(client: HttpClient): String? {
        return try {
            // Use a lightweight reflector
            client.get("https://api.ipify.org").bodyAsText()
        } catch (e: Exception) {
            null
        }
    }

//A utility object to help with PKCE
object PkceGenerator {
    fun generateVerifier(): String {
        val secureRandom = SecureRandom()
        val code = ByteArray(32)
        secureRandom.nextBytes(code)
        return Base64.encodeToString(code, Base64.URL_SAFE or Base64.NO_WRAP or Base64.NO_PADDING)
    }

    fun generateChallenge(verifier: String): String {
        val bytes = verifier.toByteArray(Charsets.US_ASCII)
        val messageDigest = MessageDigest.getInstance("SHA-256")
        val digest = messageDigest.digest(bytes)
        return Base64.encodeToString(digest, Base64.URL_SAFE or Base64.NO_WRAP or Base64.NO_PADDING)
    }
}

What we have done above is to create a Pushed Authorization Request, where the following have been added as custom parameters:

request_token: the user’s access token
ip-address: the current (external) IP address of the device
exp: a timestamp for 10 seconds from now
application_URL: the URL of the actual application the user needs to be redirected to once the session has been created.

Next is to craft a DaVinci flow that can use these inputs to deliver the desired outcome.

The second (and far more interesting) DaVinci flow

Before we dive into flow logic, we need to understand a bit about how PingOne SSO and DaVinci work together to handle pushed authorisation requests. In this case, because our Session Transfer Application client has been configured to require PAR and because it has the required flow linked via a DaVinci Policy, any PAR request (once validated to protocol correctness) will be passed to the DaVinci flow as a standard PingOne Flow invocation, with any custom parameters provided via the {{global.parameters.authorizationRequest}} object. Hence to obtain the access token in the flow, we would use {{global.parameters.authorizationRequest.request_token}} and so on.

Our example flow then looks as follows:

The steps are as follows:

Check expiry of the request. This is done by using a Function node to compare the exp claim in the authorisation request to the current timestamp. Note that this check is perhaps not entirely necessary, since the PAR functionality in Ping One already constrains the validity of the request_uri, but it is included here as just one of any number of additional security checks that could be added to the flow.

Check IP address: Again we use a function node to check the current IP address as seen by DaVinci against the address that was included in the PAR payload.

Validate request token: this is the critical step where we ensure that the access token passed in the PAR payload is valid before extracting the token subject to create a session. In this example, I am using DaVinci’s Token Management -> Validate JWT Token capability and using the PngOne’s environment’s JWKS endpoint to provide the public key for validation. An alternative approach would be to make a REST call to the token introspection endpoint.

Create a (web) session for the user: having ensured that a valid token has been provided, we are free to create the necessary session, represented by the PingOne ST cookie in the user’s browser. The simplest way to do this is to use the PingOne Authentication -> Create or Update Session capability

Redirect to the target application: The final step is to generate a redirect so that the actual application (in our example the MyAccount app) can start its own OIDC flow to transparently log the user in based on the session cookie we just created. I’m using a simple Custom HTML template node in DaVinci with a Javascript redirect.

A final test

We should have everything we need and our application experience now looks as follows:

In our final episode…

In the next article, I will build on this approach and look at a number of advanced techniques we could use to make this hand-off process even more secure.

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community.

Ping Orchestration SDKs 2.0

Wed, 15 Apr 2026 00:00:00 GMT

Ping Orchestration SDKs 2.0 are our next generation of client-side SDKs for JavaScript, iOS, and Android! They give you one unified way to connect your apps to PingOne DaVinci flows, PingOne Advanced Identity Cloud / PingAM journeys, and OIDC redirect with any OIDC-compliant server. You integrate once, then evolve journeys and flows on the server without constantly rewriting your app.

Want to get started now? Jump to Getting Started!

Key features

The SDKs handle multi-client orchestration for you. A single app can work with multiple OAuth clients simultaneously, such as one for primary login and another for step-up or high-risk actions. The SDK manages tokens and clients so your code can focus on business logic rather than OAuth details.

They also integrate Ping’s universal services through the orchestration layer. The SDK can collect device and behavioral context (for example, with PingOne Protect) and feed that into your DaVinci flows or AIC/PingAM journeys so you can drive risk-based decisions from a single place. As we add more services, like PingOne MFA for PingOne or privacy-preserving biometrics with PingOne Keyless, they appear through the same orchestration model instead of new one-off integrations.

Across JavaScript, Android, and iOS, the orchestration model is consistent. Teams can reuse patterns across web and native apps, and new developers can ramp up faster because the concepts look and feel the same on each platform.

Why Orchestration 2.0?

Historically, DaVinci flows and AIC/PingAM journeys had separate SDK stories. Orchestration 2.0 brings them together into one orchestration-first family across JS, Android, and iOS.

The older ForgeRock SDKs evolved into several large libraries. Orchestration 2.0 replaces that with a modular, pluggable design with networking, journeys, FIDO/passkeys, MFA, device binding, device ID/profiling, and more, so you only include what you need and stay aligned with modern Kotlin, Swift, and JS practices. This single orchestration plane is where we focus on performance, security, and new capabilities.

Benefits vs. ForgeRock SDKs

If you use the ForgeRock JS, Android, or iOS SDKs today, Orchestration 2.0 gives you one SDK family for both DaVinci and journeys. The same core ideas apply whether you’re building SPAs or native apps with AIC/PingAM.

The architecture is more modular: journey orchestration, FIDO2/passkeys, OATH and Push MFA, device binding, migration helpers, device ID/profiling, jailbreak/root detection, and reCAPTCHA Enterprise are all focused modules. You import only what you need, which helps with footprint and security. The orchestration model also adds built-in multi-client support, so scenarios like primary login plus step-up are handled by the SDK instead of custom token juggling. Everything sits on modern JavaScript, Android, and iOS foundations.

Why new SDKs vs. evolving ForgeRock SDKs

The ForgeRock SDKs assumed separate paths for DaVinci and AIC/PingAM and concentrated a lot of behavior into a small number of libraries. That made it hard to keep adding features, support richer token patterns, and plug in new services without extra complexity.

With Orchestration 2.0, we refactored orchestration into a new architecture, split cross-cutting concerns (networking, storage, device binding, FIDO, MFA, and so on) into modules, and made these SDKs the contract for all new integrations and universal services. The goal is that app development feels simpler and more consistent, even as the platform becomes more powerful behind the scenes.

If you use ForgeRock SDKs with PingOne AIC/PingAM

The ForgeRock JS, Android, and iOS SDKs are now deprecated. They’ll receive critical security and bug fixes for about two years after Orchestration 2.0 GA, until 15 April 2028. After that, they won’t be updated, and the expectation is that customers move to the Orchestration SDKs.

For most AIC/PingAM customers, treat migration as a structured project. Start with the detailed guides to understand how to migrate from the ForgeRock SDKs to the Ping Orchestration SDKs. These guides provide concrete examples of how to migrate existing ForgeRock integrations to the new SDKs and make it easier to map journey callbacks, device behavior, MFA flows such as OATH, and Push.

Use AI Coding Agents (GitHub Copilot, Cursor, Claude Code, etc) to expedite migration:

Context-ready: We’ve included structured migration.md files for the ping-android-sdk and the ping-ios-sdk. You can feed these files directly into your AI’s context to help it automatically map old ForgeRock classes to the new Orchestration 2.0 modules.

Automated Refactoring: Use prompts to help the agent rewrite your networking and journey logic, significantly reducing the manual effort of updating callback handlers and device binding code.

Coming Soon: We are currently developing a dedicated We now have Agent Skills will act as a migration specialist, providing real-time, project-specific guidance for moving your unique identity flows into the new orchestration plane. Refer to our ping-sdk-agent-skills repo or our build with AI documentation for more information.

A common pattern is to run the new and legacy SDKs side by side. The Orchestration SDKs can coexist with the old ones, and dedicated migration modules for device binding, device ID, and OATH/Push (plus encrypted state helpers) are there to migrate identifiers without forcing most users to re-enroll. After you’re confident in the new model, you initialize the Orchestration SDKs in your apps, move UI and callback handling to the new patterns, and keep most behavior in AIC/PingAM journeys so you can keep iterating without constant app releases.

A typical migration has three phases:

Start with inventory and design: list all apps and journeys using the ForgeRock SDKs, classify the flows they rely on: sign on, registration, self-service, MFA, device binding, passkeys, and so on, and call out any reliance on Transactional Authorization or the Token Vault.
From there, you run a pilot on one representative mobile or web app. You integrate the Orchestration SDKs in a feature branch, use the migration guides and sample apps (with or without AI assistance) to map journeys to the new orchestration model, and validate device binding and device ID migration in a non-production environment.
After you feel confident, you move into rollout: promote the pilot to production, extend the new SDKs to other apps and platforms, and then remove the legacy SDK dependencies when you have full coverage.

In the Orchestration 2.0 release, Transactional Authorization and the JavaScript Token Vault are not included. If you rely on either in production, contact your Ping representative and open a support case so we can work through options with you rather than attempting a direct, like-for-like migration.

Docs, Login Widget, and resources

DaVinci SDK docs have been folded into the Orchestration SDK documentation. DaVinci-focused guides and tutorials now live there, and older DaVinci-only pages will redirect or point you to the new docs. If you used the “DaVinci module” docs before, the Orchestration SDK JavaScript, Android, and iOS docs are now your primary reference.

The Login Widget now lives in its own repository, allowing it to evolve independently while remaining part of the orchestration story. It is referenced from both the deprecated ForgeRock SDK docs and the Orchestration SDK docs as one of the available integration options alongside a fully custom UI.

Sample applications for JavaScript, Android, and iOS SDK and the SDK repositories and packages are all linked from the Ping Developer Portal. The portal acts as the central entry point for Orchestration SDK documentation, API references, tutorials, so you can find everything in one place.

Getting Started

To get started with the Orchestration SDKs:

Reference our tutorials for DaVinci or AIC/PingAM.
Clone our SDK sample apps repository and enter relevant server details to understand the fundamentals and walk through core orchestration flows end to end, so you can compare a working reference to your current setup before touching production or wondering how to integrate authentication flows into your existing mobile and web apps.
Integrate into your existing app.

The SDKs are available from standard locations: JavaScript on GitHub and NPM, Android on GitHub and Maven, and iOS on GitHub and Swift Package Manager. The Ping Developer Portal will be the main entry point, bringing together orchestration docs, sample apps, and API references in one place.

ℹ️ Note: Soon you’ll see We now have AI-powered Agent Skills and tools to help integrate into existing apps or set up sample apps quickly at our ping-sdk-agent-skills repo.

References

SDK Sample applications: https://github.com/ForgeRock/sdk-sample-apps
SDK repositories:
- iOS: https://github.com/ForgeRock/ping-ios-sdk/tree/master
- Android: https://github.com/ForgeRock/ping-android-sdk/tree/master
- JS: https://github.com/ForgeRock/ping-javascript-sdk/tree/main
All Ping Identity’s SDKs: https://developer.pingidentity.com/sdks.html
Orchestration SDK Documentation: https://developer.pingidentity.com/orchsdks/index.html
PingOne Advanced Identity Cloud/PingAM Login Widget: https://developer.pingidentity.com/login-widget/index.html
Deprecated ForgeRock SDK Documentation: https://docs.pingidentity.com/sdks/latest/index.html

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community!

Understanding Virtual Properties

Fri, 10 Apr 2026 00:00:00 GMT

This post was originally published on Gwiz Kid.

Introduction

PingOne Advanced Identity Cloud (AIC) and PingIDM (IDM) contain an impressive range of flexible identity configuration schema that allow you to define complex relationships and dynamic concepts given the data inside your directory. And if that sentence sounded complicated, it’s because it is: relationships are hard enough in the real world, let alone when configuring it in an enterprise identity management system!

This Guide will walk you through the concepts of Virtual Properties and Relationship-Derived Virtual Properties (otherwise known as RDVPs). It’s expected that you are comfortable with navigating the identity management console in PingIDM or AIC and have a reasonable understanding of managing properties within that console. While this Guide covers RDVPs, it is not a primer on Relationships in either platform.

This Guide is broken down into the following sections:

Virtual Properties
Relationship-Derived Virtual Properties

By the end of this Guide you will have gained an understanding on where and when to use each virtual property type as well as how to configure those properties. You will also have configured a set of simple examples illustrating the capabilities of those properties.

Virtual Properties

A Virtual Property is a Property that can dynamically calculate its own data. Rather than having a separate sub-process generate and store a value, a Virtual Property handles the dirty work for you directly on the property itself.

A great example of when a Virtual Property can be used is a user’s full name. We could have a function in our client app(s) that pulls in the user’s Given Name and Surname and then merges them together, but we might run into consistency issues on how that name is displayed. If we are provisioning users to an application, we’d have to repeat our work again to ensure that our target app gets the same value. Rather, with a Virtual Property we can define a “Full Name” value that ensures that the name is consistent each and every time it needs to be referenced.

But it’s more than just combining values together. Virtual Properties have access to IDM’s scripting engine, meaning that you can return whatever values you deem necessary to be retrieved alongside your object - even if the value doesn’t live on that object! As an example, let’s say you’re a retailer that uses a third-party service to calculate and store a user’s clothing sizes. Since that service is holding the sizing information, why not just reach out via API to pull in the user’s size dynamically? No need to create a polling schedule, no need to store that value both in your system and in theirs - the data is in one spot but can be returned in more than one type of request.

Creating a Virtual Property

We will walk through specific examples of virtual properties below, but the big thing you need to know when defining a Virtual Property is the Virtual Property Setting, Return by Default, and onRetrieve Scripting.

To make an element a Virtual Property, enable the “Virtual Property” option under the “Show Advanced Options” section on the property’s main page.

Creating a Virtual Property

Enabling this checkbox does three things:

It informs IDM that this property is a virtual property and as a result cannot be modified directly by the user. Whether or not you enable “User Editable” in the advanced options will not change this behavior.
It enables and displays the “Return by Default” checkbox, which lets you specify if this property should show up as a default field when querying the object (kind of like how the _id property shows up in every query). For most cases, enable Return by Default. If you don’t, the virtual property won’t show up throughout your platform UI (which is expecting static values) or your application unless explicitly requested.
It enables and displays the “Query” tab, which lets you specify queries to interact with relationships and define Relationship-Derived Virtual Properties - more on that later.

Now that your property is defined as being a Virtual Property, to make it useful you’ll want to define an onRetrieve script that auto-calculates the dynamic data. The scripts for your property are located in the “Scripts” tab.

What Makes a Virtual Property a Virtual Property?

You’ve probably noticed that your properties have two more scripts available - onValidate and onStore. In fact, all three script types are available (including onRetrieve) whether or not you enabled this element to be a Virtual Property. What gives?

Virtual Properties in IDM are special in that they cannot be edited and can be returned by default. Regular properties, while able to be dynamically updated, can still be configured to be edited and have to be specified to be returned.

Virtual properties can also use onValidate and onStore scripts when defining their data. But what makes Virtual Properties interesting is that they can dynamically calculate data at time of retrieval WITHOUT having to store that information. By making a property virtual, you are indicating that this data will always be available and up to date when requested.

So as a recap: Virtual Properties give you a way to define a property that is calculated and returned at run-time and that your system recognizes will always be dynamically calculated. When creating a Virtual Property, you’re probably using the onRetrieve script because then you aren’t storing a value that could easily fall out of date.

Defining the onRetrieve Script

The onRetrieve script lets you return a value when requested. The returned value is not stored unless explicitly provided when updating the object.

PingIDM supports JavaScript and Groovy for scripting. However, since JavaScript is available in both AIC and PingIDM, our examples in this guide will stick with JavaScript only.

There are two main documents you should be referencing when working with scripts in IDM:

Script Triggers & Variables: This page will tell you for each script type what default variables exist within the script itself.
Script Functions: This page will define the types of functions that extend capabilities, such as encryption/decryption, interacting with identity resources, or performing REST calls.

The most important takeaways from those documents are found in the below sections.

IDM Scripting Variables

It’s easy to miss, but the documentation for onRetrieve actually exists in two parts of the Script Triggers page: the Managed Configuration Object and in the Property Object. In the case of a Virtual Property, we care about the Property Object details.

There are two variables in particular that you’ll likely deal with the most: object and property.

The object variable is the object that is being requested. That means your Virtual Property can request, via object notation, other properties from your object to be used within the Virtual Property. Think, for example, referencing a user’s student ID from their profile to retrieve a list of library books they’ve checked out in an external library service.
The property variable is the property you’re returning. The property variable is required in an onRetrieve script if you want to return data. To use, set property = whatever variable/value you’ve created at the end of your script and you’re done.

The predefined variables are protected. If you create a variable with the same name your script won’t work as expected.

IDM Scripting Functions

There are a good number of script functions available to you, but the following in particular will likely be your go-tos:

`openidm.query()`

openidm.query queries resource objects along with a query filter. Resource objects can be managed objects or the underlying system configuration. There may be use cases in which you need to pull data that exists off of another resource based on data that you have on your existing object and the query function lets you get that data to be dynamically returned in your Virtual Property.

As an example, let’s say that you wanted a list of all of the child organizations that you are a member of (as a result of being a member of the parent organization). You could query the organizations managed object to get those IDs based on a property you have on your user.

var query = object.memberOfOrgIDs.map(orgID => `parentIDs eq '${orgID}'`).join(' or ');
var myChildOrgs = openidm.query("managed/alpha_organization", {"_queryFilter": query}).result;

`openidm.action()`

openidm.action performs HTTP actions on a particular resource. This could be an action on something in AIC, say sending an email template:

var emailParams = {
    "templateName" : "welcome",
    "to" : user.mail,
    "cc" : "ccUser1@example.com,ccUser2@example.com",
    "bcc" : "bigBoss@example.com",
    "object" : {
        "this": "value",
        "that": "another value"
    }
};
openidm.action("external/email", "sendTemplate",  emailParams);

But it could also be interacting with custom IDM endpoints:

openidm.action("endpoint/{yourEndpointName}", "yourEndpointAction", params);

As well as interacting with external REST APIs:

var convertObjectToQueryParams = (object) => {
  return Object.keys(object)
    .map(key => encodeURIComponent(key) + '=' + encodeURIComponent(object[key]))
    .join('&');
};

var body = {
  "foo": "bar"
};

var params = {
  url: `https://my-endpoint-example.example`,
  method: 'POST',
  body: convertObjectToQueryParams(body),
  authenticate: {
    type: 'bearer',
    token: token
  }
};
var response = openidm.action('external/rest', 'call', params);

There are plenty of other use cases for openidm.action but the above will serve you well when working with Virtual Properties.

`identityServer.getProperty()`

This one is a bit sneaky because it’s most useful in AIC and doesn’t appear in the aforementioned documentation. identityServer.getProperty(esvName) lets you reference ESVs stored in Google Secrets Manager within your scripts. Just remember - your ESVs are referenced with dots and not dashes, so the ESV you created with the name esv-my-cool-esv would be referenced as identityServer.getProperty('esv.my.cool.esv').

As always with ESVs, be careful not to leak sensitive data in your scripting.

Now that we’ve gotten a sense of Virtual Properties, let’s make a couple examples and test them out!

Virtual Property Examples

If you’re using PingOne Advanced Identity Cloud (e.g. AIC), head to the Native IDM Console underneath Native Consoles → Identity Management. If you are using PingIDM, you’re already where you need to be.

In our example we will be updating our User object (in AIC, that’ll be called alpha_user) to return the “Full Name” attribute we discussed above. In the Managed Objects page (normally your homepage, but also under Configure → Managed Objects) click on your User object. The property editor for your user should appear along with all of the pre-defined properties that exist on that user.

Click the “+ Add a Property” button and add a new property with the name custom_fullName, the label “Full Name”, and the type String and then hit “Save”.

Creating the Full Name Property

Click on your new property to edit it.

At this point, we are dealing with a standard String property. You can enter in a full name value and it’ll store that value. What we want is a property that dynamically updates based on the details of the givenName and sn of our user.

The Generic Full Name String Property

Click on “Show advanced options”, uncheck “User Editable”, and check “Virtual”. You’ll notice that an additional property, “Return by Default” appears. Check the “Return by Default” property if you want the full name to show up in UIs (like the end-user dashboard and the administrative UI), by default in API calls, or if you want this property to be fetched in provisioners - otherwise you may not have access to the result.

In our case we are going to check “Return by Default” since we will want to see the value in the UI.

The Advanced Configuration

Save the changes. When you do, something interesting happens: A Query Configuration tab appears at the top of the property. We’ll get back to that later - right now, what we care about is the Scripts tab.

Let’s define the script that makes our Virtual Property tick.

Example: Manipulating Existing Properties

Click on the Scripts tab, select the onRetrieve script type and click “+ Add Script”. A Script Manager window will appear with the ability to select a script type, provide an inline script or a file, and pass variables into that script. If you’re using AIC, you’ll only have access to JavaScript and the Inline Script option (don’t worry, you can still pass variables too) - in PingIDM, you can pick and choose what you prefer.

Your inline script should look like this:

property = object.givenName + " " + object.sn;

Hit Save.

Note: To set your property variable, you must put the property definition at the end of your script. Otherwise, the value will not be set. If you are setting property in more than one location in your script, you can alternatively end the script with just the value property.

Create a user with a First and Last name and then take a look at their properties. You should see the concatenated First and Last name.

The Full Name Virtual Property

Now this script by itself isn’t particularly exciting. In fact, the cn property on the user already has this information. Why don’t we change this property to update the order of the First and Last name given the country they reside in, based on common ordering in those areas?

Updated your onRetrieve function to the following:

var givenFamilyNameOrderCountries = ["US", "ES", "AU", "CA", "GB"];
var familyGivenOrderCountries = ["FR", "JP", "CN", "IN"];

if (givenFamilyNameOrderCountries.includes(object.country)) {
    property = object.givenName + " " + object.sn;
} else if (familyGivenOrderCountries.includes(object.country)) {
    property = object.sn + " " + object.givenName;
} else {
    property = object.givenName + " " + object.sn;
}

On your user, change your country to US and then to IN. You’ll see that the order of your first and last name flips.

The Full Name Virtual Property, Surname First

Now, before any of you send me a strongly-worded email:

This is an example. It’s not how you should be determining name order - ideally, other information like the user’s language preference and possibly a boolean on their profile could help determine the positioning of a person’s name.
Yes, we have variables. But then you would have had to have typed each of those country codes one at a time into the variable array(s) you created. I just saved you 5 minutes of time and reduced your risk of carpal tunnel syndrome.

That all being said, onto a more interesting use case.

Example: Returning Data from External APIs

Now that we have the capability to get data based on attributes, let’s pass some of that data into an external REST API. Here’s where we really get into the good stuff Virtual Properties have to offer: if the data you need lives elsewhere, and you don’t really want that data inside your directory (AIC or PingDS or otherwise), Virtual Properties let you get that data when you need it without having to set up and perform any syncing operations. Your data is always up to date because it is asking for the data from the source.

A Note On Performance: Consider the implications of reaching out to an external API if you are making many read operations on your data. If the frequency as to which you’re getting this property far exceeds the frequency that data is updated, you should consider updating the property via a scheduled job or onStore trigger instead.

We’re going to update our virtual property to guess the country of the user based on their first name if their country code was not provided. Then, that country can be used in the same way as above to determine the user’s name order.

We’ll use the free nationalize.io API to do this. Update your onRetrieve script to the following:

var givenFamilyNameOrderCountries = ["US", "ES", "AU", "CA", "GB"];
var familyGivenOrderCountries = ["FR", "JP", "CN", "IN"];
var country = object.country;

if (country == null || country === "") {
    var params = {
        url: `https://api.nationalize.io/?name=${encodeURIComponent(object.givenName)}`,
        method: 'GET',
    };
    var response = openidm.action('external/rest', 'call', params);
    var sorted_countries = response.country.sort((a, b) => b.probability - a.probability)
    var filtered_countries = sorted_countries
        .filter(c => givenFamilyNameOrderCountries.includes(c.country_id) || familyGivenOrderCountries.includes(c.country_id));
    if (filtered_countries.length > 0) {
        country = filtered_countries[0].country_id;
    }
}

if (givenFamilyNameOrderCountries.includes(country)) {
    property = object.givenName + " " + object.sn;
} else if (familyGivenOrderCountries.includes(country)) {
    property = object.sn + " " + object.givenName;
} else {
    property = object.givenName + " " + object.sn;
}

Now, testing with common names from different countries, you should see the name order position accordingly. Feel free to test with the name combinations below to see for yourself - remembering to remove the Country code for the HTTP call to be made.

Expected Order	Given Name	Surname
Surname, Given Name	Ashok	Kumar
Given Name, Surname	John	Doe

Relationship-Derived Virtual Properties (RDVPs)

Virtual Properties can be updated either on time of retrieval or based on notifications received from a relationship tied to the managed object this property lives in. When we are updating the property based on information provided by the relationship, we are working with a Relationship-Derived Virtual Property, or RDVP.

A Relationship-Derived Virtual Property updates based on notifications from the Relationships linked to its Managed Object. An RDVP has access to content from the Object’s Relationships and can traverse the entire Relationship path to create a value composed from an aggregate of that traversal.

Let’s look at an example of when an RDVP might be useful - a management chain.

A Simple Management Diagram

In the diagram above, Joe is the CEO and the top of the management hierarchy. Jess is one of his direct reports, and Jim lives at the bottom of the hierarchy underneath another of Joe’s reports.

This hierarchy is defined by relationships - the linkages between each manager and their reports.

If you wanted to get a list of all of the Managers above an Employee, how would you go about it? Normally, it would likely be a series of queries that would look something like this:

Get the Employee
Find the Employee’s Manager
Get the Manager
Find the Manager’s Manager
Get the Manager’s Manager
Find the Manager’s Manager’s Manager
…
Manager X has no Manager, return

Think about this the other way, too. If I wanted to get all of the Employees under a Manager, and each Manager has more than one Employee, how many operations do I have to take? Now what if I had to perform this action every time I entered an application, or every time I pull data on a user? This is starting to sound a lot like one of those classic graph traversal interview questions!

RDVPs travel the Relationships for you and update a static result on the object directly at time of change from anywhere in the Relationship.

If we looked at the previous example, if I wanted to get a list of the Employee’s Managers, or a list of the Manager’s Employees, the data is on the User directly. If the Employee is promoted, or switches teams, and the managerial hierarchy changes, the data on the User updates automatically.

When to Use RDVPs

RDVPs update when the data updates in the relationship, anywhere in the relationship(s) you are getting the data from.

There’s a time and a place to use RDVPs as a result:

If the data updates	…and you want to get that data	…then you should use
Frequently	Infrequently	A Virtual Property
Infrequently	Frequently	An RDVP

RDVPs are triggered on relationship notifications and can trigger additional notifications as a result of them updating. If you’re not careful, these notifications can get rather noisy - one change could result in hundreds (if not hundreds of thousands) of changes cascading through your directory. The tradeoff is that you aren’t making that same calculation at time of retrieval - the likely point in which your enforcement point or authorization server is attempting to make a real-time decision based on that information.

RDVPs should only traverse a relationship tree in one direction. Cyclical RDVPs could result in cyclical updates that end in slowdown, or potentially takedown, of your entire system.

RDVPs are stored. They are only updated when the data they’re related to updates. If your relationship notifications do not inform the RDVP to change, they will not change. This is a good and a bad thing - it means you have a static representation of your relationship data, but it also means that representation is a snapshot of what the data was when the notification was triggered. A newly-configured RDVP won’t have any data in it until the linked relationship notifies it to be updated (i.e. a specific property in that relationship has updated).

Creating an RDVP

Remember that “Query” tab we talked about earlier that our Virtual Property enabled? That is specifically the editor for RDVPs, and is the secret sauce to making these properties work.

The RDVP Query Configuration Tab

Let’s walk through each of the fields in more detail:

Referenced Relationship Fields

The Referenced Relationship Fields define what relationships should be referenced to create this RDVP. Since you could be referencing more than one relationship these fields are defined as an array.

For instance, let’s say that you wanted to traverse the user’s manager relationship. To do so, your “referenced relationship fields” property would be ["manager"].

As a more complicated example, let’s say that you wanted to get a list of data aggregated from all of your managers and reports. Since you are now looking at both your manager and reports relationship, your array would look like [["manager"], ["reports"]].

More complex still, let’s say that you need to calculate information based on a relationship’s relationship. Perhaps you want an RDVP that gives me a list of all of my coworkers under my manager, i.e. your manager’s reports. If you want to calculate off of a relationship of a relationship, in this case your manager’s reports, your array would look like [["manager", "reports"]]. If you’re dealing with a singular relationship chain, you don’t need the nested array (we saw that earlier with the manager-only relationship) but for clarity it’s recommended to use the array approach shown here.

The concepts above can be chained together. Perhaps I want to reference data not only on an nth-level relationship, but also another direct relationship (or another nth-level relationship). If we use the above examples, maybe you want not only data on your manager’s reports (i.e. your coworkers) but also your reports. Then your array would look like [["manager", "reports"], ["reports"]].

You can see an example of a complex Referenced Relationship Field in action on the effectiveAssignments property. This property is looking at both the assignments on the user but also the assignments on the roles related to that user, since roles have their own assignments.

Why do the documentation examples not show nested arrays? As RDVPs evolved, they went from referencing a single object relationship, to being able to traverse from one relationship to another in the chain, to being able to reference multiple relationships and relationship chains simultaneously. While a single array of values is a valid approach, it doesn’t account for the newer capabilities added to RDVPs.

Referenced Object Fields

The Referenced Object Fields define what data is to be gathered from the referenced relationship(s) to create the RDVP. This is a comma-separated list of properties that exist on the referenced relationship fields.

As an example, let’s say you wanted to get a reference to your manager (like what your manager relationship already does). Your referenced relationship field would be ["manager"] and the referenced object field can be left blank.

Now, let’s say that you wanted to get all of the information on your manager. In that case, use * for your referenced object field.

It’s likely you don’t need all of that information. Instead, let’s just get the email address of your manager. Your referenced object field would be mail.

Now RDVPs get interesting when you start traversing more than one layer in your relationship. What if you wanted the email addresses of all of your managers, i.e. your manager’s manager, your manager’s manager’s manager, and so on?

Firstly, you could specify a depth of traversal by modifying your referenced relationship field. If you are always getting your manager’s manager’s email address, your Referenced Relationship field would look like ["manager", "manager"].

Since the referenced object field references your relationship’s property, and an RDVP itself is a static property, you can reference RDVPs as a reference object field in an RDVP. So if you wanted to get all of your manager’s emails in the hierarchy and your RDVP is called managerEmails, your referenced object fields would be mail, managerEmails.

Let’s quickly break down how an RDVP referencing itself in its referenced object field works, top down:

In the above example, the CEO of your company doesn’t have any managers. As a result, both of their referenced object fields would return null and their managerEmails property would be null.
Let’s say that the CTO reports to the CEO. Their referenced mail object field would be the mail of their manager, the CEO. Their referenced managerEmails field would be null since the CEO’s is null and that’s what is being referenced.
Your boss reports to the CTO. As a result, their referenced mail object field is the mail of their manager, the CTO. Their referenced managerEmails field is the managerEmails field of the CTO, which contains the CEO’s mail.
Starting to see where this is going? Since you report to your boss, the referenced mail object field is your boss’ mail, and your referenced managerEmails is the managerEmails field of your boss, which is both the CTO and the CEO’s emails!

All of these objects are calculated on store, meaning that you have a static field defining hierarchical data that would require many loops or recursions to traditionally aggregate. All of the processing power required to calculate this deeply-nested data is handled once at time of update.

A useful callout: If you are referencing more than one relationship field, only the relationship(s) with the referenced object field will provide data. As an example, if your referenced relationship fields looked like [["manager"], ["adminOfOrg"]] and your referenced object fields looked like mail, unless you added an email property to your Organization you will only be getting the email of your manager.

Flatten Properties

RDVPs will return by default an array of objects which includes the referenced object fields you’ve requested, the _id of the managed object’s relationship (i.e. the relationship ID), and the _rev (i.e. the revision of that relationship). Flatten properties will return an array containing just the requested fields. Even if you request more than one field, those fields will be concatenated together in the array in sequential order of listing. This makes managing, and interacting with, multiple object fields much easier.

Let’s take the above example. If you set up a referenced relationship field of ["manager"] and a referenced object field of mail,managerEmails by default your response may look something like this:

"managerEmails": [
    {
        "mail": "theBoss@example.com",
        "managerEmails": [
            {
                "mail": "theCTO@example.com",
                "managerEmails": [
                    {
                        "mail": "theCEO@example.com",
                        "managerEmails": [

                        ],
                        "_id": "7162ddd4-591a-413e-a30b-3a5864bee5ec",
                        "_rev": "0"
                    }
                ],
                "_id": "02b166cc-d7ed-46b7-813f-5ed103145e76",
                "_rev": "2"
            }
        ],
        "_id": "f1e2d3c4-b5a6-7890-1234-56789abcdef0",
        "_rev": "0"
    }
]

Yuck. That’ll get annoying to traverse real quickly.

With flatten properties enabled, your result looks like this:

"managerEmails": [
    "theBoss@example.com",
    "theCTO@example.com",
    "theCEO@example.com"
]

Much nicer.

When flattening properties, it’s important to understand what data types you are flattening. It’s best practice to flatten only if you are working with string, boolean, or number properties and if all of your properties are of the same type. Otherwise, you’ll end up with a jumble of objects in an array that will be very difficult to parse later.

Delete Property Configuration

This is a UI-only addition that will remove the above configuration. You can accomplish the same by deleting the values in their respective fields (which is probably best considering the UI keeps these values.

Warning: Deleting your property configuration doesn’t delete the data on your property. Just because you changed a configuration doesn’t change the fact that the data only updates when it’s notified. If you are greatly overhauling what an RDVP is meant to do it may be wise to create a new property or define a means to notify all of the objects that contain that property to update.

Notifications

For an RDVP to be calculated at all, there needs to be a relationship change notification. A relationship change notification indicates to related objects that “hey, something has happened here that you care about” which informs those objects to update their RDVPs accordingly.

There are three ways in which a notification can be configured on a property:

Notify Relationships, under the advanced details of a property
Notify, under the relationship editor
Notify Self, under the advanced details of a relationship

The “Notify” and “Notify Self” flags signal to the base objects when the relationship has changed (e.g. a relationship has been added or removed). Notify will notify the downstream relationship, and Notify Self will notify the object you’re currently on.

The “Notify Relationships” flag signals to the specified relationship when the specific property has changed.

Rarely you may need to notify a property to update that isn’t directly related to you. To do so, use “Notify Relationships” on a relationship property to notify indirect relationships.

Notifications Example

Looking back at our manager emails example:

The manager emails property is meant to store a record of the email addresses of a user’s managers up the management hierarchy. That means that the value should recalculate if:

The employee gets a new manager
Any manager upstream (e.g. the manager’s manager) has been changed
Any manager upstream has changed their email address

In terms of notifications, then:

The owner of the manager relationship should Notify Self which tells itself to update when the relationship has changed.
The owner of the reports relationship should Notify which tells the reports to recalculate based on this relationship changing.
The mail attribute should Notify Relationships to the reports that the email has changed.

A common trip-up when defining notifications is that your relationship definition describes what it’s pointing to, not what it lives on. Your manager has reports: you have a manager. If you need to update yourself when you change your manager, you need to put Notify Self on your Manager relationship property and not on your reports property. If your manager needs to let you know that something has changed, they need to Notify their reports property.

Let’s look at a more complicated real-world example: effectiveAssignments.

Effective Assignments lists all assignments tied to a user. Assignments can be directly assigned to a user (via the assignments relationship) but they can also be assigned to a role which then is assigned to a user (via the roles relationship). As a result, effective assignments change if:

The user has added or removed an assignment relationship
The user has added or removed a role relationship
The role related to a user has added or removed an assignment relationship
Any of the related assignments have changed their properties

Start by taking a look at the Query Configuration for effectiveAssignments on the user. You’ll see that it’s referencing both the assignments directly related to the user as well as the assignments tied to roles ([["roles","assignments"],["assignments"]]), and that it’s returning all the properties within the assignments (*). This definition should inform you that notifications will be occurring on the user (where this property is located), roles, and assignments and that we need to notify based on properties updating from assignments specifically.

Looking at these relationships, you’ll see the following:

On the Assignment object:
- Notify is enabled for its members relationship. This notifies the user linked to the assignment if their relationship has changed.
- Notify is enabled if its roles relationship. This notifies the role linked to the assignment if their relationship has changed.
- Notify Relationships is enabled for roles and members on the attributes property and the weight property. This notifies users and roles if the attributes and weight properties on the assignment have changed, as these properties are referenced in RDVPs.
On the Role object:
- Notify is enabled for its members relationship. This notifies the user linked to the role if their relationship has changed.
- Notify Self is enabled on the assignments relationship. This notifies the role if the relationship has changed with the assignment.
- Notify Relationships is enabled for members on the assignments relationship. This notifies the user if the role’s assignments have changed, which is used in the effectiveAssignments RDVP definition.
On the User object:
- Notify Self is enabled on both the assignments and roles relationships. This notifies the user if their relationships have changed with either assignments or roles.

Enough talk: let’s build an RDVP and see it in action.

RDVP Examples

An RDVP requires a relationship to derive the property. So that we don’t alter notifications for pre-existing relationships, let’s create a brand new relationship that we can use.

This example will expand on the manager and employee concept and add in departments. Departments are going to link together users and other departments so that we can create a hierarchical view of our business.

Departmental Structure

To start, head back to the Native IDM Console. Under the Managed Objects view (Configure → Managed Objects) click the New Managed Object button and give it the following details:

Name	Value
Managed Object Name	department
Readable Title	Department

The rest of the values can be left blank. Click Save, and then using the “Add a Property” button on the next screen add a property with the name name, the Label Name, the type String, and make the value required. In the advanced properties, set this value to “Searchable”.

The Base Department Object

Go to your Identity Management Screen (in AIC, that’s in the Platform UI under Identities → Manage, and in PingIDM that’s the Manage Tab) and click on the Departments object. You should be able to create a new Department with its own name.

An Example Department

Next, let’s add the relationships to our Department object.

The Department should be able to have employees and should be able to have subdepartments.

In the department management page, add a new property called employees with the type relationship and hit save. You’ll be taken to the relationship management page - here you should select your User (in AIC, that’s alpha_user for the alpha realm) and select the userName and mail properties as display properties. Hit save.

You’ve now created a unidirectional linkage between a department and a user, in which that linkage will display the username and the email address of that employee in REST calls and the Platform UI.

The Employees Relationship Resource Linkage

The center of the relationship property uses arrows to define how the relationship links one property to another. Right now you should see a connection from department to employee with a bubble in the middle that says “Has one employees”. A department can have more than one employee, so click that bubble and change the relationship from “one” to “many”. Hit Save.

Currently your relationship is unidirectional: only the department object is aware of the linkage to the user. It’s likely that you need to be able to reference this relationship from the user as well, just as it’s likely that the relationship should be assignable from the user. Select the “Two-way Relationship” bubble that’s over the arrow pointing from your user object to your department object and select the “Has one” option. Create a reverse property with the name custom_department, giving it the display property of name. Hit save, and then save again on the property page.

The Employee/Department Relationship

Note: You’ll probably notice that your reverse relationship will by default set the Readable Title to the name of the relationship property. To change, go to the relationship definition and update the property directly.

We are going to create one more relationship: the concept of a parent department and children departments. This will give us the nesting that we outlined at the beginning of this example.

Create a new relationship entitled parent with the resource of department and the display property of name. Make it a bidirectional relationship, has many, with the reverse property name of children and the same display property as the other direction (name). This new relationship indicates that a department can have many children but only one parent.

The Parent/Children Relationship

Go back to the platform UI where you defined your Example organization. You’ll see two new tabs - one that lets you set Employees and another where you can set Children, as well as a dropdown that lets you select another Department as the Parent of the Department you’re on.

The Updated Department Object, with Relationships

Alright, we’ve created our example relationship with some bidirectional linkages that branch across more than one object. Let’s create some RDVPs to make referencing nested data easier.

Example: Single-Level Linkage

A department can be a parent of one or more departments. As an administrator, be it HR, management, or otherwise, you likely want to quickly understand what departments are children of your department.

Let’s create an RDVP that lists the names of all of the children departments of the parent.

Inside the department object, create an Array property with the name of childNames and label of Names of Children. Click into that property, unset User Editable, and set Virtual and Return By Default (we need that still for the Platform UI). Next, go to the Query Configuration and set the referenced relationship field as ["children"] and the referenced object field as name. Hit save.

The ChildNames Property

Create a brand-new department (I’m naming mine Child1) and assign your Example department as a parent. Go back to your Example department and…

Something Seems Off

…wait, where’s the Child Name?

While the RDVP’s query is configured to get the data we need, we haven’t configured any way to notify the RDVP to update.

The department will need to be notified in the following locations:

When the parent has added/removed a child
When the child has assigned/unassigned a parent.

First, in the parent relationship enable Notify. This tells the children to notify their parent to update when their relationship has changed.

Warning: Never set Notify on a non-reverse relationship. This will corrupt your managed JSON.

Notify on the Parent Department Relationship

Next, in the children relationship enable Notify Self. This tells the parent that it should update when the parent/child relationship has been changed, which it needs to update the Child Names.

Notify Self on the Children Department Relationship

Head back to your Example department. You’ll now see that… the child names still aren’t there?

Remember, RDVPs update only when they are notified to update. Since that child relationship was set before we created our notifications, nothing informed the RDVP to update.

In your Example department, remove Child1 from your Children and then re-add them. Go back to your details page (you may need to refresh the page afterwards, too, to see the change) and you’ll see an odd jumble of JSON.

The Raw RDVP

The Raw JSON will give you a better sense of what’s going on here. Your RDVP is returning the relationship details along with the value you’re requesting from the object (i.e. the name).

The RDVP JSON Output

In some cases, this level of detail is exactly what we want - it gives us the extra information we need to perform additional analysis like relationship querying. In the case of our name list, though, it’s probably unnecessary.

Head back to your Query Configuration for the childNames property and check “Flatten Properties”, then unassign and reassign the child relationship (if you want, try to assign the parent from Child1 to show that your notifications are working from both sides of the relationship). Your results are now returning as an array of just the child names.

Much Better

But what if you change the name of the child? Right now, nothing would happen - your parent is only getting notified if the relationship changes, not if the property changes.

In the name property of your department object, add the parent relationship to Notify Relationships.

Notifying the Parent if the Name Changes

With that notification in place, if your department changes their name they immediately let their parent know to update their RDVP accordingly.

You now have an RDVP that gives you an easy glance into the direct descendants of your department. But what if your sub-departments can go a level deeper?

Example: Multi-Level Linkage

Create a new department named Grandchild1 and assign its parent to Child1. You’ll see that the Child can see the Grandchild but the Parent (the Example department) has no visibility into the grandchild. If you’ve created a property that is meant to give visibility into all of the sub-departments that your department oversees, it’s likely that you want to see all of them, not just the first layer of direct assignments.

Back in your childNames RDVP, update the referenced object fields to be name,childNames. This tells the RDVP to not only reference the name of your children, but the childNames property on your children.

The Nested Referenced Object Fields

Unassign and reassign the grandchild from the child. The parent (example) department should have the grandchild, right?

Nope! Right now we are letting our direct relationships know when changes have been made but we aren’t propagating that information farther along the hierarchy. In other words: our parents know when they’ve changed children, and our children are letting our parents know when they’ve changed their parents, but our children aren’t letting our parents know when they’ve changed their children.

Back in the children property, set Notify Relationships to parent. This says that when you’ve modified your children you will let your parent know that something has changed and that they need to update their own information accordingly.

Notifying the Parent from the Children Relationship

From Child1, unassign and reassign Grandchild1 again. Going back to Example, you’ll see both the child and grandchild in your RDVP.

The Multi-Level RDVP

Now we have a way to see nested relationship data in a handy-dandy, easy-to-reference array. Let’s take this a step further and get data from another relationship in our department: the employees.

Example: Multi-Relationship Linkage

If you’re getting the names of the departments you cover, you may want to also get some details on the employees that work across those departments.

Create a new Array property called employeeEmails with the label Emails of Employees. Like before, disable “User Editable” and enable both “Virtual” and “Return by Default”.

Your query configuration will now have to reference two different relationships: your department’s employees as well as their children. The employees relationship will give us the data for the employees that work directly for this department and the children will give us information about the employees that work in the child departments.

Set your referenced relationship fields to [["employees"],["children"]], your referenced object fields to mail,employeeEmails, and enable Flatten Properties. This query is stating that we are looking for the mail and employeeEmails properties on both the employees relationship and the children relationship. Since mail only exists on employees and employeeEmails only exist on children we’ll get a running list of email addresses across the direct and indirect assignments.

The Employee Emails Query Configuration

Taking what we’ve learned from the prior examples, we should know that while the children of the department are notifying the department when changes are made, we’ll need to additionally notify the department about the employees to keep this RDVP up to date. If you want to test your understanding, try to set up the notifications yourself before checking your work below.

Solution (Click to View)

In the department managed object:
- Set Notify Self to true on the employees relationship
- Set Notify Relationships to parent on the employees relationship
In the user managed object:
- Set Notify to true on the custom_departments relationship
- Set Notify Relationships to custom_departments on the mail property

Create three users: parentEmployee, childEmployee, and grandchildEmployee. Then, either via the admin interface for the user or the department, assign the users accordingly. You should see their emails pass upward to your parent department.

The Multi-Relationship RDVP in Action

Example: The Organization Model

You may have noticed something familiar about the model we created. In essence, the hierarchy we built and the RDVPs we designed are a slightly-modified, rudimentary implementation of the Organization Model in AIC. On top of the RDVPs we built, Organizations have two additional User/Organization relationships with their own RDVPs gathering those relationships to be used in the platform for things like delegated administration. Relationships, and RDVPs, are the foundational principles that the Organization structure is built upon - and you now know how it works and how to expand upon it!

Conclusion

By completing this Guide, you’ve learned:

What are Virtual Properties and Relationship-Derived Virtual Properties
How to choose between the two types
Once chosen, how to configure the property

Outside of just Virtual Properties, you’ve additionally learned:

Common IDM scripting techniques
The basics of Relationships and a detailed understanding of configuring notifications from those relationships

Armed with this knowledge, you should be able to design and build complex, dynamic properties that match the requirements you need for your business and applications.

Join the discussion on the Ping Identity developer community.

Hardening the handoff: a pattern for app-to-web single sign-on

Wed, 08 Apr 2026 00:00:00 GMT

This post was originally published on Medium.

We’ve all been there, haven’t we? That shiny mobile app that you’ve just downloaded from your favourite brand, the one that’s offered you a really clean and modern sign in experience (without browser hand-offs, perhaps even using a passkey for quick login), suddenly and inexplicably spits you out into a browser view when you tap a particular button or menu item. Hybrid apps — those that combine both native and web elements — are an unavoidable reality for many organisations (and their users) as they look to balance time to market on new features with ever-stretched engineering budgets and the technical debt further down the stack that they’ve never quite managed to pay off.

As identity professionals who care about that delicate balance between user experience and security, the question that comes up time and again is this: what is the best way to secure these apps? How do I ensure a slick user authentication process at the start and then safely re-use that session across all aspects of my application, when some parts of it are delivered via browser or web-view? In this article, I’ll explore the challenges that these hybrid app models present to us and propose a workable solution based on modern identity standards (with a sprinkling of identity orchestration). The solution I describe below has been built and tested using Ping Identity’s PingOne SSO identity provider together with the PingOne DaVinci identity orchestration engine.

Eager for the punchline? Here’s the succinct summary for those on a time and attention budget!

The session transfer problem

Before we can start to solve the challenges that we face in securing hybrid mobile applications, we should start by better defining the problem space. For the purposes of this discussion, we define a hybrid mobile application as a native application running on a mobile device where certain portions of the application’s functionality are delivered via a web browser or web view on the device — that is to say, the app is not fully native. The exact specifics of how and when the app switches context between a native delivery versus a browser-based delivery of functionality are not important, however there are two requirements that we must fulfil, namely

access to the browser-based content requires an authenticated user session (presumably in the form of a browser session cookie, which is how these things have always been done)
the user has already performed authentication in order to access the app itself and as such should not be prompted to re-authenticate in order to access the browser-based content.

A number of follow-on points are salient here and those who have grappled with this situation in the past are no doubt familiar with them. The most important ones are, perhaps, as follows:

In a native application context, the authenticated user session is typically represented by an OAuth access token, issued to the application by a trusted Authorisation Server in response to a user login.
There are established best practices for how a native application should go about obtaining such a token by leveraging the Auth Code Flow with PKCE via the system browser. This approach is battle-hardened and peer-reviewed and should always be the first alternative considered when building a user authentication process for a native app.
To directly contradict the previous point, however, many (if not most) digital product owners and UX designers find the experience trade-off unacceptable and thus strongly resist using a browser-delivered authentication ceremony within the context of a native application, preferring to use fully native SDKs to interact directly with the authentication service to obtain the necessary access token.
Whichever approach is selected for initial user authentication, the basic requirement is the same in terms of providing a single-sign-on experience if the app includes hybrid web content; in order for the user to access said content without re-authentication, there needs to be a session cookie present in the browser at the time that content is requested. This is the most basic requirement (the sine qua non, if you will) without which the user is guaranteed to be prompted for repeat authentication

All this talk of cookies is possibly making you hungry by now, but we do need to explore the intricacies just a little deeper before taking a well-earned coffee break! This problem really is all about cookies, though — that much we cannot deny. One would think and would hope that the pattern of using the system browser to obtain authentication credentials from the user in the first place would create a session cookie in that browser as a serendipitous side effect (and give us a further piece of ammunition in convincing our product owner and UX colleagues to eschew a fully-native alternative). In practice, however, this approach has been shown to be non-deterministic at best, if not downright flaky, due to the somewhat arcane and seemingly ever-changing rules regarding cookie persistence and visibility across browser tabs and invocations. Without going into all of the details, I think it is sufficient to say that, based on the experiences of many doing this work in the field today, we cannot assume that a session cookie set during initial login will be available during subsequent browser-based interactions. The reasons for this are all very well-meant; examples being Apple’s Intelligent Tracking Prevention feature and Google’s equivalent Privacy Sandbox work — designed to increase user privacy. As a result, even if we are lucky enough to stumble upon a configuration on a given device that does give us the cookie visibility that we need, there is every chance that further tightening of cookie rules in the future could break our solution, leaving both product owners and (more importantly) end users furious.

What we are left with is a challenge to solve, broadly defined as follows:

“how, then, do we engineer a mechanism where the access token that represents the logged-in user within the native context can be used to create a browser session cookie at the point that the user needs to access web content”

It goes without saying that any such mechanism MUST be secure and avoid exposing us and our users to malicious theft of tokens, user sessions and the applications and API’s that these protect.

A standards-based pattern for secure session transfer

We know that we need a mechanism whereby we can take the app’s representation of an authenticated user session, the OAuth access token, and turn this into an authenticated session in a web browser, in the form of a session cookie. OAuth does not provide a standardised pattern or grant type that we can use to solve this problem and as a result a number of approaches have emerged, many of which fall down on either user experience or security, and sometimes both.

A naive approach to the problem would be to launch a new OAuth authorisation request in the browser via the Auth Code flow, and simply pass the app’s access token directly to the Authorisation Server as a custom URL parameter. This does imply that whatever OAuth Server implementation is in use must provide the capability to extract the access token from the query string, validate it and create a web session cookie for the subject of the token. While not many implementations that I’ve encountered will provide this sort of “access-token-to-web-session” mechanism out of the box, most will offer some sort of customisation capability, via plug-in or extension script that will allow such a mechanism to be built.

I would advise against this approach for a number of reasons, with the most critical being the security risk that it carries.

We must remember, at all times, the inherent security challenge implied by the Bearer Token model, where simple possession of an access token grants whoever holds the token full power to use it. We should assume that any access token issued to a native application client would be a powerful artefact indeed and allow a malicious actor the ability to invoke any API on the application back-end should they manage to obtain it. Adding such a dangerous object to a URL query string and sending it out “into the wild” where it could almost trivially be intercepted is not the solution we seek.

The alternative approach that I recommend is to use a relatively-recent addition to the OAuth family of standards to achieve the same outcome in a way that provides better protection of the access token during the session transfer process, namely OAuth 2.0 Pushed Authorization Requests (or PAR), described in RFC 9126. To set the scene, let’s look at the abstract of the document that describes the approach:

“This document defines the pushed authorization request (PAR) endpoint, which allows clients to push the payload of an OAuth 2.0 authorization request to the authorization server via a direct request and provides them with a request URI that is used as reference to the data in a subsequent call to the authorization endpoint.”

To paraphrase and simplify, PAR allows us to provide our sensitive access token directly to the Authorisation Server via a direct HTTPS Post from our native app code, rather than including it as an insecure query string parameter in the browser. This separation of data payloads between the “back channel” (direct POST) and the “front channel” (browser GET) significantly improves the security baseline of what we need to achieve and provides solid scaffolding for the further work we need to do.

An additional advantage to the approach is that PAR gives us a ready-made query string parameter, in the form of the returned request_uri, that is guaranteed to be single-use and short-lived, thus reducing the very large attack surface that the alternative approach inherently creates.

I mentioned further work above, and it is important to realise that while PAR does provide a great starting point, it is not the complete solution to this challenge by itself. There is more to be done both in terms of user experience and also security, which we’ll explore in the next section. For now, though, let’s describe the “bones” of the approach here, in the form of a worked example

Alice opens the Acme Inc native application and clicks the “Login” button. She is authenticated via a native authentication experience (no browser pop-up) that results in a valid OAuth access token being sent to the app. The app responsibly and securely stores this access token on her behalf.
Alice clicks the “Manage My Profile” button in the app. Acme Inc delivers profile management via an embedded browser view within the app, and the web backend that serves this content requires a session cookie in order to identify Alice and link her to the correct profile.
When Alice clicks the button, native app code retrieves her access token and initiates a secure POST to the Acme Inc Authorisation Server’s PAR Endpoint. The post body includes access token as a custom parameter, in addition to client_id, scope and all the other required OAuth parameters. In accordance with the PAR standard, the Authorisation server returns a response including a request_uri, a single use value that acts as a reference to the request data that has been provided.
The native app code now opens a browser window, passing in the URL of the Acme Inc Authorisation Server’s authentication endpoint, with the request_uri from the previous step as a parameter. The Authorisation Server uses identity orchestration to validate the provided access token and create a web session for Alice, before redirecting her to the profile management application, where the browser cookie now ensures a single-sign-on experience

The informed reader will, of course, have many remaining questions based on the above explanation. Let’s address them now.

Enabling secure session transfer on top of PAR

Native applications are public clients from an OAuth point of view. Put another way using language extracted directly from RFC6749, “it is assumed that any client authentication credentials included in the application can be extracted”. The implications of this reality are far reaching and many of them beyond the scope of this discussion, but it matters here because it means we cannot use a confidential client (with a client secret) to kick off our PAR request from inside the app.

It is important to realise here that we are not using PAR for its ability to complete an end-to-end flow, that ends with a redirection and ultimate token issuance to the same OAuth client that initiated the request. We are rather using PAR as a way to initiate a browser flow and then build on the side effect of the session cookie that is created. This means that we do not, in fact, want to ever complete the flow that we start via PAR. We only want to go as far as creating a session cookie before we break out and redirect the user to the actual application, which will start its own Auth Code flow from scratch, using its own client_id, redirect_uri, PKCE enforcement, etc.

The combination of the two factors above suggests that we should configure and use a specific OAuth Client as a sort of session transfer proxy — that is, a completely new client unrelated to either the native app that starts the transfer or the web app that ultimately benefits. We should take as many precautions as we can to lock down this session transfer client such that it can only be used for a single purpose, but also we should be sure not to add any configurations to our existing clients that could weaken their existing security posture.

Let’s describe the flow again, adding the additional details that we have described above.

Alice clicks the “Manage my profile” button in the app. The app code starts the PAR process using the client_id of the dedicated Session Transfer Client. It includes a scope such as “session_transfer” in the request, and generates a PKCE Code Challenge that it includes with the request. Note that the corresponding Code Verifier can be discarded at this point since this flow is not intended to ever result in an access token issuance.
The app code includes three other pieces of information (at minimum). These are the access token that it already holds for the user, the IP address that it is using, and the URL of the profile management application.
It sends the PAR request to the authorisation server and obtains a response that contains a request_uri, which it appends to the AS’s authorization endpoint URL before opening a browser tab to initiate the front-channel flow.
When the front-channel request hits the Authorisation Server, the request is validated (to ensure it has not expired or already been used) before being handed to the identity orchestration engine for further processing.
The orchestration engine (as above, I have tested this with PingOne DaVinci, mileage may vary if using a different platform) must introspect or validate the provided access token to ensure that it is valid, has not expired and was indeed issued to the expected client (the mobile app). It should also compare the IP address provided as part of the PAR request to the IP address passed via the current HTTP request, to ensure that the backend and frontend requests come from the same place. Further checks can be implemented using orchestration logic as required.
Should the above checks succeed, the orchestration engine extracts the “sub” claim from the access token to determine the appropriate user, and sets a session cookie in the browser for that same user.
At this point, the orchestration logic simply redirects the browser to the URL of the profile management application (the same URL that was provided via the PAR back-channel initiation in step 3). This is the step that interrupts the flow started by the Session Transfer Client and ensure that no auth code or access token is ever issued.
The profile management application now receives the browser redirect and is responsible for initiating its own OAuth/OpenID Connect Auth Code flow, just as it would had a browser opened the app URL directly. It should generate its own redirect to the AS, including its own client_id and redirect_uri, its own appropriate scopes and its own PKCE Code Challenge. The AS will start a user authentication process that should complete with no further user interaction required, based on the presence of the session cookie set in step 6.
The browser is thus redirected back to the profile management application with everything that is needed to display logged-in user content.

TL;DR

My good friend and proof-reader Gransomeuk pointed out that some folks will just want the take away, rather than the full three course meal. With his help, here’s the summary, with a nifty sequence diagram to match.

Phase 1 (Back-Channel): The mobile app passes the highly sensitive access token directly to the Authorization Server over a secure connection (POST). In return, it gets a short-lived reference string (request_uri). This solves the problem of putting the Access Token in a visible URL query string.
Phase 2 (Front-Channel): The app opens the browser using only the reference string. The Identity Orchestration engine (e.g., PingOne DaVinci) verifies that the person in the browser is the same person who holds the app token (by checking IP addresses, etc) and drops a session cookie in the browser.
Phase 3 (SSO): The browser is redirected to the target Web Application. Because the cookie now exists, the Web App can sign the user in automatically via standard OpenID Connect without asking the user to type in a password again.

“Next time on…”

In the interests of keeping things digestible, I will publish two follow up articles in the coming weeks.

The first will explore the technical implementation of this pattern end-to-end, using PingOne SSO and PingOne DaVinci, together with a simple Android application to show it all working.

The second will dive a little deeper into some of the security implications of this approach, highlight the advantages, point out a number of inherent drawbacks and also suggest further steps that can be taken to harden the implementation.

References and further reading

Securing MCP Servers with Ping’s MCP Gateway

Wed, 01 Apr 2026 00:00:00 GMT

You’ve been shipping MCP servers and each one comes with its own OAuth handler, its own scope-checking logic, its own audit hooks. Security code that should be administered centrally ends up copy-pasted across every server you build.

The MCP security gateway capabilities in PingGateway solve this by acting as a security bouncer in front of your MCP servers. The bouncer checks credentials at the door, enforces the rules, and logs everything — so your servers never have to.

You can find a deeper dive into MCP’s architecture, workflow, and security model in the Ping Identity MCP documentation.

Where PingGateway sits as your MCP security gateway

In a typical setup, PingGateway as an MCP security gateway sits between the MCP client (the AI agent) and your MCP server.

What PingGateway adds for MCP servers

By fronting your MCP server, PingGateway validates that requests are syntactically correct MCP, enforces operational requirements like audit and throttling, enforces authorization of the request, and mediates security tokens before forwarding to the MCP server.

Your server continues to implement tools and domain behavior; the gateway provides the surrounding security and operational controls.

What capabilities does PingGateway provide?

PingGateway extends its proven API security stack with MCP-aware capabilities you configure once and reuse across every server:

McpValidationFilter: Validates Origin / Accept headers and MCP / JSON‑RPC format and populates an McpContext so subsequent filters (throttling, policy, metrics) can inspect method and tool names.
McpProtectionFilter: Serves OAuth 2.0 Protected Resource Metadata (/.well-known/oauth-protected-resource/...) on behalf of your MCP endpoint, ensures the access token’s aud matches the configured resourceId and uses PingGateway’s OAuth 2.0 resource server capabilities to validate tokens and enforce scopes.
McpAuditFilter: Emits MCP‑specific audit events (who called which tool, where, and with what result)
MCP metrics: Exposes Prometheus metrics per MCP method/tool (counts, latencies, errors).
MCP throttling: Rate limits access per route, per tool, per client or per identity.

Seeing it in action: the “unauthenticated” request

The gateway’s job is to stop what shouldn’t get through — and wave through what should. If the MCP client (AI agent) sends a request without the proper identity tokens required by the Ping Identity platform, the gateway will block it.

The situation: missing authorization header.

An AI agent sends a tool call without an Authorization header:

POST /mcp/v1/call_tool

{
  "method": "tools/call",
  "params": {
    "name": "access_customer_database",
    "arguments": {
      "customer_id": "12345"
    }
  }
}

Result: 401 Unauthorized — rejected by PingGateway before the request ever reaches your server.

With valid credentials, the gateway allows the request through.

The same agent retries with a valid, scoped Bearer token:

POST /mcp/v1/call_tool
Authorization: Bearer <valid-access-token>

{
  "method": "tools/call",
  "params": {
    "name": "access_customer_database",
    "arguments": {
      "customer_id": "12345"
    }
  }
}

Result: 200 OK — PingGateway validates the token, confirms scope, logs the event, and forwards the request to your MCP server. Your server never saw the first request at all.

Benefits for the MCP server developer

MCP security shouldn’t be implemented in each MCP server’s codebase
Without a gateway, each MCP server grows its own OAuth, scopes, auditing, throttling, and risk logic.
With MCP Security Gateway, a standard PingGateway route in front of each MCP server centralizes that logic; you reuse the pattern for every new server.
Comply with MCP authorization by configuration, not code
MCP requires OAuth 2.0 Protected Resource Metadata so agents know which AS to use and which resource they call. PingGateway serves this metadata and validates tokens according to it, so you configure security once instead of coding it per server.
Gain observability “for free”
Audit logs and metrics at the gateway show which tools are used, by whom, and how often, without extra instrumentation in your MCP code.
Protect MCP servers from noisy or malicious agents
Central throttling and policy/risk rules ensure your servers only see pre‑validated, rate‑limited, authorized requests.
Integrate legacy or sensitive backends cleanly
Use token mediation at the gateway to map agent tokens to whatever your backends expect (different scopes, JWT formats, API keys, mTLS), keeping your MCP server’s backend calls simple and aligned with existing security models.

The gateway acts as the “bouncer,” ensuring the server only spends resources processing requests that are properly formatted, authenticated, and authorized.

Get started!

The MCP security gateway tutorial walks you through the complete setup. Download the sample MCP agent and server (or bring your own), insert PingGateway in front of your MCP server, and enable MCP processing and authorization in the gateway configuration.

MCP exposes your business capabilities to AI agents. PingGateway makes sure only the right agents — with the right credentials and the right permissions — ever reach them.

Next steps

Get started with the MCP security gateway tutorial.
Visit the MCP documentation on the Ping Identity developer portal.
Check out developer resources for all Ping Identity products at developer.pingidentity.com.
Join the discussion on the Ping Identity Developer Community.

We Rebuilt the PingOne API Docs. Here’s What’s New.

Wed, 01 Apr 2026 00:00:00 GMT

Introduction

If you build integrations, you probably spend a lot of time staring at API documentation. So when we decided to overhaul the PingOne API docs, our goal was simple: get out of your way and make it easier for you to actually test and write code.

The new site officially went live in early January. Here’s a quick rundown of what changed and how to use the new features.

It’s a lot faster and easier to navigate

The most obvious improvement is performance. The site loads faster, the pages are lighter, and the layout now matches the rest of the Ping Identity documentation ecosystem.

We also reorganized the navigation so you don’t have to dig through endless menus to find helpful information:

New to PingOne? We have plenty of resources to help you get up and running quickly. Jump into our Getting Started guide, explore Foundations, or follow along with step-by-step tutorials in the Use Case Library.
Learn about APIs: You can dive straight into the PingOne Platform SSO or Auth APIs to see detailed info on all endpoints, which are logically grouped by functional area.
Universal services: These now have their own dedicated section, making it clearer how they fit into the wider Ping Identity portfolio.
Smart search: If you still can’t find what you need, the search bar now uses the same AI-assisted backend as our other doc sites.

Test endpoints in your browser

For every endpoint, you’ll see example requests and responses in multiple programming languages. More importantly, we completely rebuilt the Try Request feature:

Live testing: Plug in your parameters, hit the button, and get real API responses back immediately.
Persistent parameters: You no longer have to copy and paste the same environment or user IDs over and over. Your parameters carry over from one API call to the next. This includes access tokens, so you don’t have to constantly re-authenticate.
Secure local storage: To keep things safe, those variables only live in your web browser’s session storage. The second you close the tab, they’re gone.

Update your bookmarks

To keep things simple, all developer-focused content, including cloud and on-premise APIs, now lives in one place: the Developer Portal.

Check out the new PingOne API docs at developer.pingidentity.com/pingone-api.

Let us know what you think

This launch was a massive effort, but the work doesn’t stop here. Documentation is never really “finished.”

Give the new site a spin. If you run into a weird bug, see a typo, or have any suggestions, let us know by clicking the feedback icon in the top-right corner of each page.

Happy coding!

Next steps

Visit our new PingOne API documentation.
Check out developer resources for all Ping Identity products at developer.pingidentity.com.
Join the discussion on the Ping Identity Developer Community.

Introducing the PingOne Advanced Identity Cloud (AIC) MCP Server

Tue, 31 Mar 2026 00:00:00 GMT

Developers have already discovered that LLMs (such as Claude, Gemini, GPT, Grok, and others) accelerate workflows across coding, debugging, and operations. A real breakthrough has been the ability to create custom agents within the IDE. Now developers can write specialized agent workflows that combine reasoning, tooling, and domain logic to solve problems autonomously.

To help these agents work effectively, we need a bridge between the AI and your actual services. That is where MCP (Model Context Protocol) comes in.

Today, we are excited to introduce the AIC MCP Server. This tool connects your PingOne Advanced Identity Cloud (AIC) environment directly to the AI agents you use every day in IDEs like Cursor, VS Code, and GitHub Copilot, or command-line tools like Claude Code and Gemini CLI.

What Exactly is an MCP Server?

Think of the Model Context Protocol (MCP) as a universal remote for AI. In the past, every AI platform had to build its own unique way to talk to different databases or services. MCP changes that by creating a standard “contract.”

It allows an AI agent to see a list of available tools, understand what they do, and know exactly how to call them. When you use an MCP server, you aren’t just giving an AI a window into your data; you’re giving it a specialized “hand” to perform tasks for you.

You can find a more detailed look into MCP’s architecture, workflow, and security model in the Ping Identity MCP documentation.

How the AIC MCP Server Works

PingOne Advanced Identity Cloud (AIC) is Ping Identity’s modern, single-tenant identity platform. It manages users, authentication flows, roles, policies, audit logs, and customer-facing themes. If you’re running an identity operation, AIC is where the configuration lives.

The AIC MCP server is an open-source TypeScript tool, distributed through npm, which exposes 40+ tools that wrap AIC’s REST APIs and packages them as MCP-compatible functions. Instead of manually navigating the console or hand-crafting API requests, you describe what you want in natural language. Your agent translates that to the right MCP tools, the MCP server handles the API calls and authentication, and returns results that the agent can reform into natural language.

Here’s the practical difference:

Task	Without MCP	With AIC MCP Server
Find failed logins from 9 PM – 11 PM yesterday	20 minutes (console navigation, log filtering, export)	1 minute (“Show me authentication failures from 9 PM – 11 PM yesterday”)
Create a new role with specific permissions	15 minutes (console form, multi-step workflow)	2 minutes (“Create a role called product-admin with these permissions: …”)
List all users in a specific group	10 minutes (API docs, construct request, parse response)	30 seconds (“Which users are in the engineers group?”)

Why This Matters: MCP Adoption Is Evolving

MCP has become the standard for AI-to-infrastructure integration. Popular developer tools (such as Claude Desktop, Cursor, GitHub Copilot, VS Code, Gemini CLI) all now support MCP. Developers are moving from being software engineers or technical admins to being agent orchestrators.

Identity and access management (IAM) is a perfect fit for AI assistance. Configuration can be repetitive. Audits demand detailed log parsing. Bulk operations can be tedious. Configuration updates may take a while when navigating multiple screens and modals in the web console. IAM is also not an isolated capability, often connected to other systems that benefit from being managed as a group. In this way, MCP clients allow connection of multiple MCP servers from different providers to bridge multi-service, multi-product workflows. The more systems connected, the more autonomy an agent has, the more the user can delegate.

For developers, this means faster operations. Less manual console navigation. Less copying and pasting IDs between tabs. Reduced context-switching.

Core Capabilities: 35+ Tools Across Five Categories

The AIC MCP server exposes 35+ tools organized into five functional areas:

Managed Objects: Perform “search, create, and update” tasks for users, roles, groups, and organizations. (for example, “Find all users with an @acme.com email.”)
Themes & Branding: Update your login pages, logos, and brand colors across different regions programmatically.
Logging & Audits: Query activity logs by time, user, or error type—perfect for quick security check-ups.
Secrets & Variables: Securely manage API keys and environment variables without having to hard-code them.
Authentication Journeys: Build and test complex login flows (journeys) and the scripts that power them.

The server exposes many tools providing broad capability, with every action authenticated using OAuth 2.0 with PKCE and tied to your user identity in the audit log.

Getting Started: Hands-On Walkthrough

Getting the AIC MCP Server running takes 5 minutes. You’ll need:

A Sandbox or Development AIC tenant.
Node.js 18+ on your machine (or Docker).
An MCP-compatible AI client (Claude Desktop is recommended).
5 minutes of setup time.

Step 1: Configure Your MCP Client

Find your AIC tenant’s base URL in the console (for example, my-tenant.forgeblocks.com). Then add the configuration to your MCP client’s config file:

{
  "mcpServers": {
    "aic-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ping-identity/aic-mcp-server"],
      "env": {
        "AIC_BASE_URL": "your-tenant.forgeblocks.com"
      }
    }
  }
}

Replace your-tenant.forgeblocks.com with your actual tenant URL (no https:// prefix).

Step 2: Authenticate

Restart your AI client. When you first use a tool, the server will:

Open your browser to your AIC login screen.
Ask you to log in with your AIC admin credentials as an administrator.
Show you the permissions the server needs (scopes like fr:idm:\*, fr:idc:monitoring:\*).
After you’re authenticated, securely save your token in your OS keychain (where available).

This is a one-time setup for the session. The token stays in your keychain and can be reused until expiry or ephemerally if using the Docker image. Subsequent tool calls reuse the cached token, if it is still valid.

Step 3: Make Your First Tool Call

Count all users in the system and show me the total.

Behind the scenes, your agent will:

Understand the available tools provided by the MCP server.
Call the listManagedObjects tool to discover object types.
Call queryManagedObjects to fetch users.
Return the count in plain English.

Expected response: “There are 247 users in your AIC tenant.”

Real-World Use Case: Debugging Authentication Issues

It’s 8 AM. A high-priority bug report just landed: “A recent change to the primary user authentication journey has caused failures in overnight tests.” You need to:

Analyze the bug and map it to the existing auth journey.
Provision test identities that match the specific failure criteria.
Trace the logs to find the exact line of code or configuration causing the break.
Patch the journey and verify the fix immediately.

Without the server: 45 minutes of context switching (Jira, documentation, console, log aggregators, scripts).

With the AIC MCP Server (and other MCP servers that interact with ticket systems and UX):

1. Analyze the Bug and Journey

Your prompt to Claude:

Read bug report AUTH-802 and show me the current 'SSO-Onboarding' journey configuration.  Compare with recent closed tickets that may have caused a breaking change.

The Action: Your agent fetches the ticket details using the ticket system MCP server and pulls the journey configuration. It identifies a probable failure that happens during a user lookup step from an external data source. Time to insight: 30 - 60 seconds.

2. Reproduce with Test Users

Your prompt to Claude:

Create three test users: two with valid metadata in the external data source and one with invalid data to replicate the reported error.

The Action: Agent calls createManagedObject and tools related to the external data source. It returns key details for fresh accounts tailored to your debugging needs. Result: Environment ready in 20 seconds.

3. Trace Logs & Identify the Root Cause

Your prompt to Claude:

Run a test authentication for the user with invalid data. Show me the logs and highlight any stack traces.

The Action: Agent triggers a mock login and calls queryLogs. Result: “Found an error relating to user lookup. The journey isn’t handling user lookup where there is invalid data correctly.” Time to discovery: 5 minutes.

4. Update & Re-test

Your prompt to Claude:

Update the 'SSO-Onboarding' journey to include appropriate error handling when user data lookups fail, then re-test with the same user.

The Action: Agent calls saveJourney with the fix and re-runs the authentication trace. Result: “Test passed. Redirect successful. Journey updated in Dev environment.”

Total time saved: 30 - 45 minutes of manual work → less than 10 minutes of natural language queries. The workflow can be packaged up into an agent to save more time later. The difference compounds across your team.

Security and Caveats

OAuth 2.0 Authentication

Every tool call is authenticated with your AIC credentials using OAuth 2.0 (PKCE flow). Your password is never stored. The resulting access token is saved securely in your OS keychain—the same place your browser stores credentials.

Audit Trail

All actions—queries, creates, updates, deletes—appear in your AIC audit log tied to your user identity and are traceable as MCP-based interactions. There’s full traceability for compliance and security reviews.

Sandbox and Development Only

Currently, the server works with Sandbox and Development AIC tenants only. Production support is on the roadmap. This ensures you can safely experiment and iterate without risk to live systems.

Agent Permissions

Only use the MCP server with AI agents you trust. The agent has the same permissions as your authenticated user. If you’re an AIC admin, the agent is an admin. Always review agent prompts and tool calls before deploying them to production workflows.

Open Source

The server is Apache 2.0 licensed and open-source on GitHub. Review the code, audit the dependencies, and contribute. The entire codebase is at github.com/pingidentity/aic-mcp-server.

Next Steps: Try It Today, Give us Feedback

Run your first agent workflow.
Consider your developer workflows, how can the MCP server be used to turn repetitive or menial tasks into automated, intelligent workflows?
Share your use cases and workflows with the Ping Identity developer community.
If you find issues or would like to see enhancements, raise an issue on the code repository. We’re listening!

The AIC MCP Server is in early release. Your feedback shapes what comes next!

References

GitHub Repository: https://github.com/pingidentity/aic-mcp-server
NPM Package: https://www.npmjs.com/package/@ping-identity/aic-mcp-server
PingOne AIC Documentation: https://docs.pingidentity.com/pingoneaic/
Model Context Protocol (MCP) Specification: https://modelcontextprotocol.io/specification/2025-11-25
OAuth 2.0 PKCE (RFC 7636): https://tools.ietf.org/html/rfc7636

Introducing the PingOne MCP server

Tue, 31 Mar 2026 00:00:00 GMT

Introduction

Developers building applications using PingOne eventually hit the same friction point. Application code is in the IDE, while application configuration, audit logs, policies, and user journey flows are managed in the web console.

That context switch is the problem, not the task itself. Registering an application in PingOne or spinning up a new environment for development is straightforward. The cost is the frequent interruption leading to a break in flow, tab switching, and copying and pasting IDs.

Although frequent switching between IDE and the web console has been well accepted over the years, the expectations of application developers is shifting. Application developers are shifting to AI tools and agentic development practices. Generative code experiences such as VS Code Copilot, Claude Desktop, Claude Code, Gemini CLI, and GPT Codex are changing the ways that developers interact with their application code, and they’re changing the way developers interact with online services.

The PingOne MCP Server reduces the gap. It connects your PingOne tenant directly to MCP-compatible generative AI IDEs and CLIs. Instead of leaving your editor, you describe what you need from your application integration in natural language, and your agent handles the PingOne API calls, returns the IDs and configuration details you need, and lets you keep iterating on application code.

This isn’t about replacing the PingOne console for operational work. It’s about making identity platform configuration a first-class citizen of the development cycle, available in the same context where you write code, run tests, and ship features.

What Is MCP?

System configuration living outside the development cycle isn’t unique to PingOne. But it’s a fundamental challenge in building agentic systems: how do AI agents and IDE AI chat systems connect to the external services they need to act on?

The Model Context Protocol (MCP), originally developed by Anthropic, provides a specification for the interactions between AI systems (the abstract world of “intent”) and today’s systems (the concrete world of deterministic input/output). Before MCP, every integration between an AI agent and an external tool required custom code—bespoke connectors, point-in-time maintenance, duplicated effort across teams. MCP standardizes the connection layer, providing a “USB style” connector interface so that any MCP-compatible client (VS Code Copilot, Claude Desktop, Cursor, and others) can discover and invoke any MCP server’s capabilities using a common protocol, without needing custom code on either side.

In practical terms, an MCP server currently exposes three types of capabilities:

Tools (executable actions the agent can invoke)
Resources (contextual data to inform reasoning)
Prompts (templated workflows)

The agent discovers tools at runtime, selects what it needs, and calls them through JSON-RPC messages. Prompts and resources are loaded at the user’s request.

You can find a deeper dive into MCP’s architecture, workflow, and security model in the Ping Identity MCP documentation.

What is the PingOne MCP Server?

The PingOne MCP Server implements the MCP standard for PingOne’s Management API, exposing 14 tools across 4 capability areas, and represents the start of the journey in producing useful tools to accelerate developer workflows.

In practical terms: your AI agent in your IDE can now interact with your PingOne tenant the same way it interacts with your filesystem, your terminal, or your version control. It becomes part of the same conversation as your application code.

The initial set of tools cover what developers need most when building on PingOne:

Applications: List, retrieve, create, and update OIDC/OAuth 2.0 applications
Environments: List, retrieve, create, and update PingOne environments; manage services (such as MFA and DaVinci)
Populations: List, retrieve, create, and update user populations
Directory: Generate per-day identity trend reports.

All operations execute as the authenticated user and are logged in PingOne’s audit trail. The agent never sees your access tokens or sign-on credentials; the MCP server handles authentication entirely, returning only the data the agent needs.

Missing something you need? Get in touch! Raise an enhancement request on the code repository. Your feedback helps drive what we do next.

Getting Started: From Zero to First Tool Call

To get started you need a PingOne account (Try Ping here), an MCP-compatible client (VS Code with Copilot, Cursor, Claude Desktop, or similar).

For the adventurous, in your favourite agent IDE, try:

Help me install and configure the PingOne MCP server from github.com/pingidentity/pingone-mcp-server

Otherwise, follow the instructions below.

1. Install the Server

The easiest path on macOS or Linux is Homebrew:

brew tap pingidentity/tap
brew install pingone-mcp-server

Verify:

pingone-mcp-server --version

For Windows, the MCP server is built as an executable file, ready to download from the project releases. See the project README for full details for Windows installation and other options.

2. Set Up a Worker Application in PingOne

The server needs credentials. Create a worker application in your PingOne tenant:

Sign on to the PingOne Administration Console.
Open the environment for your Administrator users.
Go to Applications > Add (+).
Name it (for example, “PingOne MCP Server”) and choose type Worker.
Go to Configuration and configure OAuth 2.0 settings:
- Set response type to Code.
- Set grant type to Authorization Code (uncheck all others, including Client Credentials).
- Set PKCE Enforcement to S256_REQUIRED.
- Enable Refresh Token.
- Set redirect URI to http://127.0.0.1:7464/callback
- Set the Token Endpoint Authentication Method to None
Save and capture your Environment ID and Client ID from the application details.
Finally, remember to enable the MCP server application!

Although the example here uses the ‘Authorization Code’ grant type, ‘Device Code’ is also available. You can find more details in Setting Up PingOne Worker Applications for MCP Server.

3. Configure Your MCP Client

Once installed, add the server to your MCP client’s configuration. For VS Code with Copilot Chat:

{
  "servers": {
    "pingOne": {
      "type": "stdio",
      "command": "pingone-mcp-server",
      "args": [
        "run"
        // "--disable-read-only" // uncomment to enable write tools
      ],
      "env": {
        "PINGONE_MCP_ENVIRONMENT_ID": "your-environment-id-uuid",
        "PINGONE_AUTHORIZATION_CODE_CLIENT_ID": "your-client-id-uuid",
        "PINGONE_ROOT_DOMAIN": "pingone.com"
      }
    }
  }
}

If your tenant is in a different region, use pingone.ca, pingone.eu, pingone.com.au, pingone.sg or pingone.asia

To install to other IDEs, including Claude Code, Gemini and Cursor, refer to the project README.

That’s it. On first tool use, your browser opens your PingOne administrator sign-on page. After you authenticate with your admin credentials, the server caches your token securely in your OS keychain (where available) or is cached ephemerally. Every subsequent tool call validates and reuses the same token.

Real-World Use Case: Prepare an Environment for App Development

You’re building a new application feature that requires its own isolated identity configuration: a dedicated, ephemeral sandbox environment, a test user population, and an OIDC application for the OAuth flow your code will use.

Without the MCP server, you stop coding, switch to a browser, walk through the PingOne console to create the environment, toggle the services you need, create the population, register the application, copy the client ID and environment ID back into your project, and resume back.

With the PingOne MCP Server, you stay in your IDE:

Note that write tools must be enabled using --disable-read-only at startup.

Step 1 — Understand what already exists:

"List my PingOne sandbox environments and show me which services are enabled in each."

The agent calls list_environments and returns a structured overview. You can see your existing dev and staging environments, what’s running in each, and confirm there’s no overlap with what you’re about to create.

Step 2 — Create the new environment:

"Create a new sandbox environment called 'feature-payments-dev'.
Enable the MFA and DaVinci services."

The agent calls create_environment, then update_environment_services to add MFA and DaVinci, and returns the environment ID. You paste it into your .env file without leaving the editor.

Step 3 — Create the test population:

"Create a population called 'Payments Test Users' in the
feature-payments-dev environment."

The agent calls create_population. Returns the population ID. You add it to your test harness configuration inline.

Step 4 — Register the OIDC application:

"Create an OIDC application in feature-payments-dev called
'Payments App'. Use authorization code grant with PKCE enforced.
Redirect URI is http://localhost:3000/callback."

The agent calls create_oidc_application with the correct grant type, PKCE settings, and redirect URI. It returns the client ID.

Step 5 — Confirm and move on:

"Give me a summary of the feature-payments-dev environment:
environment ID, enabled services, population name and ID,
and the Payments App client ID."

The agent returns a clean summary, and you’re ready to move on. The entire flow took less than three minutes without switching context once. All four operations are in your PingOne audit log, associated with your user identity.

The process can be wrapped into a skill or an agent, and the rest of the team can benefit from the workflow.

Security Considerations

The most important thing to understand about the PingOne MCP Server’s security model: the agent is acting as you. The MCP server doesn’t have its own service account, its own permissions, or its own audit identity. When the agent calls a PingOne API through the MCP server, it calls it as your authenticated user account. Everything it does is bounded by the PingOne roles assigned to your admin account and actions are visible in the audit log, attributable to your identity.

Other features include:

Production environment restrictions. By default, all write actions are disabled on production environments. This is to protect against accidental or unintended configuration changes, even if your user has the ability to make changes to production configuration.

Write operations require an explicit decision when starting the MCP server. Running the server without --disable-read-only exposes only read tools. This is to allow you to explicitly opt in to write tools on your tenant.

Full audit trail. Every API call from the server includes a session ID and transaction ID in the request headers. You can trace any change back to the MCP server session through PingOne’s audit log.

Preview software. This is an early release. APIs and behavior may change. Use caution when using the MCP server against important environments. Found a bug? Open an issue.

Open source. Apache 2.0 licensed. Read the code, audit the dependencies, contribute a fix: github.com/pingidentity/pingone-mcp-server.

Next Steps: Try It Today, Give us Feedback

The current 14 tools cover a subset of what developers may need when developing on PingOne. But the goal is broader: PingOne configuration should be as accessible from your IDE as your database schema, your API spec, or your CI/CD pipeline. Manual steps you need to take between your code and your identity configuration is a point of friction that can be improved upon.

Near-term additions include Docker support for containerized workflows and simplified installation, expanded tool coverage across more PingOne APIs, and support for upcoming MCP specification changes as the standard evolves.

The roadmap is shaped by what you actually need. If there’s a specific tool or capability that would close a gap in your workflow, raise an enhancement request or start a discussion in the repository.

Get a PingOne trial account if you don’t have one.
Install and follow the project README.
Think about the identity configuration steps in your current developer workflow. Where does context-switching slow you down?
Share what you build with the Ping Identity community.

Your feedback shapes what comes next. Try it today and give us feedback on what you want to build.

References

PingOne MCP Server code repository: https://github.com/pingidentity/pingone-mcp-server
PingOne MCP Server releases: https://github.com/pingidentity/pingone-mcp-server/releases
PingOne documentation: https://docs.pingidentity.com/pingone/latest/
Model Context Protocol (MCP) specification: https://modelcontextprotocol.io/specification/2025-11-25
PingOne Management API: https://apidocs.pingidentity.com/pingone/platform/v1/api/
OAuth 2.0 PKCE (RFC 7636): https://tools.ietf.org/html/rfc7636
Homebrew Tap: https://github.com/pingidentity/homebrew-tap

Rapidly Deploying PingGateway with PingOne Advanced Identity Cloud (P1AIC)

Tue, 03 Mar 2026 00:00:00 GMT

This post was originally published on Medium.

Note: This blog applies to PingGateway versions from 2025 onwards. For earlier PingGateway (IG) releases, please refer to the original blog here.

Introduction

Integrating applications securely and efficiently with PingOne Advanced Identity Cloud (P1AIC) is a common requirement for developers and architects exploring modern identity platforms.

This article demonstrates how to deploy PingGateway in standalone mode and protect a sample application using Cross-Domain Single Sign-On (CDSSO) with P1AIC — all via a single automation script.

The objective is straightforward:

Enable new users to quickly stand up PingGateway, integrate it with P1AIC, and understand how CDSSO protection works end-to-end.

This deployment is designed for:

Learning and enablement
Proof-of-concept environments
Developer experimentation
Workshops and demonstrations

It is not intended as production use.

The repository containing all assets and the deployment script is located here on GitHub.

To get straight to deploying go here.

Scenario

“As a new customer, I want to understand PingGateway through hands-on experimentation — specifically how to configure it to protect an application via CDSSO with P1AIC.”

This blog walks through that exact scenario.

What the Script Deploys

The repository includes:

install_ping_gateway_P1AIC.sh — automation script
admin.json.HTTPS
admin.json.HTTP_ONLY
static-resources.json
cdsso-idc.json

When executed, the script provisions:

A PingGateway standalone instance
A Sample Application
Route configurations that:
- Reverse proxy static resources
- Protects /home/cdsso via CDSSO with P1AIC

All components are deployed on the same host for simplicity.

Architecture Overview

PingGateway runs in Standalone Mode, meaning:

It does not require deployment into a servlet container.
It runs directly from the extracted ZIP.
It uses Vert.x internally to provide its runtime engine.

The result is a lightweight, fast-starting gateway instance suitable for development and experimentation.

The end-to-end flow looks like this:

User accesses protected resource via PingGateway.
PingGateway checks for a valid OIDC token.
If no valid token is present, the browser is redirected to P1AIC.
User authenticates with P1AIC.
P1AIC redirects back to PingGateway.
PingGateway validates the token and grants access to the sample application.

This demonstrates CDSSO in action, and described in more details below:

To learn more about CDSSO check out this link

Script Execution

Step 1 — Download Assets aond Configure Networking

Download the ZIP from GitHub here.
Down the PingGateway Standalone ZIP and PingGateway Sample Application JAR from here and place both files in the same directory as the script.
By default PingGateway will be deployed against this host pinggateway.test.com and the Sample app to sample.test.com. Add both to your /etc/hosts file. For example for IP 172.168.1.10 the hosts entry will look like this:

172.168.1.10 pinggateway.test.com sample.test.com

Step 2 — Configure the Script

Modify lines 11–30 in the install_ping_gateway_P1AIC.sh script to match your environment

Step 3 — Configure P1AIC

Create a Test User

Log in to P1AIC.
Select the appropriate realm.
Navigate to Identities → Manage.
Create a new user.

Create a Gateway Agent

Navigate to Gateways and Agents.
Click New Gateway/Agent.
Select Identity Gateway.
Enter the following and hit Save:
- Agent ID (e.g. pinggateway_agent_cdsso)
- Password

Ensure these values match the script configuration:

AGENT_ID
AGENT_SECRET

Configure Redirect URIs

HTTPS:

https://pinggateway.test.com:9443/home/cdsso/redirect

HTTP:

http://pinggateway.test.com:9000/home/cdsso/redirect

Step 4 — Execute the Script

For P1AIC deployments, use HTTPS mode due to SameSite cookie requirements:

Run: ./install_ping_gateway_P1AIC.sh https
For standalone PingAM deployments run ./install_ping_gateway_P1AIC.sh http

Step 5 — Validate Deployment

After deployment, access:

https://pinggateway.test.com:9443/home/cdsso.

You should be redirected to P1AIC for authentication. Upon successful login, the Sample Application page will be displayed.

Note: If you were already logged into P1AIC during setup, log out first or use a private browser window to prevent cookie conflicts.

Step 6— Stop/Start the PingGateway

To stop/start PingGateway and the Sample App use:

Stop Services: ./install_ping_gateway_P1AIC.sh stop
Start Services: ./install_ping_gateway_P1AIC.sh start

Script Breakdown

The script performs the following high-level steps.

1. Environment Validation

The script validates:

PingGateway ZIP is present
Sample Application JAR is present
Required commands are available (unzip, curl, etc.)
The host can connect to the configured P1AIC endpoint

Execution stops if validation fails.

2. Clean Installation Handling

If a previous installation exists:

PingGateway is stopped
The sample application is stopped
The installation directory is removed

This ensures clean redeployment.

3. PingGateway Deployment

The script:

Extracts the PingGateway ZIP
Performs a temporary start/stop cycle to initialise directories
Creates required configuration folders

PingGateway is deployed in Production Mode by default.

4. Script Execution Mode

The script supports:

https mode (recommended for P1AIC)
http mode (for standalone PingAM deployments)

When HTTPS mode is selected, a self-signed certificate is generated automatically.

Note — Self-signed certificates are for demonstration only and should not be used in production.

5. Sample Application Deployment

The sample application is deployed locally and started on the configured ports, providing a target application for PingGateway to protect.

6. Route Configuration

Two routes are created:

static-resources.json — Allows PingGateway to proxy static resources (e.g., CSS) without authentication. This improves performance and mirrors real-world deployment patterns.
cdsso-idc.json — Protects the /home/cdsso context. It checks for a valid OIDC id_token, redirects unauthenticated users to P1AIC, validates tokens on return and grants access upon successful validation

Conclusion

This script provides a fast, repeatable way to deploy PingGateway locally and integrate it with PingOne Advanced Identity Cloud using CDSSO — all within minutes. It enables you to:

Deploy PingGateway in standalone mode
Understand how standalone runtime operates
Explore CDSSO behaviour with P1AIC
Observe complete end-to-end authentication flows

By simplifying setup and automating the foundational configuration, this approach accelerates learning and removes friction from experimentation. It serves as an ideal starting point for:

Developers building familiarity with PingGateway
Architects validating integration patterns
Technical enablement sessions and workshops

Most importantly, it provides a clear, structured baseline from which you can extend into more advanced routing logic, security hardening, certificate management, and production-ready deployment patterns.

In short, this script turns what could be a multi-step manual configuration process into a streamlined, educational experience — helping you move from exploration to implementation with confidence.

Ping Identity’s LTS, STS and Everything in Between: Because You Deserve Predictable Support

Fri, 05 Dec 2025 00:00:00 GMT

Introduction

Ping Identity and ForgeRock merged in 2023, bringing the two identity companies together. ForgeRock products were subsequently renamed under the Ping Identity brand, although their support policies initially remained different.

Ping Identity has announced a unified End of Life Policy based on Long Term Support (LTS). The unified policy takes effect in February 2026.

This article explains the revised policy, its lifecycle stages, and examples of how enterprises can use the support timelines when planning identity-platform upgrades.

Figure 1: Ping Identity and ForgeRock — names and lifecycle-support evolution.

Versioning scheme

Ping Identity products use semantic versioning. A version contains three dot-separated components:

Major.Minor.Maintenance

For example, the PingAM version 8.0.1 consists of:

Major: 8
Minor: 0
Maintenance: 1

For a separate explanation of software-version numbering, see Explanation of software version numbers.

Software product lifecycle stages

Ping Identity uses the following lifecycle designations:

Generally Available (GA) — The product is available for purchase. The product release date is generally called the GA date.
Active Maintenance — The product is actively developed, maintained, and supported.
End of Maintenance (EOM) — Product maintenance has stopped, but customers may still receive support. Customers can submit support cases and obtain technical assistance under Ping’s support policy.
End of Support (EOS) — The product is no longer maintained or supported.
End of Life (EOL) — The product is obsolete and receives no maintenance, support, updates, or extended support.

Figure 2: Key lifecycle stages.

Different software vendors may use different names for comparable lifecycle events. Check each vendor’s official definitions when assessing a product’s support status.

Customers may purchase Extended Limited Support (ELS) for an additional charge after a product reaches EOS. ELS is available only for specifically designated versions, so eligibility is not universal.

Avoid operating products that are unsupported or have reached EOL. Regulated sectors, including financial services, may restrict the use of such software. For example, the UK Prudential Regulation Authority and Australia’s Australian Prudential Regulation Authority (APRA) provide guidance relevant to the use of unsupported software.

Current state lifecycle: from August 2023 through February 2026

Table 1: PingAM lifecycle-stage dates, based on the heritage ForgeRock support policy.

The table presents lifecycle dates for PingAM versions 7 and 8 under the earlier support arrangement. The key points are:

Versions 7.0, 7.1, 7.2, and 7.3 have passed EOM but remain eligible for support.
EOS, EOL, and EOM calculations use the major and minor version numbers.
PingAM 7.5, the final minor version in the previous major series, does not yet have an EOM date.

Future state lifecycle and support: beyond February 2026

Beginning in February 2026, Ping Identity will designate product versions as either Long Term Support (LTS) or Short Term Support (STS).

LTS releases are intended for critical deployments that prioritize operational consistency and longer security coverage. Banks and insurance companies are examples of organizations likely to favor this model.

STS releases are intended for environments where obtaining new capabilities quickly is more important than having the longest support window.

Table 2: Comparison of LTS and STS versions.

Ping Identity expects, but does not guarantee, to introduce new LTS versions approximately every two years.

The revised framework is intended to provide both LTS and STS support paths, with more predictable maintenance and upgrade planning.

Illustrative PingAM release sequence

The following hypothetical releases demonstrate how the lifecycle model could operate:

AM 10 — STS: March 2026
AM 10.1 — STS: May 2027
AM 10.2 — LTS: November 2027
AM 11 — STS: February 2028
AM 11.1 — STS: May 2028
AM 11.2 — LTS: August 2028

Table 3: Illustrative lifecycle dates for a future PingAM release under the unified support policy.

Summary view of key benefits for enterprises

The unified policy is expected to provide four benefits for enterprises:

Stability: LTS releases provide three years of guaranteed support.
Predictability: A regular release pattern, with LTS versions expected roughly every two years, supports upgrade planning.
Flexibility: LTS versions may receive an optional additional year of ELS.
Simplicity: Heritage Ping and heritage ForgeRock products will follow one unified policy.

From self-hosted to SaaS: are lifecycle stages and support still relevant, or just a legacy concern?

Many organizations are adopting software as a service (SaaS) and other hosted services.

Ping Identity offers three cloud options:

PingOne Advanced Services: Single-tenant services.
PingOne Advanced Identity Cloud: Single-tenant services.
PingOne Cloud Platform: Multi-tenant services.

With these hosted offerings, customers do not generally manage product versions or lifecycle milestones themselves. Ping Identity manages platform updates, patches, and support, reducing the customer’s need to plan around individual software EOL dates.

Frequently asked questions

Can STS versions be used in production?

Yes. Both STS and LTS releases are production-capable. The difference is that STS versions have shorter support periods, requiring customers to plan upgrades more frequently.

Do STS and LTS versions receive patches in the same way?

Both release types receive regular patches. However, Ping Identity may schedule the patches differently for STS and LTS versions.

Is there a fixed STS release schedule comparable to the approximate two-year LTS cadence?

No fixed STS timetable is specified. Each product family determines its STS timing according to its feature backlog and customer requirements.

The stated goal is to provide at least one STS release per product each year, although some product families may publish more than one.

Does the new model extend the release approach already used by PingGateway?

Yes. PingGateway has used a similar LTS/STS-style approach since 2023, although it did not formally use those labels.

The 2025.3, 2025.6, and 2025.9 releases are STS examples, and the forthcoming 2025.11 release is an LTS version. From February 2026, all Ping products are expected to use the LTS and STS framework.

Under the new approach, the final minor release within each major release becomes the LTS version, following the practice PingGateway has used for its three-year support model.

Is there a current-version mapping for STS and LTS releases?

Yes. See Ping Identity’s End of Life Tracker.

Active versions designated as LTS or STS are covered by the unified policy. The example shown identifies PingAM 7.5 as LTS and PingAM 8.0 as STS. Other versions, including PingAM 7.4 and 7.3, continue under their existing maintenance and support policies.

Table 4: Active PingAM versions designated as STS and LTS.

Are whole major versions assigned as LTS or STS, as in the Java release model?

No. Ping Identity does not designate an entire major version as LTS or STS.

Instead, the last minor release within each major version is the LTS release. Earlier minor releases in that same major series are STS. Consequently, each major release is expected to contain one LTS version and one or more STS versions.

Conclusion

Ping Identity is consolidating the lifecycle arrangements for its heritage Ping and ForgeRock products into a unified framework containing both LTS and STS release types.

LTS releases are intended to provide a three-year guaranteed maintenance period, helping organizations operate critical systems with greater stability and plan future upgrades more consistently.

Acknowledgements

The article thanks Jessica Chow, Matthew Berzinski, and Marc Harris for reviewing the article and providing suggestions.

References

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community.

Securing High-Risk Actions: Transactional Authorization over REST

Wed, 26 Nov 2025 00:00:00 GMT

This post was originally published on Medium.

Introduction

Requiring a user to explicitly authorise access to a sensitive resource every time they attempt to access it is a common security requirement. A typical example is in financial services, where initiating a payment might trigger a one-time passcode (OTP) sent to the user’s device, or a push notification requiring approval. These additional steps increase friction intentionally, ensuring the user is genuinely present and consenting before a high-risk action is allowed.

In the PingOne Advanced Identity Cloud (P1AIC) and PingOne Advanced Identity Software (self-managed PingAM), this capability is known as Transactional Authorisation (TAuthZ). You can read more about it here.

The most common and recommended architecture for enabling Transactional Authorisation is to use a Policy Enforcement Point (PEP) such as PingGateway or the PingAgent, which interact with P1AIC or PingAM as the Policy Decision Point (PDP). Another pattern is to implement enforcement directly in applications via the Ping SDKs (JavaScript, iOS and Android).

However, some customers who operate their own application gateways prefer to interact directly with the PDP REST APIs. This blog focuses on that third approach and provides a clear, end-to-end example using an automated shell script to demonstrate how the REST flow works.

The high-level sequence of events for both application-based and gateway-based integrations is broadly the same. It’s explained in detail here, but here’s the simplified flow:

Use Case

In this blog, we demonstrate a REST-based approach to Transactional Authorization (TAuthZ) using an automated shell script. The scenario covers a high-risk operation — accessing an example makePayment API
(https://api.bankingexample.com:443/makepayment) via an HTTP POST request.

The script performs the following steps:

Authenticate the user using a standard login journey and obtain an SSO token
Authenticate an admin using an admin-specific login journey in order to access the policy endpoint, issuing an SSO token with extended session durations (for example, a 60-minute idle and max time) so the client can cache it and improve performance.
Calls the policy evaluation endpoint to request access to the protected makePayment API.
Receive a policy advice with a TransactionConditionAdvice (TxId) from the PDP instructing the client to execute a Transactional Authorization journey (for example, OTP or push approval).
Executes the required TAuthZ journey with this TxId, collecting and completing the necessary callbacks for the one-time step-up authentication flow.
Resubmits the policy evaluation request, now including the completed transactional context and TxId.
Finally, receives a one-time authorization decision granting access to the sensitive API.

This demonstrates how applications or gateways can interact directly with the PDP REST APIs to enforce secure, single-use authorization for high-risk operations.

Solution

Let’s get building 💪

All assets are located here.

Import the Journeys

For this example we’ll import three journeys:

NormalLogin — Used to simulate a standard user login.
AdminLogin — Used to simulate admin login with extended session timeouts.
TransactionalAuthZLogin — Used as the step-up authentication journey triggered by the TAuthZ policy.

Download the journey export from here.
From the P1AIC Platform UI, navigate to Journeys on the left panel > Click Import > Take a Backup if required > Select Browse > Locate and open the file from step 1 > Click Next > Start Import

Once the import is complete, the three new journeys will appear as shown below. Note that the TransactionalAuthZLogin journey should be a strong MFA journey. However, a simplified version has been used here for clarity in this blog.

Import the Transactional Authorization Policy

Download the policy XML file from here.
From the P1AIC Platform UI, expand Native Consoles > Click Access Management > Expand Authorization > Click Policy Sets.
Click Import Policy Sets > Find the XML file from step 1 > Click Open
Refresh the browser and the new transactionalAuthZ Policy Set will appear.
Clicking into it will show the makePayment policy as shown below where:
- The resource is defined as https://api.bankingexample.com:443/makepayment
- The allowed action is HTTP POST.
- The subject is set to AuthenticatedUsers
- The Transaction Environments condition targets the TransactionalAuthZLogin journey.

Create the Test Users and Apply Privileges

From the P1AIC Platform UI, Expand Identities > Click Manage > New Alpha realm — user > Create a user with the following:
- Username: policy_user
- Firstname: Policy
- Lastname: User
- Email Address: policy_user@example.com
- Password: !!_SeCu4E@Pa55w04D$
Repeat Step 1 but this time for the policy admin user:
- Username: policy_admin
- Firstname: Policy
- Lastname: Admin
- Email Address: policy_admin@example.com
- Password: !!_Adm1nSeCu4E@Pa55w04D$
From the Access Management Native Console, navigate to Identities > Groups tab > Add Group > Set the Group ID to policy_admin > Create.
Add the policy_admin user as a member and hit Save.
From the Privileges tab, enable Entitlement Rest Access and hit Save Changes.

Execute the Script

Now that we have all the configuration in place, let’s bring it to life with the script.

Download the script from here
Modify the AM_URL to match your environment
Execute the script to demonstrate the flow

The output will look this like:

./transactional_authZ_DS.sh  
Getting cookie name  
CookieName is: XXXX
*********************  
Creating end-user SSO token for user: policy_user  
End-user SSO token is: ZER7HY8OL...
*********************  
Creating policy-admin SSO token for user: policy_admin  
Policy-admin SSO Token is: o0jzAU....
*********************  
Calling transactional policy: transactionalAuthZ  
Transaction Condition Advice Id is: 195b8505-3dba-4bbc-a71a-7debed2c2596
*********************  
Calling ../authenticate endpoint with Transaction Condition Advice Id: 195b8505-3dba-4bbc-a71a-7debed2c2596 to get callbacks
*********************  
Completing callbacks for submission  
Completed callback payload:  
{  
"authId": "eyJ0eXAiOiJKV1QiLC....74",  
"callbacks": [  
....
*********************  
Calling authenticate endpoint with advice and completed callbacks  
{  
"tokenId": "ZER7HY8O....IwMQ..*",  
"successUrl": "/enduser/?realm=/alpha",  
"realm": "/alpha"  
}
*********************  
Finally, calling policy endpoint post transactional AuthZ with Transactional Conditional Advice Id of: 195b8505-3dba-4bbc-a71a-7debed2c2596  
[  
{  
"resource": "https://api.bankingexample.com:443/makepayment",  
"actions": {  
"POST": true  
},  
"attributes": {},  
"advices": {},  
"ttl": 0  
}  
]
*********************

Conclusion

Transactional Authorization (TAuthZ) is a powerful capability within PingOne Advanced Identity Cloud (P1AIC) and PingAM, enabling organisations to enforce strong, step-up authentication precisely at the moments where risk is highest. Whether approving a financial transaction, confirming a high-value action, or validating a user’s intent, TAuthZ offers a reliable way to introduce friction only when it truly matters.

This blog illustrates how to execute a complete Transactional Authorization flow entirely over REST. By walking through user authentication, admin token retrieval, policy evaluation, TxId handling, step-up journey execution, and final policy re-evaluation, we showed how an application or custom gateway can interact directly with the PDP — while still leveraging the full power and flexibility of PingAM’s decisioning capabilities.

Smarter “Remember Me” with PingOne Protect

Tue, 21 Oct 2025 00:00:00 GMT

This post was originally published on Medium.

Introduction

In the world of Identity and Access Management (IAM), it’s always a balancing act between security and user experience. Organisations want to introduce just the right amount of friction, at the right moment, and in the right context to protect users without disrupting them. The goal is to maintain a seamless, trusted customer journey while minimising drop-off and frustration.

To achieve this, many businesses have implemented a “Remember Me” capability within their web channels. Once a user successfully signs in, subsequent visits allow them to be logged in automatically without re-entering their credentials — a familiar and convenient feature which is especially common in retail environments.

However, “Remember Me” in isolation has its flaws. While it delivers convenience, it often lacks the intelligence to adapt when the context changes. For example, what if a user originally authenticates from the UK but suddenly appears to log in from Singapore — an impossible traveller scenario? What if their IP address shifts unexpectedly, the login occurs at an unusual time, or even worse, a bot attempts access? Without continuously evaluating these contextual signals, “Remember Me” might meet the bar for user experience but falls short on adaptive security — failing to introduce the right friction at the right moment.

This is where PingOne Protect steps in. It continuously analyses behavioural and contextual signals across multiple attack vectors to assign risk scores and trigger appropriate mitigation or action, to ensure convenience is not achieved at the expense of security.

To learn more about the use cases for PingOne Protect integration with PingOne Advanced Identity Cloud (P1AIC) check out this link.

Use Case

In this blog, we’ll enhance the Persistent Cookie feature in PingOne Advanced Identity Cloud — the functionality that enables the “Remember Me” capability by integrating it with PingOne Protect.

Here’s how it works:

During the initial login, PingOne Protect evaluates the context and returns a risk score:

If the score is low, a Persistent Cookie (PCookie) is set, and the login proceeds as normal.
If the score is not low, no PCookie is set — effectively disabling “Remember Me” for that session, but does so silently, without disrupting the user experience.

On subsequent visits, if a valid PCookie is found, PingOne Protect performs another risk assessment:

If the risk remains low, the cookie is trusted, a new session is created automatically and the user is seamlessly signed in.
If the risk is elevated, the user isn’t blocked outright; instead, the PCookie is deleted and they’re redirected to re-enter their credentials — introducing just the right level of friction, at the right moment, based on the current context and signals.

Solution

Let’s get building! 💪

Before we dive in, it’s worth noting that this solution showcases the power of the PingOne platform — apart from a single Custom Node used to display nodeState variables for clarity and education, it’s built entirely with out-of-the-box nodes, requiring no customisation or extensions.

Setup a Mapped PingOne Environment

In this section we’ll create a PingOne environment with PingOne Protect deployed:

If you have a PingOne subscription navigate to this page and hit “Sign On” at the top right of the page and login. On success you’ll be re-directed to the https://console.pingone.eu/ page. If you don’t have a subscription, you can get a demo environment through this link. Enter your business email address and hit “Try Ping”.
From the PingOne Console > Hit Environments on the left panel > Blue + icon next to Environments.
Select Build your own solution > click PingOne Protect > Hit Next.

On the environment name enter an appropriate name, for example env-pingoneaic-**mycompany-ew2-sandbox1** > Select the region > Hit Finish.

Create a Worker Application

Follow these steps to create OIDC credentials for the PingOne AIC tenant to integrate with PingOne Protect. Note the PingOne API and Authorization URLs, for example https://auth.pingone.com, https://auth.pingone.eu etc.

Create Environment Secrets and Variables (ESVs) in P1AIC

Follow these steps to create three ESVs that map to the PingOne Worker Credentials from the last step.
Additionally, create an ESV named esv-hmac-signing-key (string secret) to sign the persistent cookie. Generate a 256-bit key using one of the following commands:
- OpenSSL: openssl rand -base64 32
Finally create an ESV (string variable) called esv-persist-cookie-domainwith a value of the Fully Qualified Domain Name of your tenant. For example openam-darinder-test.forgerock.io.

These ESVs make it easy to update configuration values when promoting to higher environments.

Create a PingOne Service in P1AIC

Follow these steps to create a PingOne Service in your P1AIC tenant. For the secondary configuration be sure to use the ESVs defined above.

After creating the configuration set the PingOne API Server URL and Authorization Server URL as per the address noted in the “Create a Worker Application” section:

Import the Custom Display NodeState Node

Download Display-NodeState.json from GitHub here to your local machine.
From the P1AIC platform admin UI, expand Journeys on the left navigation panel > Custom Nodes
Click Import Nodes (or Import if other Custom Nodes are present) > Browse > open Display-NodeState.json > Import Nodes > Done. A new node called Output Variable from NodeState should be created.

Journey Import

From the journey_exports directory here, download the journey to your local machine.
From the P1AIC platform admin UI, expand Journeys on the left navigation panel > click Journeys > Import.
If need be take a backup or skip.
Click Browse > find the PersistWithProtect-journeyExport.json file > Open > Next > Start Import.

A few points to note:

The PingOne Protect Evaluation nodes uses the default Risk Policy Set ID. As a best practice a new risk policy should be created and the ID set in this parameter. From the PingOne Console > Expand Threat Protection > Risk Policies > Global Policies Blue + > Set a name > Configure as required > Apply > Copy the resulting Policy ID into this parameter. For example a05cccb8-ada5–44e3-a6cd-cefdbc0c942f
Additional BOT_MITIGATION and AITM_MITIGATION (Adversary-In-The-Middle) items were added to the Recommended Actions parameter of the PingOne Protect Evaluation nodes to demonstrate the node’s flexibility in mapping specific risk results to additional outcomes.
The PingOne Protect Result node captures additional context just before the session is created, ensuring maximum accuracy for future assessment of the user’s risk posture and behaviour.

Journey Breakdown

This journey demonstrates how to implement a “Remember Me” (persistent login) flow enhanced with PingOne Protect risk evaluation.
It combines persistent cookie management with adaptive risk analysis to allow seamless logins for low-risk sessions while enforcing re-authentication for higher-risk ones.

On every execution of the journey, the PingOne Protect Initialize node runs first to begin context and device data capture.

The journey then checks for the presence of a persistent cookie named persist-session.
If persist-session is found:
- The PingOne Protect Evaluation node calls PingOne Protect to evaluate the context and calculate risk.
- For a Low risk outcome, the PingOne Protect Result node is invoked, and seamless “Remember Me” functionality is preserved.
- For any other outcome, the persistent cookie is removed, the PingOne Protect Risk value stored in nodeState is displayed for insight, and the user is redirected to authenticate again.
If persist-session is not found:
- The user is prompted for their username and password, and the PingOne Protect Evaluation node again evaluates context and risk.
- If a Low risk outcome is returned, a new persistent cookie is set, enabling “Remember Me” on future logins.
- For all other outcomes (except ClientError, which shows an error message), the PingOne Protect Risk value is displayed for eudcation and understanding.
- Login is still permitted — the session proceeds, but without setting the persistent cookie — ensuring user access is not disrupted, only “Remember Me” functionality is withheld.

Demo

Check out the video below for a live demo

PingOne Protect offers powerful monitoring and visual dashboards that translate complex security data into clear, actionable insights. With real-time visibility into analysed events, risk trends, geolocation anomalies and high-risk user behaviour, organisations can quickly assess and respond to emerging threats. Here’s an example dashboard:

Conclusion

The integration of PingOne Protect with PingOne Advanced Identity Cloud elevates a simple “Remember Me” feature into an intelligent, adaptive security capability. By continuously evaluating contextual and behavioural risk, it ensures that convenience does not come at the expense of protection.

Users enjoy seamless, low-friction logins when their behaviour is trusted, while higher-risk sessions automatically trigger the right level of friction — discreetly and without disruption. The result is a smarter, more secure “Remember Me” experience that balances usability with robust risk-based control — all achieved through a no-code, out-of-the-box Ping Identity platform implementation.

Unleashing Success: Key Ingredients for PingOne Advanced Identity Cloud

Mon, 05 Jun 2023 00:00:00 GMT

This post was originally published on Medium.

Introduction

In today’s digital landscape, organizations face a multitude of challenges when it comes to managing identities and ensuring secure access to their systems. PingOne Advanced Identity Cloud is a powerful solution that enables businesses to streamline their identity and access management (IAM) processes. However, the success of a PingOne Advanced Identity Cloud project depends on several critical factors. In this blog post, we will explore the key ingredients necessary for a successful PingOne Advanced Identity Cloud project.

Roles and responsibility

Understanding the roles and responsibility of the PingOne Advanced Identity Cloud components, external applications, and overall solution will allow an organisation to allocate resources during the project and help maintain the solution moving forward. Knowing where to find the right resources to assist will expedite issue resolution and allow for more efficient solution development.

Platform components

PingOne Advanced Identity Cloud is a SaaS application deployed to Google Cloud Platform. The software components deployed inside the platform are managed by Ping Identity, while external software components that make up the overall solution but do not fit inside the platform are managed by the organisation.

Ping Identity components

Ping Identity is responsible for deploying, managing, upgrading, and monitoring the various software components as part of the platform. Ping Identity also regularly backs up data and provides High Availability and Disaster Recovery. Organisations no longer have to be concerned with spinning up complex architectures for various environments, as Ping Identity does this all for you. Each customer receives a development, staging, and production environment to start, and customers can request any number of sandbox environments to support development; see the environment documentation for more detail.

The following Ping Identity software and services are all wrapped up in a single PingOne Advanced Identity Cloud Platform:

PingAM
PingIDM
PingDS
Cloud DevOps — Promoting configuration
Admin UIs / Hosted Pages

Organisation components

The organisation is responsible for deploying, managing, and upgrading the software and solution components deployed outside of PingOne Advanced Identity Cloud, but still acting as part of the overall solution. Of course, any Ping Identity products deployed onsite will still be covered by Ping Identity product support.

The organisation’s components may include:

Custom UIs backed by the Ping SDKs
Remote Connector Servers
Edge components like PingGateway
The organisation’s own CI/CD pipeline
Overall solution monitoring

Customer solution

During the project, a solution will be custom-built by the deployment team to meet the organisation’s requirements. This solution is the product that the organisation owns and is delivering to its customers. Maintenance, monitoring, and enhancements to this product are the responsibility of the organisation. Ping Identity maintains responsibility for the underlying software inside PingOne Advanced Identity Cloud and offers around-the-clock support for any issues that may arise with the software.

For organisations to support the product they are delivering to their customers, some may train or even hire internal technical resources, consult a partner organisation or SI, and may engage Ping Identity technical consultants as required. See Ping Identity technical consulting services for more information.

Technical skills and training

Ping Identity provides comprehensive product training for all of its products; these can be accessed through Ping Identity Training. It is highly recommended that technical resources assigned to the PingOne Advanced Identity Cloud project have attended relevant courses. The courses can help enable resources prior to the project and on an ongoing basis as new technical resources are onboarded. Working with a trusted partner or SI can also help to reinforce the technical skills required. Ping Identity technical consultants will work alongside your teams and assist with the implementation.

Clear objectives and requirements

The foundation of any successful project lies in clearly defining its objectives and requirements. Start by identifying the pain points within your organisation’s current identity management infrastructure and determine the specific goals you aim to achieve with the PingOne Advanced Identity Cloud. These objectives could include enhancing user experience, strengthening security measures, or streamlining administrative tasks.

When moving your solution from an on-premise or legacy system to PingOne Advanced Identity Cloud, we recommend you “Reimagine” your solution using this opportunity to retire technical debt. What are the outcomes that need to be achieved, how will successful achievement of those outcomes be measured, and how will those outcomes benefit your organisation and its customers? Building this into a well-defined roadmap allows alignment between the project team and stakeholders around a shared vision. It is critical that this vision is defined before the project commences, coupled with a clearly defined MVP and key outcome milestones with measurable success criteria.

If you can’t define success, you can’t succeed.

Comprehensive planning and strategy

Once the project objectives are established, it’s essential to develop a comprehensive plan and strategy. Consider factors such as the scope of the project, the resources required, the timeline, and the potential risks involved. Collaborate closely with key stakeholders, including IT teams, security experts, and business leaders, to ensure that the project aligns with broader organisational goals and addresses specific user needs effectively. A project manager for the organisation sitting as part of the project team, and with clear boundaries and scope, will ensure the project focuses on its MVP while meeting its broader long-term goals.

Robust architecture and design

The architecture and design of your PingOne Advanced Identity Cloud deployment are critical for its success. Work closely with experienced architects and developers to design a scalable, flexible, and secure solution that can accommodate your organisation’s current and future requirements. Consider factors such as user volumes, integration capabilities, compliance regulations, and the need for customisation. A well-thought-out architecture will help optimise performance, minimise downtime, and support future expansion. Ping Identity technical consultants will work with the organisation to ensure the solution architecture developed is sufficient for your needs and meets best practices, and can then be incorporated into the organisation’s overall design.

Seamless integration and data migration

A successful implementation of PingOne Advanced Identity Cloud relies on seamless integration with your existing systems. Ensure that your project team has a deep understanding of your organisation’s technology landscape to establish smooth integration points. A careful approach to data migration is also vital to ensure a seamless transition from legacy systems to the new solution. Data cleansing, mapping, and validation processes should be executed meticulously to maintain data integrity and prevent any disruptions to user access or experience. Many organisations’ legacy systems retain inaccurate or even corrupt data; it’s critical that the migration to a cutting-edge platform like PingOne Advanced Identity Cloud is viewed as an opportunity to remove this technical debt. Ping Identity technical consultants can help the organisation understand what is necessary to meet requirements.

Thorough testing and quality assurance

Testing and quality assurance are crucial stages of any project implementation. Conduct comprehensive testing to validate the functionality, security, and performance of your PingOne Advanced Identity Cloud deployment. Test different scenarios, such as user registration, authentication, authorisation, and password management, to ensure a seamless end-user experience. Invest in automated testing tools and techniques to increase efficiency and accuracy while minimising the risk of human error. Work with your Ping Identity customer deployment manager and Ping Identity technical consultants on planning your testing to ensure your solution is ready for your customers.

User adoption and change management

Successful implementation of PingOne Advanced Identity Cloud is not just about the technical aspects; it also requires a focus on user adoption and change management. Plan and execute a robust change management strategy that includes clear communication, training programs, and ongoing support to ensure a smooth transition for end users. Address any concerns or resistance to change by highlighting the benefits of the new system and demonstrating its usability. This is particularly important as the move to PingOne Advanced Identity Cloud offers:

Modern standards-based integration patterns
Opportunities to provide dynamic yet secure authentication options
The ability to remove antiquated legacy functionality as you move into the future

Continuous monitoring and optimization

Once your PingOne Advanced Identity Cloud project is live, it’s crucial to have a process for continuous monitoring and optimization.

Implement proactive monitoring tools to identify and address potential service disruptions and maximise customer satisfaction. For example, monitoring authentication may not provide a complete picture of the entire user experience. It may be important to include self-service flows, authentication, authorization, token generation, and other critical operations. Monitoring the correct critical aspects of your solution will enable the business to proactively react.

Regularly review and optimize the solution based on user feedback, evolving business requirements, and industry best practices. Stay up to date with Ping Identity’s releases and updates to leverage new features and enhancements that can further improve your IAM processes. Ping Identity Support can be contacted around the clock to provide product support, and Ping Identity technical consultants or one of Ping Identity’s experienced partners can be engaged to assist with the solution.

Conclusion

A successful PingOne Advanced Identity Cloud project requires a combination of careful planning, robust architecture, seamless integration, thorough testing, user-centric change management, and ongoing monitoring and optimization. A clear understanding of the roles and responsibilities of the platform and solution will help with resource allocation and expedite issue resolution.

By investing time and effort into each of these key ingredients, organizations can unlock the full potential of Ping Identity’s powerful IAM solution, delivering enhanced security, improved user experience, and streamlined identity management processes.

Do you have thoughts or questions on this article? Join the discussion on the Ping Identity developer community.