diff --git a/.gitignore b/.gitignore index df7ebe2..fcfe641 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,4 @@ docs/ *.local.json .env.local .env +.plans/ diff --git a/evals/prompts/ping-foundation.yaml b/evals/prompts/ping-foundation.yaml index a4881e9..e5dd814 100644 --- a/evals/prompts/ping-foundation.yaml +++ b/evals/prompts/ping-foundation.yaml @@ -175,6 +175,52 @@ trigger_prompts: expected_tier: curated notes: "Bare 'AIC' → pingone-st." + # ----- Config promotion (added 2026-06-22) ----- + + - id: T-83 + prompt: "How do I promote my PingOne configuration from sandbox to production — what's supported and what's not?" + expected_anchors: + - plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md + expected_tier: curated + notes: "PingOne native promotion scope + constraints." + + - id: T-84 + prompt: "We use AIC with dev, staging, and prod tenants. What's the right way to promote config between them?" + expected_anchors: + - plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md + expected_tier: curated + notes: "AIC self-service promotion topology → config-promotion anchor." + + - id: T-85 + prompt: "We want a Terraform-based config-as-code pipeline for promoting PingOne and PingFederate config across environments. Where do we start?" + expected_anchors: + - plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md + expected_tier: curated + notes: "Terraform GitOps promotion pattern → config-promotion anchor." + + # ----- Ping CLI automation (added 2026-06-22) ----- + + - id: T-80 + prompt: "How do I use pingcli to export my PingOne and PingFederate configuration as Terraform HCL?" + expected_anchors: + - plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md + expected_tier: curated + notes: "Explicit pingcli + Terraform export → cross-platform CLI anchor." + + - id: T-81 + prompt: "Set up multiple Ping CLI configuration profiles so I can promote DaVinci changes from dev to prod in CI/CD." + expected_anchors: + - plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md + expected_tier: curated + notes: "Multi-env profiles + CI/CD promotion → ping-cli-basics." + + - id: T-82 + prompt: "How do I authenticate pingcli to PingFederate and run admin API calls from a script?" + expected_anchors: + - plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md + expected_tier: curated + notes: "pingcli PingFederate auth + raw API → ping-cli-basics." + non_trigger_prompts: - id: N-01 prompt: "Build a DaVinci flow for customer login with risk-based step-up MFA." @@ -203,6 +249,16 @@ non_trigger_prompts: expected_skill: ping-quickstart notes: "Bare command with no platform named — must route to ping-quickstart for clarification first." + - id: N-07 + prompt: "Design a DaVinci flow that does passwordless login with passkeys." + expected_skill: ping-orchestration + notes: "DaVinci flow design belongs in ping-orchestration, not ping-foundation, even though pingcli can manage DaVinci resources." + + - id: N-08 + prompt: "How do I rotate the client secret on my PingOne Worker app?" + expected_skill: ping-foundation + notes: "Secret rotation is a platform admin task → core-admin-patterns.md, not config-promotion.md." + ambiguous_prompts: - id: A-01 prompt: "Configure MFA." diff --git a/evals/prompts/ping-orchestration.yaml b/evals/prompts/ping-orchestration.yaml index 5c65351..493fcf1 100644 --- a/evals/prompts/ping-orchestration.yaml +++ b/evals/prompts/ping-orchestration.yaml @@ -132,6 +132,29 @@ trigger_prompts: expected_tier: curated notes: "feedback: push MFA transaction approval trigger" + # ----- Config promotion (added 2026-06-22) ----- + + - id: T-59 + prompt: "I built a registration journey in our AIC dev tenant — how do I promote it to staging without breaking ESVs?" + expected_anchors: + - plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md + expected_tier: curated + notes: "AIC journey promotion + ESV gotcha → journey-and-flow-promotion anchor." + + - id: T-60 + prompt: "What's the best way to move a DaVinci flow from one PingOne environment to another and keep connector credentials per environment?" + expected_anchors: + - plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md + expected_tier: curated + notes: "DaVinci flow promotion variables → journey-and-flow-promotion anchor." + + - id: T-61 + prompt: "We have scripted decision nodes referencing environment-specific endpoints. How do we promote the journey across environments?" + expected_anchors: + - plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md + expected_tier: curated + notes: "Scripted Decision node + ESV placeholder during AIC promotion." + non_trigger_prompts: - id: N-01 prompt: "How do I install PingFederate on RHEL and configure initial admin settings?" diff --git a/plugins/ping-identity/skills/ping-app-integration/SKILL.md b/plugins/ping-identity/skills/ping-app-integration/SKILL.md index d59ec41..0a68132 100644 --- a/plugins/ping-identity/skills/ping-app-integration/SKILL.md +++ b/plugins/ping-identity/skills/ping-app-integration/SKILL.md @@ -11,6 +11,8 @@ metadata: Implementation skill for integrating Ping Identity into web, mobile, and application SDK experiences. +**What this skill does for you:** Generates app-side integration code — SDK wiring, OIDC/PKCE flows, token handling — and guides you through the SDK docs and troubleshooting where code generation alone is not enough. Primarily an artifact-generating skill. + ## Invocation Invoke explicitly with `/ping-app-integration` or by saying "use ping-app-integration to...". diff --git a/plugins/ping-identity/skills/ping-foundation/SKILL.md b/plugins/ping-identity/skills/ping-foundation/SKILL.md index 4fd5d87..d1e380f 100644 --- a/plugins/ping-identity/skills/ping-foundation/SKILL.md +++ b/plugins/ping-identity/skills/ping-foundation/SKILL.md @@ -1,6 +1,6 @@ --- name: ping-foundation -description: "Use when setting up, configuring, or administering any Ping Identity platform — PingOne, PingOne Advanced Identity Cloud (AIC), or Ping Advanced Identity Software (PingAM, PingFederate, PingAccess, PingDirectory, PingID). Covers tenant/environment creation, app registration (including Worker apps and service accounts for M2M API access), SSO, directories, policies, and branding. Requires a named or clearly implied platform." +description: "Use when setting up, configuring, or administering any Ping Identity platform — PingOne, PingOne Advanced Identity Cloud (AIC), or Ping Advanced Identity Software (PingAM, PingFederate, PingAccess, PingDirectory, PingID). Covers tenant/environment creation, app registration (including Worker apps and service accounts for M2M API access), SSO, directories, policies, branding, and CLI-driven configuration automation (pingcli, Terraform/CaC export, multi-env promotion). Requires a named or clearly implied platform." compatibility: Designed for Ping Identity platform tasks. MCP tools for PingOne and PingOne Advanced Identity Cloud (AIC) are used when available; console instructions provided as fallback. metadata: publisher: Ping Identity @@ -11,6 +11,8 @@ metadata: 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. MCP tools handle execution; this skill supplies architecture patterns, sequencing, configuration constraints, and guardrails. +**What this skill does for you:** Generates configuration and drives setup directly through MCP tools where they exist (PingOne, AIC); where a tool does not exist, it guides you through the docs with the correct sequencing, field constraints, and guardrails. Both modes are available — it uses whichever the platform supports for the task. + ## Invocation Invoke explicitly with `/ping-foundation` or by saying "use ping-foundation to...". @@ -26,6 +28,7 @@ Trigger on ANY question about setting up, configuring, administering, or plannin - Configure authentication policies, sign-on policies, or branding - Administer PingFederate, PingAccess, PingDirectory, or PingID - Deploy or upgrade on-premises Ping software +- Automate configuration with Ping CLI (`pingcli`), export Terraform/CaC packages, or manage multi-environment promotion pipelines - Advisory: "How should I structure my tenant?", "What client type should I use?" ## When NOT to use this skill @@ -93,6 +96,13 @@ Trigger on ANY question about setting up, configuring, administering, or plannin | PingAccess web app and API protection | `references/curated/ping-software/pingaccess-basics.md` | | Cross-platform admin patterns (LDAP, OIDC, APIs) | `references/curated/cross-platform/core-admin-patterns.md` | +## Cross-platform tooling + +| Task | Anchor | +|---|---| +| CLI-driven config, multi-env profiles, Terraform/CaC export across PingOne, DaVinci, PingFederate | `references/curated/cross-platform/ping-cli-basics.md` | +| Promote configuration between environments (PingOne native promotion, AIC self-service promotions, Ping CLI + Terraform config-as-code) | `references/curated/cross-platform/config-promotion.md` | + ## MCP execution See `references/runtime/mcp-preflight.md` for MCP config and Cursor preflight steps. diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md new file mode 100644 index 0000000..79036c3 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md @@ -0,0 +1,177 @@ +--- +title: "Configuration Promotion Across Environments" +product_family: cross-platform +products: ["pingone", "pingone-st", "pingfederate", "pingaccess", "pingdirectory"] +capabilities: ["foundation"] +services: [] +audience: ["admin", "architect", "operator"] +use_cases: ["workforce", "customer", "cross-platform"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-06-22" +slug: "https://developer.pingidentity.com/config-automation-promotion/configuration_promotion_landing_page.html" +--- + +# Configuration Promotion Across Environments + +How to move Ping Identity configuration between development, staging, and production environments across PingOne, AIC, and Ping Software. + +## Scope + +**Covers:** Choosing a promotion model; environment topology rules; what promotes vs what does not; promotion variables and ESV placeholders; hard limits and constraints; rollback; GitOps with Ping CLI + Terraform; model selection. + +**Does NOT cover:** Journey- and flow-specific promotion concerns — scripted decision node ESV gotchas, DaVinci flow versioning, environment lock impact on running journeys — see `ping-orchestration` → `references/curated/cross-platform/journey-and-flow-promotion.md`. Secret rotation — see `references/curated/cross-platform/core-admin-patterns.md`. Bulk user import and data migration (users, sessions, audit logs are never promoted — only static config moves). Ping CLI install and CRUD — see `references/curated/cross-platform/ping-cli-basics.md`. + +--- + +## Three promotion models + +| Model | Applies to | What moves | What does not move | Sequential constraint | +|---|---|---|---|---| +| **PingOne native promotion** | PingOne (multi-tenant cloud) | Applications, DaVinci flows and policies, sign-on policies, and most PingOne resources | Authorize, Credentials, Privilege, Recognize, runtime user data, sessions, audit logs | Source/target same org; check live docs for current resource scope | +| **AIC self-service promotions** | PingOne Advanced Identity Cloud | Journeys, scripts, themes, AM/IDM static config, ESV references | Live users, sessions, user-created applications, runtime data | Sequential pairs only: dev→staging, staging→production. Non-sequential promotion not supported. | +| **Ping CLI + Terraform (config-as-code)** | PingOne, PingFederate, DaVinci, and supported universal services | Terraform-managed config via Ping Identity Terraform providers | Per-resource, determined by provider support | None — Terraform manages state independently per target environment | + +--- + +## Environment topology + +### PingOne + +- Source and target must be in the **same PingOne organization**. +- The **Promotion Admin** role (or equivalent) is required in **both** the source and target environment. +- Both environments should expose the **same connected services** — promoting an application that references a service not enabled in the target will fail. +- Check the linked Ping documentation for resource types currently supported by the promotion API. + +### AIC + +- Promotion chain: **dev → staging → production**. Non-sequential (dev → production) is not supported. +- **Sandbox environments are excluded** from all promotion chains. Sandbox is a separate, isolated tier. +- If **UAT environments** are present, they are inserted into the chain: dev → UAT → staging → production. +- Rollback is available via API; it is not exposed in the admin console. + +### Ping Software (PingFederate, PingAccess, PingDirectory) + +- Configuration is managed via **server profiles** (Git-backed config-as-code). Promotion = merging and applying a server-profile branch. +- The Ping Identity Terraform providers cover PingFederate and PingDirectory for state-managed config-as-code. PingAccess does not have a Terraform provider. + +--- + +## What promotes vs what does not + +| Category | PingOne native | AIC self-service | Terraform/Ping CLI | +|---|---|---|---| +| Applications and OAuth clients | ✓ | ✓ (static; user-created apps excluded) | ✓ | +| Authentication flows / journeys / trees | ✓ (DaVinci flows) | ✓ (AIC journeys and AM config) | ✓ | +| Policies (sign-on, flow) | ✓ | ✓ | ✓ | +| Themes and branding | ✓ | ✓ | ✓ | +| Scripts | n/a | ✓ | ✓ | +| ESV / environment variables | Promotion variables only | ESV references move; secrets must be pre-configured in target | Via Terraform provider variables | +| Users, sessions, audit logs | ✗ never | ✗ never | ✗ never | +| Runtime user data (devices, MFA enrollments) | ✗ never | ✗ never | ✗ never | +| PingOne Authorize, Credentials, Privilege, Recognize | ✗ excluded | n/a | ✓ (where provider support exists) | + +--- + +## Promotion variables, ESVs, and placeholders + +Environment-specific values (connection endpoints, client IDs, URIs) must be externalised before promotion so the config is portable. + +| Platform | Mechanism | Key constraint | +|---|---|---| +| PingOne native | **Promotion variables** — named substitution tokens in the exported config | Created in the source environment; target environment values are specified at creation time in the source | +| AIC | **Environment secrets and variables (ESVs)** | ESVs referenced in static config must exist in the upper environment. AIC's integrity check blocks promotion if any ESV is missing or if an encrypted secret is embedded directly in config rather than referenced via an ESV. | +| Terraform | **Terraform input variables / `.tfvars` files per environment** | Standard Terraform pattern; per-environment variable files hold the target-specific values | + +--- + +## Hard limits and constraints + +| Platform | Constraint | Details | +|---|---|---| +| PingOne native | 100 resources per promotion (auto-included dependencies excluded from count) | Larger environments require multiple staged promotions | +| PingOne native | Environment lock not required | Source environment remains writable during promotion | +| PingOne native | Rollback restores the most recent promotion's state in the target | Available via admin console and API | +| AIC | **Environment lock required** on source and target during promotion | Blocks ESV API and most admin APIs in the development environment; **authentication flows for end users are unaffected** | +| AIC | Promotions take 10–45 minutes | Service restart in the upper environment is part of the process | +| AIC | Rollback available via API only | Admin console does not expose rollback | +| Terraform provider coverage | Resource and data source support varies by provider | Check the [Ping Terraform provider docs](https://terraform.pingidentity.com) for available resources and data sources | + +For current availability of specific resource types in native PingOne promotion, check the linked Ping documentation — this list changes as the feature evolves. + +--- + +## Rollback + +| Platform | Rollback model | How to trigger | +|---|---|---| +| PingOne native | Restores the target environment to its state before the most recent promotion | Admin console → Promote, or Configuration Management API | +| AIC | Restores the upper environment's prior static config set | API only (`POST /promotions/{id}/rollback`) | +| Terraform | Revert to prior state file or prior `apply` | Standard Terraform rollback — revert the commit and re-apply | + +--- + +## Choosing a promotion model + +For Ping's own guidance on model selection see the [configuration promotion overview](https://developer.pingidentity.com/config-automation-promotion/configuration_promotion_landing_page.html). + +| Scenario | Typical fit | Why | +|---|---|---| +| Config lives entirely within one PingOne org; team prefers admin-console workflow | PingOne native promotion | Designed for same-org, in-console use; automatic dependency management; no toolchain required | +| AIC tenant with dev/staging/prod environments | AIC self-service promotions | The platform-provided self-service promotion path for AIC; sequential pairs enforced by the platform (dev→staging→production only) | +| Cross-product (PingOne + PingFederate), cross-org, or Git-backed audit trail needed | Ping CLI + Terraform | Terraform providers cover PingFederate and PingDirectory (no PingAccess provider); Ping CLI CRUD for PingFederate is still rolling out — check the [compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html); state tracking and drift detection via Terraform | +| Mix of PingOne and AIC in the same pipeline | Can combine both | Native/AIC handles per-platform config; Terraform handles cross-product baseline and long-term state | +| PingFederate configuration between servers | Server profiles (Git) + Terraform provider | PingFederate's native config-as-code model; no equivalent in-console promotion UI | + +--- + +## Prerequisites + +- **PingOne native:** Promotion Admin role in both source and target environments; both in the same org. +- **AIC:** AIC tenant admin access in both environments; ESVs pre-configured in the upper environment. +- **Ping CLI / Terraform:** PingOne Worker app with admin roles; PingFederate admin API OAuth client; Terraform CLI; Ping Identity Terraform providers installed. + +--- + +## Common variants + +| Variant | Notes | +|---|---| +| Single-org PingOne, console workflow | Use native promotion for quick dev→test iteration; graduate to Terraform for long-term state management | +| AIC standard chain (dev/staging/prod) | Self-service promotions; ESVs must exist in target before promoting | +| AIC with UAT | dev → UAT → staging → production; non-sequential skips not supported | +| Cross-org or multi-tenant | Only Terraform covers this; native promotion is same-org only | +| Community tooling (fr-config-manager, frodo) | Widely used by AIC customers for bespoke config management; not an official Ping product — see their respective GitHub repositories | + +--- + +## Common gotchas + +| Symptom | Cause | Fix | +|---|---|---| +| AIC promotion blocked by integrity check | Missing ESV or encrypted secret embedded in config | Create the missing ESV in the upper environment; replace inline secrets with ESV references | +| PingOne promotion fails on service dependency | Target env missing a service the source config references | Enable the service in the target environment before promoting | +| AIC promotion locks admin APIs longer than expected | Large config sets take 10–45 minutes; lock is held throughout | Schedule promotions during low-traffic windows; monitor the promotion status API | +| Rollback restores unexpected state | Multiple promotions in quick succession | Wait for each promotion to complete before running the next; check the promotion history before rollback | +| Terraform provider missing a resource type | Resource not yet in provider support | Check the Ping Terraform provider changelog; use `pingcli pingone api` for a raw read in the interim | + +--- + +## Related references + +- `references/curated/cross-platform/ping-cli-basics.md` — Ping CLI install, profiles, and CRUD commands +- `references/curated/cross-platform/core-admin-patterns.md` — secret rotation, API patterns +- `references/curated/pingone-mt/tenant-and-environment-setup.md` — environment setup prerequisites +- `ping-orchestration` → `references/curated/cross-platform/journey-and-flow-promotion.md` — journey, script, and DaVinci flow promotion specifics + +--- + +## Source + +- [Configuration promotion overview](https://developer.pingidentity.com/config-automation-promotion/configuration_promotion_landing_page.html) +- [PingOne configuration management](https://docs.pingidentity.com/pingone/early-access-features/ea-p1_promote.html) +- [AIC self-service promotions](https://docs.pingidentity.com/pingoneaic/tenants/self-service-promotions.html) +- [AIC promotion FAQ](https://docs.pingidentity.com/pingoneaic/tenants/self-service-promotions-faqs.html) +- [AIC configuration placeholders (ESVs)](https://docs.pingidentity.com/pingoneaic/tenants/configuration-placeholders.html) +- [Ping Terraform provider](https://terraform.pingidentity.com) 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 index c429bb4..bebdee6 100644 --- 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 @@ -151,7 +151,7 @@ Admin access to the relevant platform: PingOne organization admin, AIC superadmi ## Source -[PingOne API Reference](https://apidocs.pingidentity.com/pingone/platform/v1/api/) +[PingOne API Reference](https://developer.pingidentity.com/pingone-api/platform/introduction.html) [PingFederate Admin API](https://docs.pingidentity.com/pingfederate/latest/admin-api-reference/pf-admin-api-reference.html) [PingAccess Admin API](https://docs.pingidentity.com/pingaccess/latest/pa-admin-api/pa-admin-api.html) [PingDirectory Admin Guide](https://docs.pingidentity.com/pingdirectory/latest/pd-directory-server-administration-guide/pd-ds-admin-overview.html) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md new file mode 100644 index 0000000..e7dae3a --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md @@ -0,0 +1,162 @@ +--- +title: "Ping CLI — Configuration Automation Basics" +product_family: cross-platform +products: ["pingone", "pingfederate", "davinci", "pingone-authorize", "pingone-mfa", "pingone-protect", "pingone-verify", "pingone-credentials"] +capabilities: ["foundation"] +services: ["protect", "verify", "mfa", "credentials", "authorize"] +audience: ["admin", "developer", "operator"] +use_cases: ["workforce", "customer", "cross-platform"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-06-24" +slug: "https://developer.pingidentity.com/pingcli/" +--- + +# Ping CLI — Configuration Automation Basics + +Ping CLI (`pingcli`) is the unified open-source command-line tool for managing configuration across PingOne, PingFederate, DaVinci, and the Ping universal services. + +## Scope + +**Covers:** Why to use Ping CLI, install and first-run, configuration profile model, connecting Ping services, CRUD via per-product subcommands (1.x), CI/CD patterns. + +**Does NOT cover:** Features below 1.x. Interactive agent-driven config. Long-term Terraform state management — see the PingOne and PingFederate Terraform providers. DaVinci flow design — see `ping-orchestration`. Per-service policy semantics — see `ping-universal-services`. + +--- + +## Why Ping CLI + +Ping CLI (`pingcli`) addresses the gap between the interactive admin console (good for humans, not scriptable) and raw REST API calls (scriptable, but require managing auth, base URLs, and retries manually). It provides: + +- **Consistent CRUD interface** across PingOne, DaVinci, PingFederate, and the Ping universal services without raw `curl` calls +- **Profile-based authentication** so the same scripts run against dev, staging, and production using different credentials per environment +- **Automatic auth and base URL injection** — no per-command token management +- **CI/CD friendly** — non-interactive auth via env vars, `--output-format json`, detailed exit codes + +For the current list of supported products and per-service CRUD availability, see the [product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html). + +> **Legacy note:** `pingctl` (earlier tool) is replaced by `pingcli`. Migrate by re-configuring profiles under the new tool. + +--- + +## Install + +| Platform | Method | Command | +|---|---|---| +| macOS | Homebrew (recommended) | `brew install pingidentity/tap/pingcli` | +| Linux | Package manager (apt/yum) or binary | See [Linux install guide](https://developer.pingidentity.com/pingcli/latest/install/linux.html) | +| Windows | Binary download | See [Windows install guide](https://developer.pingidentity.com/pingcli/latest/install/windows.html) | +| CI/CD | Docker image | `docker run pingidentity/pingcli:latest` | + +Verify: `pingcli version` + +--- + +## Configuration profiles + +Profiles are named groups of settings stored in `$HOME/.pingcli/config.yaml`. Use one profile per target environment (dev, staging, prod). + +| Operation | Command | +|---|---| +| Create a profile | `pingcli config profiles create --name dev` | +| Switch active profile | `pingcli config profiles use dev` | +| List profiles | `pingcli config profiles list` | +| View active profile | `pingcli config profiles show` | +| Delete a profile | `pingcli config profiles delete dev` | + +--- + +## Connecting Ping services + +Configure Ping CLI connections according to the [official documentation](https://developer.pingidentity.com/pingcli/latest/pingcli_landing_page.html). Once configured, verify connectivity: + +```bash +pingcli config profiles show +``` + +--- + +## CRUD examples + +Per-product subcommands follow consistent `list`, `get`, `create`, `update`/`replace`, `delete` patterns: + +```bash +# PingOne — list environments +pingcli pingone environments list + +# PingOne — create an application from a JSON config file +pingcli pingone applications create -f app.json + +# DaVinci — list flows in an application +pingcli davinci flows list -e + +# PingOne MFA — replace a device policy +pingcli mfa mfa-device-policies replace -f policy.json +``` + +Universal-service connectors are accessible both at top level (`pingcli davinci ...`, `pingcli mfa ...`) and under the PingOne connector umbrella (`pingcli pingone davinci ...`). Both paths use the same PingOne Worker app credentials. + +--- + +## CI/CD patterns + +Ping CLI is well-suited for CI/CD pipelines. Configure credentials according to the [official documentation](https://developer.pingidentity.com/pingcli/latest/pingcli_landing_page.html) — do not store secrets in skill instructions. + +```bash +# JSON output for pipeline parsing +pingcli pingone applications list --output-format json + +# Detailed exit codes for conditional pipeline steps +# Exit 0 = success; 1 = error; 2 = success with warnings +pingcli -D pingone environments list +``` + +**Profile-per-environment pattern:** Create one profile per environment (dev/staging/prod), each binding to a different Worker app. Scripts switch profiles to operate against the correct environment. + +--- + +## Prerequisites + +- Ping CLI installed and authenticated — follow the [official setup guide](https://developer.pingidentity.com/pingcli/latest/pingcli_landing_page.html) +- Network access from the CLI host to each product's admin API endpoint + +--- + +## Common variants + +| Variant | Notes | +|---|---| +| Single tenant, one profile | Default setup; one profile, one Worker app | +| Multi-environment scripting | One profile per env; scripts switch profiles before running commands | +| Docker-only CI | Run `pingidentity/pingcli:latest` as a container step; pass credentials as env vars | +| Migrating from `pingctl` | Re-configure profiles under `pingcli`; `pingctl` commands are not compatible | + +--- + +## Common gotchas + +| Symptom | Cause | Fix | +|---|---|---| +| 404 on environment lookup | Wrong region in profile | Verify region string matches the PingOne tenant domain (e.g., `eu` for `pingone.eu`) | +| 403 on `applications create` | Worker app missing roles | Verify the Worker app has the required admin roles in the PingOne environment | +| `pingcli init` wizard skips a service | Service credentials not configured | Re-run `pingcli config set` for the missing service manually | + +--- + +## Related references + +- `references/curated/cross-platform/foundation-overview.md` — platform overview and admin model +- `references/curated/cross-platform/core-admin-patterns.md` — cross-product admin patterns +- `references/curated/pingone-mt/app-registration.md` — Worker app setup (prerequisite for PingOne auth) +- `references/curated/ping-software/pingfederate-basics.md` — PingFederate admin API context + +--- + +## Source + +- [Ping CLI overview and docs](https://developer.pingidentity.com/pingcli/) +- [Install guide](https://developer.pingidentity.com/pingcli/latest/pingcli_landing_page.html) +- [Product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) +- [Command reference](https://developer.pingidentity.com/pingcli/latest/command_reference/pingcli.html) +- [GitHub: pingidentity/pingcli](https://github.com/pingidentity/pingcli) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-mt/tenant-and-environment-setup.md b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-mt/tenant-and-environment-setup.md index fcc2878..8f22d9c 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-mt/tenant-and-environment-setup.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-mt/tenant-and-environment-setup.md @@ -205,4 +205,4 @@ Administrator role assignments cross environment boundaries: a user in the Admin [PingOne environments](https://docs.pingidentity.com/pingone/platformconsole/p1_c_environments.html) [PingOne MFA device policies](https://docs.pingidentity.com/pingone/mfa/p1_c_mfa_device_policies.html) [PingOne OIDC application setup](https://docs.pingidentity.com/pingone/platformconsole/p1_c_apps.html) -[PingOne API reference](https://apidocs.pingidentity.com/pingone/platform/v1/api/) +[PingOne API reference](https://developer.pingidentity.com/pingone-api/platform/introduction.html) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/am-services.md b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/am-services.md index 42c6838..f0329e3 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/am-services.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/am-services.md @@ -222,7 +222,7 @@ Per-input validation rules invoked by `ValidatedUsernameNode`, `ValidatedPasswor Default user profile attribute exposure. Foundational; rarely modified. ### Email Service -**Currently unused on AIC.** Email delivery is handled by IDM Notifications, not this AM service. Do not invest time configuring this — configure email under IDM (Identity Management → Email). +**Not used on AIC.** In AIC, email delivery is configured via **Email Provider** and **Email Templates** (under Tenant Settings), not this AM service. Do not configure this AM-level service on AIC — it has no effect. For standalone PingIDM, configure email in IDM; for standalone PingAM, journey nodes connect to an external email provider directly. ### Dashboard Service *(See Global services above.)* diff --git a/plugins/ping-identity/skills/ping-identity-for-ai/SKILL.md b/plugins/ping-identity/skills/ping-identity-for-ai/SKILL.md index 2ff20be..c9a09f6 100644 --- a/plugins/ping-identity/skills/ping-identity-for-ai/SKILL.md +++ b/plugins/ping-identity/skills/ping-identity-for-ai/SKILL.md @@ -11,6 +11,8 @@ metadata: AI-era identity patterns: Identity for AI, Verified Trust, agent identity, agent security, and AI application authentication. +**What this skill does for you:** Guides you through architecture, patterns, and design decisions for securing AI agents with Ping. It is currently conceptual rather than executable — there are no dedicated ID4AI MCP tools, so it does not generate ID4AI-specific configuration. For the parts that map to existing platform capabilities (e.g. agent client credentials, PingGateway routes), it hands off to `ping-foundation` and `ping-app-integration`, which generate config and code. + ## Invocation Invoke explicitly with `/ping-identity-for-ai` or by saying "use ping-identity-for-ai to...". diff --git a/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/agent-security-patterns.md b/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/agent-security-patterns.md index bc4d558..0e6141d 100644 --- a/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/agent-security-patterns.md +++ b/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/agent-security-patterns.md @@ -46,7 +46,7 @@ Registered agents appear in the AI Agents list (Directory > AI Agents in the Pin AIC provides a dedicated DCR endpoint for AI agents: `/aiagent/register` (in addition to the standard `/register`). This endpoint onboards AI agents as dynamic OAuth 2.0 clients with agent-specific defaults. -> **Availability:** Production-ready as of 2026-06-03. Currently available on the **Rapid channel** only; Regular channel promotion is planned. +> **Availability:** Channel availability changes over time — check the [AIC AI Agents release notes](https://docs.pingidentity.com/pingoneaic/release-notes/rapid-channel/ai-agents.html) before relying on this endpoint in a given tenant. AIC AI agents can perform tasks on behalf of end users through a delegated token exchange process (RFC 8693), maintaining distinct accountability and granular access control. diff --git a/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/identity-for-ai-overview.md b/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/identity-for-ai-overview.md index d9b7e2f..05e4455 100644 --- a/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/identity-for-ai-overview.md +++ b/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/identity-for-ai-overview.md @@ -75,7 +75,7 @@ Ping Identity's Identity for AI solution covers five distinct problem areas. Eac ### Agent Identity - **PingOne** — AI Agents feature; register agents as first-class OAuth 2.0 identities with lifecycle management. License: Agent IAM Core (contact Ping Sales). -- **PingOne AIC** — `/aiagent/register` DCR endpoint for dynamic agent onboarding; AI Agents admin UI in realm left-nav. **Available on Rapid channel as of 2026-06-03; Regular channel promotion planned.** +- **PingOne AIC** — `/aiagent/register` DCR endpoint for dynamic agent onboarding; AI Agents admin UI in realm left-nav. Check the [AIC release notes](https://docs.pingidentity.com/pingoneaic/release-notes/rapid-channel/ai-agents.html) for current channel availability. - **PingFederate** — Dynamic client registration (DCR) for agent self-enrollment at runtime. ### Agent Security diff --git a/plugins/ping-identity/skills/ping-orchestration/SKILL.md b/plugins/ping-identity/skills/ping-orchestration/SKILL.md index b14f352..1b10ef3 100644 --- a/plugins/ping-identity/skills/ping-orchestration/SKILL.md +++ b/plugins/ping-identity/skills/ping-orchestration/SKILL.md @@ -11,6 +11,8 @@ metadata: Design and build authentication flows, orchestration logic, and journey-based experiences across Ping Identity platforms. MCP tools handle execution; this skill supplies design patterns, node sequencing, branching logic, and platform-specific constraints. +**What this skill does for you:** Builds journeys and flows directly through MCP tools where they exist (AIC journeys); where a tool does not exist, it guides you through the design with node sequencing, branching logic, and platform constraints. Both modes are available — it uses whichever the platform supports for the task. + ## Invocation Invoke this skill explicitly with `/ping-orchestration` or by saying "use ping-orchestration to...". @@ -95,6 +97,7 @@ Sub-routing by task and journey use case: see `references/curated/pingone-st/rou | Task | Reference | |---|---| | Passkeys / passwordless / FIDO2 design across PingOne, PingOne Advanced Identity Cloud (AIC), Ping Software | `references/curated/cross-platform/passkeys-and-passwordless.md` | +| Promote journeys, scripts, themes, or DaVinci flows between dev/staging/production | `references/curated/cross-platform/journey-and-flow-promotion.md` | --- diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md new file mode 100644 index 0000000..41d9fe2 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md @@ -0,0 +1,197 @@ +--- +title: "Promoting Journeys, Scripts, and DaVinci Flows Between Environments" +product_family: cross-platform +products: ["pingone", "pingone-st"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-06-22" +slug: "https://docs.pingidentity.com/pingoneaic/tenants/self-service-promotions.html" +--- + +# Promoting Journeys, Scripts, and DaVinci Flows Between Environments + +Journey-, script-, and DaVinci-flow-specific concerns when promoting between AIC and PingOne environments. + +## Scope + +**Covers:** What journey and flow config moves; AIC ESV and script gotchas; DaVinci flow versioning and promotion variables; environment lock impact on running journeys; per-node promotion considerations; rollback. + +**Does NOT cover:** General promotion model choice, environment topology, Terraform/CaC pipeline, and cross-product config promotion — see `ping-foundation` → `references/curated/cross-platform/config-promotion.md` for those. This anchor covers only the platform-native promotion mechanisms for journeys, flows, and their specific gotchas: AIC self-service promotions for journeys/scripts/themes, and PingOne native promotion for DaVinci flows and flow policies. + +--- + +## What journey and flow config moves + +### AIC self-service promotions + +**Moves (static config):** +- Journeys (authentication trees) and all node configurations +- Scripted Decision node scripts +- Themes and hosted pages customisations +- AM service config (OAuth2 Provider, OIDC, Session, CORS, Social IdPs, WebAuthn, etc.) +- IDM managed-object schema and scripts +- ESV references (the reference moves; the ESV value itself must exist in the target) + +**Does not move (dynamic / runtime data):** +- Live user sessions +- User-created or self-registered applications +- MFA device enrollments +- User profile data and custom attributes + +### PingOne DaVinci flows + +**Moves via native PingOne promotion:** +- Flow definitions — **most recently deployed version only** (not all versions; if you have 4 versions and version 3 is the most recently deployed, only version 3 promotes) +- Flow policies (with their referenced flow versions auto-included as dependencies) +- Connector configuration structure (connection IDs and non-secret settings) — **exception: LDAP gateway credentials cannot be promoted or managed using promotion variables** and must be manually configured in each environment + +**Connector credentials do not move directly.** PingOne gates promotion of any attribute marked sensitive (client secrets, API keys, passwords embedded in connector config) — the promotion cannot proceed until a **sensitive promotion variable** exists for each blocked attribute. Variables are created in the *source* environment with the target-specific value specified at that point; the connector structure is then promoted and resolves to those target values at promotion time, not the source's. + +--- + +## AIC: ESV and script gotchas + +### ESV integrity check + +AIC runs an integrity check before starting any promotion. Promotion is **blocked** if: +- A static config item references an ESV that does not exist in the target environment +- An encrypted secret is embedded directly in config rather than referenced via an ESV + +**Fix before promoting:** Create the missing ESVs in the upper environment. Replace any inline secrets with ESV references using the AIC admin console (Environments → Environment Secrets & Variables). + +### Orphaned or missing scripts + +If a Scripted Decision node references a script that is not included in the static config export (e.g. it was created outside the normal journey-editing workflow), the promotion may succeed but the journey fails at runtime when that node executes. + +**Fix:** Verify all scripts referenced by Scripted Decision nodes appear in the pre-promotion config snapshot. AIC's self-service promotion UI shows the full list of static resources included. + +### PII / sensitive data in script logs + +Review Scripted Decision node scripts for `logger.error(...)` or `logger.message(...)` calls that log user attributes before promoting to production. Production log retention is longer and may be subject to compliance requirements. + +--- + +## DaVinci flow promotion: versioning and variables + +### Flow versioning + +Each DaVinci flow has multiple versions; only the **most recently deployed version** is promoted to the target environment. Ensure the correct version is deployed before triggering a promotion. + +### Flow-policy dependency + +Flow policies reference specific flows and specific versions of those flows. **Promote the flow policy** — the promotion service then auto-includes the referenced flow versions as dependencies. If you promote a flow independently without also promoting its flow policy, the policy in the target environment may reference a different version than the one you promoted. + +### Promotion variables for connector credentials + +In DaVinci, connector credentials (client secrets, webhook URLs, API keys) are environment-specific. PingOne auto-detects sensitive attributes and requires **sensitive promotion variables** before the promotion can proceed: + +1. When you select a connector config resource for promotion, PingOne identifies sensitive attributes and auto-selects them as requiring variables — you cannot clear this. +2. In the **source environment**, create a sensitive promotion variable for each blocked attribute and specify the target environment's value at that point. +3. The promotion proceeds; the connector resolves to those target values after promotion, not the source's. + +--- + +## Environment lock impact during AIC promotion + +AIC requires an **environment lock** on both source and target during a promotion. + +| During lock | Effect | +|---|---| +| End-user authentication flows | **Unaffected** — runtime auth continues | +| AIC admin console | Read-only; most writes blocked in the source (dev) environment | +| ESV API | Blocked in both locked environments (source and target) during promotion | +| Journey editing (AIC MCP Server, admin console) | Blocked in source during lock | +| Promotion duration | 10–45 minutes depending on config size | + +**Implication for iterative development:** If you are actively editing journeys, schedule promotions during off-hours or low-activity windows to avoid blocking your development workflow. + +--- + +## Sequential pair routing + +AIC self-service promotions enforce a sequential chain: + +``` +dev → staging → production +(with UAT, if present: dev → UAT → staging → production) +``` + +Non-sequential promotion (dev → production directly) is not supported. To validate changes quickly in production-like conditions, promote to staging first, verify, then promote from staging to production. + +Sandbox environments sit outside all promotion chains — you cannot promote to or from a sandbox. + +--- + +## Per-node promotion considerations + +| Node type | Promotion concern | +|---|---| +| Scripted Decision | Script reference must exist in the target; verify script is included in the static config snapshot before promoting | +| SAML/OIDC federation nodes | Entity IDs and redirect URIs are often environment-specific; use ESVs for issuer URLs and endpoints | +| PageNode / themes | Theme customisations move with the journey; ensure themes are included in the static config snapshot | +| Inner journeys | The inner journey must exist (or be co-promoted) in the target before the outer journey is promoted | +| WebAuthn / FIDO2 nodes | `origins` and `relyingPartyDomain` are environment-specific — use ESVs | +| Push MFA nodes | FCM/APNS credentials are environment-specific; store via ESVs | + +--- + +## Rollback for journeys + +If a promoted journey causes issues in the upper environment, AIC self-service rollback restores the prior static config set: + +- **Trigger:** `POST /promotions/{promotionId}/rollback` (API only; admin console does not expose rollback) +- **Behaviour:** The upper environment's journey/script set is restored to its pre-promotion state. In-flight sessions on the promoted journey are not interrupted — they continue against the current version in memory until they time out. +- **After rollback:** Diagnose the issue in the source (dev) environment, fix, and re-promote. + +--- + +## Choosing native promotion vs Terraform for journey/flow work + +| Scenario | Typical fit | Why | +|---|---|---| +| AIC journey iteration within one tenant chain | AIC self-service promotions | Platform-provided self-service path for AIC; admin-console-driven; sequential pairs enforced by the platform (dev→staging→production only) | +| DaVinci flow changes within one PingOne org | PingOne native promotion | In-console; automatic dependency management; same-org constraint applies | +| Multi-org, multi-cloud, or Git-backed audit trail needed | Ping CLI + Terraform | Terraform providers cover PingFederate, PingDirectory, and PingOne (no PingAccess provider); Ping CLI CRUD for PingFederate is still rolling out — check the [compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html); state tracking and drift detection via Terraform | +| Mixed AIC journeys + DaVinci flows in the same pipeline | Can combine both | Each platform's native model handles its own config; Terraform manages cross-product baseline | + +--- + +## Prerequisites + +- Promotion Admin role (PingOne) or AIC tenant admin access in both environments +- All ESVs referenced in journey/flow config must be pre-created in the target environment +- DaVinci flow promotion variables assigned in the target before promotion +- All dependent inner journeys or scripts co-included in the promotion + +--- + +## Common variants + +| Variant | Notes | +|---|---| +| AIC standard dev/staging/prod chain | Sequential pairs; ESVs pre-configured in each upper env | +| AIC with UAT tier | dev → UAT → staging → production; cannot skip UAT | +| DaVinci flow to a sandbox (test) | Supported in PingOne native promotion; sandbox counts as a valid target env | +| Terraform-managed journey baseline | Manage with Ping Identity Terraform providers; promote via PR + apply | + +--- + +## Related references + +- `ping-foundation` → `references/curated/cross-platform/config-promotion.md` — model selection, topology, general constraints, and rollback +- `references/curated/pingone-st/journey-design-patterns.md` — journey design best practices before promoting +- `references/curated/pingone-mt/davinci-overview.md` — DaVinci flow concepts and versioning + +--- + +## Source + +- [AIC self-service promotions](https://docs.pingidentity.com/pingoneaic/tenants/self-service-promotions.html) +- [AIC promotion FAQ](https://docs.pingidentity.com/pingoneaic/tenants/self-service-promotions-faqs.html) +- [AIC configuration placeholders (ESVs)](https://docs.pingidentity.com/pingoneaic/tenants/configuration-placeholders.html) +- [PingOne configuration management](https://docs.pingidentity.com/pingone/early-access-features/ea-p1_promote.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 index c9fdbda..5f1c475 100644 --- 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 @@ -15,7 +15,7 @@ slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" # AIC — Node Fundamentals -Tribal knowledge and non-obvious invariants about how nodes behave in AIC journeys. Rules here are validated from live AIC sessions — they are not documented clearly in official docs and are common sources of bugs. +Behavioural invariants and composition rules for nodes in AIC journeys, validated against live AIC sessions. This file complements the per-node reference docs with the cross-node behaviour an agent needs to wire journeys correctly the first time. ## Scope diff --git a/plugins/ping-identity/skills/ping-quickstart/SKILL.md b/plugins/ping-identity/skills/ping-quickstart/SKILL.md index 0f4ba20..43e61e8 100644 --- a/plugins/ping-identity/skills/ping-quickstart/SKILL.md +++ b/plugins/ping-identity/skills/ping-quickstart/SKILL.md @@ -11,6 +11,8 @@ metadata: Front door for all Ping Identity work. Detects the user's platform, identifies what they are trying to accomplish, and routes them to the correct skill. +**What this skill does for you:** Orientation and routing only — it determines your platform and goal and hands off to the skill that does the work. It does not itself generate configuration or walk through product docs. + ## Invocation Invoke this skill explicitly with `/ping-quickstart` or by saying "use ping-quickstart to...". @@ -19,10 +21,9 @@ Invoke this skill explicitly with `/ping-quickstart` or by saying "use ping-quic Trigger on ANY of the following — including questions, evaluation discussions, and advisory requests: -- "Where do I start with Ping Identity?" +- "Where do I start with Ping Identity?" / "I'm new to Ping — what should I set up first?" - "Which Ping product do I need?" - "Help me choose between PingOne, PingOne Advanced Identity Cloud, and PingFederate" -- "I'm new to Ping — what should I set up first?" - "I inherited a Ping deployment and don't know where to begin" - "We're evaluating Ping Identity — what should we be asking?" - "Pros and cons of PingOne vs PingOne Advanced Identity Cloud vs PingFederate; cloud or on-prem?" @@ -32,7 +33,6 @@ Trigger on ANY of the following — including questions, evaluation discussions, - "We want to add identity verification / KYC — where do we start?" - "What's the recommended starting point for Ping employee identity?" - "What license do I need for DaVinci / Protect / Verify?" -- "I inherited a Ping deployment — where do I start?" - "Test this end to end / validate my Ping setup / how do I prove the path works before going live" **Catch-all rule:** Trigger this skill whenever the user's platform or starting point is unknown or unclear, when they use "where do we start", "what should we set up first", "what's the recommended starting point", or "not sure whether to use [product A] or [product B]" framing. Trigger on migration intents (ForgeRock → Ping, Okta → Ping, Auth0 → Ping). Trigger when platform is not yet specified and the user is in evaluation or orientation mode. diff --git a/plugins/ping-identity/skills/ping-quickstart/references/curated/common-starting-patterns.md b/plugins/ping-identity/skills/ping-quickstart/references/curated/common-starting-patterns.md index fd9dfd7..82b7ea1 100644 --- a/plugins/ping-identity/skills/ping-quickstart/references/curated/common-starting-patterns.md +++ b/plugins/ping-identity/skills/ping-quickstart/references/curated/common-starting-patterns.md @@ -158,12 +158,6 @@ Known gotchas: --- -## Note: Migrating from Okta or Auth0 - -No public migration guide or toolset currently exists on Ping's docs for Okta or Auth0 migration. Direct the customer to their Account Executive or open a support case. Partner tooling is available but not documented on official Ping docs. - ---- - ## Pattern 6: Add identity verification (KYC) **Platform:** PingOne + PingOne Verify diff --git a/plugins/ping-identity/skills/ping-universal-services/SKILL.md b/plugins/ping-identity/skills/ping-universal-services/SKILL.md index 5835e13..60260d0 100644 --- a/plugins/ping-identity/skills/ping-universal-services/SKILL.md +++ b/plugins/ping-identity/skills/ping-universal-services/SKILL.md @@ -11,6 +11,8 @@ metadata: Shared strategic services used across PingOne, PingOne Advanced Identity Cloud (AIC), and Ping Software Suite — invoked from flows rather than administered as standalone products. Covers PingOne Protect (risk), PingOne Verify (identity proofing / KYC), PingOne Credentials (verifiable credentials), PingOne IGA (governance), PingOne Authorize (fine-grained authorization), and cross-platform SSO. +**What this skill does for you:** Generates service and policy configuration and drives it through MCP tools where they exist; where a tool does not exist, it guides you through the docs with the policy fields, thresholds, and node-wiring constraints for each service. Both modes are available — it uses whichever the platform supports for the task. + ## Invocation Invoke explicitly with `/ping-universal-services` or by saying "use ping-universal-services to...". @@ -35,7 +37,6 @@ Invoke explicitly with `/ping-universal-services` or by saying "use ping-univers - If the user mentions "add security" or "prevent suspicious logins" without naming a specific service, ask a clarifying question — the task may be Protect (risk scoring) or just MFA (orchestration). - If the task is **MFA node/connector wiring within a journey or flow** (not MFA policy or device management): use `ping-orchestration` — that is flow design, not service configuration. - If the task is generic app / SDK integration without referencing a named Universal Service: use `ping-app-integration`. -- **PingOne Recognize** — not yet GA; this skill will cover it when available. ## Multi-skill use cases diff --git a/plugins/ping-identity/skills/ping-universal-services/references/curated/mfa-region-and-service-model.md b/plugins/ping-identity/skills/ping-universal-services/references/curated/mfa-region-and-service-model.md index e733566..18b9a8a 100644 --- a/plugins/ping-identity/skills/ping-universal-services/references/curated/mfa-region-and-service-model.md +++ b/plugins/ping-identity/skills/ping-universal-services/references/curated/mfa-region-and-service-model.md @@ -93,7 +93,7 @@ Methods available depend on environment type and service model: | Windows / Mac login | — | — | ✓ (PingID service) | | RADIUS Gateway (VPN) | — | ✓ | ✓ | -> **Native region limitation (current):** Some PingID integrations (Windows/Mac login, desktop app, YubiKey OTP) are not yet available in native V2 regions. These will be introduced progressively from Q3 2026. Check `docs.pingidentity.com/pingone/strong_authentication_mfa/` for the latest availability. +> **Native region note:** Availability of some PingID integrations (Windows/Mac login, desktop app, YubiKey OTP) varies by region and is expanding over time. Check `docs.pingidentity.com/pingone/strong_authentication_mfa/` for the methods available in the target region before designing around them. --- diff --git a/plugins/ping-identity/skills/ping-universal-services/references/curated/service-invocation-patterns.md b/plugins/ping-identity/skills/ping-universal-services/references/curated/service-invocation-patterns.md index 7526d22..caa41d4 100644 --- a/plugins/ping-identity/skills/ping-universal-services/references/curated/service-invocation-patterns.md +++ b/plugins/ping-identity/skills/ping-universal-services/references/curated/service-invocation-patterns.md @@ -210,7 +210,7 @@ Authorize REST response (abbreviated): ## Source [PingOne DaVinci connector library](https://docs.pingidentity.com/davinci/connectors) -[PingOne Protect API reference](https://apidocs.pingidentity.com/pingone/platform/v1/api/#post-create-risk-evaluation) -[PingOne Verify API reference](https://apidocs.pingidentity.com/pingone/verify/v1/api/) -[PingOne Authorize API reference](https://apidocs.pingidentity.com/pingone/authorize/v1/api/) +[PingOne Protect API reference](https://developer.pingidentity.com/pingone-api/protect/introduction.html) +[PingOne Verify API reference](https://developer.pingidentity.com/pingone-api/verify/introduction.html) +[PingOne Authorize API reference](https://developer.pingidentity.com/pingone-api/authorize/introduction.html) [AIC journey node reference](https://docs.pingidentity.com/pingoneaic/journeys/auth-nodes.html) diff --git a/rules/authoring-rules.md b/rules/authoring-rules.md index 3ecd4e7..bc0b725 100644 --- a/rules/authoring-rules.md +++ b/rules/authoring-rules.md @@ -116,14 +116,41 @@ slug: "" # canonical docs URL for this topic | Value | Platform | |---|---| | `pingone-mt` | PingOne (multi-tenant cloud) | -| `pingone-st` | PingOne ST (single-tenant) | +| `pingone-st` | PingOne Advanced Identity Cloud (AIC) | | `ping-software` | Ping Software Suite (on-premises) | | `cross-platform` | Spans multiple platform families | +> **Naming note:** The `pingone-st` value is a stable internal routing tag and directory name — it denotes **PingOne Advanced Identity Cloud (AIC)**. Always call the platform "PingOne Advanced Identity Cloud (AIC)" or "AIC" in prose. Never surface "PingOne ST" or "single-tenant" as the product name in author-facing or agent-facing text. + Use `cross-platform` only when the content genuinely applies without modification to two or more platform families. If a doc has platform-specific sections, pick the primary family and note variants in the body. --- +## 1a. Editorial principles — accuracy, tone, and durability + +Skills and MCP tool descriptions ride alongside the product and the official docs. They must not get ahead of shipped behaviour, and they must not editorialise about Ping's own products or documentation. + +**Follow the product — do not jump ahead of it.** Only document behaviour that is shipped and documented. If a capability is not yet supported by the product or has no stable querying logic, do not invent it in a skill or MCP description. When in doubt, defer to the official docs. + +**No statements that go stale.** Do not bake release timing, channel state, or version-promotion plans into reference prose. These rot between updates and mislead agents. + +- ❌ "Available on the Rapid channel as of 2026-06-03; Regular channel promotion planned." +- ❌ "Not yet GA; this skill will cover it when available." +- ❌ "These will be introduced progressively from Q3 2026." +- ✅ State the capability, then link to the live release notes / docs for current availability: "Check the [AIC release notes](…) for current channel availability." + +If availability genuinely gates usage, express it as a durable constraint plus a pointer to the authoritative source — not a dated promise. + +**No negative framing about Ping docs or products.** Reference files describe capability and behaviour neutrally. Do not characterise the official docs or product as deficient, and do not position skill content as compensating for them. + +- ❌ "Not documented clearly in official docs and a common source of bugs." +- ❌ "Tribal knowledge the docs don't cover." +- ✅ "Behavioural invariants validated against live sessions; complements the per-node reference docs." + +The test: state what the content **is** and what it **enables**, not what the docs or product **lack**. + +--- + ## 2. Curated anchors — how to write them ### Curated anchors (`references/curated/`) diff --git a/shared/taxonomies/capability-map.md b/shared/taxonomies/capability-map.md index ab275b7..67d4d2e 100644 --- a/shared/taxonomies/capability-map.md +++ b/shared/taxonomies/capability-map.md @@ -8,7 +8,7 @@ Maps user intents to the owning umbrella skill. Used by SKILL.md routing logic a |---|---|---| | Orientation / "Where do I start?" | ping-quickstart | Product detection, platform selection, initial direction | | Setup / Admin / Configuration | ping-foundation | Tenant setup, apps, directories, policies, branding, on-prem admin | -| Flows / Journeys / Orchestration | ping-orchestration | DaVinci flows, PingOne ST journeys, PingAM auth trees | +| Flows / Journeys / Orchestration | ping-orchestration | DaVinci flows, AIC journeys, PingAM auth trees | | AI identity / Agent trust | ping-identity-for-ai | Identity for AI, Verified Trust, agent security patterns | | Shared strategic services | ping-universal-services | Protect, Verify, Credentials, SSO, IGA, Neo, Authorize | | App / SDK / mobile integration | ping-app-integration | Web, mobile, SDK, browser flows, on-prem app integration | diff --git a/shared/taxonomies/platform-families.md b/shared/taxonomies/platform-families.md index ecbc308..803d2e1 100644 --- a/shared/taxonomies/platform-families.md +++ b/shared/taxonomies/platform-families.md @@ -11,13 +11,13 @@ Cloud-hosted administration surface: environment setup, tenant management, apps, **Routing tag:** `pingone-mt` -## PingOne ST +## PingOne Advanced Identity Cloud (AIC) -Fully managed identity platform built on PingAM/ForgeRock lineage. Distinct control plane, object model, and administration UI from PingOne MT. +Fully managed identity platform built on PingAM, PingIDM, and PingDS. Distinct control plane, object model, and administration UI from PingOne (multi-tenant cloud). -**Products:** PingOne ST, PingAM (within PingOne ST), PingIDM (within PingOne ST), PingDS (within PingOne ST) +**Products:** PingOne Advanced Identity Cloud (AIC), PingAM (within AIC), PingIDM (within AIC), PingDS (within AIC) -**Routing tag:** `pingone-st` +**Routing tag:** `pingone-st` (the tag is a stable internal identifier; the platform it denotes is AIC) ## Ping Software Suite (On-Premises) @@ -29,7 +29,7 @@ On-premises and self-managed deployments. Different deployment model, topology, ## Shared / Cross-Platform -Universal Services and patterns that span multiple platform families. Used when capability is invoked from both PingOne MT and PingOne ST contexts. +Universal Services and patterns that span multiple platform families. Used when capability is invoked from both PingOne (multi-tenant cloud) and AIC contexts. **Services:** PingOne Protect, PingOne Verify, PingOne Credentials, PingOne SSO, PingOne IGA, PingOne Neo, PingOne Authorize @@ -42,6 +42,6 @@ Universal Services and patterns that span multiple platform families. Used when Apply platform family routing before any capability or product routing: 1. Is the user working in PingOne admin console or PingOne APIs? → `pingone-mt` -2. Is the user working in PingOne ST tenant admin, identity cloud, or AM/IDM/DS? → `pingone-st` +2. Is the user working in AIC tenant admin, identity cloud, or AM/IDM/DS? → `pingone-st` 3. Is the user deploying, configuring, or operating on-prem software? → `ping-software` -4. Is the service invoked across both PingOne MT and PingOne ST? → `cross-platform` +4. Is the service invoked across both PingOne (multi-tenant cloud) and AIC? → `cross-platform` diff --git a/shared/taxonomies/service-map.md b/shared/taxonomies/service-map.md index 6b97b50..3e7ba08 100644 --- a/shared/taxonomies/service-map.md +++ b/shared/taxonomies/service-map.md @@ -4,12 +4,12 @@ Maps Ping Universal Services and strategic shared services to platform context a ## Universal Services -These services are consumed across PingOne MT and PingOne ST. They are not configuration destinations; they are capabilities invoked from within a platform. +These services are consumed across PingOne (multi-tenant cloud) and AIC. They are not configuration destinations; they are capabilities invoked from within a platform. | Service | Platform Context | Primary Skill | Notes | |---|---|---|---| -| PingOne Protect | PingOne MT, PingOne ST via connector | ping-universal-services | Risk signals, adaptive auth, bot detection | -| PingOne Verify | PingOne MT, PingOne ST via connector | ping-universal-services | Identity verification, document check, liveness | +| PingOne Protect | PingOne (MT), AIC via connector | ping-universal-services | Risk signals, adaptive auth, bot detection | +| PingOne Verify | PingOne (MT), AIC via connector | ping-universal-services | Identity verification, document check, liveness | | PingOne Credentials | PingOne MT | ping-universal-services | Verifiable credentials, digital wallet | | PingOne SSO | PingOne MT | ping-universal-services | Workforce SSO, app federation, SAML/OIDC | | PingOne IGA | PingOne MT | ping-universal-services | Identity governance, access requests, certifications | @@ -23,7 +23,7 @@ These services are tightly coupled to orchestration. Route to ping-orchestration | Service | Primary Skill | Notes | |---|---|---| | PingOne DaVinci | ping-orchestration | Flow builder, connector library, CIAM orchestration | -| PingOne ST Journeys / Trees | ping-orchestration | PingAM authentication trees, journey nodes | +| AIC Journeys / Trees | ping-orchestration | PingAM authentication trees, journey nodes | ## On-Premises Strategic Services diff --git a/shared/templates/AUTHORING-RULES.md b/shared/templates/AUTHORING-RULES.md index 3ecd4e7..bc0b725 100644 --- a/shared/templates/AUTHORING-RULES.md +++ b/shared/templates/AUTHORING-RULES.md @@ -116,14 +116,41 @@ slug: "" # canonical docs URL for this topic | Value | Platform | |---|---| | `pingone-mt` | PingOne (multi-tenant cloud) | -| `pingone-st` | PingOne ST (single-tenant) | +| `pingone-st` | PingOne Advanced Identity Cloud (AIC) | | `ping-software` | Ping Software Suite (on-premises) | | `cross-platform` | Spans multiple platform families | +> **Naming note:** The `pingone-st` value is a stable internal routing tag and directory name — it denotes **PingOne Advanced Identity Cloud (AIC)**. Always call the platform "PingOne Advanced Identity Cloud (AIC)" or "AIC" in prose. Never surface "PingOne ST" or "single-tenant" as the product name in author-facing or agent-facing text. + Use `cross-platform` only when the content genuinely applies without modification to two or more platform families. If a doc has platform-specific sections, pick the primary family and note variants in the body. --- +## 1a. Editorial principles — accuracy, tone, and durability + +Skills and MCP tool descriptions ride alongside the product and the official docs. They must not get ahead of shipped behaviour, and they must not editorialise about Ping's own products or documentation. + +**Follow the product — do not jump ahead of it.** Only document behaviour that is shipped and documented. If a capability is not yet supported by the product or has no stable querying logic, do not invent it in a skill or MCP description. When in doubt, defer to the official docs. + +**No statements that go stale.** Do not bake release timing, channel state, or version-promotion plans into reference prose. These rot between updates and mislead agents. + +- ❌ "Available on the Rapid channel as of 2026-06-03; Regular channel promotion planned." +- ❌ "Not yet GA; this skill will cover it when available." +- ❌ "These will be introduced progressively from Q3 2026." +- ✅ State the capability, then link to the live release notes / docs for current availability: "Check the [AIC release notes](…) for current channel availability." + +If availability genuinely gates usage, express it as a durable constraint plus a pointer to the authoritative source — not a dated promise. + +**No negative framing about Ping docs or products.** Reference files describe capability and behaviour neutrally. Do not characterise the official docs or product as deficient, and do not position skill content as compensating for them. + +- ❌ "Not documented clearly in official docs and a common source of bugs." +- ❌ "Tribal knowledge the docs don't cover." +- ✅ "Behavioural invariants validated against live sessions; complements the per-node reference docs." + +The test: state what the content **is** and what it **enables**, not what the docs or product **lack**. + +--- + ## 2. Curated anchors — how to write them ### Curated anchors (`references/curated/`)