Ping Identity

Connect Ping Identity to authenticate end users with your Char widget. This guide covers both PingOne (cloud) and PingFederate (on-premises/hybrid) configurations.

Prerequisites

A Ping Identity account (PingOne or PingFederate)
Admin access to create applications
Access to the Char dashboard

Quick Links

PingOne Admin Console

PingOne Documentation

PingOne documentation

OIDC Configuration

OpenID Connect overview

PingFederate Docs

PingFederate documentation

SDK References

oidc-client-ts

TypeScript OIDC client library

react-oidc-context

React context for OIDC authentication

PingOne Configuration

Create an Application in PingOne

Sign in to the PingOne Admin Console
Navigate to Applications → Applications
Click + Add Application
Select OIDC Web App
Enter application details:

Setting	Value
Application Name	`Char Widget`
Description	AI widget authentication
Icon	(Optional) Upload an icon

Click Save

Configure OIDC Settings

In your application’s OIDC tab:

Setting	Value
Application Type	Single Page App
Grant Type	Authorization Code, Implicit (for legacy)
Response Type	Code, ID Token
PKCE Enforcement	Required (recommended)
Redirect URIs	Your callback URLs
Signoff URLs	Your logout URLs

Click Save.

Configure Token Settings

In the Resources tab:

Enable the scopes you need: openid, profile, email
Optionally add custom scopes for additional claims

In the Policies tab:

Assign an authentication policy (or use default)

Note Your Environment ID and Client ID

From PingOne:

Environment ID: Found in Settings → Environment → Properties
Client ID: Found in your application’s Configuration tab
Region: Note your PingOne region (NA, EU, AP, CA)

Find your Environment ID and Client ID in PingOne

The issuer URL format is:

https://auth.pingone.{region}/{{environment-id}}/as

Configure Char

In the Char Dashboard:

Navigate to Settings → Integration
Under SSO Configuration, select Custom OIDC as the provider
Enter your configuration:

Field	Value
Client ID	Your PingOne Client ID
Issuer URL	`https://auth.pingone.{region}/{environment-id}/as`

Click Test Connection to verify
Click Save Changes

PingOne Configuration Reference

Char Field	PingOne Value	Example
Provider Type	Custom OIDC	`custom_oidc`
Client ID	Application Client ID	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`
Issuer URL	PingOne issuer	`https://auth.pingone.com/12345678-abcd-1234-efgh-567890abcdef/as`

PingOne Regions

Region	Code	Auth URL
North America	`com`	`auth.pingone.com`
Europe	`eu`	`auth.pingone.eu`
Asia-Pacific	`asia`	`auth.pingone.asia`
Canada	`ca`	`auth.pingone.ca`

Ensure you use the correct regional domain for your PingOne environment. Using the wrong region will result in connection failures.

PingFederate Configuration

For on-premises or hybrid PingFederate deployments:

Create an OAuth Client

Sign in to your PingFederate Admin Console
Navigate to Applications → OAuth → Clients
Click Add Client
Configure the client:

Setting	Value
Client ID	Your chosen client ID
Client Authentication	None (public client)
Redirect URIs	Your callback URLs
Allowed Grant Types	Authorization Code, Implicit
Allowed Scopes	openid, profile, email

Configure OpenID Connect Policy

Navigate to Applications → OAuth → OpenID Connect → Policies
Create or modify a policy
Ensure the policy includes the required scopes and claims
Assign the policy to your OAuth client

Configure Char for PingFederate

In the Char Dashboard:

Field	Value
Client ID	Your PingFederate Client ID
Issuer URL	`https://{pingfederate-host}`

The issuer URL is your PingFederate server’s base URL.

Token Requirements

Char validates Ping Identity tokens with these requirements:

Claim	Requirement
`iss`	Must match your configured issuer URL
`aud`	Must include your configured Client ID
`sub`	Required - Ping user identifier
`exp`	Must not be expired

Standard Ping ID Token Claims

Claim	Description
`sub`	User identifier
`email`	User’s email address
`name`	User’s full name
`given_name`	First name
`family_name`	Last name
`preferred_username`	Username
`updated_at`	Last profile update timestamp

Example: Obtaining and Passing the Token

PingOne SDK
React (oidc-client-ts)
PingFederate (JavaScript)

import "@mcp-b/embedded-agent/web-component";

// PingOne authentication using Authorization Code + PKCE
const config = {
  authority: 'https://auth.pingone.com/{environment-id}/as',
  client_id: 'your-client-id',
  redirect_uri: window.location.origin + '/callback',
  response_type: 'code',
  scope: 'openid profile email',
  code_challenge_method: 'S256',
};

// After successful authentication and token exchange
function handleCallback(idToken) {
  const agent =
    document.querySelector("webmcp-agent") ?? document.createElement("webmcp-agent");

  if (!agent.isConnected) {
    document.body.appendChild(agent);
  }

  agent.setAttribute("auth-token", idToken);
}

import { UserManager } from 'oidc-client-ts';
import { useEffect, useState } from 'react';
import "@mcp-b/embedded-agent/web-component";

const userManager = new UserManager({
  authority: 'https://auth.pingone.com/{environment-id}/as',
  client_id: 'your-client-id',
  redirect_uri: window.location.origin + '/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

function App() {
  const [user, setUser] = useState(null);

  useEffect(() => {
    userManager.getUser().then(setUser);
  }, []);

  useEffect(() => {
    if (user?.id_token) {
      const agent = document.querySelector("webmcp-agent");
      if (agent) {
        agent.setAttribute("auth-token", user.id_token);
      }
    }
  }, [user]);

  return <webmcp-agent />;
}

import { UserManager } from 'oidc-client-ts';
import "@mcp-b/embedded-agent/web-component";

const userManager = new UserManager({
  authority: 'https://sso.yourcompany.com', // PingFederate URL
  client_id: 'your-client-id',
  redirect_uri: window.location.origin + '/callback',
  response_type: 'code',
  scope: 'openid profile email',
  // PingFederate-specific metadata
  metadataUrl: 'https://sso.yourcompany.com/.well-known/openid-configuration',
});

userManager.getUser().then((user) => {
  if (user?.id_token) {
    const agent =
      document.querySelector("webmcp-agent") ?? document.createElement("webmcp-agent");

    if (!agent.isConnected) {
      document.body.appendChild(agent);
    }

    agent.setAttribute("auth-token", user.id_token);
  }
});

Custom Attributes and Claims

PingOne Custom Attributes

Navigate to Directory → User Attributes
Add custom attributes as needed
Map attributes to OIDC claims in your application’s Attribute Mapping

// Custom attributes appear in the token
const tokenClaims = parseJwt(idToken);
console.log('Department:', tokenClaims.department);
console.log('Employee ID:', tokenClaims.employee_id);

PingFederate Attribute Mapping

In PingFederate Admin Console:

Navigate to Applications → OAuth → OpenID Connect → Policies
Edit your policy’s Attribute Contract
Add custom attributes and map them to data sources

PingOne Groups

To include group memberships in tokens:

In PingOne Admin, navigate to your application
Go to Resources tab
Add a custom scope or use p1:read:user scope
Configure attribute mapping to include groups

// Access groups from token
const tokenClaims = parseJwt(idToken);
console.log('Groups:', tokenClaims.p1.groups);

Troubleshooting

INVALID_ISSUER error

The issuer URL doesn’t match:

Check the format: https://auth.pingone.{region}/{environment-id}/as
Verify region: Use the correct regional domain (com, eu, asia, ca)
Check Environment ID: Must match your PingOne environment
Include /as suffix: The issuer URL must end with /as

INVALID_AUDIENCE error

The token’s audience doesn’t match:

Verify the Client ID matches exactly (including hyphens)
Ensure you’re using the ID token, not the access token
Check that the application type is configured as SPA

JWKS_FETCH_FAILED error

Char couldn’t reach Ping’s JWKS endpoint:

PingOne: https://auth.pingone.{region}/{environment-id}/as/jwks
PingFederate: https://{pingfederate-host}/pf/JWKS
Verify your environment/server is accessible
Use Test Connection in the dashboard

PKCE required error

If PingOne returns a PKCE error:

Ensure your client library supports PKCE
Use code_challenge_method: 'S256' in your configuration
Consider using oidc-client-ts which handles PKCE automatically

PingFederate metadata not found

If the well-known configuration isn’t found:

Verify the PingFederate server URL
Check that OIDC is enabled on your PingFederate instance
The metadata URL should be {base-url}/.well-known/openid-configuration

Adaptive Authentication

PingOne supports adaptive MFA based on risk signals:

Configure authentication policies in Policies → Authentication
Set up risk policies in Policies → Risk
Users may be prompted for MFA based on risk score

This doesn’t affect Char integration - tokens are issued after successful authentication regardless of MFA steps.

Security Best Practices

Enable PKCE for all SPA applications
Configure MFA policies appropriate for your security requirements
Use short token lifetimes and implement refresh tokens
Enable risk-based authentication in PingOne
Review sign-on activity in PingOne audit logs
Configure IP restrictions if needed
Use PingOne Protect for advanced threat detection
Regularly rotate client secrets (for confidential clients)

Introduction

How-to Guides

Explanation

Ping Identity

Prerequisites

Quick Links

PingOne Admin Console

PingOne Documentation

OIDC Configuration

PingFederate Docs

SDK References

oidc-client-ts

react-oidc-context

PingOne Configuration

PingOne Configuration Reference

PingOne Regions

PingFederate Configuration

Token Requirements

Standard Ping ID Token Claims

Example: Obtaining and Passing the Token

Custom Attributes and Claims

PingOne Custom Attributes

PingFederate Attribute Mapping

PingOne Groups

Troubleshooting

Adaptive Authentication

Security Best Practices

Introduction

How-to Guides

Explanation

​Prerequisites

​Quick Links

PingOne Admin Console

PingOne Documentation

OIDC Configuration

PingFederate Docs

​SDK References

oidc-client-ts

react-oidc-context

​PingOne Configuration

​PingOne Configuration Reference

​PingOne Regions

​PingFederate Configuration

​Token Requirements

​Standard Ping ID Token Claims

​Example: Obtaining and Passing the Token

​Custom Attributes and Claims

​PingOne Custom Attributes

​PingFederate Attribute Mapping

​PingOne Groups

​Troubleshooting

​Adaptive Authentication

​Security Best Practices

Prerequisites

Quick Links

SDK References

PingOne Configuration

PingOne Configuration Reference

PingOne Regions

PingFederate Configuration

Token Requirements

Standard Ping ID Token Claims

Example: Obtaining and Passing the Token

Custom Attributes and Claims

PingOne Custom Attributes

PingFederate Attribute Mapping

PingOne Groups

Troubleshooting

Adaptive Authentication

Security Best Practices