PingOne Advanced Identity Cloud: Architecture, Features, and Developer Guide

PingOne Advanced Identity Cloud (AIC) is the platform you land on when Ping Identity positions you for cloud-native IAM. It combines the ForgeRock AM/IDM engines with Ping’s DaVinci no-code orchestration, all hosted as managed SaaS. If you’ve worked with ForgeRock Identity Cloud or legacy PingFederate, AIC will feel familiar — but the console, APIs, and deployment model are different enough to require a dedicated ramp-up.

This guide covers what AIC actually is, how its architecture works, and how to get your first application integrated.

What Is PingOne Advanced Identity Cloud?

AIC is Ping’s answer to cloud-native CIAM and workforce IAM. After acquiring ForgeRock in 2023, Ping combined ForgeRock Identity Cloud’s capabilities with its own DaVinci orchestration platform into a single SaaS offering.

What AIC includes:

• Authorization Server (AS): OAuth 2.0/OIDC/SAML 2.0/FAPI authorization server based on ForgeRock AM
• Identity Store: Managed user directory with schema extension support
• Identity Management (IDM): Provisioning, reconciliation, connectors to HR/AD/SCIM sources
• DaVinci: Visual no-code flow builder for authentication journeys, registration, and MFA
• Governance (optional add-on): Access reviews, entitlement management, IGA

What AIC is NOT:

• Not self-hosted — you don’t run it on your infrastructure
• Not PingFederate — if you have existing PF config, there’s a migration path but no direct export/import
• Not just PingOne — the legacy PingOne SSO product is a separate offering

Tenant Structure

Every AIC tenant has one or more Environments (e.g., production, staging, dev). Each environment has its own:

• Environment ID (a UUID, shown in the admin console)
• Authorization server base URL: https://<tenant-domain>/<environment_id>/as
• OIDC discovery: https://<tenant-domain>/<environment_id>/as/.well-known/openid-configuration
• Admin API: https://<tenant-domain>/v1/environments/<environment_id>

The tenant domain format is typically auth.pingone.com, auth.pingone.eu, or a custom domain.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                 PingOne Advanced Identity Cloud              │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ Authorization│  │  DaVinci     │  │  Identity Mgmt   │  │
│  │ Server (AM)  │  │ Orchestration│  │  (IDM/SCIM)      │  │
│  │ OIDC/SAML/   │  │ Flows &      │  │  Provisioning    │  │
│  │ FAPI         │  │ Connectors   │  │  Sync            │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
│         │                 │                  │              │
│  ┌──────┴─────────────────┴──────────────────┴──────────┐  │
│  │              Identity Store (User Directory)           │  │
│  └────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
         ↕ OIDC/SAML/API          ↕ SCIM/REST
   Your Applications          External Systems (AD, HR, LDAP)

Authentication flow:

1. User hits your app → redirected to AIC authorization endpoint
2. AIC runs a DaVinci flow (or default AM tree/journey) for authentication
3. AM issues tokens → returned to your app via redirect
4. Your app validates tokens using the JWKS endpoint or token introspection

Setting Up an OIDC Application

Step 1: Create the Application

In the AIC admin console:

1. Navigate to Applications → Applications → + (Add Application)
2. Select OIDC Web App (for server-side apps) or Single Page App (for SPAs)
3. Set a name and click Save

Step 2: Configure the Application

Under the Configuration tab:

Redirect URIs:       https://your-app.example.com/callback
                     http://localhost:3000/callback  (dev only)

Sign On URL:         https://your-app.example.com/

Token Endpoint Auth: CLIENT_SECRET_BASIC  (for web apps)
                     NONE (for SPAs using PKCE)

Grant Types:         ✅ Authorization Code
                     ✅ Refresh Token
                     ☐ Implicit (avoid — deprecated)

Enable PKCE Enforcement for public clients (SPAs, mobile apps). This is a security best practice — even for confidential clients, PKCE adds protection against authorization code interception.

Step 3: Note Your Endpoints

From the Overview tab, copy:

• Client ID: <uuid>
• Client Secret: Shown once — store in a secrets manager

Your token endpoint:

https://auth.pingone.com/<env_id>/as/token

Authorization endpoint:

https://auth.pingone.com/<env_id>/as/authorize

Discover all endpoints programmatically:

curl https://auth.pingone.com/<env_id>/as/.well-known/openid-configuration | jq .

Step 4: Test an Authorization Code Flow

# Step 1: Build authorization URL
AUTH_URL="https://auth.pingone.com/<env_id>/as/authorize?\
response_type=code\
&client_id=<client_id>\
&redirect_uri=https://your-app.example.com/callback\
&scope=openid+profile+email\
&state=$(openssl rand -hex 16)\
&code_challenge=<pkce_challenge>\
&code_challenge_method=S256"

# Step 2: Exchange code for tokens
curl -X POST https://auth.pingone.com/<env_id>/as/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<auth_code>" \
  -d "redirect_uri=https://your-app.example.com/callback" \
  -d "client_id=<client_id>" \
  -d "client_secret=<client_secret>" \
  -d "code_verifier=<pkce_verifier>"

Configuring SAML 2.0 SSO

For legacy enterprise apps using SAML, AIC acts as an IdP.

Add a SAML Application

1. Applications → + → SAML Application
2. Upload SP metadata XML (preferred) or enter manually:
   • ACS URL: https://sp.example.com/sso/acs
   • Entity ID: https://sp.example.com
3. Configure Name ID format (typically urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)

Download IdP Metadata

Give this URL to your SP:

https://auth.pingone.com/<env_id>/saml20/idp/metadata

Or download XML: Applications → your SAML app → Configuration → Download Metadata

Attribute Mapping

AIC sends user attributes in the assertion. Map them in the Attribute Mappings tab:

DaVinci: No-Code Authentication Flows

DaVinci is where you customize what happens during login — step-up MFA, fraud checks, custom registration, account linking.

Flow Basics

A DaVinci flow is a visual graph of connectors (nodes). Each connector wraps an API or internal service:

• PingOne Authentication — triggers the AIC login session
• PingOne MFA — sends push/OTP to enrolled devices
• HTTP — custom API call to your backend (risk check, account lookup)
• Error — returns a user-facing error message

Linking a Flow to Your Application

1. Create and test your flow in DaVinci → Flows
2. In DaVinci → Applications, create a policy that references the flow
3. In your OIDC Application → Experience tab, set the DaVinci policy

Once linked, every authorization request to that client triggers your DaVinci flow instead of the default AM login tree.

Example: Require MFA for Admin Users

[Start] → [Get User] → [Check Group: is-admin?]
                              │ yes
                        [PingOne MFA: Push] → [Success]
                              │ no
                        [PingOne Auth: Password] → [Success]

Build this in the DaVinci visual editor — no code required.

MFA Configuration

Enroll a Device via API

# Get user ID first
USER_ID=$(curl -s "https://api.pingone.com/v1/environments/<env_id>/users?filter=email eq \"[email protected]\"" \
  -H "Authorization: Bearer <mgmt_token>" | jq -r '._embedded.users[0].id')

# Send MFA enrollment email
curl -X POST "https://api.pingone.com/v1/environments/<env_id>/users/$USER_ID/mfaEnabled" \
  -H "Authorization: Bearer <mgmt_token>" \
  -H "Content-Type: application/json" \
  -d '{"mfaEnabled": true}'

Supported MFA Methods

User Management API

AIC exposes a REST API for SCIM-compatible user management:

# Get management token (client credentials)
MGMT_TOKEN=$(curl -s -X POST "https://auth.pingone.com/<env_id>/as/token" \
  -d "grant_type=client_credentials&client_id=<worker_app_id>&client_secret=<secret>&scope=p1:read:user p1:create:user p1:update:user" \
  | jq -r '.access_token')

# Create a user
curl -X POST "https://api.pingone.com/v1/environments/<env_id>/users" \
  -H "Authorization: Bearer $MGMT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "username": "alice",
    "name": {"given": "Alice", "family": "Smith"},
    "population": {"id": "<population_id>"}
  }'

# Search users
curl "https://api.pingone.com/v1/environments/<env_id>/users?filter=email sw \"alice\"" \
  -H "Authorization: Bearer $MGMT_TOKEN"

The management API requires a Worker Application (client credentials flow) with appropriate scopes. Never use your end-user application’s client for management operations.

PingOne vs PingFederate vs PingOne AIC

Common Errors and Fixes

invalid_client on token endpoint

• Check that your Client ID and secret are correct
• Verify the client has the correct grant type enabled
• Confirm the redirect URI matches exactly (trailing slash matters)

access_denied during authorization

• User is blocked by a DaVinci flow condition (check flow logs in DaVinci → Flows → Executions)
• Population restrictions — user may be in a population not assigned to the application
• MFA required but device not enrolled

SAML Response: InResponseTo attribute not matching any outstanding AuthnRequest

• Session mismatch — typically caused by replay or stale browser cache
• Fix: clear cookies and restart the SP-initiated flow

401 Unauthorized on management API

• Management token has expired (default 1 hour) — re-request it
• Worker application missing required scopes — check the token’s scope claim
• Using wrong environment ID in the API URL

Troubleshooting with Logs

Enable detailed logs under Settings → Environment → Audit Logs. Filter by:

• Actor (user or application)
• Action (SSO_LOGIN, TOKEN_ISSUED, MFA_FAILED)
• IP address

For DaVinci flow failures, check DaVinci → Flows → [flow name] → Executions — each execution shows the step-by-step result including error details.

Related Articles

For PingOne MFA push notification setup and OTP configuration, see the dedicated guide:

• PingID MFA Integration: Push Notifications and OTP Configuration
• Navigating Ping Identity: Features, Use Cases, and Comparisons
• SAML Decoder Tool — Debug SAML assertions from AIC inline