Overview

This guide covers the complete configuration required to enable PingID as a SAML 2.0 Identity Provider (IdP) for Velaro agent SSO. Both the PingID side (IdP configuration) and the Velaro side (SP configuration) must be completed.

How it works:

1. Agent enters their email on the Velaro console login page

2. Velaro detects the site's PingID configuration and redirects to PingID with a SAML AuthnRequest

3. Agent authenticates on PingID's login page

4. PingID posts a signed SAMLResponse back to Velaro's ACS endpoint

5. Velaro validates the signature, finds the agent account by email, and signs them in

Prerequisites

Before starting, ensure:

- You have admin access to a PingOne environment

- The agent's email address in PingID exactly matches their Velaro account email

- The PingID Integration feature flag is enabled for the site (toggle in the Velaro admin UI under site integrations)

- SSO, including PingID SSO, is only available on the Enterprise subscription plan.

Part 1 — PingID Configuration (IdP Side)

Step 1 — Create a New SAML Application

1. Log in to the PingOne admin console

2. Navigate to Applications → Applications

3. Click Add Application

4. Select SAML Application and click Configure

Step 2 — Configure SAML Settings

Fill in the following fields under the SAML Configuration tab:

Field	Value
ACS URL (Assertion Consumer Service URL)	https://app.velaro.com/Sso/Ping
Entity ID (Audience URI)	https://app.velaro.com
SLO Endpoint	(leave blank — not supported)
Subject NameID Format	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Assertion Validity Duration	300
Sign	Sign Assertion
Signing Algorithm	RSA_SHA256
Signing Key	PingOne SSO Certificate (default)
Encryption	Disabled
Enforce Signed AuthnRequest	Disabled

Note: The ACS URL is case-sensitive. Use exactly Sso/Ping — not sso/ping or SSO/PING.

Step 3 — Configure Attribute Mappings ⚠️ Critical

This step is the most commonly missed. Without it, PingID sends a UUID as the user identifier instead of their email, and login will fail.

1. Go to the Attribute Mappings tab of the PingID SAML application you created

2. Find the saml_subject row (this controls what is sent as the SAML NameID)

3. Set the value to Email Address

Attribute	PingOne User Attribute
saml_subject	Email Address ← must be this

Step 4 — Assign Users

1. Go to the Access tab of your application

2. Assign the agents who should be able to use SSO

3. Each agent's email in PingID must match their email in Velaro

Step 5 — Get the Signing Certificate

Velaro needs PingID's signing certificate to validate the SAML assertion signature.

Option A — From the IdP Metadata URL (recommended):

Open this URL in a browser (substitute your environment ID):

https://auth.pingone.sg/{environment-id}/saml20/metadata/{application-id}

Find the <ds:X509Certificate> value inside the <IDPSSODescriptor> block. Copy the raw base64 string — it starts with MIID or MIIC.

Option B — From the PingOne admin console:

1. Go to Certificates & Key Pairs (under Environment → Settings)

2. Find the certificate used as the signing key for your application

3. Click Download Certificate → export as PEM or CRT

4. Open the file and copy only the base64 content between (and excluding) the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines

Important: Save the certificate as raw base64 only — no PEM headers, no line breaks. It should be a single continuous string starting with MIID...

Part 2 — Velaro Configuration (SP Side)

Step 1 — Enable the Feature Flag

In the Velaro admin console, navigate to the site's integration settings and enable PingID Integration.

Step 2 — Save the PingID Configuration

Sign in as admin in Velaro, then navigate to account site settings. Go to Integrations > Configuration, find PingID, then click Configure.

Enter the SSO Login URL and X.509 Certificate:

SSO Login URL: https://auth.pingone.sg/{environment-id}/saml20/idp/sso

X.509 Certificate: MIIDejCCAmKgAwIBAgIG...

Field	Description
loginUrl	The SP-initiated SSO URL from PingID — always ends in /saml20/idp/sso
certificate	Raw base64 X.509 certificate from Step 5 above — no PEM headers, no line breaks

Step 3 — Verify the Configuration

Test the login flow end-to-end:

1. Open https://app.velaro.com

2. Enter the test agent's email address

3. Click SSO Login

4. Confirm redirect to PingID's login page

5. Authenticate with PingID credentials

6. Confirm successful landing in the Velaro console

Troubleshooting

Symptom	Cause	Fix
INVALID_ACS_URL from PingID	ACS URL in PingID doesn't exactly match what Velaro sends	Ensure PingID ACS URL is https://app.velaro.com/Sso/Ping — check capitalisation
Redirected back to login (no error shown)	Certificate mismatch or wrong email in NameID	Contact Velaro support — check server logs for SsoController warnings
PingID SSO failed - no site found and log shows email is a UUID	saml_subject attribute mapped to User ID instead of Email Address	Fix attribute mapping in PingID — see Part 1, Step 3
PingID SSO failed - no site found and log shows correct email	Certificate stored in Velaro doesn't match PingID's signing cert	Re-fetch cert from IdP metadata URL and re-save via the Velaro admin
MatchCertificates failed - invalid x509 certificate in logs	Certificate saved with PEM headers (-----BEGIN CERTIFICATE-----)	Re-save as raw base64 only — strip the headers
PingID SSO failed - integration disabled	EnablePingIntegration flag is off	Enable via admin UI under site integrations
PingID SSO failed - user not found in Velaro	Agent email in PingID doesn't match any Velaro account	Align the email addresses between PingID and Velaro

Reference

ACS Endpoint

Environment	URL
Production	https://app.velaro.com/Sso/Ping

SP Entity ID

Environment	Entity ID
Production	https://app.velaro.com

PingID SSO URLs by Region

Region	SSO URL
PingOne (Singapore)	https://auth.pingone.sg/{environment-id}/saml20/idp/sso
PingOne (North America)	https://auth.pingone.com/{environment-id}/saml20/idp/sso
PingOne (Europe)	https://auth.pingone.eu/{environment-id}/saml20/idp/sso
PingOne (Canada)	https://auth.pingone.ca/{environment-id}/saml20/idp/sso

Implementation Notes

Manual IdP configuration. Velaro does not expose a /saml/metadata URL. PingID is configured by entering the ACS URL and entity ID directly — a one-time setup step that requires no ongoing maintenance. Most enterprise IdP administrators are familiar with this approach.

Session termination on logout. Logging out of the Velaro console immediately invalidates the agent's bearer token — the Velaro session is fully terminated. The PingID IdP session remaining active is standard SAML SSO behavior and is by design: it allows agents to re-authenticate instantly without a password prompt, which is the expected experience on assigned enterprise workstations.

Consistent post-login navigation. After SSO login, agents always land on the Velaro console home page — the same starting point every agent reaches when beginning their shift. This is intentional. Deep link preservation is not supported.

Assertion-level signing is required. Velaro requires PingID to sign the SAML Assertion, not just the Response wrapper. Assertion signing is the stronger security posture: it ensures user identity claims cannot be tampered with inside a validly-signed response envelope. Response-only signing does not provide this guarantee. PingID supports assertion signing natively as a single configuration setting in the SAML app.