Ping Identity Developer Portal Blog

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!

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.

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.

Ping Identity Developer Portal Blog

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

Where we’ve come from

What it is used for

Developers in the terminal

Deterministic automation and CI/CD

Headless, AI-first use cases

What you can do today

Interactive guided setup

Authenticate across multiple services

Manage configuration across products and services

Profiles for every environment

Make raw API calls when you need them

Output built for scripting

Quality-of-life extras

Getting started

What’s next

Can we improve? Your feedback matters

And finally

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

Background: How PingOne administration worked before group level assignment

The customer problem: shared identity, many brands

How group-level roles behave

Tackling user creation

Some example scenarios

1. Brand help desks

2. Specialized admin teams

Designing your model with group-level assignments

Securing ChatGPT apps with OAuth 2.0 and CIBA

Context

MyHotels demo

End user experience

How ChatGPT apps work

The Identity Provider

PingOne Authorize

Token exchange

CIBA

The user journeys in detail

1. Public hotel search

2. Member-rate search

3. Booking with approval

Conclusion

Links

Help us shape the future of Ping Identity's documentation

Take the survey

Docs for Agents: making Ping Identity documentation work with AI

The problem: great docs, invisible to agents

What we built

Markdown alternates for every page

llms.txt indexes

JSON-LD structured data

A “Docs for Agents” landing page

Accept: text/markdown content negotiation

Try it out

What’s next

Resources

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

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

Why this pattern is worth the extra work

Step 1: Securely obtaining a DaVinci SDK token

Step 2: Invoking the login flow with the widget

Step 3: Generating tokens without returning them to the browser

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

Step 5: Finalizing the BFF application session

Step 6: Hardening the browser-facing routes

Putting it all together

A few practical caveats

Over to you

Understanding the Org Model

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

Footnotes

PingOne DaVinci Primer: Creating Dynamic Experiences with PingOne Populations

`Accept: text/markdown` content negotiation