From 5cf8b82d3a26718566b6d0a26686bcb4003aa02b Mon Sep 17 00:00:00 2001 From: Brando Dill Date: Thu, 14 May 2026 11:44:22 -0400 Subject: [PATCH 01/27] Initial commit --- LICENSE | 21 +++++++++++++++++++++ README.md | 2 ++ 2 files changed, 23 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..269570a --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Brando Dill + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..219555d --- /dev/null +++ b/README.md @@ -0,0 +1,2 @@ +# agent-skills +Public facing repo that exposes all of Ping's Agent Skills through a unified, consistent layer From 71c746e6f3d50d700de5813fbbe11ae515a004d4 Mon Sep 17 00:00:00 2001 From: "brando.dill" Date: Tue, 19 May 2026 13:22:56 -0400 Subject: [PATCH 02/27] Initial Structure --- .claude-plugin/marketplace.json | 22 + .claude/settings.local.json | 12 + plugins/ping-identity/README.md | 57 +++ plugins/ping-identity/platform-scope.md | 49 +++ plugins/ping-identity/plugin-map.md | 40 ++ plugins/ping-identity/references/index.json | 69 ++++ plugins/ping-identity/routing-hints.md | 42 ++ .../skills/ping-foundation/SKILL.md | 177 +++++++++ .../ping-foundation/ping-marketplace.json | 37 ++ .../cross-platform/core-admin-patterns.md | 98 +++++ .../cross-platform/foundation-overview.md | 62 +++ .../policy-and-branding-basics.md | 84 ++++ .../tenant-and-environment-setup.md | 79 ++++ .../curated/pingone-st/app-setup.md | 129 ++++++ .../pingone-st/authentication-fundamentals.md | 117 ++++++ .../curated/pingone-st/directory-setup.md | 159 ++++++++ .../curated/pingone-st/foundation-overview.md | 115 ++++++ .../pingone-st/themes-and-customization.md | 126 ++++++ .../generated/cross-platform/top-10.json | 8 + .../generated/ping-software/pingaccess.md | 30 ++ .../generated/ping-software/pingam.md | 30 ++ .../generated/ping-software/pingdirectory.md | 31 ++ .../generated/ping-software/pingfederate.md | 31 ++ .../generated/ping-software/pingid.md | 29 ++ .../generated/ping-software/top-25.json | 8 + .../references/generated/pingone-mt/apps.md | 28 ++ .../generated/pingone-mt/directories.md | 28 ++ .../generated/pingone-mt/policies.md | 28 ++ .../generated/pingone-mt/tenants.md | 28 ++ .../generated/pingone-mt/top-25.json | 8 + .../generated/pingone-st/administration.md | 28 ++ .../generated/pingone-st/customization.md | 27 ++ .../generated/pingone-st/identity-data.md | 28 ++ .../generated/pingone-st/reports.md | 27 ++ .../generated/pingone-st/self-service.md | 28 ++ .../generated/pingone-st/top-25.json | 8 + .../skills/ping-orchestration/SKILL.md | 159 ++++++++ .../ping-orchestration/ping-marketplace.json | 34 ++ .../pingone-mt/davinci-flow-patterns.md | 40 ++ .../curated/pingone-mt/davinci-overview.md | 40 ++ .../pingone-st/journey-design-patterns.md | 299 ++++++++++++++ .../account-recovery-and-username-reminder.md | 138 +++++++ .../financial-services-step-up.md | 194 +++++++++ .../mfa-authentication-multi-method.md | 199 ++++++++++ .../password-reset-and-update.md | 131 ++++++ .../passwordless-mfa-registration.md | 209 ++++++++++ .../pingone-protect-risk-integration.md | 197 +++++++++ .../progressive-profiling.md | 156 ++++++++ ...l-and-local-registration-authentication.md | 182 +++++++++ .../pingone-st/nodes/basic-auth-nodes.md | 204 ++++++++++ .../nodes/federation-contextual-nodes.md | 257 ++++++++++++ .../nodes/identity-management-nodes.md | 375 ++++++++++++++++++ .../curated/pingone-st/nodes/mfa-nodes.md | 319 +++++++++++++++ .../pingone-st/nodes/node-fundamentals.md | 103 +++++ .../pingone-st/nodes/risk-management-nodes.md | 237 +++++++++++ .../curated/pingone-st/nodes/utility-nodes.md | 355 +++++++++++++++++ .../generated/cross-platform/top-10.json | 8 + .../generated/ping-software/top-25.json | 8 + .../generated/pingone-mt/top-25.json | 8 + .../generated/pingone-st/top-25.json | 8 + .../skills/ping-quickstart/SKILL.md | 105 +++++ .../ping-quickstart/ping-marketplace.json | 29 ++ .../choose-the-right-ping-platform.md | 60 +++ .../references/common-starting-patterns.md | 63 +++ .../references/getting-started-overview.md | 63 +++ shared/evals/routing-eval.md | 235 +++++++++++ shared/generated/docs-by-platform.json | 8 + shared/generated/global-doc-catalog.json | 7 + shared/schemas/doc-frontmatter-schema.json | 73 ++++ shared/schemas/reference-manifest-schema.json | 51 +++ shared/taxonomies/capability-map.md | 25 ++ shared/taxonomies/platform-families.md | 47 +++ shared/taxonomies/routing-rules.md | 39 ++ shared/taxonomies/service-map.md | 34 ++ shared/templates/AUTHORING-RULES.md | 285 +++++++++++++ shared/templates/SKILL.reference-authoring.md | 193 +++++++++ shared/templates/SKILL.template.md | 95 +++++ .../templates/curated-reference.template.md | 48 +++ .../templates/ping-marketplace.template.json | 25 ++ 79 files changed, 7252 insertions(+) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .claude/settings.local.json create mode 100644 plugins/ping-identity/README.md create mode 100644 plugins/ping-identity/platform-scope.md create mode 100644 plugins/ping-identity/plugin-map.md create mode 100644 plugins/ping-identity/references/index.json create mode 100644 plugins/ping-identity/routing-hints.md create mode 100644 plugins/ping-identity/skills/ping-foundation/SKILL.md create mode 100644 plugins/ping-identity/skills/ping-foundation/ping-marketplace.json create mode 100644 plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/core-admin-patterns.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/foundation-overview.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/policy-and-branding-basics.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/tenant-and-environment-setup.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/app-setup.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/authentication-fundamentals.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/directory-setup.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/foundation-overview.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/themes-and-customization.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/cross-platform/top-10.json create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingaccess.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingam.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingdirectory.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingfederate.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingid.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/top-25.json create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/apps.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/directories.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/policies.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/tenants.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/top-25.json create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/administration.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/customization.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/identity-data.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/reports.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/self-service.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/top-25.json create mode 100644 plugins/ping-identity/skills/ping-orchestration/SKILL.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/ping-marketplace.json create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-mt/davinci-flow-patterns.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-mt/davinci-overview.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-design-patterns.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/account-recovery-and-username-reminder.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/financial-services-step-up.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/mfa-authentication-multi-method.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/password-reset-and-update.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/passwordless-mfa-registration.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/pingone-protect-risk-integration.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/progressive-profiling.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/social-and-local-registration-authentication.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/basic-auth-nodes.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/federation-contextual-nodes.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/identity-management-nodes.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/mfa-nodes.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/node-fundamentals.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/risk-management-nodes.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/utility-nodes.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/generated/cross-platform/top-10.json create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/generated/ping-software/top-25.json create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/generated/pingone-mt/top-25.json create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/generated/pingone-st/top-25.json create mode 100644 plugins/ping-identity/skills/ping-quickstart/SKILL.md create mode 100644 plugins/ping-identity/skills/ping-quickstart/ping-marketplace.json create mode 100644 plugins/ping-identity/skills/ping-quickstart/references/choose-the-right-ping-platform.md create mode 100644 plugins/ping-identity/skills/ping-quickstart/references/common-starting-patterns.md create mode 100644 plugins/ping-identity/skills/ping-quickstart/references/getting-started-overview.md create mode 100644 shared/evals/routing-eval.md create mode 100644 shared/generated/docs-by-platform.json create mode 100644 shared/generated/global-doc-catalog.json create mode 100644 shared/schemas/doc-frontmatter-schema.json create mode 100644 shared/schemas/reference-manifest-schema.json create mode 100644 shared/taxonomies/capability-map.md create mode 100644 shared/taxonomies/platform-families.md create mode 100644 shared/taxonomies/routing-rules.md create mode 100644 shared/taxonomies/service-map.md create mode 100644 shared/templates/AUTHORING-RULES.md create mode 100644 shared/templates/SKILL.reference-authoring.md create mode 100644 shared/templates/SKILL.template.md create mode 100644 shared/templates/curated-reference.template.md create mode 100644 shared/templates/ping-marketplace.template.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..f8ea494 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,22 @@ +{ + "name": "ping-identity-skills", + "owner": { + "name": "Ping Identity", + "email": "developer-experience@pingidentity.com" + }, + "description": "Agent skills for configuring, orchestrating, and integrating Ping Identity platforms — PingOne MT, PingOne Advanced Identity Cloud (ST), and on-premises Ping software.", + "plugins": [ + { + "name": "ping-identity", + "source": "./plugins/ping-identity", + "displayName": "Ping Identity", + "description": "Full skill suite for Ping Identity platforms. Covers platform setup, authentication journey design, universal services, app integration, and identity for AI workloads.", + "version": "1.0.0", + "author": { + "name": "Ping Identity" + }, + "category": "identity", + "keywords": ["ping", "pingone", "aic", "pingfederate", "identity", "authentication", "journeys", "davinci"] + } + ] +} diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..83856a6 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,12 @@ +{ + "permissions": { + "allow": [ + "mcp__plugin_polaris_glean__read_document", + "Bash(xargs sed *)", + "WebFetch(domain:docs.pingidentity.com)", + "mcp__plugin_polaris_glean__search", + "WebFetch(domain:docs.pingoneaic)", + "Bash(python3 *)" + ] + } +} diff --git a/plugins/ping-identity/README.md b/plugins/ping-identity/README.md new file mode 100644 index 0000000..f6f7771 --- /dev/null +++ b/plugins/ping-identity/README.md @@ -0,0 +1,57 @@ +# Ping Identity Plugin + +Agent skills for configuring, integrating, and operating Ping Identity platforms. + +## What this plugin is for + +- Orienting agents on which Ping platform applies to a given task +- Configuring and administering PingOne MT (multi-tenant cloud), PingOne ST (single-tenant), and on-premises Ping software +- Designing orchestration flows (DaVinci, PingOne ST journeys, PingAM trees) +- Integrating Ping into web, mobile, and SDK-based applications +- Using Ping Universal Services (Protect, Verify, IGA, Credentials, Authorize) +- Understanding Ping's Identity for AI and Verified Trust capabilities + +## Skill role: context, not execution + +MCP tools handle execution — they can create, update, and delete platform resources directly. These skills supply what the tools lack: platform architecture, correct configuration sequencing, key constraints, gotchas, and decision logic. Use skills to reason correctly about *what* to configure and *why*, then let MCP tools carry out the work. + +## MCP tool-first execution + +**If MCP tools are available for the target platform, always use them — do not instruct the user to make changes manually.** + +Before responding to any configuration or administration request, scan your available tool list for tools that can perform the required operation against the target platform (PingOne ST, PingOne MT, etc.). If matching tools exist, use them to make the change directly. + +**Execution order:** +1. Check available tools for operations matching the task (create, update, delete, list, get for the relevant resource type) +2. If found: use the tool, report what was done, show relevant IDs or output +3. If not found or the tool call fails: fall back to step-by-step console instructions + +**Never ask the user to click through the admin console for an operation an MCP tool can perform.** A direct tool call is always preferred over written instructions. + +## What this plugin is NOT for + +- Generic identity concepts not specific to Ping products +- Non-Ping identity platforms (Okta, Auth0, Microsoft Entra, etc.) +- Application business logic unrelated to identity +- Infrastructure provisioning beyond what is required to deploy Ping software + +## Standalone operation + +This plugin is self-orienting. When installed without the full `agent-skills` repo, it carries its own: + +- Platform and product scope (`platform-scope.md`) +- Skill map and routing (`plugin-map.md`, `routing-hints.md`) +- Reference index (`references/index.json`) + +Load order for a plugin-only install: +1. `README.md` → orientation +2. `plugin-map.md` → skill selection +3. `platform-scope.md` → platform detection +4. `routing-hints.md` → routing fallback (replaces `/shared/taxonomies/routing-rules.md`) +5. Selected `skills//SKILL.md` +6. `ping-quickstart`: load from `skills/ping-quickstart/references/` (flat — 1–2 files max) +7. Other skills: `skills//references/curated/` → 1–3 curated anchors, then `references/generated//` if needed + +## Full repo + +When the full `agent-skills` repo is present, defer to `/shared/taxonomies/` for canonical routing rules and platform definitions. The files in this plugin are a compact local subset — the full repo is authoritative. diff --git a/plugins/ping-identity/platform-scope.md b/plugins/ping-identity/platform-scope.md new file mode 100644 index 0000000..091e0c8 --- /dev/null +++ b/plugins/ping-identity/platform-scope.md @@ -0,0 +1,49 @@ +# Platform Scope — Ping Identity Plugin + +Defines which platforms, products, and services are in scope. Use for platform detection when `/shared/taxonomies/platform-families.md` is not available. + +## Platform Families + +| Tag | Platform | Description | +|---|---|---| +| `pingone-mt` | PingOne (multi-tenant cloud) | SaaS-hosted administration: environments, apps, directories, policies. Admin at apps.pingone.com. | +| `pingone-st` | PingOne ST (single-tenant) | Fully managed, highly customizable. Built on PingAM/PingIDM/PingDS. Distinct control plane from PingOne. | +| `ping-software` | Ping Software Suite (on-premises) | Customer-deployed server software. Different topology, ops model, and config surface from cloud families. Includes PingAM, PingIDM, PingDS, PingGateway, PingFederate, etc. | +| `cross-platform` | Shared / Universal Services | Capabilities consumed across multiple platform families (Protect, Verify, IGA, etc.). | + +## Platform Detection Signals + +**`pingone-mt`** +- "Multi-Tenant" +- "PingOne", "apps.pingone.com", "PingOne environment", "PingOne admin console" +- PingOne MFA, PingOne Risk, PingOne DaVinci, PingOne Verify, PingOne Protect, PingOne IGA, PingOne Credentials, PingOne Neo, PingOne Authorize, PingOne SSO + +**`pingone-st`** +- "Single-Tenant" +- "PingOne ST", "AIC" (legacy abbreviation), "identity cloud tenant", "PingAM", "PingIDM", "PingDS" +- "ForgeRock", "AM", "IDM", "DS" (in a PingOne ST Cloud context), PingOne ST tenant URL +- Journeys, auth trees, realms + +**`ping-software`** +- "On-prem", "Software", "Download", "Binary", ".jar", "PingFederate", "PingAccess", "PingDirectory", "PingDataSync", "PingID on-prem", "PingAM standalone", "on-prem", "self-managed", "server profile" + +**`cross-platform`** +- Service invoked from both PingOne MT and PingOne ST contexts +- Universal Services layer questions (not product-specific setup) + +## Products in Scope + +### PingOne (multi-tenant) +PingOne, PingOne MFA, PingOne Risk, PingOne DaVinci, PingOne Verify, PingOne Protect, PingOne IGA, PingOne Credentials, PingOne Neo, PingOne Authorize, PingOne SSO, PingOne Notifications + +### PingOne ST +PingOne ST, PingAM (within PingOne ST), PingIDM (within PingOne ST), PingDS (within PingOne ST) + +### Ping Software Suite +PingFederate, PingAccess, PingDirectory, PingDataSync, PingID (on-prem), PingAM (standalone), PingIDM (standalone), PingDS (standalone), PingAuthoriz, PingGateway + +## Services Out of Scope for This Plugin + +- Non-Ping identity providers +- Generic OIDC/SAML implementations not using a Ping product +- Cloud infrastructure (AWS, GCP, Azure) beyond what Ping software runs on diff --git a/plugins/ping-identity/plugin-map.md b/plugins/ping-identity/plugin-map.md new file mode 100644 index 0000000..60cecf3 --- /dev/null +++ b/plugins/ping-identity/plugin-map.md @@ -0,0 +1,40 @@ +# Plugin Map — Ping Identity + +Index of included skills, their purpose, and when to use each. Use this file to select the correct skill before loading any SKILL.md. + +## Skills + +### ping-quickstart +**Path:** `skills/ping-quickstart/` +**Use when:** The user does not know which Ping platform or product applies, or explicitly asks "where do I start?" +**Not for:** Any task where the platform is already known — go directly to the right skill. + +### ping-foundation +**Path:** `skills/ping-foundation/` +**Use when:** The task is setup, configuration, or administration of a platform — tenant/environment creation, app registration, directory setup, authentication policy, branding. +**Not for:** Designing flows or journeys (→ ping-orchestration); invoking shared services (→ ping-universal-services); app/SDK code integration (→ ping-app-integration). + +### ping-orchestration *(planned)* +**Path:** `skills/ping-orchestration/` +**Use when:** The task is designing or troubleshooting a DaVinci flow, PingOne ST journey, or PingAM authentication tree. + +### ping-universal-services *(planned)* +**Path:** `skills/ping-universal-services/` +**Use when:** The task involves invoking a Ping Universal Service: Protect, Verify, Credentials, IGA, Neo, or Authorize — across PingOne MT or PingOne ST. + +### ping-app-integration *(planned)* +**Path:** `skills/ping-app-integration/` +**Use when:** The task is integrating Ping into an application — Android SDK, iOS SDK, React SDK, DaVinci SDK, browser flows, or on-prem app-side configuration. + +### ping-identity-for-ai *(planned)* +**Path:** `skills/ping-identity-for-ai/` +**Use when:** The task involves securing AI agents, Verified Trust, or identity patterns for AI-driven applications. + +## Selection rule + +1. Unknown platform or starting point → `ping-quickstart` +2. Setup / config / admin → `ping-foundation` +3. Flow / journey / orchestration design → `ping-orchestration` +4. Shared service invocation → `ping-universal-services` +5. App / SDK integration code → `ping-app-integration` +6. AI agent or trusted identity patterns → `ping-identity-for-ai` diff --git a/plugins/ping-identity/references/index.json b/plugins/ping-identity/references/index.json new file mode 100644 index 0000000..ba6fec4 --- /dev/null +++ b/plugins/ping-identity/references/index.json @@ -0,0 +1,69 @@ +{ + "plugin": "ping-identity", + "description": "Local reference index for plugin-only installs. Lists all curated anchors and generated shortlists by skill and platform branch.", + "last_updated": null, + "skills": { + "ping-quickstart": { + "references": [ + "skills/ping-quickstart/references/getting-started-overview.md", + "skills/ping-quickstart/references/choose-the-right-ping-platform.md", + "skills/ping-quickstart/references/common-starting-patterns.md" + ] + }, + "ping-foundation": { + "curated": [ + "skills/ping-foundation/references/curated/cross-platform/foundation-overview.md", + "skills/ping-foundation/references/curated/cross-platform/tenant-and-environment-setup.md", + "skills/ping-foundation/references/curated/cross-platform/policy-and-branding-basics.md", + "skills/ping-foundation/references/curated/cross-platform/core-admin-patterns.md", + "skills/ping-foundation/references/curated/pingone-st/foundation-overview.md", + "skills/ping-foundation/references/curated/pingone-st/app-setup.md", + "skills/ping-foundation/references/curated/pingone-st/authentication-fundamentals.md", + "skills/ping-foundation/references/curated/pingone-st/themes-and-customization.md", + "skills/ping-foundation/references/curated/pingone-st/directory-setup.md" + ], + "generated": { + "pingone-mt": "skills/ping-foundation/references/generated/pingone-mt/top-25.json", + "pingone-st": "skills/ping-foundation/references/generated/pingone-st/top-25.json", + "ping-software": "skills/ping-foundation/references/generated/ping-software/top-25.json", + "cross-platform": "skills/ping-foundation/references/generated/cross-platform/top-10.json" + } + }, + "ping-orchestration": { + "curated": [ + "skills/ping-orchestration/references/curated/pingone-st/journey-design-patterns.md", + "skills/ping-orchestration/references/curated/pingone-st/nodes/basic-auth-nodes.md", + "skills/ping-orchestration/references/curated/pingone-st/nodes/mfa-nodes.md", + "skills/ping-orchestration/references/curated/pingone-st/nodes/risk-management-nodes.md", + "skills/ping-orchestration/references/curated/pingone-st/nodes/identity-management-nodes.md", + "skills/ping-orchestration/references/curated/pingone-st/nodes/utility-nodes.md", + "skills/ping-orchestration/references/curated/pingone-st/nodes/federation-contextual-nodes.md", + "skills/ping-orchestration/references/curated/pingone-st/scripted-decision-nodes.md", + "skills/ping-orchestration/references/curated/pingone-st/inner-journeys.md", + "skills/ping-orchestration/references/curated/pingone-mt/davinci-overview.md", + "skills/ping-orchestration/references/curated/pingone-mt/davinci-flow-patterns.md" + ], + "generated": { + "pingone-mt": "skills/ping-orchestration/references/generated/pingone-mt/top-25.json", + "pingone-st": "skills/ping-orchestration/references/generated/pingone-st/top-25.json", + "ping-software": "skills/ping-orchestration/references/generated/ping-software/top-25.json", + "cross-platform": "skills/ping-orchestration/references/generated/cross-platform/top-10.json" + } + }, + "ping-universal-services": { + "note": "Planned. Not yet built.", + "curated": [], + "generated": {} + }, + "ping-app-integration": { + "note": "Planned. Not yet built.", + "curated": [], + "generated": {} + }, + "ping-identity-for-ai": { + "note": "Planned. Not yet built.", + "curated": [], + "generated": {} + } + } +} diff --git a/plugins/ping-identity/routing-hints.md b/plugins/ping-identity/routing-hints.md new file mode 100644 index 0000000..708bdfe --- /dev/null +++ b/plugins/ping-identity/routing-hints.md @@ -0,0 +1,42 @@ +# Routing Hints — Ping Identity Plugin + +Lightweight routing rules for plugin-only installs. Replaces `/shared/taxonomies/routing-rules.md` when the full repo is absent. + +## Step 1 — Select the skill + +| User intent | Skill | +|---|---| +| "Where do I start?", "Which product?", "Help me choose" | `ping-quickstart` | +| "Set up", "configure", "admin", "create environment/tenant", "add app", "manage directory", "install" | `ping-foundation` | +| "Build a flow", "DaVinci", "journey", "auth tree", "orchestrate" | `ping-orchestration` | +| "AI agent identity", "Verified Trust", "identity for AI" | `ping-identity-for-ai` | +| "Use Protect", "Verify", "IGA", "Credentials", "Authorize", "Neo" | `ping-universal-services` | +| "Integrate my app", "SDK", "mobile", "React", "iOS", "Android", "web login" | `ping-app-integration` | + +## Step 2 — Detect the platform + +| Signal | Platform tag | +|---|---| +| "PingOne", "apps.pingone.com", PingOne admin console | `pingone-mt` | +| "AIC", "PingOne ST", "PingAM", "IDM", "ForgeRock", "Identity Management", "IGA" | `pingone-st` | +| "PingFederate", "PingAccess", "PingDirectory", "PingAM", "PingIDM", "PingDirectory", "PingAuthorize", "PingDS", PingGateway", "software", "on-prem", "self-managed" | `ping-software` | +| Service question spanning PingOne MT and PingOne ST | `cross-platform` | +| Unknown | Ask: "Are you in PingOne, PingOne ST, or on-premises software?" | + +## Step 3 — Select reference tier (stop at first sufficient tier) + +1. `skills//references/curated/` — load 1–3 anchor docs +2. `skills//references/generated//` — scan shortlist for matching titles + +## Cross-skill escalation + +| Task spans... | Also reference | +|---|---| +| Flow or journey design | `ping-orchestration` SKILL.md | +| Shared service (Protect, Verify, IGA) | `ping-universal-services` SKILL.md | +| App/SDK code | `ping-app-integration` SKILL.md | +| Platform orientation | `ping-quickstart` SKILL.md | + +## Principle + +Use the smallest context first. Only widen retrieval when the current tier cannot complete the task. diff --git a/plugins/ping-identity/skills/ping-foundation/SKILL.md b/plugins/ping-identity/skills/ping-foundation/SKILL.md new file mode 100644 index 0000000..fd1c689 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/SKILL.md @@ -0,0 +1,177 @@ +--- +name: ping-foundation +description: Platform setup, administration, and core configuration for PingOne MT, PingOne ST (AIC), and on-premises Ping software. Use for ANY question about setting up environments, registering OIDC/SAML apps, managing directories and user populations, configuring authentication policies, branding, or administering PingFederate/PingAccess/PingDirectory/PingID — including advisory, planning, and "how should I..." questions, not just execution tasks. Also invoke with /ping-foundation. +compatibility: Designed for Ping Identity platform tasks. MCP tools for PingOne MT or PingOne ST are used when available; console instructions provided as fallback. +metadata: + publisher: Ping Identity + version: "1.0" +--- + +# ping-foundation + +Platform setup, administration, and core configuration for all Ping Identity deployments. Covers tenant and environment setup, apps, directories, policies, branding, and on-premises software administration. + +> **Role of this skill:** MCP tools handle execution — they can create, update, and delete platform resources directly. This skill supplies the context those tools lack: architecture patterns, correct sequencing, configuration constraints, platform concepts, and guardrails. Use it to reason correctly about *what* to do and *why* before (or alongside) using MCP tools to do it. + +## Invocation + +Invoke this skill explicitly with `/ping-foundation` or by saying "use ping-foundation to...". + +## When to use this skill + +Trigger on ANY of the following — including questions, planning, and advisory requests, not just implementation tasks: + +- "Set up a PingOne environment" +- "Configure an application in PingOne MT or PingOne ST" +- "Manage directories, identity stores, or user populations" +- "Configure authentication policies or sign-on policies" +- "Set up branding, custom domains, or notification templates" +- "Administer PingFederate, PingAccess, PingDirectory, or PingID" +- "Deploy or upgrade on-premises Ping software" +- "Register an OIDC or SAML app in AIC / PingOne ST" +- "What do I need to configure to get [app type] working?" +- "How should I set up my tenant / realm / environment?" +- "What's the right way to structure my directory / populations?" +- "Should I use a confidential or public client for my app?" +- "Advise me on how to configure [platform feature]" +- "What are the pros and cons of [platform configuration option]?" +- "Help me plan my PingOne ST / PingOne MT setup before I build" +- "I'm not sure how to approach [admin or configuration task] in Ping" + +**Catch-all:** Trigger this skill whenever the user asks ANY question about setting up, configuring, administering, or planning a Ping Identity platform — even if phrased as a question, a planning discussion, or an advisory request rather than a direct "do this" instruction. + +## When NOT to use this skill + +- If the primary task is **designing a DaVinci flow or PingOne ST journey**: use `ping-orchestration` +- If the task is **invoking a Universal Service** (Protect, Verify, IGA, Credentials): use `ping-universal-services` +- If the task is **integrating Ping into an app or SDK**: use `ping-app-integration` +- If unsure which platform: use `ping-quickstart` first + +## Multi-skill use cases + +Foundation is almost always the starting point, but rarely the only skill needed. Ping Identity platforms require significant configuration across multiple layers to reach a complete, production-ready solution — expect to compose several skills together. + +`ping-foundation` is responsible for the platform layer. Other skills pick up where it leaves off: + +| What comes next | Skill | +|---|---| +| Authentication flow or journey logic on top of the configured platform | `ping-orchestration` | +| Adding risk, MFA step-up, identity verification, or governance | `ping-universal-services` | +| Wiring the configured platform into an app, SDK, or mobile client | `ping-app-integration` | +| Securing AI agents or building trusted identity for AI workloads | `ping-identity-for-ai` | + +**Example — Workforce SSO with MFA and PingFederate:** +1. `ping-foundation` — install PingFederate, configure the SP connection, connect PingDirectory +2. `ping-foundation` — configure the authentication policy / adapter chain +3. `ping-universal-services` — add PingID MFA step-up via the PingOne MFA adapter +4. `ping-app-integration` — configure the application to use the PingFederate OIDC or SAML endpoint + +**Example — CIAM registration on PingOne ST:** +1. `ping-foundation` — provision the PingOne ST tenant, configure the realm and identity store +2. `ping-orchestration` — design the registration journey with email verification +3. `ping-universal-services` — add PingOne Verify for identity proofing within the journey +4. `ping-app-integration` — integrate the PingOne ST-hosted login page into the web or mobile app + +Do not attempt to drive all of this from `ping-foundation` alone. Complete the platform setup here, then hand off to the appropriate skill for each subsequent layer. + +--- + +## Routing — Step 1: Which platform? + +| Platform signal | Branch | +|---|---| +| PingOne admin console, PingOne APIs, PingOne environment | [PingOne MT](#pingone-mt) | +| PingOne ST tenant admin, identity cloud, PingAM, PingIDM, PingDS | [PingOne ST](#pingone-st) | +| PingFederate, PingAccess, PingDirectory, PingID, PingAM standalone | [Ping Software Suite](#ping-software-suite) | + +--- + +## PingOne MT + +**Sub-routing by task:** + +| Task | Reference | +|---|---| +| Create or manage environments/tenants | `references/generated/pingone-mt/tenants.md` | +| Add or configure applications (OIDC, SAML) | `references/generated/pingone-mt/apps.md` | +| Configure sign-on policies, MFA policies | `references/generated/pingone-mt/policies.md` | +| Manage directories, populations, user attributes | `references/generated/pingone-mt/directories.md` | + +**Curated anchors** (load first — 1 to 3 max): +- `references/curated/cross-platform/foundation-overview.md` +- `references/curated/cross-platform/tenant-and-environment-setup.md` +- `references/curated/cross-platform/policy-and-branding-basics.md` + +**Generated shortlist** (fallback): +- `references/generated/pingone-mt/top-25.json` + +--- + +## PingOne ST + +**Sub-routing by task:** + +| Task | Reference | +|---|---| +| Platform orientation, tenant/realm architecture | `references/curated/pingone-st/foundation-overview.md` | +| Register OIDC, OAuth 2.0, or SAML applications | `references/curated/pingone-st/app-setup.md` | +| Understand journeys, nodes, realm auth settings | `references/curated/pingone-st/authentication-fundamentals.md` | +| Themes, branding, custom CSS, hosted pages | `references/curated/pingone-st/themes-and-customization.md` | +| Identity store, user schema, LDAP/AD, provisioning | `references/curated/pingone-st/directory-setup.md` | +| Reporting, auditing, logs | `references/generated/pingone-st/reports.md` | +| Self-service portal, end-user flows | `references/generated/pingone-st/self-service.md` | + +**Curated anchors** (load first — 1 to 3 max, pick the ones matching the task): +- `references/curated/pingone-st/foundation-overview.md` +- `references/curated/pingone-st/app-setup.md` +- `references/curated/pingone-st/authentication-fundamentals.md` +- `references/curated/pingone-st/themes-and-customization.md` +- `references/curated/pingone-st/directory-setup.md` + +**Generated shortlist** (fallback for topics not yet covered by curated files): +- `references/generated/pingone-st/top-25.json` + +--- + +## Ping Software Suite + +**Sub-routing by product:** + +| Product | Reference | +|---|---| +| PingFederate | `references/generated/ping-software/pingfederate.md` | +| PingAccess | `references/generated/ping-software/pingaccess.md` | +| PingDirectory | `references/generated/ping-software/pingdirectory.md` | +| PingID (on-prem) | `references/generated/ping-software/pingid.md` | +| PingAM (standalone) | `references/generated/ping-software/pingam.md` | + +**Curated anchors** (load first): +- `references/curated/cross-platform/foundation-overview.md` +- `references/curated/cross-platform/core-admin-patterns.md` + +**Generated shortlist** (fallback): +- `references/generated/ping-software/top-25.json` + +--- + +## MCP tool-first execution + +Before writing any instructions, scan your available tool list for MCP tools that can perform the required operation against the target platform (PingOne ST, PingOne MT, etc.). + +**If matching tools are available:** use them to perform the configuration directly. Do not write step-by-step console instructions for operations an MCP tool can execute. Only provide instructions for steps no tool covers (portal-only actions, unsupported operations). + +**If no matching tools are available:** proceed with curated references and console instructions as described below. + +## Retrieval escalation + +1. Load 1–3 curated anchors matching the detected platform and task. Stop if sufficient. +2. If not sufficient, scan the matching generated shortlist. Pull summaries for relevant titles only. + +## Cross-skill escalation + +| If the task also involves... | Reference skill | +|---|---| +| DaVinci flows or PingOne ST journey design | `ping-orchestration` | +| Shared services (Protect, Verify, IGA, Credentials) | `ping-universal-services` | +| App/SDK code integration | `ping-app-integration` | +| Platform selection or orientation | `ping-quickstart` | diff --git a/plugins/ping-identity/skills/ping-foundation/ping-marketplace.json b/plugins/ping-identity/skills/ping-foundation/ping-marketplace.json new file mode 100644 index 0000000..9532b26 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/ping-marketplace.json @@ -0,0 +1,37 @@ +{ + "skill_id": "ping-foundation", + "display_name": "Ping Identity Foundation", + "description": "Platform setup, administration, and core configuration for PingOne, PingOne Advanced Identity Cloud, and on-premises Ping software. Covers environments, applications, directories, policies, and branding.", + "version": "1.0.0", + "publisher": "Ping Identity", + "tags": { + "product_family": ["pingone-mt", "pingone-st", "ping-software"], + "products": [ + "pingone", + "pingone-st", + "pingfederate", + "pingaccess", + "pingdirectory", + "pingid", + "pingam" + ], + "capabilities": ["foundation"], + "audience": ["admin", "architect", "operator"], + "use_cases": ["workforce", "customer", "cross-platform"], + "protocols": ["oidc", "saml", "oauth2", "ldap", "scim"] + }, + "entry_point": "SKILL.md", + "references": { + "curated_path": "references/curated/", + "generated_path": "references/generated/" + }, + "related_skills": [ + "ping-quickstart", + "ping-orchestration", + "ping-universal-services", + "ping-app-integration" + ], + "min_context_tokens": 500, + "max_curated_docs": 3, + "max_shortlist_docs": 25 +} diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/core-admin-patterns.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/core-admin-patterns.md new file mode 100644 index 0000000..95c31c4 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/core-admin-patterns.md @@ -0,0 +1,98 @@ +--- +title: "Core Admin Patterns" +product_family: cross-platform +products: ["pingone", "pingone-st", "pingfederate", "pingaccess", "pingdirectory", "pingid"] +capabilities: ["foundation"] +audience: ["admin", "operator"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "" +slug: "" +--- + +# Core Admin Patterns + +Recurring administration patterns across PingOne MT, PingOne ST, and Ping Software Suite. + +## Scope + +Covers: common admin patterns that apply broadly across platforms. +Does NOT cover: deep per-product reference — see generated shortlists for product-specific detail. + +--- + +## Pattern: Connecting an external directory (LDAP/AD) + +**Required fields across all platforms:** + +| Field | Notes | +|---|---| +| LDAP server URL | Use `ldaps://` (TLS); plain LDAP only acceptable in isolated dev environments | +| Bind DN / principal | Service account with read access; write access required if provisioning back | +| Bind password | Store in a secret/ESV, not plaintext config | +| Base DN | Scope the search to the smallest subtree that contains the target users | +| Username attribute | `uid` for LDAP; `sAMAccountName` for AD | +| User search filter | `(uid=*)` for LDAP; `(&(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))` to exclude disabled AD accounts | + +**Admin surfaces:** +- PingOne MT: Connections → External Directories → + Add Directory +- PingOne ST: Realm → Identity Stores → + Add Identity Store (type: LDAP) via AM admin console +- PingFederate: System → Data Stores → + Add Data Store → LDAP + +--- + +## Pattern: Registering an OIDC application + +**Required fields across all platforms:** + +| Field | Notes | +|---|---| +| Client ID | Unique identifier; auto-generated or custom | +| Client Secret | Required for confidential clients (web apps, M2M); omit for public clients (SPA, native) | +| Redirect URIs | Exact match required; add all environments upfront | +| Grant Types | Authorization Code (web apps), Client Credentials (M2M); avoid Implicit in new apps | +| Scopes | Minimum: `openid`; add `profile`, `email` as needed | + +**Client type decision:** confidential (can hold a secret) vs. public (cannot — SPA or native app). Public clients require PKCE. + +**Admin surfaces:** +- PingOne MT: Applications → + Add Application → OIDC Web App +- PingOne ST: Realm → Applications → OAuth 2.0 → + Create Client (AIC console) or AM console → OAuth 2.0 → Clients +- PingFederate: Applications → OAuth → Clients → + Add Client + +--- + +## Pattern: API-driven configuration + +All platforms expose REST APIs for automation: + +| Platform | Base URL pattern | +|---|---| +| PingOne MT | `https://api.pingone.com/v1/environments/{envId}/...` | +| PingOne ST | `https:///am/json/...` or `https:///openidm/...` | +| PingFederate | `https://:9999/pf-admin-api/v1/...` | +| PingAccess | `https://:9000/pa-admin-api/v3/...` | + +**Authentication per platform:** +- PingOne MT: Worker app (client credentials grant) +- PingOne ST: AM OAuth2 client or IDM service account +- PingFederate / PingAccess: HTTP Basic against the admin API (or OAuth2 if configured) + +--- + +## Pattern: Backup and restore + +| Platform | Mechanism | +|---|---| +| PingOne MT | Admin API environment export; or use frodo-lib / frodo-cli for config export | +| PingOne ST | Admin API exports; or environment-level export from AIC admin console | +| PingFederate | Server → Archive Configuration (ZIP); Git-backed server profiles recommended | +| PingAccess | System → Backup → Export Configuration | +| PingDirectory | `backup` and `restore` CLI tools | + +## Related references + +- `foundation-overview.md` +- `tenant-and-environment-setup.md` diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/foundation-overview.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/foundation-overview.md new file mode 100644 index 0000000..cf87a7f --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/foundation-overview.md @@ -0,0 +1,62 @@ +--- +title: "Ping Foundation Overview" +product_family: cross-platform +products: ["pingone", "pingone-st", "pingfederate", "pingaccess", "pingdirectory"] +capabilities: ["foundation"] +audience: ["admin", "architect"] +use_cases: ["workforce", "customer"] +doc_type: concept +status: current +canonical: true +last_updated: "" +slug: "" +--- + +# Ping Foundation Overview + +Core concepts for platform setup and administration across all Ping Identity platforms. + +## Scope + +Covers: the shared administrative model across PingOne MT, PingOne ST, and Ping Software Suite. +Does NOT cover: flow design (see `ping-orchestration`) or app integration code (see `ping-app-integration`). + +## Core concepts + +### PingOne MT + +- **Environment**: top-level container; maps to an org or project. Holds apps, populations, policies, and connections. +- **Population**: user store within an environment. Users belong to one population. +- **Application**: OIDC or SAML app registered in PingOne. Policies attach to apps. +- **Sign-on Policy**: ordered set of authentication rules applied to app sign-in. +- **Directory**: user data store; default is PingOne Directory; external LDAP can be connected. + +### PingOne ST + +- **Tenant**: top-level admin unit. One tenant per PingOne ST deployment. +- **Realm**: identity domain inside a tenant. Each realm has its own identity store, policies, and journeys. +- **Identity Store**: PingDS (default) or external LDAP/AD. +- **Journey / Auth Tree**: orchestrated authentication or registration flow. Core orchestration primitive. +- **Theme**: UI customization applied to hosted pages within a realm. + +### Ping Software Suite + +- **Server Profile**: configuration-as-code pattern for PingFederate and PingAccess. +- **Connection**: SP connection (PingFederate) or resource (PingAccess) defines a federation or protection relationship. +- **Adapter**: PingFederate authentication adapter for a specific credential type (HTML form, RADIUS, Kerberos, etc.). +- **Virtual Host**: PingAccess per-site routing configuration. +- **Backend**: PingAccess upstream application definition. + +## Setup sequence (generic) + +1. Provision the platform (environment / tenant / server) +2. Configure identity store / directory +3. Register applications +4. Define authentication policy / journey / adapter chain +5. Test sign-in + +## Related references + +- `tenant-and-environment-setup.md` +- `policy-and-branding-basics.md` +- `core-admin-patterns.md` diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/policy-and-branding-basics.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/policy-and-branding-basics.md new file mode 100644 index 0000000..d72c900 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/policy-and-branding-basics.md @@ -0,0 +1,84 @@ +--- +title: "Policy and Branding Basics" +product_family: cross-platform +products: ["pingone", "pingone-st"] +capabilities: ["foundation"] +audience: ["admin"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "" +slug: "" +--- + +# Policy and Branding Basics + +Core configuration decisions for authentication policy and UI branding across PingOne MT and PingOne ST. + +## Scope + +Covers: sign-on policies, MFA policies, themes, and hosted page customization. +Does NOT cover: DaVinci flow design or PingOne ST journey logic — see `ping-orchestration`. + +--- + +## PingOne MT — Authentication Policies + +**Sign-on policy structure:** +- An ordered list of actions evaluated at sign-in +- Actions: Login, MFA, Identity Verification, Progressive Profiling, Agreement +- Policies attach to one or more applications; each app can reference a different policy + +**Action conditions:** always, risk-based (requires PingOne Protect), or device-based + +**MFA policy:** +- Controls which MFA methods are allowed: TOTP, SMS, email OTP, FIDO2, passkeys +- Configured at environment level; can be overridden per application +- Must be assigned to a sign-on policy's MFA action to take effect + +**Admin surface:** Policies → Sign-on → + Add Policy + +--- + +## PingOne MT — Branding + +| Setting | Location | +|---|---| +| Logo, colors, favicon | Branding → Edit | +| Email / SMS notification templates | Branding → Email / SMS templates | +| Custom domain (required for branded hosted pages) | Settings → Custom Domains | + +--- + +## PingOne ST — Policies + +- Authentication policies are realm-scoped +- Auth trees/journeys define the login flow — see `ping-orchestration` for journey design +- Policy sets apply authorization rules after authentication completes + +**Journey-as-policy:** In PingOne ST, the journey itself is the authentication policy. Bind a journey to the realm default or to a specific application to control which flow is used. + +**Admin surface:** Realm → Authentication → Trees or Journeys + +--- + +## PingOne ST — Theming + +- Themes are realm-scoped; one theme can serve as the realm default, others can override per journey +- Customize: logo, colors, fonts, layout (card or full-page), custom CSS + +**Admin surface:** Realm → Theming → Themes → + New Theme + +**Assignment levels:** + +| Level | Effect | +|---|---| +| Realm default | All journeys in the realm use this theme unless overridden | +| Journey override | Overrides realm default for all pages shown during that journey | + +## Related references + +- `foundation-overview.md` +- `tenant-and-environment-setup.md` +- `core-admin-patterns.md` diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/tenant-and-environment-setup.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/tenant-and-environment-setup.md new file mode 100644 index 0000000..16497cb --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/tenant-and-environment-setup.md @@ -0,0 +1,79 @@ +--- +title: "Tenant and Environment Setup" +product_family: cross-platform +products: ["pingone", "pingone-st"] +capabilities: ["foundation"] +audience: ["admin"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "" +slug: "" +--- + +# Tenant and Environment Setup + +Provisioning requirements and key configuration decisions for a new PingOne environment or PingOne ST tenant. + +## Scope + +Covers: initial provisioning and configuration of environments/tenants. +Does NOT cover: on-prem server installation (see `core-admin-patterns.md`). + +## PingOne MT — New Environment + +**Admin surface:** apps.pingone.com → Environments → + Add Environment + +**Required decisions:** +- Environment type: Sandbox, Development, or Production — determines SLA and capability profile +- Region selection: affects data residency +- Services to enable: MFA, Verify, DaVinci, Risk, etc. must be explicitly activated per environment +- Initial population: create an admin population or connect an external directory before adding users + +**Key settings to establish before adding apps or users:** + +| Setting | Location | +|---|---| +| Custom domain | Settings → Custom Domains | +| Notification sender (email/SMS) | Settings → Notifications | +| Default sign-on policy | Policies → Sign-on | + +**Prerequisites:** PingOne organization account with admin access. + +--- + +## PingOne ST — New Tenant + +**Admin surface:** Your PingOne ST tenant URL (provided by Ping during onboarding) + +**Required decisions:** +- Identity store: PingDS (default, no setup needed) or external LDAP/AD (requires additional configuration) +- Realm usage: `alpha` and `bravo` realms exist by default; decide which to use for customer-facing vs. internal flows before registering apps +- Custom domain: must be configured before go-live for production tenants + +**Key settings to establish before adding journeys or apps:** + +| Setting | Location | +|---|---| +| Identity store selection | Realm → Identity Stores | +| Custom domain | Tenant Settings → Custom Domains | +| Email provider | Email → SMTP or Ping-managed | +| Default theme | Themes → create or edit per realm | + +**Common post-setup tasks:** +- Import users or configure LDAP sync +- Enable social providers (Google, Apple, etc.) +- Configure federation (SAML SP or OIDC RP) + +**Prerequisites:** PingOne ST subscription; tenant URL and initial superadmin credentials from onboarding email. + +## Related references + +- `foundation-overview.md` +- `policy-and-branding-basics.md` + +## Source + +[PingOne Documentation](https://docs.pingidentity.com/pingone/) +[PingOne ST Documentation](https://docs.pingidentity.com/pingoneaic/) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/app-setup.md b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/app-setup.md new file mode 100644 index 0000000..46957bd --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/app-setup.md @@ -0,0 +1,129 @@ +--- +title: "PingOne ST — App Setup" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["foundation"] +services: [] +audience: ["admin", "developer"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-19" +slug: "https://docs.pingidentity.com/pingoneaic/latest/getting_started/getting_started-create_oauth2_client.html" +--- + +# PingOne ST — App Setup + +Register OIDC, OAuth 2.0, and SAML applications in PingOne ST so they can authenticate users through journeys. + +## Scope + +**Covers:** OIDC client registration, OAuth 2.0 client setup, SAML SP/IdP registration, key configuration fields. +**Does NOT cover:** Journey design — see `authentication-fundamentals.md`. Provisioning to external systems — see `directory-setup.md`. + +--- + +## Application types + +| Type | When to use | +|---|---| +| OIDC / OAuth 2.0 client | Web apps, SPAs, mobile apps, M2M service accounts needing tokens | +| SAML SP | Enterprise apps using SAML 2.0 federation | +| SAML IdP | PingOne ST acting as IdP to a third-party SP | + +--- + +## OIDC / OAuth 2.0 application + +**Admin surface:** AIC tenant admin console → Applications → OAuth 2.0 Clients → + Create Client + +**Required configuration:** + +| Field | Notes | +|---|---| +| Client ID | Auto-generated or custom; must be unique within the realm | +| Client Secret | Required for confidential clients; omit for public (SPA, native) | +| Redirect URIs | Exact match enforced; add all environments upfront to avoid `redirect_uri mismatch` in lower envs | +| Grant Types | Authorization Code (web apps), Client Credentials (M2M), Refresh Token as needed; avoid Implicit | +| Scopes | Minimum: `openid`; add `profile`, `email`, `address`, `phone` as needed | +| Client Type | Confidential (can hold a secret) or Public (SPA/native; requires PKCE) | + +**Client authentication methods:** +- `client_secret_basic` — HTTP Basic header; most common for confidential clients +- `client_secret_post` — client ID/secret in POST body +- `private_key_jwt` — JWT signed with client's private key; recommended for high-security M2M + +**OIDC discovery endpoint:** +`https:///am/oauth2/realms/root/realms//.well-known/openid-configuration` + +**Token options:** +- Access token format: server-side (stateful) or JWT (stateless) +- ID token encryption: optional; configure if the client cannot inspect the JWT +- Refresh token expiry: per-client override or realm default + +--- + +## SAML application + +**Admin surface:** AIC admin console → Applications → SAML Applications → + Register Application + +**Required configuration:** + +| Field | Notes | +|---|---| +| Entity ID | Unique SP identifier; typically the app's base URL or a URN | +| ACS URL | Assertion Consumer Service URL — where PingOne ST POST-binds the SAML response | +| Single Logout URL | Optional; required for SLO support | +| Name ID Format | `email`, `persistent`, or `transient` — dictated by SP requirements | +| Signing | Enable response and/or assertion signing; export IdP metadata to share with SP admin | + +**Metadata exchange:** Import SP metadata XML if available to auto-populate ACS URL, entity ID, and certificates. Export PingOne ST IdP metadata from Applications → SAML Applications → (app) → Export Metadata. + +--- + +## Assigning a journey to an application + +An OIDC or SAML app uses the realm's default authentication journey unless overridden. + +**Override location:** Application settings → Authentication → Journey + +Use per-app journey assignment to serve distinct login experiences (e.g., workforce vs. customer, standard vs. high-assurance) without modifying the realm default. + +--- + +## Provisioning from apps + +Applications can provision user accounts to 40+ external systems (Salesforce, Workday, Active Directory, Microsoft Entra ID) using PingIDM connectors. + +**Admin surface:** Applications → Provisioning + +Configure provisioning after basic app setup is complete and the identity store is verified. + +--- + +## Prerequisites + +- PingOne ST tenant with admin access +- Realm configured with at least one identity store (see `directory-setup.md`) +- At least one authentication journey ready or in progress (see `authentication-fundamentals.md`) + +## Common variants + +| Variant | Note | +|---|---| +| SPA | Public client type, PKCE required, no client secret | +| M2M / service account | Client Credentials grant, no redirect URI needed | +| Realm-scoped clients | Clients registered in `alpha` are not available in `bravo` and vice versa | + +## Related references + +- `authentication-fundamentals.md` +- `foundation-overview.md` +- `directory-setup.md` + +## Source + +[Register OAuth 2.0 clients — PingOne ST](https://docs.pingidentity.com/pingoneaic/latest/getting_started/getting_started-create_oauth2_client.html) +[OIDC client registration](https://docs.pingidentity.com/pingoneaic/latest/am-oidc-guide/oidc-client-registration.html) +[SAML application registration](https://docs.pingidentity.com/pingoneaic/latest/am-saml2-guide/saml2-sp-registration.html) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/authentication-fundamentals.md b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/authentication-fundamentals.md new file mode 100644 index 0000000..77715f4 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/authentication-fundamentals.md @@ -0,0 +1,117 @@ +--- +title: "PingOne ST — Authentication Fundamentals" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["foundation"] +services: [] +audience: ["admin", "developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-19" +slug: "https://docs.pingidentity.com/pingoneaic/latest/am-journey-guide/journey-overview.html" +--- + +# PingOne ST — Authentication Fundamentals + +Understand and configure authentication in PingOne ST: the journey model, realm authentication settings, and key design rules before building any login flow. + +## Scope + +**Covers:** Journey/tree concepts, realm authentication settings, node basics, journey design rules. +**Does NOT cover:** Specific node-by-node flow design — that belongs in `ping-orchestration`. Application-to-journey assignment — see `references/curated/pingone-st/app-setup.md`. + +## Key steps / content + +### The journey model + +Authentication in PingOne ST is driven by **journeys** (also called authentication trees in PingAM). A journey is a configurable directed graph of **nodes** connected by outcome branches. + +- Journeys replace static login pages with flexible, branching flows +- Nodes perform a single function: collect a credential, evaluate a condition, invoke a service, set a session variable +- Branches connect nodes to the next step based on the outcome (e.g., `True` / `False`, `Match` / `No Match`, `Success` / `Failure`) +- Journeys can be nested: an inner journey node invokes another journey and passes its result upstream + +**End states:** Every journey must reach one of two terminal nodes: +- `Success` — authentication approved, session created +- `Failure` — authentication denied + +### Realm authentication settings + +**Admin surface:** AIC admin console → Authentication → Journeys (or AM admin console → Realm → Authentication → Settings) + +| Setting | Purpose | +|---|---| +| Default authentication journey | Used when no specific journey is requested (e.g., `/login` with no `authIndexType` parameter) | +| Default failure URL | Where users land after a `Failure` outcome when the client does not specify | +| Default success URL | Where users land after a `Success` outcome when the client does not specify | +| Session settings | Idle timeout, max session time, session quota (max concurrent sessions per user) | + +**Per-application override:** A specific journey can be assigned to an individual application. Set at Application settings → Authentication → Journey. Different apps can present different login flows without modifying the realm default. + +### Node categories and common nodes + +| Category | Examples | +|---|---| +| **Input / collection** | Username Collector, Password Collector, Choice Collector, Attribute Collector | +| **Credential validation** | Data Store Decision (validates username + password against identity store) | +| **MFA / step-up** | WebAuthn Registration/Authentication, OTP Email/SMS, Push Authentication | +| **Conditional logic** | Scripted Decision, Attribute Present Decision, Session Data Decision | +| **Session / profile** | Set Session Properties, Set Persistent Cookie, Profile Completeness Decision | +| **External integrations** | Social Provider Handler, LDAP Decision, HTTP Client, Platform Password | + +**Scripted Decision node:** Executes a custom JavaScript or Groovy script to implement logic not covered by built-in nodes. The script returns a named outcome that maps to a branch. Requires a Decision Node script defined in Scripts. + +**Transient state:** Nodes can store intermediate values in transient state (in-memory, session-duration) or shared state (survives across inner journeys). Use transient state to pass the username collected in one node to a validation node further down the journey. + +### Key design rules + +These are constraints that prevent broken or unexpected behavior: + +| Rule | Why it matters | +|---|---| +| Do not set a journey as both **default** AND **always run** | "Always run" forces re-execution of the journey on every request, including mid-session. Combined with "default," this can create redirect loops. | +| Do not map a journey to the default ACR value if it is set to "always run" | Same loop risk via ACR-based routing. | +| If a user re-authenticates with the same journey during an active session, journey processing is skipped by default | This is intentional session-level caching. Override with `ForceAuth=true` if re-authentication is required. | +| Duplicate journeys via the editor (More → Duplicate) before modifying production journeys | Preserves a working copy. Journeys cannot be version-controlled natively in the console. | + +### Journey activation + +Journeys must be **activated** to be available for authentication. A deactivated journey still exists in the editor but returns an error if invoked. + +**Admin surface:** Journey editor → More (⋮) → Activate / Deactivate + +### How clients invoke a journey + +| Method | When to use | +|---|---| +| Application override | Preferred; set once in app config, no per-request parameters needed | +| OIDC `acr_values` | Append `&acr_values=` to the authorization request | +| Direct AM endpoint | `/login?authIndexType=service&authIndexValue=` — use for testing or legacy integrations | + +## Prerequisites + +- PingOne ST tenant with at least one realm configured +- Identity store connected to the realm (see `references/curated/pingone-st/directory-setup.md`) +- Admin access to Authentication → Journeys + +## Common variants + +| Variant | Note | +|---|---| +| Inner journeys | Nest frequently-reused logic (e.g., MFA step) into a reusable inner journey invoked by a Journey node | +| Workforce vs. CIAM | Workforce flows are often simpler (username + password + MFA). CIAM flows add registration, progressive profiling, and verification steps — typically built in `ping-orchestration`. | +| ForgeRock AM auth trees | Same underlying model as PingAM trees. Existing ForgeRock trees can be migrated to PingOne ST journeys with node mapping. | + +## Related references + +- `references/curated/pingone-st/app-setup.md` +- `references/curated/pingone-st/foundation-overview.md` +- `references/curated/pingone-st/directory-setup.md` + +## Source + +[Journey overview — PingOne ST](https://docs.pingidentity.com/pingoneaic/latest/am-journey-guide/journey-overview.html) +[Authentication nodes reference](https://docs.pingidentity.com/pingoneaic/latest/am-authentication/authentication-node-reference.html) +[Getting started: authentication journey](https://docs.pingidentity.com/pingoneaic/latest/getting_started/getting_started-authentication_journey.html) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/directory-setup.md b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/directory-setup.md new file mode 100644 index 0000000..1819981 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/directory-setup.md @@ -0,0 +1,159 @@ +--- +title: "PingOne ST — Directory Setup (User Management)" +product_family: pingone-st +products: ["pingone-aic", "pingidm", "pingds"] +capabilities: ["foundation"] +services: [] +audience: ["admin", "architect"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-19" +slug: "https://docs.pingidentity.com/pingoneaic/latest/getting_started/getting_started-identity_store.html" +--- + +# PingOne ST — Directory Setup (User Management) + +Identity store options, schema configuration, and provisioning patterns for PingOne ST. + +## Scope + +**Covers:** PingDS identity store, external LDAP/AD connection, managed objects and schema, provisioning and reconciliation. +**Does NOT cover:** Authentication journey configuration — see `authentication-fundamentals.md`. Deep provisioning flow design — see `ping-orchestration`. + +--- + +## Identity store options + +Each realm must be associated with an identity store. + +| Option | When to use | +|---|---| +| PingDS (default) | New deployments; cloud-native, fully managed by Ping Identity | +| External LDAP / AD | Migrating from on-prem directory; AD remains authoritative | +| Multiple stores | Advanced: route different user populations to different stores | + +PingDS requires no additional setup — users created via PingIDM are stored here automatically. + +**Admin surface:** AM admin console → Realm → Identity Stores → + Add Identity Store + +--- + +## External LDAP / Active Directory configuration + +**Required fields:** + +| Field | Example / Notes | +|---|---| +| LDAP server URL | `ldaps://ad.example.com:636` — TLS strongly recommended | +| Bind DN | `uid=pingbind,ou=service,dc=example,dc=com` | +| Bind password | Use a secret/ESV rather than plaintext | +| Base DN | `dc=example,dc=com` | +| User search filter | `(uid=*)` for LDAP; `(sAMAccountName=*)` for AD | +| Group search filter | `(objectClass=groupOfNames)` | + +**Active Directory specifics:** +- Username attribute: `sAMAccountName` (not `uid`) +- Account enable/disable: controlled via `userAccountControl` +- Object identifier: GUID — configure `objectGUID` as the DS object identifier +- Kerberos pass-through auth: supported via LDAP gateway + +**Constraint:** The DS certificate must be shared with the AM container before TLS connectivity will succeed. + +--- + +## Managed objects and user schema (PingIDM) + +**Default managed object types:** + +| Object type | Purpose | +|---|---| +| `user` | End-user identity | +| `role` | Access role assigned to users | +| `assignment` | Maps a role to an entitlement | +| `group` | User group | +| `organization` | Org hierarchy node (B2B / delegated admin) | + +**Critical:** Do not delete default managed objects. Removing them can break the tenant. + +**Schema extension:** +- Custom attributes on `user` must be added via the IDM admin console before they can be set or queried +- **Admin surface:** IDM admin console → Managed Objects → user → Properties → + Add Property +- Properties not defined in schema will not appear in the UI and their sub-properties cannot be configured +- Custom object types (e.g., IoT devices, contracts) are supported + +**Core user properties:** `userName`, `password`, `mail`, `givenName`, `sn`, `telephoneNumber`, `displayName`, `accountStatus` + +--- + +## Provisioning and reconciliation + +PingIDM uses **mappings** to move identity data between systems. + +**Mapping components:** + +| Component | Purpose | +|---|---| +| Source | Where data originates (e.g., `system/ldap/account`) | +| Target | Where data is written (e.g., `managed/alpha_user`) | +| Attribute map | Source attribute → target attribute | +| Conditions | JavaScript expression to control whether the mapping fires (e.g., active accounts only) | +| Transforms | JavaScript function to reshape values (e.g., combine first + last → displayName) | + +**Reconciliation phases:** +1. Source reconciliation — identifies changes in the source +2. Target reconciliation — detects orphaned target objects (handles deletions) + +**LDAP/AD connector key settings:** + +| Setting | Notes | +|---|---| +| `objectClassesToSynchronize` | `inetOrgPerson` for LDAP; `user` for AD | +| `attributesToSynchronize` | Leave empty to sync all; restrict for performance | +| `accountSynchronizationFilter` | LDAP filter to scope which accounts sync | +| `changeLogBlockSize` | Default 100; increase for high-volume directories | + +**Outbound provisioning:** 40+ connectors available (Microsoft Entra ID, Salesforce, Workday, Active Directory, ServiceNow). Admin surface: IDM admin console → Connectors → + New Connector. + +--- + +## User creation methods + +| Method | Notes | +|---|---| +| IDM admin console | Manual; Managed Objects → user → + New User | +| Self-registration journey | User-initiated via authentication journey (see `ping-orchestration`) | +| SCIM inbound | External HR/provisioning system pushes via SCIM 2.0 endpoint | +| Reconciliation | PingIDM pulls from external directory on schedule | +| REST API | `POST /openidm/managed/alpha_user` | + +--- + +## Prerequisites + +- PingOne ST tenant with at least one realm +- For external LDAP/AD: LDAPv3-compliant server; TLS certificate shared with AM container; service account credentials +- For PingDS multi-server replication: same encryption passphrase on all nodes + +## Common variants + +| Variant | Note | +|---|---| +| Alpha realm users | Stored as `managed/alpha_user`; realm prefix is part of the path | +| Multiple realms | Each realm has its own user store path: `bravo_user`, `alpha_user`, etc. | +| Hybrid: PingDS + AD | PingDS as primary; AD connector syncs a subset of attributes on schedule | +| Delegated administration | Use `organization` managed objects to scope admin access to a subset of users | + +## Related references + +- `foundation-overview.md` +- `authentication-fundamentals.md` +- `app-setup.md` + +## Source + +[Identity store setup — PingOne ST](https://docs.pingidentity.com/pingoneaic/latest/getting_started/getting_started-identity_store.html) +[Managed objects — PingIDM](https://docs.pingidentity.com/pingoneaic/latest/idm-guide/managed-objects.html) +[LDAP connector configuration](https://docs.pingidentity.com/pingoneaic/latest/idm-connector-reference/ldap-connector.html) +[Provisioning and reconciliation](https://docs.pingidentity.com/pingoneaic/latest/idm-guide/provisioning-overview.html) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/foundation-overview.md b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/foundation-overview.md new file mode 100644 index 0000000..62aeda3 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/foundation-overview.md @@ -0,0 +1,115 @@ +--- +title: "PingOne ST — Foundation Overview" +product_family: pingone-st +products: ["pingone-aic", "pingam", "pingidm", "pingds"] +capabilities: ["foundation"] +services: [] +audience: ["admin", "architect"] +use_cases: ["workforce", "customer"] +doc_type: concept +status: current +canonical: true +last_updated: "2026-05-19" +slug: "https://docs.pingidentity.com/pingoneaic/latest/index.html" +--- + +# PingOne ST — Foundation Overview + +Conceptual orientation for PingOne ST (Advanced Identity Cloud): what it is, how it is structured, and what each component does before any configuration begins. + +## Scope + +**Covers:** Tenant architecture, core components, realm model, admin control plane. +**Does NOT cover:** Step-by-step setup tasks — see: +- `references/curated/pingone-st/app-setup.md` for application registration +- `references/curated/pingone-st/authentication-fundamentals.md` for journeys +- `references/curated/pingone-st/directory-setup.md` for identity stores and users +- `references/curated/pingone-st/themes-and-customization.md` for branding + +## Key steps / content + +### What PingOne ST is + +PingOne ST (formerly ForgeRock Identity Cloud) is a fully managed, single-tenant SaaS identity platform. It runs a complete identity stack — authentication, identity management, and directory services — inside a dedicated tenant owned by Ping Identity but configured by the customer. + +It is distinct from PingOne MT (multi-tenant cloud) in: +- Deployment model: single-tenant per customer, not shared infrastructure +- Control plane: AIC admin console at a customer-specific URL, not apps.pingone.com +- Customization depth: full journey/tree authoring, schema extension, custom scripts +- Component model: three integrated products (PingAM, PingIDM, PingDS) vs. PingOne's service-based model + +### Core components + +| Component | Role | +|---|---| +| **PingAM** | Authentication and access management. Handles OAuth 2.0, OIDC, SAML 2.0, session management, and journey execution. | +| **PingIDM** | Identity management. Manages users, roles, groups, organizations, and provisioning to external systems. | +| **PingDS** | Directory services. Backend data store for identity data. PingDS ships as the default identity store. | + +These three components are pre-integrated in every PingOne ST tenant. They share a common data plane but expose separate admin surfaces. + +### Tenant architecture + +``` +Tenant (one per customer) +└── Realm (one or more logical identity domains) + ├── Identity Store (PingDS or external LDAP/AD) + ├── Applications (OIDC/SAML clients) + ├── Journeys / Auth Trees (authentication flows) + ├── Policies (authorization rules) + └── Themes (hosted page branding) +``` + +**Tenant:** The top-level isolated environment. All configuration is scoped to a tenant. Tenants come in types: development, staging, production, sandbox — each with different SLA and capability profiles. + +**Realm:** A logical partition inside a tenant for grouping identities, applications, and authentication configuration. The default realms are `alpha` (typically customer-facing) and `bravo` (typically internal/workforce). Additional realms can be created. + +**Identity Store:** The backend user data repository associated with a realm. PingDS is the default. External LDAP/AD can be configured as an additional or replacement store. + +### Admin control plane surfaces + +| Surface | What it controls | +|---|---| +| AIC tenant admin console | Realm management, journeys, apps, themes, users, audit | +| AM admin console | Low-level OAuth2/SAML configuration, realms, advanced auth settings | +| IDM admin console | Managed objects, schema, connectors, provisioning mappings | +| REST APIs | All above surfaces; preferred for automation | + +Most day-to-day admin work happens in the AIC tenant admin console. The AM and IDM consoles are used for advanced configuration not yet surfaced in the unified console. + +### Environment types + +| Type | Purpose | +|---|---| +| Development | Feature development and testing | +| Staging | Pre-production validation | +| Production | Live traffic; highest SLA | +| Sandbox | Isolated exploration; no production data | +| UAT | User acceptance testing | + +Production tenants support multi-region high availability. + +## Prerequisites + +- PingOne ST subscription provisioned by Ping Identity +- Tenant URL and initial superadmin credentials from onboarding email +- Understanding of OAuth 2.0, OIDC, or SAML 2.0 for application integration planning + +## Common variants + +| Variant | Note | +|---|---| +| ForgeRock Identity Cloud | Previous branding; same product. Documentation and community content may use this name. | +| Multiple realms | Large deployments often use separate realms for workforce vs. customer identity domains. | +| Custom domains | Production tenants should configure a custom domain before going live. | + +## Related references + +- `references/curated/pingone-st/app-setup.md` +- `references/curated/pingone-st/authentication-fundamentals.md` +- `references/curated/pingone-st/directory-setup.md` +- `references/curated/pingone-st/themes-and-customization.md` + +## Source + +[PingOne ST Documentation](https://docs.pingidentity.com/pingoneaic/latest/index.html) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/themes-and-customization.md b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/themes-and-customization.md new file mode 100644 index 0000000..63166cc --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/themes-and-customization.md @@ -0,0 +1,126 @@ +--- +title: "PingOne ST — Themes and Customization" +product_family: pingone-st +products: ["pingone-aic"] +capabilities: ["foundation"] +services: [] +audience: ["admin", "developer"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-19" +slug: "https://docs.pingidentity.com/pingoneaic/latest/ui-customization-guide/ui-theming.html" +--- + +# PingOne ST — Themes and Customization + +Apply branding to PingOne ST hosted pages using the Theme Editor and custom CSS. + +## Scope + +**Covers:** Theme creation, visual configuration, custom CSS, theme assignment to realms and journeys, hosted page coverage. +**Does NOT cover:** Email template customization — configured separately under Notifications. Custom journey UI nodes — that is a `ping-orchestration` scripting task. + +--- + +## Theming model + +Themes are applied in layers: + +``` +Tenant +└── Realm (realm-level default theme) + └── Journey (journey-level override) + └── Hosted pages served to end users +``` + +A single tenant can serve distinct branding to different user populations by assigning different themes to different realms or journeys. + +**Admin surface:** AIC admin console → Realm → Theming → Themes → + New Theme + +--- + +## Theme configuration fields + +| Field | Notes | +|---|---| +| Logo | Appears on login, enrollment, and account pages | +| Favicon | Browser tab icon | +| Colors | Primary, secondary, link, background — hex values | +| Font | Web-safe fonts or custom font family; CDN fonts require CSP update | +| Layout | Card layout (centered, default) or full-page | + +--- + +## Custom CSS + +**Access:** Theme Editor → Custom CSS tab + +Use browser DevTools against hosted pages to identify target element class names before writing overrides. + +**CSP constraint:** PingOne ST hosted pages enforce a Content Security Policy. External fonts or assets loaded from custom CSS require the origin to be added to the CSP configuration. + +**CSP admin surface:** AIC admin console → Security → Content Security Policy + +**Social button positioning:** social login buttons appear above username/password fields by default. CSS controls visual stacking only — the actual flow order is controlled by Social Provider Handler node placement in the journey. + +--- + +## Theme assignment + +| Level | Effect | Admin surface | +|---|---|---| +| Realm default | All journeys in the realm use this theme unless overridden | Realm → Theming → Set Default Theme | +| Journey override | All pages shown during that journey use this theme | Journey editor → (journey settings) → Theme | + +--- + +## Hosted pages covered by themes + +| Page type | Themed | +|---|---| +| Login / sign-on | Yes | +| Registration | Yes | +| Password reset | Yes | +| MFA enrollment | Yes | +| Account (end-user self-service) | Yes | +| Consent | Yes | +| Error pages | Partial — system errors may not be fully themed | + +--- + +## Localization + +- Hosted page strings are driven by the browser's `Accept-Language` header +- Custom locale files can be added for supported languages +- Admin console and hosted pages support localization independently + +--- + +## Prerequisites + +- PingOne ST tenant with at least one realm +- Admin access to Theming +- If using CDN fonts: CSP must allow the font origin before the theme is applied + +## Common variants + +| Variant | Note | +|---|---| +| Multi-brand | One theme per brand; assign each to the appropriate realm or journey | +| Workforce vs. CIAM | Use realm-level themes to separate internal and external page branding | +| Dark mode | Not natively supported; achievable via custom CSS overriding color variables | +| Account pages | End-user account management at `/am/XUI/` is also themed but configured separately under Account pages | + +## Related references + +- `foundation-overview.md` +- `authentication-fundamentals.md` +- `app-setup.md` + +## Source + +[UI theming — PingOne ST](https://docs.pingidentity.com/pingoneaic/latest/ui-customization-guide/ui-theming.html) +[UI customization overview](https://docs.pingidentity.com/pingoneaic/latest/ui-customization-guide/ui-overview.html) +[Getting started: apply basic branding](https://docs.pingidentity.com/pingoneaic/latest/getting_started/getting_started-apply_branding.html) diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/cross-platform/top-10.json b/plugins/ping-identity/skills/ping-foundation/references/generated/cross-platform/top-10.json new file mode 100644 index 0000000..bf2a176 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/cross-platform/top-10.json @@ -0,0 +1,8 @@ +{ + "_comment": "Machine-generated. Do not hand-edit. Regenerated by CI workflow build-reference-manifests.yml on docs publish.", + "skill": "ping-foundation", + "branch": "cross-platform", + "generated_at": null, + "max_docs": 10, + "docs": [] +} diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingaccess.md b/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingaccess.md new file mode 100644 index 0000000..558fe23 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingaccess.md @@ -0,0 +1,30 @@ +--- +title: "Ping Software Suite — PingAccess" +product_family: ping-software +products: ["pingaccess"] +capabilities: ["foundation"] +audience: ["admin", "architect"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# Ping Software Suite — PingAccess + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- Installation and initial setup +- Virtual host and site configuration +- Protected resource (application) setup +- Agent and engine configuration +- Token provider integration (PingFederate) +- SSL/TLS certificate management +- Clustering and high availability + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `ping-software` → `foundation` + `pingaccess` product entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingam.md b/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingam.md new file mode 100644 index 0000000..d57d04c --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingam.md @@ -0,0 +1,30 @@ +--- +title: "PingAM — Foundation" +product_family: ping-software +products: ["pingam"] +capabilities: ["foundation"] +audience: ["admin", "architect"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# PingAM — Foundation + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- PingAM standalone installation and initial configuration +- Realm and identity store setup +- Authentication tree and journey basics (see ping-orchestration for design patterns) +- OAuth 2.0 / OIDC authorization server +- Federation (SAML IdP and SP) +- Certificate and keystore management +- Clustering + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `ping-software` → `foundation` + `pingam` product entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingdirectory.md b/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingdirectory.md new file mode 100644 index 0000000..6225a6b --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingdirectory.md @@ -0,0 +1,31 @@ +--- +title: "Ping Software Suite — PingDirectory" +product_family: ping-software +products: ["pingdirectory"] +capabilities: ["foundation"] +audience: ["admin", "operator"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# Ping Software Suite — PingDirectory + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- Installation and initial setup +- Schema configuration and extension +- Replication topology setup +- Access control (ACIs) +- Backends and backend databases +- Password storage and policies +- SCIM and REST API configuration +- PingDataSync integration + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `ping-software` → `foundation` + `pingdirectory` product entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingfederate.md b/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingfederate.md new file mode 100644 index 0000000..31c6ad6 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingfederate.md @@ -0,0 +1,31 @@ +--- +title: "PingFederate — Foundation" +product_family: ping-software +products: ["pingfederate"] +capabilities: ["foundation"] +audience: ["admin", "architect"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# PingFederate — Foundation + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- Installation and initial configuration +- Server settings (base URL, certificates, runtime node) +- IdP and SP connection setup (SAML, OIDC) +- OAuth 2.0 authorization server configuration +- Authentication adapters and policies +- Password Credential Validators +- Data stores (LDAP, JDBC) +- Clustering and high availability + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `ping-software` → `foundation` + `pingfederate` product entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingid.md b/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingid.md new file mode 100644 index 0000000..bcfecfa --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/pingid.md @@ -0,0 +1,29 @@ +--- +title: "Ping Software Suite — PingID" +product_family: ping-software +products: ["pingid"] +capabilities: ["foundation"] +audience: ["admin"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# Ping Software Suite — PingID + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- PingID on-premises setup and configuration +- PingID integration with PingFederate +- MFA policy configuration +- Device enrollment and management +- Notification service configuration (push, SMS, email) +- PingID SDK integration points + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `ping-software` → `foundation` + `pingid` product entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/top-25.json b/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/top-25.json new file mode 100644 index 0000000..4870c2c --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/ping-software/top-25.json @@ -0,0 +1,8 @@ +{ + "_comment": "Machine-generated. Do not hand-edit. Regenerated by CI workflow build-reference-manifests.yml on docs publish.", + "skill": "ping-foundation", + "branch": "ping-software", + "generated_at": null, + "max_docs": 25, + "docs": [] +} diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/apps.md b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/apps.md new file mode 100644 index 0000000..92ae178 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/apps.md @@ -0,0 +1,28 @@ +--- +title: "PingOne MT — Applications" +product_family: pingone-mt +products: ["pingone"] +capabilities: ["foundation"] +audience: ["admin", "developer"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# PingOne MT — Applications + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- Adding OIDC and SAML applications +- Native/mobile app registration +- Worker app registration (machine-to-machine) +- App attribute mapping +- Application policies and assignments + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `pingone-mt` → `foundation` capability entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/directories.md b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/directories.md new file mode 100644 index 0000000..88dd372 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/directories.md @@ -0,0 +1,28 @@ +--- +title: "PingOne MT — Directories" +product_family: pingone-mt +products: ["pingone"] +capabilities: ["foundation"] +audience: ["admin"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# PingOne MT — Directories + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- PingOne Directory (built-in) +- External LDAP/AD connection +- User populations and attribute schema +- User import and provisioning +- SCIM provisioning from HR systems + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `pingone-mt` → `foundation` capability entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/policies.md b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/policies.md new file mode 100644 index 0000000..7842a28 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/policies.md @@ -0,0 +1,28 @@ +--- +title: "PingOne MT — Policies" +product_family: pingone-mt +products: ["pingone"] +capabilities: ["foundation"] +audience: ["admin"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# PingOne MT — Policies + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- Sign-on policies and actions +- MFA policies and device management +- Password policies +- Risk-based policies (requires PingOne Protect) +- Agreement and progressive profiling actions + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `pingone-mt` → `foundation` capability entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/tenants.md b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/tenants.md new file mode 100644 index 0000000..c4b8a9d --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/tenants.md @@ -0,0 +1,28 @@ +--- +title: "PingOne MT — Tenants and Environments" +product_family: pingone-mt +products: ["pingone"] +capabilities: ["foundation"] +audience: ["admin"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# PingOne MT — Tenants and Environments + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- Environment creation and management +- Organization and license management +- Region selection and data residency +- Environment-level settings (custom domains, notifications, branding) +- Admin roles and delegated administration + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `pingone-mt` → `foundation` capability entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/top-25.json b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/top-25.json new file mode 100644 index 0000000..927b85b --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-mt/top-25.json @@ -0,0 +1,8 @@ +{ + "_comment": "Machine-generated. Do not hand-edit. Regenerated by CI workflow build-reference-manifests.yml on docs publish.", + "skill": "ping-foundation", + "branch": "pingone-mt", + "generated_at": null, + "max_docs": 25, + "docs": [] +} diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/administration.md b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/administration.md new file mode 100644 index 0000000..b776c91 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/administration.md @@ -0,0 +1,28 @@ +--- +title: "PingOne ST — Administration" +product_family: pingone-st +products: ["pingone-st", "pingam", "pingidm", "pingds"] +capabilities: ["foundation"] +audience: ["admin"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# PingOne ST — Administration + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- Tenant and realm management +- Admin roles and delegated administration +- Custom domains +- Email and notification configuration +- Audit logging and monitoring + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `pingone-st` → `foundation` capability entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/customization.md b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/customization.md new file mode 100644 index 0000000..e3cb10d --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/customization.md @@ -0,0 +1,27 @@ +--- +title: "PingOne ST — Customization" +product_family: pingone-st +products: ["pingone-st"] +capabilities: ["foundation"] +audience: ["admin", "developer"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# PingOne ST — Customization + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- Theming and hosted page customization +- Custom CSS and logo +- Localization and language support +- Custom domains and certificates + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `pingone-st` → `foundation` capability entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/identity-data.md b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/identity-data.md new file mode 100644 index 0000000..3ddb4cd --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/identity-data.md @@ -0,0 +1,28 @@ +--- +title: "PingOne ST — Identity Data" +product_family: pingone-st +products: ["pingone-st", "pingidm", "pingds"] +capabilities: ["foundation"] +audience: ["admin", "developer"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# PingOne ST — Identity Data + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- Identity schema and attribute configuration (PingIDM) +- PingDS directory setup and schema extension +- User import, provisioning, and reconciliation +- LDAP/AD integration +- SCIM provisioning + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `pingone-st` → `foundation` capability entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/reports.md b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/reports.md new file mode 100644 index 0000000..956da09 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/reports.md @@ -0,0 +1,27 @@ +--- +title: "PingOne ST — Reports" +product_family: pingone-st +products: ["pingone-st"] +capabilities: ["foundation"] +audience: ["admin"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# PingOne ST — Reports + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- Audit log access and filtering +- Authentication event reports +- Admin event logs +- Log forwarding (Splunk, Elastic, SIEM) + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `pingone-st` → `foundation` capability entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/self-service.md b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/self-service.md new file mode 100644 index 0000000..c6de28d --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/self-service.md @@ -0,0 +1,28 @@ +--- +title: "PingOne ST — Self-Service" +product_family: pingone-st +products: ["pingone-st"] +capabilities: ["foundation"] +audience: ["admin", "developer"] +doc_type: reference +status: current +canonical: false +last_updated: "" +slug: "" +--- + +# PingOne ST — Self-Service + +_Generated reference stub. Replace with curated content or populate from docs manifest._ + +## Topics covered by this branch + +- End-user self-service portal configuration +- Password reset and account recovery +- Profile update flows +- Progressive profiling +- Consent management + +## Source + +Populate from: `shared/generated/docs-by-platform.json` → `pingone-st` → `foundation` capability entries. diff --git a/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/top-25.json b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/top-25.json new file mode 100644 index 0000000..4d56ba1 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/generated/pingone-st/top-25.json @@ -0,0 +1,8 @@ +{ + "_comment": "Machine-generated. Do not hand-edit. Regenerated by CI workflow build-reference-manifests.yml on docs publish.", + "skill": "ping-foundation", + "branch": "pingone-st", + "generated_at": null, + "max_docs": 25, + "docs": [] +} diff --git a/plugins/ping-identity/skills/ping-orchestration/SKILL.md b/plugins/ping-identity/skills/ping-orchestration/SKILL.md new file mode 100644 index 0000000..e0137db --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/SKILL.md @@ -0,0 +1,159 @@ +--- +name: ping-orchestration +description: Design and build authentication flows, journeys, and orchestration logic for Ping Identity platforms. Use for ANY question about DaVinci flows, PingOne ST journeys, PingAM trees, scripted decision nodes, or branching authentication/registration logic — including advisory, planning, "what nodes do I need", "how should I design my flow", and "advise me before I build" requests, not just implementation tasks. Also invoke with /ping-orchestration. +compatibility: Designed for Ping Identity orchestration tasks. MCP tools for PingOne ST are used when available to create and update journeys directly. +metadata: + publisher: Ping Identity + version: "1.0" +--- + +# ping-orchestration + +Design and build authentication flows, orchestration logic, and journey-based experiences across Ping Identity platforms. + +> **Role of this skill:** MCP tools handle execution — creating, updating, and managing journeys and flow nodes directly. This skill supplies what the tools lack: flow design patterns, node sequencing, branching logic, scripting guidance, and platform-specific constraints. Use it to reason correctly about *what* to build and *why* before (or alongside) using MCP tools to do it. + +## Invocation + +Invoke this skill explicitly with `/ping-orchestration` or by saying "use ping-orchestration to...". + +## When to use this skill + +Trigger on ANY of the following — including questions, planning, and advisory requests, not just implementation tasks: + +- "Build a login journey in PingOne ST" +- "Design a registration flow with email verification" +- "Create a DaVinci flow for customer login" +- "Add a scripted decision node to my authentication tree" +- "Configure a PingAM authentication tree" +- "Build MFA step-up logic in a journey" +- "Design a self-service password reset flow" +- "Orchestrate identity proofing in a registration journey" +- "What nodes do I need for [flow scenario]?" +- "How should I structure my journey for [use case]?" +- "What's the right way to handle [authentication or registration pattern]?" +- "Advise me on how to design my [journey / DaVinci flow] before I build it" +- "What are the pros and cons of using [node type / flow pattern]?" +- "Help me plan my registration / login / MFA flow" +- "I'm not sure how to approach [journey design challenge]" +- "Should I use inner journeys / scripted nodes / DaVinci connectors for this?" + +**Catch-all:** Trigger this skill whenever the user asks ANY question about designing, planning, or advising on authentication flows, journeys, or orchestration logic in PingOne ST, PingOne MT / DaVinci, or PingAM — even before implementation starts, even if phrased as a question or planning discussion. + +## When NOT to use this skill + +- If the platform is not yet set up (no tenant, no realm, no app registered): use `ping-foundation` first +- If the task is **configuring the platform layer** (apps, directories, policies, branding): use `ping-foundation` +- If the task is **invoking a Universal Service** (Protect, Verify, IGA, Credentials) without needing flow design: use `ping-universal-services` +- If the task is **integrating the flow into an app or SDK**: use `ping-app-integration` +- If unsure which platform: use `ping-quickstart` first + +## Multi-skill use cases + +Orchestration sits in the middle of the stack — platform foundation must exist before flows can be built, and other skills extend what those flows can do. + +| What comes before | Skill | +|---|---| +| Tenant, realm, identity store, and app must be configured first | `ping-foundation` | + +| What comes after | Skill | +|---|---| +| Add risk scoring, MFA step-up, identity verification within the flow | `ping-universal-services` | +| Wire the finished flow into a web, mobile, or SDK-based app | `ping-app-integration` | + +**Example — CIAM registration with identity proofing on PingOne ST:** +1. `ping-foundation` — provision tenant, configure realm and identity store, register OIDC app +2. `ping-orchestration` — design the registration journey: username collection, email OTP, profile completion +3. `ping-universal-services` — add PingOne Verify node for document and liveness check +4. `ping-app-integration` — integrate the hosted login page into the web or mobile app + +**Example — DaVinci workforce SSO with adaptive MFA:** +1. `ping-foundation` — configure PingOne MT environment, add SSO application +2. `ping-orchestration` — build the DaVinci flow: username/password, MFA step-up branch +3. `ping-universal-services` — invoke PingOne Protect for risk-based MFA decision + +Complete the platform setup in `ping-foundation` first. Then use this skill for the flow layer. Do not design flows before the underlying platform is configured. + +--- + +## MCP tool-first execution + +Before writing any instructions, scan your available tool list for MCP tools that can perform the required operation against the target platform (journey create/update, node update, script create, etc.). + +**If matching tools are available:** use them to build or modify the flow directly. Do not write step-by-step console instructions for operations an MCP tool can execute. + +**If no matching tools are available:** proceed with curated references and console instructions as described below. + +--- + +## Routing — Step 1: Which platform? + +| Platform signal | Branch | +|---|---| +| PingOne ST tenant, PingAM, identity cloud, ForgeRock lineage | [PingOne ST](#pingone-st) | +| PingOne MT + DaVinci | [PingOne MT / DaVinci](#pingone-mt--davinci) | + +--- + +## PingOne ST + +**Sub-routing by task:** + +| Task | Reference | +|---|---| +| Journey design principles, patterns, resilience, security | `references/curated/pingone-st/journey-design-patterns.md` | +| Node composition rules, PageNode usage, child node gotchas | `references/curated/pingone-st/nodes/node-fundamentals.md` | +| Username/password collection, ValidatedUsernameNodeV2, passthrough auth, session entry, lifecycle outcomes | `references/curated/pingone-st/nodes/basic-auth-nodes.md` | +| MFA: WebAuthn, OATH, push, OTP, recovery codes | `references/curated/pingone-st/nodes/mfa-nodes.md` | +| Risk scoring, lockout, CAPTCHA, auth level, PingOne Authorize | `references/curated/pingone-st/nodes/risk-management-nodes.md` | +| User registration, attributes (PRESENT/EQUALS), consent, KBA, T&C, social login, SelectIdP, TimeSince | `references/curated/pingone-st/nodes/identity-management-nodes.md` | +| Scripting, page composition, session, state, async, polling, LoginCount (AT/EVERY), EmailSuspend/EmailTemplate config | `references/curated/pingone-st/nodes/utility-nodes.md` | +| SAML/OIDC federation, Twilio Verify, device/cookie/cert | `references/curated/pingone-st/nodes/federation-contextual-nodes.md` | +| Scripted Decision node deep-dive | `references/curated/pingone-st/scripted-decision-nodes.md` | +| Inner journeys and reusable flow components | `references/curated/pingone-st/inner-journeys.md` | + +**Journey use case patterns** (load when the task matches a named use case): + +| Use case | Reference | +|---|---| +| Account recovery, username reminder, anti-enumeration | `references/curated/pingone-st/journey-use-cases/account-recovery-and-username-reminder.md` | +| Password reset (unauthenticated) or password update (authenticated) | `references/curated/pingone-st/journey-use-cases/password-reset-and-update.md` | +| MFA device registration (WebAuthn, OATH, Push, SMS, VOICE) | `references/curated/pingone-st/journey-use-cases/passwordless-mfa-registration.md` | +| Multi-method MFA authentication with retry loops and recovery codes | `references/curated/pingone-st/journey-use-cases/mfa-authentication-multi-method.md` | +| PingOne Protect risk integration (init/eval pattern, step-up chain) | `references/curated/pingone-st/journey-use-cases/pingone-protect-risk-integration.md` | +| Financial services step-up, transaction authorization, PingOne Authorize | `references/curated/pingone-st/journey-use-cases/financial-services-step-up.md` | +| Progressive profiling (login-count trigger, attribute gate) | `references/curated/pingone-st/journey-use-cases/progressive-profiling.md` | +| Social + local registration and authentication, email verification gate | `references/curated/pingone-st/journey-use-cases/social-and-local-registration-authentication.md` | + +**Generated shortlist** (fallback): +- `references/generated/pingone-st/top-25.json` + +--- + +## PingOne MT / DaVinci + +**Sub-routing by task:** + +| Task | Reference | +|---|---| +| DaVinci flow concepts, connectors, variables | `references/curated/pingone-mt/davinci-overview.md` | +| DaVinci flow design patterns | `references/curated/pingone-mt/davinci-flow-patterns.md` | + +**Generated shortlist** (fallback): +- `references/generated/pingone-mt/top-25.json` + +--- + +## Retrieval escalation + +1. Load 1–3 curated anchors matching the detected platform and task. Stop if sufficient. +2. If not sufficient, scan the matching generated shortlist. Pull summaries for relevant titles only. + +## Cross-skill escalation + +| If the task also involves... | Reference skill | +|---|---| +| Platform setup not yet complete | `ping-foundation` | +| Shared services (Protect, Verify, IGA, Credentials) within the flow | `ping-universal-services` | +| App/SDK code integration | `ping-app-integration` | +| Platform selection or orientation | `ping-quickstart` | diff --git a/plugins/ping-identity/skills/ping-orchestration/ping-marketplace.json b/plugins/ping-identity/skills/ping-orchestration/ping-marketplace.json new file mode 100644 index 0000000..8cd0109 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/ping-marketplace.json @@ -0,0 +1,34 @@ +{ + "skill_id": "ping-orchestration", + "display_name": "Ping Identity Orchestration", + "description": "Design and build authentication flows, journeys, and orchestration logic. Covers PingOne ST journeys and authentication trees, DaVinci flows (PingOne MT), scripted decision nodes, inner journeys, and multi-step registration and login patterns.", + "version": "1.0.0", + "publisher": "Ping Identity", + "tags": { + "product_family": ["pingone-mt", "pingone-st"], + "products": [ + "pingone-st", + "pingam", + "davinci", + "pingone" + ], + "capabilities": ["orchestration"], + "audience": ["developer", "architect", "admin"], + "use_cases": ["workforce", "customer"], + "protocols": ["oidc", "oauth2", "saml"] + }, + "entry_point": "SKILL.md", + "references": { + "curated_path": "references/curated/", + "generated_path": "references/generated/" + }, + "related_skills": [ + "ping-foundation", + "ping-universal-services", + "ping-app-integration", + "ping-quickstart" + ], + "min_context_tokens": 500, + "max_curated_docs": 3, + "max_shortlist_docs": 25 +} diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-mt/davinci-flow-patterns.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-mt/davinci-flow-patterns.md new file mode 100644 index 0000000..5480082 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-mt/davinci-flow-patterns.md @@ -0,0 +1,40 @@ +--- +title: "PingOne MT — DaVinci Flow Patterns" +product_family: pingone-mt +products: ["davinci", "pingone"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: draft +canonical: false +last_updated: "2026-05-19" +slug: "" +--- + +# PingOne MT — DaVinci Flow Patterns + +_Curated anchor stub. Replace with authored content covering common DaVinci flow patterns: login, registration, MFA step-up, progressive profiling, and error handling._ + +## Scope + +**Covers:** Common DaVinci flow design patterns, branching logic, error paths, reusable subflow patterns. +**Does NOT cover:** DaVinci concepts and setup — see `davinci-overview.md`. + +## Key steps / content + +_To be authored._ + +## Prerequisites + +- PingOne MT environment with DaVinci enabled +- At least one DaVinci connector configured + +## Related references + +- `references/curated/pingone-mt/davinci-overview.md` + +## Source + +[DaVinci flow design](https://docs.pingidentity.com/davinci/latest/flows-overview.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-mt/davinci-overview.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-mt/davinci-overview.md new file mode 100644 index 0000000..f8de382 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-mt/davinci-overview.md @@ -0,0 +1,40 @@ +--- +title: "PingOne MT — DaVinci Overview" +product_family: pingone-mt +products: ["davinci", "pingone"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: draft +canonical: false +last_updated: "2026-05-19" +slug: "" +--- + +# PingOne MT — DaVinci Overview + +_Curated anchor stub. Replace with authored content covering DaVinci concepts: flows, connectors, variables, subflows, and the relationship between DaVinci and PingOne policies._ + +## Scope + +**Covers:** DaVinci flow model, connector types, flow variables, subflow patterns, DaVinci policy assignment in PingOne. +**Does NOT cover:** PingOne MT environment and app setup — see `ping-foundation`. Detailed connector configuration — see per-connector references. + +## Key steps / content + +_To be authored._ + +## Prerequisites + +- PingOne MT environment with DaVinci enabled +- Admin access to DaVinci console + +## Related references + +- `references/curated/pingone-mt/davinci-flow-patterns.md` + +## Source + +[DaVinci overview](https://docs.pingidentity.com/davinci/latest/davinci-overview.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-design-patterns.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-design-patterns.md new file mode 100644 index 0000000..92969ec --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-design-patterns.md @@ -0,0 +1,299 @@ +--- +title: "AIC and PingAM — Journey Design Reference" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect", "admin"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-19" +slug: "https://docs.pingidentity.com/pingoneaic/journeys/auth-nodes.html" +--- + +# AIC and PingAM — Journey Design Reference + +How to design, review, and reason about AIC and PingAM journeys in a way that is useful to architects, developers, support teams, and product teams. Applies to sign-in, MFA, registration, passwordless, recovery, profile management, delegated administration, and cross-channel identity flows. + +## Scope + +**Covers:** Journey design principles, lifecycle modeling, risk and fallback patterns, session behavior, messaging, supportability, and product-specific notes for AIC and PingAM. +**Does NOT cover:** Individual node configuration — see `nodes/`. DaVinci flow design — see `../pingone-mt/davinci-overview.md`. Platform setup — see `ping-foundation`. + +--- + +## Before designing: seven questions to answer first + +Before suggesting any node or implementation detail, an agent should be able to answer: + +1. Who is the user or actor? +2. What state are they in now? +3. What does success mean? +4. What should happen if risk increases? +5. What should happen if a dependency fails? +6. What changes in session or assurance posture after success or failure? +7. What will support need to reconstruct the experience later? + +If any of these are undefined, the journey is not ready to build. + +--- + +## Core design principles + +### Start with the user and lifecycle state, not the node list + +Define actor types first: customer, employee, admin, delegated admin, partner admin, or machine actor. + +Define lifecycle states: invited, pending verification, active, suspended, disabled, locked, closed. + +Define the attributes that matter: username, email, phone, tenant, locale, MFA state, recovery identifiers, consent state, role, group, entitlement state. + +Keep these meanings consistent across login, registration, recovery, and step-up flows. If one app interprets the same user state differently from another, the experience will drift and support will become harder. + +### Keep the journey explicit and explainable + +A journey diagram should show the happy path, risk branches, fallback branches, degraded-mode behavior, and user-facing outcomes. + +Every branch should answer: what happened, what the user sees, what they can do next, and whether support or an admin is needed. + +Avoid hidden behavior that only exists in scripts or policy conditions with no user-visible explanation. + +### Match friction to risk + +Use a small, understandable set of risk outcomes: allow, light check, step-up, limited fallback, or safe deny. + +Do not challenge every user the same way. Do not under-protect privileged or high-impact actions because the main flow was optimized for speed. + +The right question is not "can we add more authentication?" but "when is additional friction justified, for whom, and for which action?" + +### Design for clear fallback behavior + +Journeys should define what happens when: +- A risk engine is unavailable +- An email or SMS provider is delayed +- A factor is unavailable +- A link is expired or a token is stale +- An upstream IdP is slow +- A required claim is missing + +Avoid loops, blank screens, silent retries, and raw technical errors. If the preferred path is unavailable, the user should get either a safe alternate route or a clear explanation of why the flow cannot continue. + +### Keep session behavior understandable + +Decide explicitly what happens after: sign-in, password change, privilege elevation, MFA reset, device deregistration, logout, and entitlement changes. + +Be explicit about idle timeout, max lifetime, renewal, forced re-authentication, and revocation behavior. + +If a session posture changes, the experience should make that visible instead of forcing support to infer it from logs. + +### Keep messaging safe, human-readable, localized, and accessible + +User-facing text should explain the next step without exposing raw policy outcomes, protocol details, stack traces, or account existence. + +This matters especially for login, recovery, step-up, and degraded-mode messaging. Accessibility and localization are not polish items — they are part of the journey definition. + +### Design for change and operations + +Important journeys should be observable, versioned, tested, and safe to roll forward or back. + +Identity journeys are products, not one-time diagrams. They need release discipline, telemetry, support readiness, and rollback plans. + +--- + +## Good default journey shape + +### Step 1 — Define persona, channel, trust level, and success criteria + +- Is this SIAM, workforce, B2B, or delegated admin? +- Does the flow start in hosted UI, an SDK, a native app, a browser redirect, a webview, or an external IdP? +- What outcome should the user achieve, in business terms? + +### Step 2 — Model the happy path first + +Start with the shortest correct flow for the intended user. Confirm which systems are read from, which are written to, and what timing assumptions exist. Keep early branching to a minimum until the intended baseline experience is clear. + +### Step 3 — Add risk and policy branches + +- What causes extra friction? +- What causes a hard block versus limited fallback? +- Where do privileged flows differ from normal ones? + +### Step 4 — Add fallback and degraded-mode behavior + +- What happens if signals, factors, providers, or claims are unavailable? +- Include retry guidance, alternate channels, assisted options, and stop conditions. +- Explicitly prevent redirect loops and repeated returns to unusable screens. + +### Step 5 — Add safe messaging and state transitions + +Use non-technical, localized, accessible messaging. Make recovery, consent, timeout, step-up, and error states understandable. Preserve anti-enumeration requirements wherever account existence or user status could leak. + +### Step 6 — Add telemetry and supportability + +Include correlation IDs or equivalent reference codes where the user experience or support workflow needs them. Capture journey version, major branch decisions, failure categories, and abandonment points. Make sure support can reconstruct what the user saw. + +### Step 7 — Version and release conservatively + +Clone or version before major customization. Roll out high-impact identity changes in controlled stages. Know how to roll back without breaking users who are mid-journey. + +--- + +## What "good" looks like by journey type + +### Sign-in and MFA + +A good sign-in journey is short for low-risk users, stronger for high-risk situations, and predictable across channels. + +- Use contextual risk to decide when to add friction instead of applying the same challenge to every user and channel. +- Keep prompts and outcomes consistent across hosted, SDK, mobile, embedded, and custom UI. +- Prefer phishing-resistant and lower-friction approaches where appropriate (passkeys, passwordless). +- Define what happens when the preferred authenticator is unavailable. +- Define what happens when the user changes device, location, browser, privilege level, or assurance level. +- Make session upgrades, step-up prompts, and token posture changes visible in the UX. + +**Common failure patterns:** too much friction for low-risk users; too little for privileged users; inconsistent MFA between mobile and web; no alternate factor when the preferred factor fails; unexplained step-up prompts. + +### Registration and onboarding + +A good registration journey aligns to the identity model and to downstream system expectations. + +- Align form fields and validation with the identity model so registration does not drift from profile, recovery, and entitlement logic. +- Define which attributes are required, optional, conditionally required, or externally mastered. +- Decide where verification happens: email, phone, MFA setup, admin approval, or identity verification. +- Show users what is happening when provisioning or synchronization takes time. +- Test under realistic load including email verification, MFA setup, and cross-device handoffs. +- Include edge cases: duplicate emails, existing accounts, partially provisioned users, disabled identities, conflicting invites. + +**Common failure patterns:** attributes that do not match downstream requirements; no clear status when provisioning lags; assuming single-device flows; weak handling of duplicate or partially created accounts. + +### Recovery and self-service + +Recovery is one of the highest-risk journey families and should be treated as such. + +- Treat recovery as a high-risk journey. Add stronger verification, step-up authentication, or identity verification where justified. +- Use non-revealing messages ("If an account exists, we've sent instructions") paired with rate limits, lockouts, and clear next steps. +- Recovery artifacts (links, codes, tokens) should be short-lived, one-time use, and invalidated after use or suspected compromise. +- Define distinct handling for: password reset, username reminder, MFA reset, device recovery, email/phone change, and assisted recovery. +- Define what happens when limits trigger, when abuse is suspected, and when assisted recovery is required. + +**Common failure patterns:** reusable or long-lived recovery artifacts; messages with no next step; strong MFA in sign-in but weak verification in recovery; delivery-channel failures with no alternate route. + +### Passwordless and step-up evolution + +The long-term direction should be lower friction with stronger assurance. + +- Reduce dependence on passwords where possible. +- Prefer strong authenticators over memorized secrets when the use case supports it. +- Use step-up based on risk and action sensitivity rather than applying it everywhere by default. +- Roll out passwordless changes incrementally — only some users may be ready. +- Make sure fallback and recovery are mature before aggressively reducing password-based options. + +**Common failure patterns:** assuming all populations are ready for the same passwordless posture; removing fallback too early; excessive step-up fatigue; changing friction without explaining why. + +### Profile, entitlement, and delegated flows + +These flows are often treated as secondary, but they are where state drift becomes visible. + +- Treat profile updates, device changes, consent changes, role changes, and delegated admin actions as identity journeys. +- Make state changes visible and predictable. +- Define how session and access should change after profile, role, or device updates. +- In B2B and delegated admin journeys, make privilege scope obvious and separate from end-user views. +- Show admins what they can do, cannot do, and the current state of the tenant or user. + +**Common failure patterns:** role changes that do not affect active sessions as expected; delegated admin actions with weak scope cues; missing auditability for high-impact actions. + +--- + +## Common watch-outs + +- Do not let different apps interpret the same user state, role, or attribute differently — that creates drift across login, recovery, delegated, and profile flows. +- Do not leak account existence or internal conditions through recovery, sign-in, step-up, or error messages. +- Do not assume web-only behavior. Cross-channel transitions, deep links, app switching, webviews, and native flows need explicit design and testing. +- Do not rely on undefined degraded behavior. Risk engine outages, directory lag, email/SMS delays, claim gaps, and IdP failures should have intentional fallback UX. +- Do not let session and privilege changes be invisible. Regenerate or invalidate sessions after sign-in, password change, privilege change, or device change, and make the effect clear. +- Do not customize OOTB flows without a rollback path or clone/version strategy. +- Do not ship journey changes without telemetry, version awareness, and support readiness. +- Do not treat accessibility, localization, or cross-device behavior as optional. + +--- + +## Product-specific notes + +### AIC + +AIC guidance should be read with a tenant-security and operational lens. + +- AIC security guidance stresses HTTPS-only usage, trusted cookie-domain configuration, CORS controls, CSRF protections for `/am/json/` endpoints, and audit logging as part of secure tenant design. +- For account recovery, AIC guidance recommends step-up authentication, risk-based signals (PingOne Protect), stronger identity verification where needed, verified and unique recovery identifiers, and regular review of recovery processes. + +When reasoning about AIC journeys, pay attention to: +- How hosted pages, cookies, and APIs interact across domains +- How tenant security controls affect experience design +- How recovery identifiers are verified and protected +- How risk signals affect sign-in and recovery consistency +- How auditability and support tracing are preserved + +### PingAM + +PingAM guidance should be read with a realm, redirect, and session-governance lens. + +- Reserve the root realm for administrative operations; use another realm (e.g., `alpha`) for journey work. +- Enable only the `goto`/redirect targets you actually trust after journey completion — PingAM denies them by default until the validation service is configured. +- Be intentional with session lifetime settings and client-side sessions, because session behavior is a core part of the security outcome. + +When reasoning about PingAM journeys, pay attention to: +- Realm boundaries and administrative separation +- Redirect and return URL trust boundaries +- Session lifetime and idle timeout posture +- How the journey hands control back to the relying application +- How privilege and assurance changes affect active sessions + +--- + +## Recommended agent behavior when using this reference + +**Speak in terms of journey intent, risk, fallback, session impact, state transitions, and user-visible behavior — not just nodes and plumbing.** + +When describing or proposing a journey, include: +- Who the user is +- What state they begin in +- What success means +- What the main path is +- Where risk or policy branches appear +- What fallback exists if dependencies fail +- What changes in session, token, or assurance posture occur +- What the user sees at each important branch +- What telemetry or traceability is needed + +When recommending changes, call out: +- Security impact +- User-experience impact +- Supportability impact +- Rollout and rollback considerations +- Cross-channel implications + +If the request is implementation-specific, follow up with environment-specific material before prescribing exact nodes, scripts, policy settings, redirect patterns, or session settings. + +If the request is high level, stay at the level of design patterns, user-visible behavior, operational watch-outs, and journey structure. + +**Prefer guidance that is safe, explainable, supportable, and testable over guidance that is merely technically possible.** + +--- + +## Related references + +- `nodes/basic-auth-nodes.md` +- `nodes/mfa-nodes.md` +- `nodes/risk-management-nodes.md` +- `nodes/identity-management-nodes.md` +- `nodes/utility-nodes.md` +- `nodes/federation-contextual-nodes.md` +- `scripted-decision-nodes.md` +- `inner-journeys.md` + +## Source + +[Authentication nodes — PingOne AIC](https://docs.pingidentity.com/pingoneaic/journeys/auth-nodes.html) +[Authentication node reference](https://docs.pingidentity.com/auth-node-ref/latest/overview.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/account-recovery-and-username-reminder.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/account-recovery-and-username-reminder.md new file mode 100644 index 0000000..77f668c --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/account-recovery-and-username-reminder.md @@ -0,0 +1,138 @@ +--- +title: "PingOne ST — Account Recovery and Username Reminder" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-21" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — Account Recovery and Username Reminder + +Design patterns for the OOTB account recovery and username reminder journey family, derived from live AIC journey exports. + +## Scope + +**Covers:** Anti-enumeration wiring, EmailSuspendNode resume URI pattern, DisplayUserNameNode, in-browser vs. email-body username delivery, email template variables. +**Does NOT cover:** Password reset or password update — see `journey-use-cases/password-reset-and-update.md`. MFA reset — compose with `nodes/mfa-nodes.md`. + +--- + +## Account Recovery (Username Recovery) + +The OOTB Account Recovery journey recovers a **username** (not a password) by looking up the account by email address and displaying the username in the browser after email verification. + +**Node sequence:** +``` +PageNode (collect mail) + → IdentifyExistingUserNode (identityAttribute: mail, identifier: userName) + → true AND false → EmailSuspendNode (anti-enumeration) + → DisplayUserNameNode (shows recovered username in browser) + → InnerTreeEvaluatorNode (tree: Login) + → true → SuccessNode + → false → FailureNode +``` + +**Email template:** `emailVerification` — contains `{{object.resumeURI}}` as the resume link. 24-hour expiry. English only in OOTB. + +**Key decision:** Username is shown in the browser after email verification (via `DisplayUserNameNode`). The user then proceeds directly to Login. This is suitable when you want the user to see their username and immediately authenticate. + +--- + +## Forgotten Username (Email Delivery) + +The OOTB Forgotten Username journey sends the username inside the email body rather than displaying it in the browser. + +**Node sequence:** +``` +PageNode (collect mail, validateInputs: false) + → IdentifyExistingUserNode (identityAttribute: mail, identifier: userName) + → true AND false → EmailSuspendNode (anti-enumeration) + → InnerTreeEvaluatorNode (tree: Login) + → true → SuccessNode + → false → FailureNode +``` + +**Email template:** `forgottenUsername` — contains `{{object.userName}}` inline in the email body; also provides `{{object.resumeURI}}` as a login link. Bilingual (English + French) in OOTB — the only bilingual template in the standard set. + +**Key decision:** No `DisplayUserNameNode` — the username never appears in the browser. The user receives it by email and then follows the resume link to the Login journey. + +--- + +## Anti-Enumeration Pattern + +**Critical:** Both `true` and `false` outcomes from `IdentifyExistingUserNode` must connect to the **same** `EmailSuspendNode`. The user-facing message must be identical regardless of whether an account was found. + +``` +IdentifyExistingUserNode + → true ─┐ + ├─→ EmailSuspendNode ("If the details provided match our records...") + → false ─┘ +``` + +**User-facing message (OOTB):** `"If the details provided match our records, you will receive an email with further instructions."` + +**Never route `true` and `false` to different messages** — that leaks account existence and violates the OWASP recommendation against username enumeration. + +**Rate limiting:** The anti-enumeration message alone does not prevent abuse. Add rate limiting at the WAF or API gateway level for production deployments. + +--- + +## EmailSuspendNode Configuration + +| Field | Value | Notes | +|---|---|---| +| `emailTemplateName` | `emailVerification` or `forgottenUsername` | Template must contain `{{object.resumeURI}}` | +| `objectLookup` | `true` | Required for the template to access managed object attributes | +| Message | User-facing browser message | Shown while the user waits for the email | + +**Resume URI behavior:** When the user clicks the link in the email, the journey resumes at the node immediately after `EmailSuspendNode`. The resume URI is single-use and time-limited (24 hours in OOTB templates). + +--- + +## Email Template Variables + +| Variable | Available in | Notes | +|---|---|---| +| `{{object.resumeURI}}` | Both templates | Journey resume link; required for email-gated flows | +| `{{object.userName}}` | `forgottenUsername` | Embeds the username in the email body; use `{{#if object.userName}}` conditional | +| `{{object.mail}}` | Available | User's email address | + +--- + +## DisplayUserNameNode vs. email-body delivery + +| Approach | When to use | +|---|---| +| `DisplayUserNameNode` (Account Recovery) | User should see their username in the browser and immediately log in; in-person or single-device flow | +| Email body delivery (Forgotten Username) | Username delivered out-of-band; user may be on a different device when reading the email | + +--- + +## Inner Journey Handoff + +Both OOTB journeys end with `InnerTreeEvaluatorNode(tree: Login)` — the user is routed into the Login journey after recovery. This avoids duplicating authentication logic in the recovery journey. + +**Configuration:** The Login inner journey must exist and be activated in the same realm. + +## Prerequisites + +- Email notification service configured in the tenant +- Email templates (`emailVerification`, `forgottenUsername`) present in IDM notification templates +- `managed/alpha_user` with `mail` and `userName` attributes accessible + +## Related references + +- `journey-use-cases/password-reset-and-update.md` +- `nodes/identity-management-nodes.md` +- `nodes/utility-nodes.md` + +## Source + +[Authentication nodes — PingOne AIC](https://docs.pingidentity.com/pingoneaic/journeys/auth-nodes.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/financial-services-step-up.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/financial-services-step-up.md new file mode 100644 index 0000000..b36f723 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/financial-services-step-up.md @@ -0,0 +1,194 @@ +--- +title: "PingOne ST — Financial Services Step-Up and Transaction Authorization" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: ["protect"] +audience: ["developer", "architect"] +use_cases: ["customer", "workforce"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-21" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — Financial Services Step-Up and Transaction Authorization + +Design patterns for financial-grade authentication journeys: full lifecycle credential outcomes, PingOne Authorize for per-transaction policy, step-up MFA, KBA, and operational routing. Derived from the Financial Services and Money Transfer journey exports. + +## Scope + +**Covers:** `IdentityStoreDecisionNode` lifecycle outcomes, `PingOneAuthorizeNode` transaction authorization, PUSH_REQ/APPROVAL_REQ/KBA_REQUIRED action responses, Enhanced KBA, `ConfigProviderNode`, `SetSuccessUrlNode`, `PollingWaitNode`. +**Does NOT cover:** PingOne Protect risk integration — see `journey-use-cases/pingone-protect-risk-integration.md`. MFA device registration — see `journey-use-cases/passwordless-mfa-registration.md`. + +--- + +## Main Journey Structure + +``` +ScriptedDecisionNode ("Prerequisites & Init Variables") + → ScriptedDecisionNode ("Is Protect Analysis Required?") + → InnerTreeEvaluatorNode (Initialize P1 Protect) + → InnerTreeEvaluatorNode (Protect Evaluation & Mitigation) + → InnerTreeEvaluatorNode (SignOn) + → AuthLevelDecisionNode ("MFA Based On Risk Level?") + → true → InnerTreeEvaluatorNode (MFA Authentication) + → false → continue + → InnerTreeEvaluatorNode (Manage Account) + → SetSuccessUrlNode ("Redirect to Manage Account Page") + → PollingWaitNode +``` + +The `AuthLevelDecisionNode` after SignOn checks whether risk evaluation elevated the auth level — only triggers MFA if needed. This is the risk-driven step-up pattern. + +--- + +## IdentityStoreDecisionNode — Full Lifecycle Outcomes + +Used in the SignOn inner journey instead of `DataStoreDecisionNode` to handle account lifecycle states explicitly. + +- Outcomes: **TRUE** / **FALSE** / **LOCKED** / **EXPIRED** / **CANCELLED** + +**Required wiring per outcome:** + +| Outcome | Recommended routing | +|---|---| +| `TRUE` | Continue journey (authentication success) | +| `FALSE` | Retry limit → FailureNode | +| `LOCKED` | Message node ("Account locked") → account recovery flow or FailureNode | +| `EXPIRED` | Password change inner journey → re-authenticate | +| `CANCELLED` | FailureNode (user cancelled the authentication) | + +Never leave `LOCKED` or `EXPIRED` routing to a generic FailureNode in production — users cannot self-service their way out. + +--- + +## Transaction Authorization: PingOneAuthorizeNode + +Used to enforce fine-grained policy on individual transactions. Evaluates an authorization policy in PingOne Authorize, distinct from authentication. + +**Standard payment/transfer pattern:** +``` +PageNode (collect transaction details) + → PingOneAuthorizeNode + → permit → PatchObjectNode (update balance/record) → SuccessNode + → deny → message or FailureNode + → PUSH_REQ → ScriptedDecisionNode ("Push Approval Notification") + → continue / error / noMail → PageNode ("Transfer Success") + → APPROVAL_REQ → EmailSuspendNode ("Transfer Approval via Email") + → [user approves by clicking link] + → PatchObjectNode → SuccessNode + → indeterminate → FailureNode + → clientError → FailureNode +``` + +**`indeterminate` and `clientError` must have explicit handlers.** Do not leave them unwired — an indeterminate authorization should fail safe (deny), not silently succeed. + +**KBA-based authorization (Enhanced KBA):** +``` +PingOneAuthorizeNode + → KBA_REQUIRED → ScriptedDecisionNode ("Calculate KBA Threshold") + → PageNode ("Display Questions") + outcomes: error / limitExceeded / noQuestions / questions + → questions: PageNode (KBA answers) + → SuccessNode / FailureNode + → permit → proceed without KBA +``` + +`PingOneAuthorizeNode` determines *whether* KBA is required via policy — the journey then presents the appropriate questions. + +--- + +## ConfigProviderNode for Externalized Messaging + +Used to decouple user-facing message text from journey scripting. + +- Outcomes: **outcome** / **CONFIGURATION_FAILED** +- Reads from ESV (environment-level secret/variable) or configuration store +- `CONFIGURATION_FAILED` must be handled — use a fallback hardcoded message rather than routing to FailureNode + +**Pattern:** +``` +ConfigProviderNode ("Set Success Message") + → outcome → [next node uses successMessage from shared state] + → CONFIGURATION_FAILED → [proceed with fallback message] +``` + +--- + +## SetSuccessUrlNode — Post-Journey Redirect + +Used to redirect the user to an application page after the journey completes, rather than the default OIDC redirect. + +- Single `outcome` +- Place after the last journey step, before `PollingWaitNode` if async provisioning is needed + +**Observed use:** Financial Services and Money Transfer redirect to the application's account management or transfer page after session establishment. + +--- + +## PollingWaitNode at Journey End + +Used to wait for asynchronous provisioning or account operations to complete before declaring success. + +- `secondsToWait: 5` +- Outcomes: **DONE** / **EXITED** +- Observed at the end of: registration journeys (waiting for IDM to complete provisioning), financial services main journey (waiting for session enrichment) +- `EXITED`: route to SuccessNode — user has dismissed the wait screen; do not block on polling + +--- + +## T&C Enforcement in Authenticated Journeys + +Authentication journeys in financial-grade use cases enforce current T&C version on each login: + +``` +TermsAndConditionsDecisionNode + → false (not accepted or outdated) → AcceptTermsAndConditionsNode → continue + → true (accepted and current) → continue +``` + +This ensures users who have not accepted a new T&C version are prompted on the next sign-in, not just at registration. + +--- + +## Email Verification Gate in SignOn + +``` +AttributeValueDecisionNode ("Is Email Verified?") + → false → [email verification inner journey] + → [verified] → continue + → true → continue +``` + +Users who registered without completing email verification are gated on each subsequent login until they verify. + +--- + +## Security Considerations + +- `IdentityStoreDecisionNode(LOCKED)` must route to a meaningful UX — do not silently fail locked accounts +- `PingOneAuthorizeNode(indeterminate)` must fail safe — deny by default +- High-risk Protect outcomes should disable the account and send an admin notification before routing to Failure +- All `PingOneProtectResultNode` calls must appear at both success and failure paths +- Session should be re-evaluated or re-issued after a privilege change or step-up MFA event + +## Prerequisites + +- PingOne Protect service enabled (for risk integration) +- PingOne Authorize service enabled with transaction policies configured (for PingOneAuthorizeNode) +- Twilio Verify credentials configured (for SMS/VOICE MFA paths) +- Email notification templates: `disabledAccountRecovery`, `magicLinkTemplate`, transaction approval templates + +## Related references + +- `journey-use-cases/pingone-protect-risk-integration.md` +- `journey-use-cases/mfa-authentication-multi-method.md` +- `nodes/risk-management-nodes.md` +- `nodes/identity-management-nodes.md` + +## Source + +[Authentication nodes — PingOne AIC](https://docs.pingidentity.com/pingoneaic/journeys/auth-nodes.html) +[PingOne Authorize](https://docs.pingidentity.com/pingoneauthorize/latest/overview.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/mfa-authentication-multi-method.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/mfa-authentication-multi-method.md new file mode 100644 index 0000000..85537cc --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/mfa-authentication-multi-method.md @@ -0,0 +1,199 @@ +--- +title: "PingOne ST — Multi-Method MFA Authentication" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: ["mfa"] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-21" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — Multi-Method MFA Authentication + +Design patterns for the multi-method MFA authentication inner journey, supporting up to 8 factors with per-method retry loops and recovery code fallbacks. Derived from CIAM Passwordless, Financial Services, and Threat Detection journey exports. + +## Scope + +**Covers:** Device selection, per-method authentication nodes, retry-loop-with-lockout, recovery code paths per method, inner journey structure. +**Does NOT cover:** MFA device registration — see `journey-use-cases/passwordless-mfa-registration.md`. Risk-based step-up routing — see `journey-use-cases/pingone-protect-risk-integration.md`. + +--- + +## Structure Overview + +MFA authentication is always implemented as a **dedicated inner journey** called from the main journey via `InnerTreeEvaluatorNode`. This keeps MFA logic reusable and independently updatable. + +**Main journey call:** +``` +InnerTreeEvaluatorNode (tree: MFA Authentication) + → true → proceed (MFA passed) + → false → FailureNode +``` + +--- + +## Device Selection + +**Entry pattern:** A `PageNode` presents the device selector. The selection drives outcomes via an embedded `ScriptedDecisionNode` ("Select MFA Device") that reads the user's registered device state from shared state and returns the chosen method as its outcome. + +**Observed outcomes:** `EMAIL` / `SMS` / `VOICE` / `FIDO2` / `OATH` / `PUSH` / `Magic Link` / `Error` + +Each outcome routes to a per-method authentication sub-path. + +--- + +## Per-Method Authentication Paths + +### OATH (TOTP) + +``` +PageNode ("Enter Verification Code") + children: ScriptedDecisionNode ("Validate Verification Code Input Script") + + OathTokenVerifierNode (isRecoveryCodeAllowed: true) + → successOutcome → SuccessNode + → failureOutcome → RetryLimitDecisionNode + → notRegisteredOutcome → GetAuthenticatorAppNode → OATH Registration inner journey + → recoveryCodeOutcome → PageNode ("Enter Recovery Code") → [recovery code path] +``` + +**OathTokenVerifierNode config:** `totpTimeInterval: 30`, `totpHashAlgorithm: HMAC_SHA1`, `totpTimeSteps: 2`, `maximumAllowedClockDrift: 5`, `isRecoveryCodeAllowed: true` + +### Push + +``` +PushAuthenticationSenderNode (mandatory: true, messageTimeout: 120000) + → SENT → PushWaitNode (secondsToWait: 5) + → DONE → PushResultVerifierNode + → TRUE → SuccessNode + → FALSE → FailureNode + → WAITING → loop back to PushWaitNode + → EXPIRED → RetryLimitDecisionNode → Retry → re-send push / Reject → FailureNode + → EXITED → PageNode (OTP fallback for users who dismiss the push) + → NOT_REGISTERED → GetAuthenticatorAppNode → Push Registration inner journey +``` + +### WebAuthn (FIDO2) + +``` +WebAuthnAuthenticationNode (isRecoveryCodeAllowed: true, asScript: true) + → success → SuccessNode + → unsupported → FailureNode + → noDevice → GetAuthenticatorAppNode → WebAuthn Registration inner journey + → failure → RetryLimitDecisionNode + → error → FailureNode + → recoveryCode → PageNode ("Enter Recovery Code") → [recovery code path, WEB_AUTHN typed] +``` + +### Email OTP + +``` +OneTimePasswordGeneratorNode (length: 6) + → ScriptedDecisionNode ("Send OTP Email") [calls IDM openidm.action() to deliver via email] + → PageNode ("Collect OTP") + children: ScriptedDecisionNode (UI validator) + OneTimePasswordCollectorDecisionNode (passwordExpiryTime: 5) + → true → SuccessNode + → false → RetryLimitDecisionNode → retry loop / Reject → FailureNode +``` + +### SMS / VOICE (Twilio Verify) + +``` +VerifyAuthIdentifierNode (identifierAttribute: telephoneNumber) + → True → VerifyAuthSenderNode (channel: SMS or CALL) + → true → PageNode ("Collect OTP") + children: VerifyAuthCollectorDecisionNode + → true → SuccessNode + → false → RetryLimitDecisionNode → retry loop + → error → FailureNode + → False / Error → FailureNode +``` + +### Magic Link (Email Suspend) + +``` +EmailSuspendNode (emailTemplateName: magicLinkTemplate, objectLookup: true) + → outcome → SuccessNode +``` + +The simplest path — journey suspends, user clicks the link in the email, journey resumes at SuccessNode. + +--- + +## Retry-Loop-With-Lockout Pattern + +Every code-entry path (OATH, OTP, recovery codes) uses this consistent retry loop: + +``` +[Failure outcome from verifier] + → RetryLimitDecisionNode (retryLimit: 3, incrementUserAttributeOnFailure: true) + → True (Retry) → ScriptedDecisionNode ("Set Invalid Code Error Message") + → [Input PageNode] ← reads invalidCodeErrorMessage from shared state + → False (Reject) → FailureNode +``` + +The `ScriptedDecisionNode` writes `invalidCodeErrorMessage` to shared state. The PageNode script reads it via `callbacksBuilder.textOutputCallback(2, invalidCodeErrorMessage)` and renders it inline on the next page load — no extra round-trip. + +--- + +## Recovery Code Paths + +Every MFA method that supports recovery codes follows the same recovery sub-path: + +``` +[MFA verifier node] → recoveryCodeOutcome + → PageNode ("Enter Recovery Code") + children: ScriptedDecisionNode ("Validate Recovery Code Input Script") + + RecoveryCodeCollectorDecisionNode (recoveryCodeType: ) + → True → SuccessNode + → False → RetryLimitDecisionNode → retry / Reject → FailureNode +``` + +**`recoveryCodeType` values by method:** + +| MFA method | recoveryCodeType | +|---|---| +| OATH / TOTP | `OATH` | +| WebAuthn | `WEB_AUTHN` | +| Push | `PUSH` | + +Mismatching `recoveryCodeType` to the authentication method causes validation failures. + +--- + +## Inner Journey Composition + +MFA authentication is kept as a separate inner journey. Never embed all MFA paths directly in the main journey graph — the resulting node count makes the journey unmanageable and prevents reuse. + +**Recommended structure:** +``` +Main journey + → InnerTreeEvaluatorNode (ThreatDetection) ← risk evaluation + → InnerTreeEvaluatorNode (MFADeviceRegistration) ← register device if not enrolled + → InnerTreeEvaluatorNode (MFAAuthentication) ← challenge with registered device + → SuccessNode +``` + +The `MFADeviceRegistration` inner journey is only needed in journeys that allow just-in-time registration. If all users must pre-enroll, it can be omitted. + +## Prerequisites + +- User must have at least one MFA device registered (or device registration inner journey must be in the chain before this one) +- Email notification service configured for Email OTP and Magic Link methods +- Twilio Verify credentials configured for SMS/VOICE methods +- FIDO2 requires HTTPS + +## Related references + +- `journey-use-cases/passwordless-mfa-registration.md` +- `journey-use-cases/pingone-protect-risk-integration.md` +- `nodes/mfa-nodes.md` +- `nodes/federation-contextual-nodes.md` + +## Source + +[Authentication nodes — PingOne AIC](https://docs.pingidentity.com/pingoneaic/journeys/auth-nodes.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/password-reset-and-update.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/password-reset-and-update.md new file mode 100644 index 0000000..a5eba02 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/password-reset-and-update.md @@ -0,0 +1,131 @@ +--- +title: "PingOne ST — Password Reset and Authenticated Update" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-21" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — Password Reset and Authenticated Update + +Design patterns for unauthenticated password reset (email-gated) and authenticated password update (session-gated), derived from live AIC journey exports. + +## Scope + +**Covers:** Unauthenticated reset via email, authenticated password change with passwordless user branch, ValidatedPasswordNode settings, PatchObjectNode for password write. +**Does NOT cover:** Username recovery — see `journey-use-cases/account-recovery-and-username-reminder.md`. MFA reset — compose with `nodes/mfa-nodes.md`. + +--- + +## Pattern 1 — Unauthenticated Password Reset (Email-Gated) + +Used when the user does not have an active session. Identity is verified via email before a new password is accepted. + +**Node sequence:** +``` +PageNode (collect mail, required: true) + → IdentifyExistingUserNode (identityAttribute: mail, identifier: userName) + → true AND false → EmailSuspendNode (anti-enumeration) + → [journey suspends — user clicks link in email to resume] + → PageNode (collect new password, ValidatedPasswordNode, validateInput: true) + → PatchObjectNode (identityResource: managed/alpha_user) + → PATCHED → SuccessNode + → FAILURE → FailureNode +``` + +**Email template:** `resetPassword` — contains `{{object.resumeURI}}` as the reset link. Bilingual (English + French) in OOTB. + +**Anti-enumeration:** Both `IdentifyExistingUserNode` outcomes (`true` and `false`) route to the same `EmailSuspendNode`. User sees: `"If the details provided match our records, you will receive an email with further instructions."` + +**PatchObjectNode configuration:** +- `identityResource: managed/alpha_user` +- `patchAsObject: false` +- `ignoredFields: []` + +**ValidatedPasswordNode:** `validateInput: true` — new password is validated against the realm's password policy before `PatchObjectNode` writes it. + +--- + +## Pattern 2 — Authenticated Password Update (Session-Gated) + +Used when the user has an active session. No login form — the user is identified from the session. Handles both password-based and passwordless users. + +**Node sequence:** +``` +SessionDataNode (sessionDataKey: UserToken, sharedStateKey: userName) + → AttributePresentDecisionNode (presentAttribute: password) + → true (password user): PageNode ("Verify Existing Password") + → ValidatedPasswordNode (validateInput: false) + → DataStoreDecisionNode + → true: PageNode ("Update Password") + → false: FailureNode + → false (passwordless user): EmailSuspendNode + → [resume after email click] + → PageNode ("Update Password") + → PageNode ("Update Password") + → ValidatedPasswordNode (validateInput: true) + → single outcome + → PatchObjectNode (ignoredFields: [userName]) + → PATCHED → SuccessNode + → FAILURE → FailureNode +``` + +**SessionDataNode** is the canonical entry for authenticated journeys — identifies the current user from the active session without a login form. + +**AttributePresentDecisionNode** branches on `password` attribute presence: +- `true` (password set) → require current-password verification before allowing change +- `false` (passwordless user) → gate with email verification instead + +**Two ValidatedPasswordNode instances:** + +| Instance | `validateInput` | Purpose | +|---|---|---| +| "Verify Existing Password" | `false` | Old credential — no policy enforcement | +| "Update Password" | `true` | New credential — policy enforced | + +**PatchObjectNode:** `ignoredFields: [userName]` — prevents the username from being changed via this flow. + +--- + +## Decision: Reset vs. Update + +| Criterion | Use Reset | Use Update | +|---|---|---| +| User has an active session | No | Yes | +| User forgot their password | Yes | No | +| Passwordless users need support | Both | Yes (via email gate) | +| Identity verification method | Email (resume URI) | Session (SessionDataNode) or email (passwordless branch) | + +--- + +## Security Considerations + +- Email resume URIs are single-use and time-limited — do not extend expiry without increasing rate limiting +- Password change should invalidate or re-issue the session (configure via `SetSessionProperties` or session termination post-patch) +- The `DataStoreDecisionNode` verify step in authenticated update prevents session hijacking from allowing a password change without knowing the current password +- Add `RetryLimitDecisionNode` after `DataStoreDecisionNode(false)` if you want to limit failed current-password attempts before locking + +## Prerequisites + +- Email notification service configured +- `resetPassword` email template present with `{{object.resumeURI}}` +- `managed/alpha_user` with `password`, `mail`, `userName` attributes accessible +- For authenticated update: active session with `UserToken` session property + +## Related references + +- `journey-use-cases/account-recovery-and-username-reminder.md` +- `nodes/basic-auth-nodes.md` +- `nodes/identity-management-nodes.md` +- `nodes/utility-nodes.md` + +## Source + +[Authentication nodes — PingOne AIC](https://docs.pingidentity.com/pingoneaic/journeys/auth-nodes.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/passwordless-mfa-registration.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/passwordless-mfa-registration.md new file mode 100644 index 0000000..66b8390 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/passwordless-mfa-registration.md @@ -0,0 +1,209 @@ +--- +title: "PingOne ST — Passwordless MFA Device Registration" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: ["mfa"] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-21" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — Passwordless MFA Device Registration + +Design patterns for the MFA device registration inner journey, supporting 7 factor types with per-method registration paths. Derived from CIAM Passwordless and Threat Detection journey exports. + +## Scope + +**Covers:** Device selection, per-method registration inner journeys (WebAuthn, OATH, Push, Combined OATH+PUSH, SMS, VOICE), RecoveryCodeDisplayNode placement, GetAuthenticatorAppNode usage, Twilio phone validation. +**Does NOT cover:** MFA authentication after registration — see `journey-use-cases/mfa-authentication-multi-method.md`. + +--- + +## Structure Overview + +Device registration is always a **dedicated inner journey** called from the registration or sign-on journey: + +``` +InnerTreeEvaluatorNode (tree: MFA Device Registration) + → true → proceed (device registered) + → false → FailureNode +``` + +The device registration inner journey delegates each method to its own nested inner journey via `InnerTreeEvaluatorNode`. This keeps registration paths independently updatable. + +--- + +## Device Selection + +**Entry:** A `PageNode` presents the device selection screen. The selection drives an embedded `ScriptedDecisionNode` or `ChoiceCollector` that returns the chosen method as its outcome. + +**Observed outcomes:** `Error` / `FIDO2` / `OATH` / `OATH+PUSH` / `PUSH` / `SMS` / `VOICE` + +Each outcome routes to a per-method registration inner journey. + +--- + +## Per-Method Registration Paths + +### FIDO2 / WebAuthn + +``` +InnerTreeEvaluatorNode (tree: Register WebAuthn Method) + → true → EmailTemplateNode ("Notify User On Email") → SuccessNode + → false → FailureNode +``` + +**Register WebAuthn Method inner journey:** +``` +WebAuthnRegistrationNode (userVerificationRequirement: PREFERRED, asScript: true, + generateRecoveryCodes: true, maxSavedDevices: 0, + acceptedSigningAlgorithms: [ES256, RS256], timeout: 60) + → success → RecoveryCodeDisplayNode → SuccessNode + → unsupported → FailureNode + → failure → FailureNode + → error → FailureNode +``` + +**`unsupported`, `failure`, and `error` all route to FailureNode** — no method fallback in the registration path. The device selection PageNode handles method fallback upstream. + +### OATH (TOTP) + +``` +InnerTreeEvaluatorNode (tree: Register OATH MFA) +``` + +**Register OATH MFA inner journey:** +``` +GetAuthenticatorAppNode + → outcome → OathRegistrationNode (algorithm: TOTP, passwordLength: SIX_DIGITS, + totpTimeInterval: 30, generateRecoveryCodes: true, + accountName: USERNAME, issuer: ForgeRock) + → OathDeviceStorageNode + → PageNode ("Collect Verification Code") + children: ScriptedDecisionNode (UI validator) + OathTokenVerifierNode + → successOutcome → RecoveryCodeDisplayNode → SuccessNode + → failureOutcome → RetryLimitDecisionNode → retry / Reject → FailureNode +``` + +**`GetAuthenticatorAppNode`** displays ForgeRock Authenticator download links before showing the QR code, ensuring the user has an app capable of scanning it. + +**Verification at registration:** After displaying the QR code, the user must enter a valid TOTP code to confirm the device was enrolled correctly. This prevents registration of misconfigured devices. + +### Push + +``` +InnerTreeEvaluatorNode (tree: Register Push MFA) +``` + +**Register Push MFA inner journey:** +``` +PushAuthenticationSenderNode (pushType: DEFAULT, mandatory: true, messageTimeout: 120000) + → NOT_REGISTERED → GetAuthenticatorAppNode + → OathRegistrationNode (registers push device) + → PushRegistrationNode + → successOutcome → RecoveryCodeDisplayNode → SuccessNode + → failureOutcome → FailureNode + → timeoutOutcome → RetryLimitDecisionNode → retry / Reject → FailureNode + → SENT → PushWaitNode → DONE → PushResultVerifierNode + → TRUE → SuccessNode (already registered, flow completes) +``` + +### Combined OATH + Push + +``` +InnerTreeEvaluatorNode (tree: Register OATH & PUSH) +``` + +**Register OATH & PUSH inner journey:** +``` +PushAuthenticationSenderNode + → NOT_REGISTERED → GetAuthenticatorAppNode + → CombinedMultiFactorRegistrationNode (algorithm: TOTP, + passwordLength: SIX_DIGITS, generateRecoveryCodes: true) + → successOutcome → RecoveryCodeDisplayNode → SuccessNode + → failureOutcome → FailureNode + → timeoutOutcome → RetryLimitDecisionNode → retry / Reject → FailureNode + → SENT → PushWaitNode → DONE → PushResultVerifierNode → TRUE → SuccessNode +``` + +`CombinedMultiFactorRegistrationNode` registers both TOTP and Push simultaneously in a single QR scan. + +### SMS / VOICE (Twilio Verify) + +``` +AttributePresentDecisionNode (presentAttribute: telephoneNumber) + → True → VerifyAuthLookupNode (phone number format/carrier validation) + → True → VerifyAuthSenderNode (channel: SMS or CALL) + → true → PageNode ("Collect OTP") + children: VerifyAuthCollectorDecisionNode + → true → PatchObjectNode ("Update User") → SuccessNode + → false → RetryLimitDecisionNode → retry / Reject → FailureNode + → error → FailureNode + → False / Error → FailureNode + → False → FailureNode (no phone number on file) +``` + +**`VerifyAuthLookupNode`** validates the phone number before sending — catches invalid numbers before incurring Twilio delivery cost. + +**`PatchObjectNode`** at the end of SMS/VOICE registration updates the user's profile with device enrollment metadata. + +--- + +## RecoveryCodeDisplayNode Placement + +**Rule:** `RecoveryCodeDisplayNode` must appear immediately after the registration node's `successOutcome`, before any other routing step. If the user exits before seeing the codes, they permanently lose access to them. + +``` +[Registration node] → successOutcome → RecoveryCodeDisplayNode → SuccessNode +``` + +This applies to: WebAuthn, OATH, Push, and Combined OATH+PUSH registrations. + +--- + +## EmailTemplateNode Post-Registration Notification + +After successful device registration, a non-blocking notification email is sent: + +``` +SuccessNode path + → EmailTemplateNode ("Notify User On Email", emailTemplateName: ...) + → EMAIL_SENT → SuccessNode + → EMAIL_NOT_SENT → SuccessNode ← notification is best-effort; does not block +``` + +Both `EMAIL_SENT` and `EMAIL_NOT_SENT` route to SuccessNode — notification failure does not block registration completion. + +--- + +## Prerequisites + +- User must be authenticated before device registration +- ForgeRock Authenticator app available to the user (links provided by `GetAuthenticatorAppNode`) +- Twilio Verify credentials configured for SMS/VOICE methods +- `telephoneNumber` attribute populated in the user's profile for SMS/VOICE enrollment +- HTTPS required for WebAuthn + +## Common variants + +| Variant | Note | +|---|---| +| Mandatory registration at first login | Place `MFA Device Registration` ITE after `CreateObjectNode(CREATED)` in registration journey | +| Optional registration | Wrap registration ITE with a `ChoiceCollector` offering "Register now" / "Skip" | +| Limit to one method | Remove method outcomes from device selection PageNode | +| Require verification code confirmation for OATH | Already in the OOTB pattern — `OathTokenVerifierNode` in the registration inner journey | + +## Related references + +- `journey-use-cases/mfa-authentication-multi-method.md` +- `nodes/mfa-nodes.md` +- `nodes/federation-contextual-nodes.md` + +## Source + +[Authentication nodes — PingOne AIC](https://docs.pingidentity.com/pingoneaic/journeys/auth-nodes.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/pingone-protect-risk-integration.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/pingone-protect-risk-integration.md new file mode 100644 index 0000000..70430c8 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/pingone-protect-risk-integration.md @@ -0,0 +1,197 @@ +--- +title: "PingOne ST — PingOne Protect Risk Integration" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: ["protect"] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-21" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — PingOne Protect Risk Integration + +Design patterns for integrating PingOne Protect risk evaluation into AIC journeys, derived from four production journey suites (CIAM Passwordless, Financial Services, Money Transfer, Threat Detection). + +## Scope + +**Covers:** Triple-node pattern, init/eval separation via shared state, production configuration, outcome routing, new device detection, account disable on high risk, ModifyAuthLevelNode step-up chain. +**Does NOT cover:** PingOne Protect service setup — see `ping-universal-services`. Transaction authorization — see `journey-use-cases/financial-services-step-up.md`. + +--- + +## Architecture: Inner Journey Wrapping + +PingOne Protect is always wrapped in a **dedicated "Threat Detection" inner journey** called from the main journey: + +``` +Main journey + → ScriptedDecisionNode ("Is Protect Analysis Required?", outcome: true/false) + → [true] InnerTreeEvaluatorNode ("Initialize P1 Protect") ← first call: init + → [after init] InnerTreeEvaluatorNode ("Protect Evaluation & Mitigation") ← second call: eval +``` + +Keeping Protect in an inner journey allows it to be reused across multiple main journeys (sign-on, registration, authorization) and updated independently. + +--- + +## Init/Eval Separation Pattern + +A single inner journey handles both initialization and evaluation via a shared state flag (`p1ProtectAction`): + +``` +Inner journey entry: +ScriptedDecisionNode ("P1 Protect Action?", reads p1ProtectAction from shared state) + → "init" → product-PingOneProtectInitializeNode + → true → SuccessNode + → false → FailureNode + → "eval" → [evaluation branch — see below] +``` + +The calling journey sets `p1ProtectAction` to `"init"` before the first call and `"eval"` before the second. This prevents duplicating the inner journey for two slightly different calls. + +--- + +## Evaluation Branch + +``` +"eval" path: +IdentifyExistingUserNode + → ScriptedDecisionNode ("Set UserId and Username For Protect") + [sets protectUserId and protectUsername in shared state] + → ScriptedDecisionNode ("Determine Flow Type", + outcomes: Authentication / Authorization / Registration) + → product-PingOneProtectEvaluationNode (per flow type) +``` + +**PingOneProtectEvaluationNode production configuration:** + +| Field | Value | Notes | +|---|---|---| +| `flowType` | `AUTHENTICATION` / `AUTHORIZATION` / `REGISTRATION` | Set from ScriptedDecisionNode output | +| `pauseBehavioralData` | `true` | | +| `storeEvaluateResult` | `true` | | +| `deviceSharingType` | `SHARED` | | +| `scoreThreshold` | `300` | Numeric threshold for `exceed` outcome | +| `userId` | `protectUserId` | Shared state key | +| `username` | `protectUsername` | Shared state key | +| `userType` | `EXTERNAL` | | +| `recommendedActions` | `[BOT_MITIGATION, AITM_MITIGATION, TEMP_EMAIL_MITIGATION]` | | + +--- + +## Standard Outcome Routing + +``` +product-PingOneProtectEvaluationNode + → low → product-PingOneProtectResultNode (SUCCESS) → SuccessNode + → medium → step-up MFA inner journey → (on MFA success) PingOneProtectResultNode (SUCCESS) + → high → ModifyAuthLevelNode (increment: 1) + → AccountActiveDecisionNode + → AccountLockoutNode (LOCK) + → EmailTemplateNode ("Send Account Disabled Email") + → product-PingOneProtectResultNode (FAILED) → FailureNode + → exceed / failure / clientError / BOT_MITIGATION / AITM_MITIGATION / TEMP_EMAIL_MITIGATION + → product-PingOneProtectResultNode (FAILED) → FailureNode +``` + +**Critical:** `product-PingOneProtectResultNode` must be called at **both** success and failure termination paths. Omitting it on one path degrades the Protect risk model over time. + +--- + +## New Device Detection Pattern + +Used in Financial Services and Money Transfer to send notifications without blocking the journey: + +``` +product-PingOneProtectEvaluationNode + → [after low/medium routing] + → ScriptedDecisionNode ("Extract Protect Activity Params", + outcomes: highRisk / newDevice / low_medRisk) + → newDevice: ScriptedDecisionNode ("Notify New Device Detected", + outcomes: sent / noMail / error) + → all outcomes → SuccessNode ← notification is best-effort + → highRisk: ScriptedDecisionNode ("Send Suspicious Activity Mail", + outcomes: sent / noMail / error) + → all outcomes → AccountLockoutNode (LOCK) → SuccessNode + → low_medRisk → SuccessNode +``` + +All notification outcomes route forward — a failed notification email never blocks the user. + +--- + +## ModifyAuthLevelNode + AuthLevelDecisionNode Step-Up Chain + +Used to trigger MFA only when risk warrants it: + +``` +product-PingOneProtectEvaluationNode + → medium / high → ModifyAuthLevelNode (authLevelIncrement: 1) + +[Back in main journey, after Threat Detection ITE:] +AuthLevelDecisionNode (threshold: 1) + → true (level elevated) → InnerTreeEvaluatorNode (MFA Authentication) + → false (level normal) → SuccessNode (skip MFA) +``` + +This decouples the risk signal (set in the inner journey) from the step-up decision (evaluated in the main journey). + +--- + +## PingOneProtectInitializeNode Configuration + +| Field | Production value | +|---|---| +| `behavioralDataCollection` | `true` | +| `enableTrust` | `false` | +| `disableTags` | `false` | +| `consoleLogEnabled` | `false` | +| `deviceKeyRsyncIntervals` | `14` | +| `disableHub` | `false` | +| `lazyMetadata` | `false` | +| `deviceAttributesToIgnore` | `[]` | + +Cannot be placed inside a PageNode. + +--- + +## Multiple Flow Types in One Journey + +Production journeys use multiple `product-PingOneProtectEvaluationNode` instances for different flow types: +- `AUTHENTICATION` — for login flows +- `AUTHORIZATION` — for transaction/step-up flows +- `REGISTRATION` — for new user registration + +The `Determine Flow Type` ScriptedDecisionNode routes to the correct instance based on a shared state flag set earlier in the journey. + +## Prerequisites + +- PingOne Protect service enabled in the tenant environment +- Worker service ID configured in the Protect node +- Risk policy configured in PingOne Protect +- PingOne SDK 4.4.0+ on the client (required for behavioral data collection) +- `IdentifyExistingUserNode` run before evaluation (to populate `userId` for Protect) + +## Common variants + +| Variant | Note | +|---|---| +| Registration only | Use `flowType: REGISTRATION`; medium risk may block registration rather than trigger MFA | +| No account disable on high risk | Remove `AccountLockoutNode` from high-risk path; route to MFA step-up or FailureNode instead | +| Evaluation without init (returning session) | Set `p1ProtectAction: "eval"` without init for users with an existing Protect session | + +## Related references + +- `journey-use-cases/mfa-authentication-multi-method.md` +- `journey-use-cases/financial-services-step-up.md` +- `nodes/risk-management-nodes.md` + +## Source + +[PingOne Protect Evaluation node](https://docs.pingidentity.com/auth-node-ref/latest/pingone/pingone-protect-evaluation.html) +[Authentication nodes — PingOne AIC](https://docs.pingidentity.com/pingoneaic/journeys/auth-nodes.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/progressive-profiling.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/progressive-profiling.md new file mode 100644 index 0000000..58dcaaa --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/progressive-profiling.md @@ -0,0 +1,156 @@ +--- +title: "PingOne ST — Progressive Profiling" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-21" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — Progressive Profiling + +Design patterns for progressively collecting user profile data after login, without blocking authentication. Derived from the OOTB progressive profiling journey template. + +## Scope + +**Covers:** `LoginCountDecisionNode` trigger configuration, `QueryFilterDecisionNode` SCIM filter syntax, dual-gate pattern, `IncrementLoginCountNode` placement, `PatchObjectNode` for preference updates. +**Does NOT cover:** Registration-time attribute collection — see `nodes/identity-management-nodes.md`. Full profile management — see `journey-use-cases/social-and-local-registration-authentication.md`. + +--- + +## Pattern: Dual-Gate Progressive Profiling + +Progressive profiling should only prompt when two conditions are both true: +1. The user is at the right point in their lifecycle (e.g., 2nd login) +2. The data is actually missing + +``` +LoginCountDecisionNode (interval: AT, amount: 2) + → true → QueryFilterDecisionNode (filter: attribute missing or incomplete) + → true → PageNode (collect missing attributes) + → PatchObjectNode → SuccessNode + → false → SuccessNode (data already present — skip) + → false → SuccessNode (wrong login count — skip) +``` + +This pattern ensures users are never re-prompted once they have provided the data, and are not interrupted on every login. + +--- + +## LoginCountDecisionNode Configuration + +| Field | Value | Notes | +|---|---|---| +| `interval` | `AT` or `EVERY` | `AT`: trigger exactly at count N (one-time). `EVERY`: trigger at count N and every login after. | +| `amount` | `2` (OOTB) | Any positive integer | +| `identityAttribute` | `userName` | IDM attribute used to retrieve the user object | + +- Outcomes: **True** (count matches) / **False** (count does not match) +- `AT` is preferred for one-time prompts — prevents the prompt from firing on every login after count N + +--- + +## QueryFilterDecisionNode — SCIM Filter Syntax + +Evaluates a SCIM/LDAP-style filter against the user's profile attributes to determine if data is missing. + +**OOTB filter for preferences:** +``` +!(/preferences pr) or /preferences/marketing eq false or /preferences/updates eq false +``` + +This matches users who: +- Have no `preferences` attribute at all (`!(/preferences pr)`) +- OR have `preferences/marketing` set to `false` (i.e., not yet opted in) +- OR have `preferences/updates` set to `false` + +**Outcomes:** **True** (filter matches — data missing or incomplete) / **False** (filter does not match — data present) + +**Dot-path notation for nested attributes:** Use `/` as the path separator for nested attributes: `/preferences/marketing`, `/preferences/updates`. + +--- + +## AttributeCollectorNode for Nested Attributes + +When collecting nested attributes, use dot-path notation in `attributesToCollect`: + +```json +"attributesToCollect": ["preferences/updates", "preferences/marketing"] +``` + +The attribute must be defined in the identity schema before it can be collected. `required: false` allows users to skip optional fields. + +--- + +## PatchObjectNode for Preference Updates + +``` +PatchObjectNode + identityResource: managed/alpha_user + patchAsObject: false + ignoredFields: [] +``` + +- Outcomes: **PATCHED** / **FAILURE** +- `patchAsObject: false` merges only the specified attributes — does not overwrite the entire user object +- `FAILURE`: route to FailureNode (or silently log and continue, depending on data criticality) + +--- + +## IncrementLoginCountNode Placement + +**Critical:** Place `IncrementLoginCountNode` immediately after `CreateObjectNode(CREATED)` in the registration journey so the login count starts at 1 after registration. + +``` +CreateObjectNode → CREATED → IncrementLoginCountNode → SuccessNode +``` + +Without this, the count is 0 after registration. `LoginCountDecisionNode(AT=2)` will then fire on the 3rd visit (2nd login), not the 2nd. + +--- + +## Inner Journey Pattern + +Progressive profiling should be an **inner journey** called from the main sign-in journey: + +``` +Main Sign-In journey (after authentication success) + → InnerTreeEvaluatorNode (tree: Progressive Profiling) + → true → SuccessNode + → false → FailureNode (rare — only if PatchObjectNode fails) +``` + +Keeping it separate allows profiling to be updated independently and disabled without modifying the login journey. + +--- + +## Common variants + +| Variant | Notes | +|---|---| +| Trigger once, any login after N | Use `interval: EVERY` instead of `AT` | +| Trigger at multiple lifecycle points | Use multiple `LoginCountDecisionNode` instances with different amounts and different `QueryFilterDecisionNode` filters | +| Require mandatory data before access | Route `QueryFilterDecisionNode(true)` to collection before SuccessNode; remove the skip path | +| Collect a single attribute | Use a single-attribute `AttributeCollectorNode` in the PageNode | + +## Prerequisites + +- `IncrementLoginCountNode` placed in the registration journey so login count is initialized +- Custom attributes (`preferences/marketing`, etc.) defined in the IDM managed object schema before collection +- `managed/alpha_user` with write access for `PatchObjectNode` + +## Related references + +- `nodes/identity-management-nodes.md` +- `nodes/utility-nodes.md` +- `journey-use-cases/social-and-local-registration-authentication.md` + +## Source + +[Authentication nodes — PingOne AIC](https://docs.pingidentity.com/pingoneaic/journeys/auth-nodes.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/social-and-local-registration-authentication.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/social-and-local-registration-authentication.md new file mode 100644 index 0000000..4406037 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/journey-use-cases/social-and-local-registration-authentication.md @@ -0,0 +1,182 @@ +--- +title: "PingOne ST — Social and Local Registration and Authentication" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect"] +use_cases: ["customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-05-21" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — Social and Local Registration and Authentication + +Design patterns for CIAM registration and authentication journeys supporting both local credentials and social identity providers. Derived from CIAM Passwordless and basic registration journey exports. + +## Scope + +**Covers:** Social + local choice entry, `SocialProviderHandlerNodeV2` outcomes, social registration profile collection, `CreateObjectNode` with cleanup, email verification gate, T&C lifecycle, `AttributeValueDecisionNode`. +**Does NOT cover:** MFA registration after account creation — see `journey-use-cases/passwordless-mfa-registration.md`. Progressive profiling — see `journey-use-cases/progressive-profiling.md`. + +--- + +## Entry: Social + Local Choice + +``` +PageNode (outcomes: localAuthentication / socialAuthentication) + → localAuthentication → Platform Username → Platform Password → DataStoreDecisionNode + → socialAuthentication → SocialProviderHandlerNodeV2 +``` + +The entry `PageNode` embeds a `ScriptedDecisionNode` or `ChoiceCollector` that drives the `localAuthentication` / `socialAuthentication` outcomes. This pattern allows a single journey to serve both local and social users. + +--- + +## SocialProviderHandlerNodeV2 + +**Configuration:** +- Select from IdPs registered in the realm's Social Identity Provider service +- `transformScript`: maps incoming IdP claims to managed object attributes + +- Outcomes: **ACCOUNT_EXISTS** / **NO_ACCOUNT** / **SOCIAL_AUTH_INTERRUPTED** + +**Per outcome routing:** + +| Outcome | Action | +|---|---| +| `ACCOUNT_EXISTS` | Continue to authentication or profile completion | +| `NO_ACCOUNT` | Route to social registration profile collection | +| `SOCIAL_AUTH_INTERRUPTED` | Route to FailureNode | + +--- + +## Social Registration Path + +When `NO_ACCOUNT`: collect a minimal profile and create the user object. + +``` +SocialProviderHandlerNodeV2 → NO_ACCOUNT + → PageNode (social registration profile fields) + children: AttributeCollectorNode (mail, givenName, sn — required: false, validateInputs: false) + + [optional: ValidatedUsernameNode, AcceptTermsAndConditionsNode] + → RequiredAttributesPresentNode + → True → CreateObjectNode (identityResource: managed/alpha_user) + → CREATED → IncrementLoginCountNode → proceed + → FAILURE → ScriptedDecisionNode ("Delete User Entry") → FailureNode + → False → [re-display form or FailureNode] +``` + +**`RequiredAttributesPresentNode`** guards `CreateObjectNode` — prevents partial user creation when required fields are missing. + +**`CreateObjectNode(FAILURE)` cleanup:** Always follow `FAILURE` with a `ScriptedDecisionNode` that deletes any partial record (`openidm.delete("managed/alpha_user", ...)`) before routing to FailureNode. Prevents orphaned partial accounts from blocking future registrations with the same email. + +--- + +## Local Registration Path (Basic) + +``` +PageNode (single screen) + children: AttributeCollectorNode (mail, givenName, sn) + + ValidatedUsernameNode (validateInput: true) + + ValidatedPasswordNode (validateInput: true) + + AcceptTermsAndConditionsNode + → CreateObjectNode (identityResource: managed/alpha_user) + → CREATED → IncrementLoginCountNode → SuccessNode + → FAILURE → FailureNode +``` + +**Notes:** +- Co-locating `AcceptTermsAndConditionsNode` in the registration PageNode records T&C acceptance at the point of signup +- `validateInput: true` on both Username and Password enforces policy before object creation +- OOTB registration has no email verification — add `EmailSuspendNode` after `CreateObjectNode(CREATED)` if email verification is required + +--- + +## Email Verification Gate (Authentication Journey) + +After registration without email verification, the authentication journey gates unverified users: + +``` +AttributeValueDecisionNode ("Is Email Verified?", attribute: emailVerified, value: true) + → false → [email verification sub-journey] + → EmailSuspendNode (emailTemplateName: emailVerification) + → ScriptedDecisionNode ("Set Email Verification Status To True") + → PatchObjectNode (set emailVerified: true) + → continue + → true → continue +``` + +The `ScriptedDecisionNode` after `EmailSuspendNode` updates the flag before `PatchObjectNode` writes it — do not rely on `PatchObjectNode` alone. + +--- + +## T&C Lifecycle in Authentication + +Authentication journeys enforce current T&C version at each sign-in: + +``` +TermsAndConditionsDecisionNode + → false (not accepted or outdated version) → AcceptTermsAndConditionsNode → continue + → true (accepted and current) → continue +``` + +When a new T&C version is published, all existing users are prompted on their next login. Users who skip login are not prompted until they return. + +--- + +## Write Federation Information node + +After social authentication with an existing account, persist the federation link: + +``` +SocialProviderHandlerNodeV2 → ACCOUNT_EXISTS + → WriteFederationInformationNode → continue +``` + +This stores the external IdP subject identifier linked to the local account, enabling future social logins to resolve to the same user without re-prompting for profile data. + +--- + +## Duplicate Account Handling + +The OOTB `CreateObjectNode(FAILURE)` path does not distinguish between "email already in use" and other failures. For production CIAM: + +1. Run `IdentifyExistingUserNode` (by `mail`) before `CreateObjectNode` +2. If `true` (account exists): route to account-linking flow or error message +3. If `false` (new user): proceed to `CreateObjectNode` + +This prevents confusing failure messages and enables account linking for users who previously registered locally and now attempt social registration. + +--- + +## Prerequisites + +- Social Identity Providers configured in realm Social Identity Provider service +- `managed/alpha_user` schema includes `mail`, `givenName`, `sn`, `userName`, `emailVerified` attributes +- Email notification service configured for email verification flow +- `emailVerification` email template present with `{{object.resumeURI}}` + +## Common variants + +| Variant | Notes | +|---|---| +| Email verification required at registration | Add `EmailSuspendNode` immediately after `CreateObjectNode(CREATED)` before `SuccessNode` | +| Social-only (no local) | Remove `localAuthentication` branch from entry PageNode | +| Profile completion after social login | Add `AttributeCollectorNode` after `ACCOUNT_EXISTS` if profile is incomplete | +| Multiple social providers | Add outcomes to entry `PageNode` per provider; each routes to a separate `SocialProviderHandlerNodeV2` instance | + +## Related references + +- `journey-use-cases/passwordless-mfa-registration.md` +- `journey-use-cases/progressive-profiling.md` +- `nodes/identity-management-nodes.md` +- `nodes/basic-auth-nodes.md` + +## Source + +[Authentication nodes — PingOne AIC](https://docs.pingidentity.com/pingoneaic/journeys/auth-nodes.html) +[Social Provider Handler node](https://docs.pingidentity.com/auth-node-ref/latest/social-provider-handler.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/basic-auth-nodes.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/basic-auth-nodes.md new file mode 100644 index 0000000..a1f2087 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/basic-auth-nodes.md @@ -0,0 +1,204 @@ +--- +title: "PingOne ST — Basic Authentication Nodes" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: reference +status: current +canonical: true +last_updated: "2026-05-21" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — Basic Authentication Nodes + +Core nodes for credential collection, user lookup, and validation against identity stores. + +## Scope + +**Covers:** Username/password collection, credential validation, session-based user identification, attribute branching, and terminal outcomes. +**Does NOT cover:** MFA — see `nodes/mfa-nodes.md`. Flow control — see `nodes/utility-nodes.md`. + +--- + +## Credential Collection + +### Platform Username node (`ValidatedUsernameNode`) +Collects the username from the user. Writes to `username` in shared state. **Use this in AIC — do not use the deprecated Username Collector node.** + +**Configuration:** + +| Field | Notes | +|---|---| +| `validateInput` | `true` enforces IDM username policy (format, length) on submission | +| `usernameAttribute` | The IDM attribute storing the username (default: `userName`) | +| `autocompleteValues` | If set, provides HTML5 autocomplete suggestions for the input field | + +- Outcomes: single (proceeds to next node) +- Must be a PageNode child — standalone placement renders no input field + +### Platform Username node V2 (`ValidatedUsernameNodeV2`) +V2 adds prepopulation support. Use V2 when the journey may have the username already in state (e.g., re-authentication after session expiry, step-up flows). + +**Additional field vs V1:** + +| Field | Notes | +|---|---| +| `prepopulate` | `true` — input field is prepopulated with the `username` value from node state if present | + +- All other configuration identical to V1 +- Outcomes: single + +### Platform Password node (`ValidatedPasswordNode`) +Collects the password from the user. Writes to `password` in transient state. **Use this in AIC — do not use the deprecated Password Collector node.** + +**Configuration:** + +| Field | Notes | +|---|---| +| `validateInput` | `true` enforces IDM password policy on submission; `false` skips policy check (for existing credential verification) | +| `passwordAttribute` | The IDM attribute storing the password (default: `password`) | + +- Outcomes: single +- Must be a PageNode child + +**Two-instance pattern (password update journeys):** +- Instance 1 — "Verify Existing Password": `validateInput: false` (existing credential, no policy enforcement) +- Instance 2 — "New Password": `validateInput: true` (new credential, policy enforced) + +### Zero Page Login Collector node +Captures username and password in a single step without presenting an intermediate page. Useful when the client has already collected credentials. + +- Outcomes: single + +> **AIC note:** `Username Collector` and `Password Collector` nodes are not compatible with Advanced Identity Cloud. Always use `Platform Username` (`ValidatedUsernameNode`) and `Platform Password` (`ValidatedPasswordNode`) instead. + +--- + +## Credential Validation + +### Data Store Decision node +Validates username + password against the realm's configured data store. + +- Outcomes: **True** (credentials match) / **False** (credentials do not match) +- No configurable properties — operates on the realm's default data store +- Pair with `RetryLimitDecisionNode` to allow multiple attempts before lockout +- Used in authenticated password-update journeys to verify the current password before allowing a change + +**Contrast with IdentityStoreDecisionNode:** DataStoreDecisionNode returns only True/False. Use `IdentityStoreDecisionNode` when you need to handle LOCKED, EXPIRED, or CANCELLED states explicitly. + +### Identity Store Decision node +Authenticates against the cloud identity store with granular lifecycle outcomes. + +- Outcomes: **TRUE** / **FALSE** / **LOCKED** / **EXPIRED** / **CANCELLED** +- Wire each outcome explicitly: + - `LOCKED` → account-locked message or recovery path + - `EXPIRED` → password-change inner journey + - `CANCELLED` → FailureNode +- Used in financial-grade and CIAM journeys where account lifecycle states must be handled distinctly + +### LDAP Decision node +Authenticates against an external LDAP or Active Directory server. Supports password policy outcomes not available in Data Store Decision. + +- Outcomes: **True** / **False** / password policy outcomes (e.g., `EXPIRED`, `LOCKED`) +- Use when the realm is connected to an external LDAP/AD and password-policy-aware branching is needed + +### AD Decision node +Authenticates specifically against Active Directory. + +- Outcomes: **True** / **False** + +### Passthrough Authentication node +Authenticates a user against a third-party system via an ICF connector without requiring the user to re-enter credentials. The credentials are already in journey state. + +**Configuration:** + +| Field | Notes | +|---|---| +| `systemEndpoint` | Name of the ICF connector to use (configured in IDM) | +| `objectType` | ICF object type for the authenticating user | +| `identityAttribute` | The IDM attribute used as the username for authentication | +| `passwordAttribute` | The IDM attribute used as the password for authentication | + +- Outcomes: **Authenticated** / **Failed** / **Missing Input** +- `Missing Input`: username or password not present in journey state — route back to credential collection +- Use during directory migration to validate credentials against a legacy system while the primary directory is being replaced + +--- + +## Session-Based User Identification + +### Get Session Data node (`SessionDataNode`) +Extracts a value from the current active session into shared state, enabling authenticated journeys to identify the user without a login form. + +**Production configuration:** +- `sessionDataKey: UserToken` — the session property containing the user token +- `sharedStateKey: userName` — the shared state key to write the username to + +- Outcomes: single +- **Canonical entry pattern for authenticated journeys** (password update, profile management): place as the first node; the extracted `userName` is then available for `DataStoreDecisionNode`, `PatchObjectNode`, and `IdentifyExistingUserNode` downstream + +--- + +## Attribute-Based Branching + +### Attribute Present Decision node +Checks whether a specific attribute exists in the user's profile or shared state. + +- Outcomes: **True** (attribute present) / **False** (attribute absent) +- `presentAttribute: password` — detects whether a user has a password set; returns `False` for passwordless users, enabling conditional routing to email-gated verification instead of current-password challenge + +### Attribute Value Decision node +Evaluates whether a specific attribute in the user's profile matches a configured comparison operation. + +**Configuration:** + +| Field | Notes | +|---|---| +| `comparisonOperation` | `PRESENT` — checks attribute exists; `EQUALS` — checks attribute value equals `comparisonValue` | +| `comparisonAttribute` | The object attribute to evaluate (e.g., `emailVerified`) | +| `comparisonValue` | Value to compare against when using `EQUALS` (e.g., `true`) | +| `identityAttribute` | The IDM attribute used to look up the user object | + +- Outcomes: **True** / **False** +- `PRESENT` does not require `comparisonValue` — it is a null/existence check only +- Common use: "Is Email Verified?" gate — `comparisonAttribute: emailVerified`, `comparisonOperation: EQUALS`, `comparisonValue: true`; `False` triggers email verification inner journey + +--- + +## Terminal Nodes + +### Success node +Ends the journey successfully. Creates an authenticated session. Every journey must have at least one Success node. + +### Failure node +Ends the journey with an authentication failure. No session created. Use at the end of any path that should deny access. + +--- + +## Common patterns + +| Pattern | Nodes | +|---|---| +| Basic login | PageNode(ValidatedUsername + ValidatedPassword) → DataStoreDecisionNode → Success / Failure | +| Login with retry | DataStoreDecisionNode(False) → RetryLimitDecisionNode → retry loop or Failure | +| Full lifecycle login | PageNode(ValidatedUsername + ValidatedPassword) → IdentityStoreDecisionNode(TRUE/LOCKED/EXPIRED/CANCELLED/FALSE) | +| Authenticated journey entry | SessionDataNode → AttributePresentDecisionNode | +| Passwordless user branch | AttributePresentDecisionNode(`password` = False) → EmailSuspendNode / (True) → DataStoreDecisionNode | +| Email verification gate | AttributeValueDecisionNode(False) → email verification inner journey → (true) proceed | + +## Related references + +- `nodes/mfa-nodes.md` +- `nodes/utility-nodes.md` +- `nodes/risk-management-nodes.md` +- `journey-use-cases/password-reset-and-update.md` + +## Source + +[Basic authentication nodes](https://docs.pingidentity.com/auth-node-ref/latest/overview.html) +[Data Store Decision node](https://docs.pingidentity.com/auth-node-ref/latest/data-store-decision.html) +[Platform Username node](https://docs.pingidentity.com/auth-node-ref/latest/platform-username.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/federation-contextual-nodes.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/federation-contextual-nodes.md new file mode 100644 index 0000000..2f16167 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/federation-contextual-nodes.md @@ -0,0 +1,257 @@ +--- +title: "PingOne ST — Federation and Contextual Nodes" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: reference +status: current +canonical: true +last_updated: "2026-05-21" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — Federation and Contextual Nodes + +Nodes for federated identity (social login, SAML, OIDC), external OTP delivery (Twilio), device context, cookies, certificates, and behavioral signals. + +## Scope + +**Covers:** Social Provider Handler V2, SAML2, OIDC validator, Twilio Verify nodes, device profiling/geofencing, cookie decisions, certificate auth, and login count behavioral nodes. +**Does NOT cover:** App registration or IdP configuration — see `ping-foundation` → `app-setup.md`. + +--- + +## Social / Federation Nodes + +### Social Provider Handler node (V2) +Initiates authentication via a configured social identity provider or any OIDC-compliant external IdP. + +**Configuration:** +- Select from IdPs registered in the realm's Social Identity Provider service +- `transformScript`: optional script to map incoming claims to managed object attributes + +- Outcomes: **ACCOUNT_EXISTS** / **NO_ACCOUNT** / **SOCIAL_AUTH_INTERRUPTED** +- `ACCOUNT_EXISTS` → continue to authentication or profiling flow +- `NO_ACCOUNT` → profile collection PageNode → `CreateObjectNode` for social registration +- `SOCIAL_AUTH_INTERRUPTED` → FailureNode + +**Entry pattern (social + local choice):** +``` +PageNode (outcomes: localAuthentication / socialAuthentication) + → localAuthentication: Platform Username → Platform Password → DataStoreDecisionNode + → socialAuthentication: SocialProviderHandlerNodeV2 +``` + +See `journey-use-cases/social-and-local-registration-authentication.md` for full pattern. + +### OIDC ID Token Validator node +Validates a JWT ID token from an external OpenID Connect provider. Extracts claims into shared state. + +- Outcomes: **Valid** / **Invalid** +- Use when the client presents a pre-obtained ID token (e.g., native app silent authentication) + +### SAML2 Authentication node +Initiates or processes a SAML 2.0 authentication exchange with an external IdP. + +- Outcomes: **Success** / **Failure** / **Account not found** + +### Write Federation Information node +Persists federation-related data (e.g., external IdP subject, linked account) to the user's managed object. + +- Outcomes: single +- Place after Social Provider Handler or SAML2 node on the account-linking path + +### Select Identity Provider node +Presents the user with a list of identity providers to choose from (for multi-IdP login pages). + +- Outcomes: one per configured IdP + +--- + +## Twilio Verify Nodes + +Used for SMS and voice OTP delivery in MFA registration and authentication flows. + +### Twilio Verify Identifier node (`VerifyAuthIdentifierNode`) +Validates that a phone number attribute is available before sending via Twilio. + +**Configuration:** + +| Field | Observed values | Notes | +|---|---|---| +| `identifierAttribute` | `telephonenumber` / `telephoneNumber` | Case varies — check your schema attribute name | +| `identifierSharedState` | `userIdentifier` | Shared state key for the resolved phone number | + +- Outcomes: **True** / **False** / **Error** +- `False`: phone number missing — route to FailureNode or prompt user to add a phone number +- Place before `VerifyAuthSenderNode` — do not attempt to send if identifier lookup fails + +### Twilio Verify Sender node (`VerifyAuthSenderNode`) +Sends an OTP to the user's phone via SMS or voice call. + +**Configuration:** + +| Field | Observed values | +|---|---| +| `channel` | `SMS` or `CALL` | +| `accountSID` | Twilio account SID | +| `authToken` | Twilio auth token | +| `serviceSID` | Twilio Verify service SID | +| `requestIdentifier` | `false` | + +- Outcomes: **true** / **error** + +### Twilio Verify Lookup node (`VerifyAuthLookupNode`) +Validates the phone number format and carrier information before MFA device registration. + +- Outcomes: **True** / **False** / **Error** +- Use before `VerifyAuthSenderNode` in device registration flows (CIAM Passwordless MFA Device Registration) + +### Twilio Verify Collector Decision node (`VerifyAuthCollectorDecisionNode`) +Collects and verifies the OTP code the user received via Twilio. + +**Configuration:** + +| Field | Observed value | +|---|---| +| `hideCode` | `true` | +| `showResendButton` | `false` | +| `showCancelButton` | `false` | +| `identifierSharedState` | `userIdentifier` | + +- Outcomes: **true** / **false** / **error** + +**Full Twilio SMS/VOICE path:** +``` +VerifyAuthIdentifierNode(True) + → VerifyAuthSenderNode(true) + → PageNode(VerifyAuthCollectorDecisionNode) + → true → proceed + → false → RetryLimitDecisionNode → retry loop / Failure + → error → FailureNode +``` + +--- + +## Contextual Nodes + +### Device Profile Collector node +Collects device characteristics (browser, OS, IP, screen dimensions, fonts) silently from the client. + +- Outcomes: single — no visible UI interaction + +### Device Match node +Compares the current device profile against previously stored profiles for this user. + +- Outcomes: **True** (known device) / **False** (unknown device) + +### Device Geofencing node +Evaluates whether the user's device is within configured geographic boundaries. + +- Outcomes: **True** (inside fence) / **False** (outside fence) + +### Device Location Match node +Checks whether the current device location matches the user's last known location within a configured radius. + +- Outcomes: **True** / **False** + +### Device Tampering Verification node +Checks Ping SDK signals for device compromise (rooted/jailbroken). + +- Outcomes: **True** (device appears legitimate) / **False** (tampering detected) + +### Device Profile Save node +Saves the current device profile to the user's stored device list after successful authentication. + +- Outcomes: single + +--- + +## Cookie Nodes + +### Cookie Presence Decision node +Checks whether a specific cookie is present in the incoming request. + +- Outcomes: **True** (cookie present) / **False** (cookie absent) + +### Persistent Cookie Decision node +Validates a Ping Identity persistent authentication cookie. + +- Outcomes: **True** (valid cookie — user can skip re-authentication) / **False** (no valid cookie) + +### Set Persistent Cookie node +Issues a persistent authentication cookie to the client after successful authentication. + +- Outcomes: single + +### Set Custom Cookie node +Sets an arbitrary cookie on the client response. + +- Outcomes: single + +--- + +## Certificate Nodes + +### Certificate Collector node +Prompts the client to present a TLS client certificate. Stores it in transient state. + +- Outcomes: single + +### Certificate Validation node +Validates the collected certificate against configured trust anchors and CRL/OCSP. + +- Outcomes: **True** (certificate valid) / **False** (certificate invalid or untrusted) + +### Certificate User Extractor node +Extracts a username from the client certificate's Subject or SAN field and writes to shared state. + +- Outcomes: single + +--- + +## Behavioral Nodes + +### Login Count Decision node +Routes based on cumulative login count stored in the user's profile. + +- `interval: AT` (exactly N) or `AFTER` (N or more); `amount: N` +- Outcomes: **True** / **False** +- Primary use: trigger one-time progressive profiling or onboarding at a specific login number + +### Increment Login Count node +Increments the user's stored login count by 1. Single `outcome`. + +- Place post-registration and post-authentication to keep the count accurate +- Required at registration (`CreateObjectNode(CREATED)` → `IncrementLoginCountNode`) to initialize the count so `LoginCountDecisionNode` triggers on the correct subsequent login + +--- + +## Common patterns + +| Pattern | Nodes | +|---|---| +| Social login with registration fallback | Social Provider Handler V2(NO_ACCOUNT) → Attribute Collector → Create Object | +| Social + local choice at journey entry | PageNode(localAuthentication/socialAuthentication) → respective paths | +| Twilio SMS MFA | VerifyAuthIdentifier → VerifyAuthSender → PageNode(VerifyAuthCollector) → retry loop | +| Device trust check | Device Profile Collector → Device Match(False) → MFA step-up | +| Persistent cookie SSO | Persistent Cookie Decision(True) → Success / (False) → login journey | +| First-login onboarding | Login Count Decision(AT=1, True) → onboarding inner journey → Increment Login Count | +| Certificate-based auth | Certificate Collector → Certificate Validation → Certificate User Extractor → Success | + +## Related references + +- `nodes/basic-auth-nodes.md` +- `nodes/identity-management-nodes.md` +- `nodes/mfa-nodes.md` +- `journey-use-cases/social-and-local-registration-authentication.md` +- `journey-use-cases/mfa-authentication-multi-method.md` + +## Source + +[Federation nodes](https://docs.pingidentity.com/auth-node-ref/latest/overview.html) +[Social Provider Handler node](https://docs.pingidentity.com/auth-node-ref/latest/social-provider-handler.html) +[Device Profile Collector node](https://docs.pingidentity.com/auth-node-ref/latest/device-profile-collector.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/identity-management-nodes.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/identity-management-nodes.md new file mode 100644 index 0000000..c59c7b5 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/identity-management-nodes.md @@ -0,0 +1,375 @@ +--- +title: "PingOne ST — Identity Management Nodes" +product_family: pingone-st +products: ["pingone-aic", "pingam", "pingidm"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: reference +status: current +canonical: true +last_updated: "2026-05-21" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — Identity Management Nodes + +Nodes for reading, writing, and managing user identity data during authentication journeys — registration, profile collection, consent, KBA, object operations, and social federation. + +## Scope + +**Covers:** Attribute collection and validation, user object creation/update/lookup, consent, KBA, profile completeness, social login, and PingOne Verify integration. +**Does NOT cover:** Directory setup or managed object schema — see `ping-foundation` → `directory-setup.md`. Deep provisioning flows — see `ping-orchestration` reconciliation patterns. + +--- + +## User Lookup + +### Identify Existing User node +Looks up an existing user in the identity store by a specified attribute and writes the found user's identifier to shared state. + +**Configuration:** + +| Field | Purpose | +|---|---| +| `identityAttribute` | The attribute used to look up the user in the identity store (e.g., `mail`) | +| `identifier` | The shared state key populated with the found user's identifier (e.g., `userName`) | + +- Outcomes: **True** (user found) / **False** (user not found) + +**Anti-enumeration wiring:** In recovery and reset journeys, wire both `True` and `False` outcomes to the same successor node (typically `EmailSuspendNode`). The user sees an identical message regardless of whether an account exists. Never route `True` and `False` to different user-facing messages — that leaks account existence. + +**Multiple uses per journey:** Used both as an entry lookup (recovery journeys look up by `mail`) and as an in-journey user context loader (MFA inner journeys load user context before PingOne Protect evaluation). + +### Display Username node +Displays the authenticated or recovered user's username on the current page. + +- Configuration: `userName: userName`, `identityAttribute: mail` +- Outcomes: single — no branching +- Used in OOTB Account Recovery to show the recovered username in the browser after email verification, before routing to the Login inner journey +- Contrast with the Forgotten Username journey, which sends the username in the email body instead of displaying it in-browser + +--- + +## Attribute Collection + +### Attribute Collector node +Prompts the user to provide values for specified identity schema attributes. + +**Configuration:** + +| Field | Notes | +|---|---| +| `attributesToCollect` | List of schema attribute names; must be present and viewable in identity schema | +| `required` | When `true`, all fields are mandatory (node name in config: `required`, label: "All Attributes Required") | +| `validateInputs` | When `true`, enforces IDM schema policy against submitted values | +| `identityAttribute` | Attribute used to identify the managed object (default: `userName`) | + +- Outcomes: single (attribute values stored in shared state) +- Supports dot-path notation for nested attributes: `preferences/marketing`, `preferences/updates` +- Must be a PageNode child — standalone AttributeCollector renders no fields (see `nodes/utility-nodes.md` Rule 1) + +### Attribute Present Decision node +Checks whether a specific attribute exists on the managed user object (regardless of whether the field is private). + +**Configuration:** + +| Field | Notes | +|---|---| +| `presentAttribute` | The object attribute to verify is present (e.g., `password`) | +| `identityAttribute` | The attribute to query in the IDM object (e.g., `userName`) | + +- Outcomes: **True** (attribute present) / **False** (attribute absent) +- Use case: detect passwordless users — `presentAttribute: password` returns `False` for users without a password set, enabling conditional branching to email-gate verification instead of current-password challenge + +### Attribute Value Decision node +Evaluates whether a specific attribute in the user's profile matches a configured comparison operation. + +**Configuration:** + +| Field | Notes | +|---|---| +| `comparisonOperation` | `PRESENT` — checks for attribute existence; `EQUALS` — checks if attribute value equals `comparisonValue` | +| `comparisonAttribute` | The object attribute to compare (e.g., `emailVerified`) | +| `comparisonValue` | The value to compare against when using `EQUALS` operation (e.g., `true`) | +| `identityAttribute` | The attribute used to look up the IDM object (e.g., `userName`) | + +- Outcomes: **True** / **False** +- `PRESENT` is equivalent to a null-check and does not require a `comparisonValue` +- Common use: "Is Email Verified?" gate — `comparisonAttribute: emailVerified`, `comparisonOperation: EQUALS`, `comparisonValue: true`; `False` triggers email verification flow + +### Required Attributes Present node +Checks whether all required attributes are present in shared state before proceeding. + +- Outcomes: **True** (all present) / **False** (one or more missing) +- Use before `CreateObjectNode` in registration flows to prevent partial user creation + +--- + +## User Object Operations + +### Create Object node +Creates a new managed object (typically `managed/alpha_user`) using attributes collected in shared state. + +**Configuration:** + +| Field | Notes | +|---|---| +| `identityResource` | The IDM identity resource to create (e.g., `managed/alpha_user`). Must match the journey's identity resource. | + +- Outcomes: **CREATED** / **FAILURE** +- On `FAILURE`: in production journeys, the failure path runs a `ScriptedDecisionNode` ("Delete User Entry") to clean up any partially created record before routing to FailureNode — prevents orphaned partial accounts +- `CREATED`: route to `IncrementLoginCountNode` to initialize the login count to 1 (enables `LoginCountDecisionNode` to trigger on the subsequent login) + +### Patch Object node +Updates an existing managed object with attribute values from shared state. + +**Configuration:** + +| Field | Notes | +|---|---| +| `identityResource` | The IDM identity resource to patch (e.g., `managed/alpha_user`). Must match the journey's identity resource. | +| `patchAsObject` | `false` (default) — merges changes rather than replacing the whole object | +| `ignoredFields` | Fields from shared state to exclude from the patch (e.g., `[userName]` prevents username modification) | +| `identityAttribute` | Attribute used to look up the object (usually `userName` or `mail`) | + +- Outcomes: **PATCHED** / **FAILURE** +- Uses: password update, email verification status flag, preferences update, MFA device metadata update + +--- + +## Social Login + +### Social Provider Handler node (V2) +Initiates authentication via a configured social identity provider (Google, Apple, Facebook, etc.) or any OIDC-compliant external IdP. Use V2 — V1 (`SocialProviderHandlerNode`) is deprecated. + +**Configuration:** + +| Field | Notes | +|---|---| +| `script` | Transformation script to map normalized IdP claims to managed object attributes | +| `usernameAttribute` | The IDM attribute containing the username for this object | +| `clientType` | `BROWSER` (default) or `NATIVE` (for Ping SDK for Android/iOS) | +| `storeTokens` | `true` stores access and refresh tokens in transient state (needed to revoke user authorization later) | +| `subjectAttribute` | LDAP attribute from which the subject value is retrieved; only used when IDM Provisioning is disabled | +| `detectConnectionTimeOut` | `true` enables timeout detection and routes to `timeoutOutcome` | + +- Outcomes: **ACCOUNT_EXISTS** / **NO_ACCOUNT** / **SOCIAL_AUTH_INTERRUPTED** / **timeoutOutcome** (if `detectConnectionTimeOut: true`) +- `ACCOUNT_EXISTS`: continue to authentication or profile completion +- `NO_ACCOUNT`: route to profile collection PageNode → `CreateObjectNode` for social registration +- `SOCIAL_AUTH_INTERRUPTED`: route to FailureNode +- `timeoutOutcome`: route to FailureNode or retry + +**Entry pattern:** Present a PageNode with a `ScriptedDecisionNode` or `ChoiceCollector` exposing outcomes `localAuthentication` / `socialAuthentication` as the first step. The social path leads to Social Provider Handler; the local path leads to username/password collection. + +### Select Identity Provider node (`SelectIdPNode`) +Presents the user with a list of available social identity providers to choose from. Produces a `socialAuthentication` or `localAuthentication` outcome. + +**Configuration:** + +| Field | Notes | +|---|---| +| `includeLocalAuthentication` | `true` adds local username/password as an option alongside social providers | +| `offerOnlyExisting` | `true` limits choices to providers already linked to the user's account (requires IDM) | +| `passwordAttribute` | The IDM attribute that verifies the user during local authentication (required when `offerOnlyExisting: true`) | +| `identityAttribute` | Attribute used to look up an existing user (required when `offerOnlyExisting: true`) | +| `filteredProviders` | List of specific provider names to display; empty = all providers in Social Identity Provider Service | + +- Outcomes: **socialAuthentication** / **localAuthentication** +- Use `SelectIdPNode` as an alternative to a manual PageNode + ChoiceCollector entry pattern — it renders the IdP picker UI automatically + +--- + +## Consent and Terms + +### Accept Terms and Conditions node +Presents the current T&C version to the user and records acceptance with timestamp and version. + +- Outcomes: single +- Common placement: embedded as a PageNode child alongside registration fields (co-located with signup form) + +### Terms and Conditions Decision node +Checks whether the user has accepted the current version of terms. + +- Outcomes: **True** (accepted and current) / **False** (not accepted or version outdated) +- `False` → `AcceptTermsAndConditionsNode`; used in authentication journeys to enforce T&C re-acceptance when a new version is published + +### Consent Collector node +Collects user consent for data processing or specific purposes defined in the IDM consent schema. + +**Configuration:** + +| Field | Notes | +|---|---| +| `allRequired` | `true` — all configured mappings require consent to proceed | +| `message` | Localized privacy and consent notice displayed to the user | + +- Outcomes: single + +--- + +## Knowledge-Based Authentication (KBA) + +### KBA Definition node +Prompts the user to define KBA security questions and answers during enrollment. + +**Configuration:** + +| Field | Notes | +|---|---| +| `message` | Localized message describing the purpose (default: "Select a security question.") | +| `allowUserDefinedQuestions` | `true` allows users to write their own custom KBA questions | + +- Outcomes: single (questions stored in user profile) + +### KBA Verification node +Presents the user's pre-defined KBA questions and checks answers. + +**Configuration:** + +| Field | Notes | +|---|---| +| `kbaInfoAttribute` | The attribute in the IDM user object where KBA questions/answers are stored | +| `identityAttribute` | The IDM attribute used to identify the object (e.g., `userName`) | + +- Outcomes: **True** (answers correct) / **False** (answers incorrect) + +### KBA Decision node +Evaluates whether the user has already set up KBA questions (i.e., meets the system's minimum required count). + +**Configuration:** + +| Field | Notes | +|---|---| +| `identityAttribute` | The IDM attribute used to retrieve the object | + +- Outcomes: **True** (KBA set up and meets minimum) / **False** (not set up or insufficient) + +--- + +## Profile Completeness + +### Profile Completeness Decision node +Checks whether the user's profile meets a configured completeness threshold (% of non-null, user-viewable, user-editable fields). + +**Configuration:** + +| Field | Notes | +|---|---| +| `threshold` | Percentage [0–100] of required fields that must be populated | +| `identityAttribute` | The attribute to query for the IDM object | + +- Outcomes: **True** (profile meets threshold) / **False** (profile incomplete) +- Use to trigger progressive profiling after login + +### Query Filter Decision node +Evaluates an LDAP/SCIM-style filter against the user's profile attributes. + +**Configuration:** + +| Field | Notes | +|---|---| +| `queryFilter` | SCIM/LDAP-style filter string evaluated against the user object | +| `identityAttribute` | Attribute used to retrieve the user object | + +- Outcomes: **True** (filter matches) / **False** (filter does not match) +- SCIM filter syntax example: `"!(/preferences pr) or /preferences/marketing eq false or /preferences/updates eq false"` — matches users who are missing the preferences attribute OR have it set to false +- Use dot-path notation for nested attributes: `/preferences/marketing` +- Use in combination with `LoginCountDecisionNode` for progressive profiling double-gate (see `journey-use-cases/progressive-profiling.md`) + +--- + +## User Lifecycle / Provisioning + +### Time Since Decision node +Evaluates whether a specified amount of time has elapsed since the user registered. + +**Configuration:** + +| Field | Notes | +|---|---| +| `elapsedTime` | Elapsed time in minutes to compare against | +| `identityAttribute` | The attribute to query in the IDM object | + +- Outcomes: **True** (elapsed time has passed) / **False** (elapsed time has not passed) +- Use case: gate time-sensitive flows (e.g., require re-verification if account was created more than N minutes ago) + +### Passthrough Authentication node +Authenticates a user against a third-party system via an ICF connector. Enables hybrid deployments where credentials are validated against an external system (Active Directory, LDAP, custom connector). + +**Configuration:** + +| Field | Notes | +|---|---| +| `systemEndpoint` | Name of the ICF connector to use for passthrough authentication | +| `objectType` | ICF object type for the authenticating object | +| `identityAttribute` | Attribute used as the username for authentication | +| `passwordAttribute` | Attribute used as the password for authentication | + +- Outcomes: **Authenticated** / **Failed** / **Missing Input** +- `Missing Input`: one or both credentials not present in state — route to credential collection +- Use when migrating from legacy directories that cannot be replaced immediately + +--- + +## PingOne Verify (Identity Proofing) + +### PingOne Verify Evaluation node +Initiates a PingOne Verify identity proofing session (document capture, liveness check). + +- Outcomes: **Success** / **Failure** / **Error** +- Requires PingOne Verify service configured in the environment + +### PingOne Verify Completion Decision node +Checks the result of an ongoing PingOne Verify session. + +- Outcomes: **Pass** / **Fail** / **Pending** + +--- + +## PingOne User Operations + +### PingOne Create User node +Creates a user in PingOne MT from within an AIC journey. + +### PingOne Delete User node +Deletes a PingOne MT user from within an AIC journey. + +### PingOne Identity Match node +Attempts to match an authenticating user against a PingOne identity. + +- Outcomes: **Single Match** / **No Match** / **Multiple Matches** + +--- + +## Common patterns + +| Pattern | Nodes | +|---|---| +| Self-registration | AttributeCollector → RequiredAttributesPresent → CreateObject(CREATED) → IncrementLoginCount → Success | +| Create Object with cleanup | CreateObject(FAILURE) → ScriptedDecision("Delete User Entry") → FailureNode | +| Progressive profiling | ProfileCompletenessDecision(False) → AttributeCollector → PatchObject | +| T&C enforcement | TermsAndConditionsDecision(False) → AcceptTermsAndConditions → Success | +| KBA enrollment at first login | KbaDecision(False) → KbaCreate → Success | +| Anti-enumeration lookup | IdentifyExistingUser(true AND false) → EmailSuspendNode (same successor for both outcomes) | +| Passwordless branch | AttributePresentDecision(`password` = False) → EmailSuspendNode | +| Email verification gate | AttributeValueDecision(`emailVerified` EQUALS `true` = False) → email verification inner journey | +| Social + local choice | SelectIdPNode(socialAuthentication) → SocialProviderHandlerV2 / (localAuthentication) → Platform Username path | +| Passthrough auth (migration) | CredentialCollection → PassthroughAuthenticationNode(Authenticated) → Success / (Failed) → FailureNode | +| Social registration | SocialProviderHandlerV2(NO_ACCOUNT) → PageNode(AttributeCollector) → RequiredAttributesPresent → CreateObject | +| Time-gated re-verification | TimeSinceDecision(True) → verification inner journey | + +## Related references + +- `nodes/basic-auth-nodes.md` +- `nodes/utility-nodes.md` +- `journey-use-cases/account-recovery-and-username-reminder.md` +- `journey-use-cases/social-and-local-registration-authentication.md` +- `journey-use-cases/progressive-profiling.md` + +## Source + +[Identity management nodes](https://docs.pingidentity.com/auth-node-ref/latest/overview.html) +[Attribute Collector node](https://docs.pingidentity.com/auth-node-ref/latest/attribute-collector.html) +[Create Object node](https://docs.pingidentity.com/auth-node-ref/latest/create-object.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/mfa-nodes.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/mfa-nodes.md new file mode 100644 index 0000000..b088f0a --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/mfa-nodes.md @@ -0,0 +1,319 @@ +--- +title: "PingOne ST — MFA Nodes" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: ["mfa"] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: reference +status: current +canonical: true +last_updated: "2026-05-21" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — MFA Nodes + +Nodes for registering and verifying second factors: WebAuthn/passkeys, OATH/TOTP, push, OTP, and recovery codes. + +## Scope + +**Covers:** All built-in MFA node types, their configuration, outcomes, and composition patterns — including production-observed settings from live journey exports. +**Does NOT cover:** Risk-based MFA step-up routing — see `nodes/risk-management-nodes.md`. PingOne Verify (identity proofing) — see `ping-universal-services`. + +--- + +## WebAuthn / Passkeys + +### WebAuthn Registration node +Registers a FIDO2/WebAuthn authenticator (passkey, security key, platform authenticator) for a user. + +**Production configuration:** + +| Field | Observed value | Notes | +|---|---|---| +| `userVerificationRequirement` | `PREFERRED` | Allows devices without UV but prefers it | +| `authenticatorAttachment` | `UNSPECIFIED` | Platform or cross-platform authenticators accepted | +| `generateRecoveryCodes` | `true` | Always enable; recovery codes displayed immediately after | +| `maxSavedDevices` | `0` | Unlimited registered devices per user | +| `attestationPreference` | `NONE` | No attestation statement required | +| `acceptedSigningAlgorithms` | `[ES256, RS256]` | Covers most device types | +| `timeout` | `60` | Seconds before registration attempt expires | +| `asScript` | `true` | Required for hosted pages; injects WebAuthn as a script | + +- Outcomes: **success** / **unsupported** / **failure** / **error** +- On `success`: route immediately to `RecoveryCodeDisplayNode` before proceeding +- On `unsupported`, `failure`, `error`: route to FailureNode or back to device selection +- Requires HTTPS. Configure Relying Party Identifier (defaults to tenant domain). + +### WebAuthn Authentication node +Authenticates a user with a previously registered FIDO2 device. + +**Production configuration:** + +| Field | Observed value | Notes | +|---|---|---| +| `userVerificationRequirement` | `PREFERRED` | | +| `isRecoveryCodeAllowed` | `true` | Exposes `recoveryCode` outcome | +| `timeout` | `60` | | +| `detectSignCountMismatch` | `false` | Set `true` in high-security deployments to detect cloned authenticators | +| `asScript` | `true` | | + +- Outcomes: **success** / **unsupported** / **noDevice** / **failure** / **error** / **recoveryCode** +- Route `noDevice` to device registration inner journey, not directly to Failure +- Route `recoveryCode` to a dedicated PageNode embedding `RecoveryCodeCollectorDecisionNode` (type: `WEB_AUTHN`) +- Route `No Device Registered` / `noDevice` to the same failure handling as `failure` to prevent username enumeration + +### WebAuthn Device Storage node +Persists the registered WebAuthn device credential to the user's profile. + +- Place after WebAuthn Registration `success` outcome, before RecoveryCodeDisplayNode. + +--- + +## OATH / TOTP + +### OATH Registration node +Registers a TOTP/HOTP authenticator app by generating and displaying a QR code shared secret. + +**Production configuration:** + +| Field | Observed value | Notes | +|---|---|---| +| `algorithm` | `TOTP` | Standard time-based OTP | +| `passwordLength` | `SIX_DIGITS` | | +| `totpTimeInterval` | `30` | Standard 30-second window | +| `addChecksum` | `false` | | +| `generateRecoveryCodes` | `true` | Always enable | +| `minSharedSecretLength` | `32` | | +| `accountName` | `USERNAME` | Displayed in the authenticator app | +| `issuer` | `ForgeRock` or tenant name | Displayed in the authenticator app | +| `bgColor` | `032b75` | QR code background color | + +- Outcomes: single (on success; display OATH device QR code) +- Always preceded by `GetAuthenticatorAppNode` when the user may not have an authenticator app installed +- On `successOutcome`: route to `RecoveryCodeDisplayNode` + +### Get Authenticator App node +Displays download links for the ForgeRock Authenticator (Play Store + App Store) before OATH or Push registration. Used when `OathTokenVerifierNode` or `PushAuthenticationSenderNode` returns `notRegisteredOutcome` / `NOT_REGISTERED`. + +- Outcomes: single (user has acknowledged; proceed to registration) +- ForgeRock Authenticator URLs: Play Store `com.forgerock.authenticator`, App Store ID `1038442926` + +### OATH Token Verifier node +Verifies the OTP entered by the user against the registered OATH device. + +**Production configuration:** + +| Field | Observed value | Notes | +|---|---|---| +| `algorithm` | `TOTP` | | +| `totpTimeInterval` | `30` | | +| `totpHashAlgorithm` | `HMAC_SHA1` | | +| `totpTimeSteps` | `2` | Clock drift allowance: ±1 window | +| `maximumAllowedClockDrift` | `5` | Minutes | +| `hotpWindowSize` | `100` | For HOTP counter drift | +| `isRecoveryCodeAllowed` | `true` | Exposes `recoveryCodeOutcome` | + +- Outcomes: **successOutcome** / **failureOutcome** / **notRegisteredOutcome** / **recoveryCodeOutcome** +- `notRegisteredOutcome`: route to `GetAuthenticatorAppNode` → OATH Registration +- `recoveryCodeOutcome`: route to dedicated recovery code PageNode +- Must be embedded as a PageNode child, alongside a `ScriptedDecisionNode` ("Validate Verification Code") for client-side input validation +- On `failureOutcome`: route to `RetryLimitDecisionNode` (see retry-loop-with-lockout pattern below) + +### OATH Device Storage node +Persists the OATH device to the user's profile. Place after OATH Registration before proceeding. + +### HOTP Generator node +Generates an HMAC-based OTP for delivery via a side channel (email script, SMS). + +- `length: 6` — stores OTP in transient state as `oneTimePassword` +- Outcomes: single +- Used in email-delivered OTP flows where `OTPEmailSenderNode` is not used (e.g., when delivery is handled by a custom `ScriptedDecisionNode` calling IDM `openidm.action()`) + +--- + +## Push Authentication + +### Push Registration node +Registers the user's mobile device for push-based authentication. + +- Outcomes: **successOutcome** / **failureOutcome** / **timeoutOutcome** +- On `successOutcome`: route to `RecoveryCodeDisplayNode` +- Always preceded by `GetAuthenticatorAppNode` when device may not be enrolled + +### Push Sender node +Sends a push notification to the user's registered device. + +**Production configuration:** + +| Field | Observed value | Notes | +|---|---|---| +| `pushType` | `DEFAULT` | | +| `mandatory` | `true` | Requires a response | +| `messageTimeout` | `120000` | Milliseconds (2 minutes) | +| `captureFailure` | `false` | | +| `contextInfo` | `false` | | + +- Outcomes: **SENT** / **NOT_REGISTERED** +- `NOT_REGISTERED`: route to `GetAuthenticatorAppNode` → Push Registration + +### Push Wait node +Polls for the result of a sent push notification. + +- `secondsToWait: 5` +- Outcomes: **DONE** (polling complete; proceed to `PushResultVerifierNode`) / **EXITED** (user chose to enter a code instead) +- `EXITED`: route to an OTP/OATH verification PageNode as a fallback when the user dismisses the push wait screen + +### Push Result Verifier node +Verifies the final push authentication result. + +- Outcomes: **TRUE** (approved) / **FALSE** (denied) / **WAITING** (not yet responded) / **EXPIRED** (timed out) +- `WAITING`: loop back through `PushWaitNode` → `DONE` → return to PushResultVerifierNode +- `EXPIRED`: route to `RetryLimitDecisionNode` → `Retry` → re-send push; `Reject` → FailureNode +- `FALSE` (denied): route directly to FailureNode + +--- + +## OTP via Email / SMS + +### OTP Email Sender node +Generates a one-time password and sends it to the user's registered email address. + +- Outcomes: single (OTP stored in transient state) + +### OTP SMS Sender node (`OneTimePasswordSmsSenderNode`) +Generates and sends an OTP to the user's phone via SMS. + +- Outcomes: single +- Used in phone-based MFA device registration (phone-number verification before enrollment) + +### OTP Collector Decision node +Collects and validates the OTP entered by the user. + +- `passwordExpiryTime: 5` (minutes) +- Outcomes: **True** (OTP valid) / **False** (OTP invalid or expired) +- On `False`: route to `RetryLimitDecisionNode` (see retry-loop-with-lockout pattern) + +> **PageNode required:** `OTP Collector Decision` must always be a PageNode child. A standalone instance renders no input field. Always embed it in a PageNode with a `ScriptedDecisionNode` for input validation (see `nodes/utility-nodes.md` → PageNode Rule 3). + +--- + +## Recovery Codes + +### Recovery Code Display node +Generates and displays recovery codes to the user immediately after MFA enrollment. Codes are stored in the user's profile. + +- Outcomes: single +- **Always place immediately after the MFA registration node's success outcome** — before any other step. If the user exits without seeing the codes, they lose access to them. + +### Recovery Code Collector Decision node +Prompts for and validates a recovery code as an alternative to the primary MFA factor. + +- `recoveryCodeType`: set to the MFA method — `OATH` / `WEB_AUTHN` / `PUSH` +- Outcomes: **True** (code valid) / **False** (code invalid) +- Must be a PageNode child alongside a `ScriptedDecisionNode` ("Validate Recovery Code") for client-side input validation + +--- + +## Recovery Code Architecture + +The following pattern appears consistently across all production MFA journeys: + +``` +Registration: + [MFA Registration node] (generateRecoveryCodes: true) + → successOutcome → RecoveryCodeDisplayNode → proceed + +Authentication: + [MFA Verifier node] (isRecoveryCodeAllowed: true) + → recoveryCodeOutcome → PageNode(RecoveryCodeCollectorDecisionNode, ScriptedDecisionNode) + → True → Success + → False → RetryLimitDecisionNode +``` + +Each `RecoveryCodeCollectorDecisionNode` must be typed to the MFA method via `recoveryCodeType`. Mixing types (e.g., using an OATH-typed collector with a WebAuthn authentication flow) causes validation failures. + +--- + +## Combined Registration + +### Combined MFA Registration node +Registers both OATH (TOTP) and Push simultaneously in a single step. + +**Production configuration:** `algorithm: TOTP`, `passwordLength: SIX_DIGITS`, `totpTimeInterval: 30`, `generateRecoveryCodes: true` + +- Outcomes: **successOutcome** / **failureOutcome** / **timeoutOutcome** +- `timeoutOutcome`: route to `RetryLimitDecisionNode` for retry +- On `successOutcome`: route to `RecoveryCodeDisplayNode` +- Use when the device selection PageNode offers an `OATH+PUSH` combined option + +### MFA Registration Options node +Allows users to select which MFA factors to register. + +### Enable Device Management node +Enables device management capabilities for subsequent device binding nodes. + +--- + +## Device Binding + +### Device Binding node +Binds the current device to the authenticated user using a device-specific key. + +- Outcomes: **Success** / **Failure** / **Unsupported** + +### Device Binding Storage node +Persists device binding data to the user's profile. + +### Device Signing Verifier node +Verifies a device signature created by a previously bound device. + +- Outcomes: **Success** / **Failure** / **No Device Bound** + +--- + +## Retry-Loop-With-Lockout Pattern + +Every MFA input path in production journeys uses a consistent retry loop: + +``` +[Input PageNode] + → failure outcome + → RetryLimitDecisionNode (retryLimit: 3, incrementUserAttributeOnFailure: true) + → Retry → ScriptedDecisionNode ("Set Invalid Code Error Message") + → [Input PageNode] (reads invalidCodeErrorMessage from shared state via callbacksBuilder.textOutputCallback) + → Reject → FailureNode +``` + +The `ScriptedDecisionNode` sets `invalidCodeErrorMessage` in shared state. The PageNode script reads it and displays the error inline on the next render without an extra round-trip. This pattern applies to OATH, OTP, recovery code, and Push-expired retry flows. + +--- + +## Common patterns + +| Pattern | Nodes | +|---|---| +| WebAuthn login | WebAuthn Authentication → (noDevice) → WebAuthn Registration | +| TOTP registration | GetAuthenticatorAppNode → OATH Registration → OATH Device Storage → Recovery Code Display | +| TOTP authentication | PageNode(OathTokenVerifierNode + ScriptedDecisionNode) → (successOutcome) Success | +| OTP email step-up | OTP Email Sender → PageNode(OTP Collector Decision) → (True) Success | +| Push authentication | Push Sender → (SENT) Push Wait → (DONE) Push Result Verifier → (TRUE) Success | +| Push with EXITED fallback | Push Wait(EXITED) → PageNode(OathTokenVerifierNode) → retry loop | +| Combined MFA enrollment | Combined MFA Registration → Recovery Code Display → Success | +| Recovery code fallback (OATH) | OathTokenVerifierNode(recoveryCodeOutcome) → PageNode(RecoveryCodeCollectorDecisionNode[OATH]) → (True) Success | + +## Related references + +- `nodes/basic-auth-nodes.md` +- `nodes/risk-management-nodes.md` +- `nodes/utility-nodes.md` +- `journey-use-cases/mfa-authentication-multi-method.md` +- `journey-use-cases/passwordless-mfa-registration.md` + +## Source + +[MFA nodes overview](https://docs.pingidentity.com/auth-node-ref/latest/overview.html) +[WebAuthn Authentication node](https://docs.pingidentity.com/auth-node-ref/latest/webauthn-authentication.html) +[OATH nodes](https://docs.pingidentity.com/auth-node-ref/latest/oath-registration.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/node-fundamentals.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/node-fundamentals.md new file mode 100644 index 0000000..c33f0c4 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/node-fundamentals.md @@ -0,0 +1,103 @@ +--- +title: "PingOne ST — Node Fundamentals" +product_family: pingone-st +products: ["pingone-aic", "pingam"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: reference +status: current +canonical: true +last_updated: "2026-05-19" +slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" +--- + +# PingOne ST — Node Fundamentals + +Tribal knowledge and non-obvious invariants about how nodes behave in PingOne ST journeys. Rules here are validated from live AIC sessions — they are not documented clearly in official docs and are common sources of bugs. + +## Scope + +**Covers:** Node composition rules, PageNode usage, child node requirements, outcome wiring, and known gotchas. +**Does NOT cover:** Individual node reference — see the specific node files (e.g., `basic-auth-nodes.md`, `mfa-nodes.md`, `utility-nodes.md`). + +--- + +## PageNode rules + +### PageNode is never used alone + +A PageNode without child nodes renders as an empty page ("Drag nodes here") — no inputs, no outcomes, no way for the user to proceed. PageNodes only work when child nodes are declared inside `config.nodes`. + +This is the most common PageNode bug in `createJourney` calls: the PageNode is created but its children are omitted or passed as an empty array. + +### Child nodes must be declared in `config.nodes` + +When building a journey via the API or `createJourney`, child nodes of a PageNode must be listed in the `config.nodes` array. Each entry requires at minimum: + +```json +{"nodeType": "", "displayName": "