Skip to main content

​
SAML SSO with PingOne (and what differs on PingFederate)

Establish which Ping product you have before you read any further — the two setups share almost nothing but a vendor.
  • PingOne is Ping Identity’s hosted identity service, administered at console.pingone.com, and its endpoints all live under auth.pingone.com. This guide is PingOne, and every value on it is a PingOne value.
  • PingFederate is the federation server you run yourself. Its endpoints are on your host, its entity ID is whatever you chose when you deployed it, and the object you create is an SP connection, not an application. Nothing on this page’s paste table applies. Skip to PingFederate at the bottom.
Before you start
  • KnoxCall: an Enterprise plan, the owner or admin role, and at least one domain verified for single sign-on — a domain you verified for sending mail is a different proof and does not admit a login.
  • PingOne: an administrator with the Environment Admin or Identity Data Admin role in the environment you are configuring, and the environment id, which is in the console URL.
Configured KnoxCall before 8 September 2026? Re-import our SP metadata before you go further. KnoxCall now signs AuthnRequests (RSA-SHA256), publishes an encryption key so your IdP can encrypt assertions to us, and publishes a Single Logout endpoint. A PingOne application built from the older document has no verification certificate of ours on file — so Enforce Signed AuthnRequest will reject every sign-in if you switch it on — cannot be given our encryption certificate, and has no SLO endpoint of ours to call. See the call-out on the overview page for the whole story.

​
1. Create the application

PingOne console → Applications → Applications → + → Application. Name it (for example KnoxCall), choose SAML Application, and continue to Configure SAML Connection. PingOne offers two routes on that screen: Import Metadata (by URL or file) and Manually Enter. Take the import — it cannot be mis-transcribed. Replace acme with your workspace slug. That document is public, so PingOne can fetch it, and it carries the entity ID, the ACS, the SLO endpoint, the signing certificate and the encryption certificate in one read. To type them instead, choose Manually Enter: KnoxCall’s SP entity ID is its metadata URL. That is deliberate and it is what the metadata document says; do not shorten it to the origin, or PingOne’s audience will not match the one KnoxCall enforces and every assertion will be rejected. These are the default connection’s values — the connection every workspace starts with, and the one the /saml/<workspace>/… alias resolves to. If PingOne is a second identity provider for this workspace, it gets its own connection with its own handle, and its values are /sso/<workspace>/<handle>/{metadata,acs,login,slo} — for a handle of pingone, https://acme.knoxcall.com/sso/acme/pingone/acs and its three siblings. Open that connection under Settings → Single sign-on and its Certificates tab lists all five, each with a copy button. See more than one identity provider.
Setting Target Application URL to the KnoxCall login endpoint makes the PingOne application-portal tile an ordinary SP-initiated sign-in, which works with IdP-initiated login switched off. Leave it blank and the tile produces an unsolicited assertion instead, which KnoxCall refuses with saml_idp_initiated_disabled unless you have deliberately opted in — see IdP-initiated sign-in.

​
2. Attribute mappings

Open the application’s Attribute Mappings tab. PingOne starts with one mapping, saml_subject, and that one decides the NameID.

​
The NameID should be a stable identifier

PingOne maps saml_subject to Email Address by default. An email changes when a person is renamed, which gives them a second KnoxCall account, because KnoxCall recognises people by their NameID (choosing the NameID). Change saml_subject to User ID — the identifier PingOne assigns, a UUID, not made from the person’s name or address, so a rename leaves it alone. Keep the Subject NameID Format on the email-address format from step 1, which is the format KnoxCall’s sign-in request names. Once step 4 is done, run a sign-in from the connection’s Test tab in KnoxCall and read the NameID in the verdict: a UUID means you are done; an address means the connection will keep showing its NameID notice, and it will be right to.

​
The two attributes KnoxCall reads

Add both, and mark email Required so a user with an empty address fails in PingOne rather than arriving here without one: Both names are on KnoxCall’s default list, so nothing has to be named on the KnoxCall side to read them. The email attribute is required. With the NameID set to the PingOne User ID, it is the only place KnoxCall finds the person’s address — and admission is decided by that address’s domain.

​
Group names (optional)

Only needed if you want group membership to decide whether a new person lands as member or readonly. Add one more mapping, attribute name groups, PingOne user attribute Group Names. groups is one of the names KnoxCall checks without being told to, and PingOne emits one value per group the person belongs to. Whatever PingOne emits — group names, here, rather than the group UUIDs — is what you type as the keys of the group map on the KnoxCall connection. The map’s values are bounded: a group mapped to anything but member or readonly is refused at save time, because “…an IdP group may only map to member or readonly…” — those two and no others. Owner and admin are granted by a human on the team page and by nothing else.

​
3. Signing, encryption and signed requests (optional, and worth doing)

All three live on the application’s Configuration tab, under SAML Settings.
  • Enforce Signed AuthnRequest. KnoxCall signs every sign-in request it sends. Switch this on and give PingOne the certificate from the use="signing" KeyDescriptor in our metadata document as the Verification Certificate, and PingOne will check the signature rather than ignoring it. Switch it on without uploading the certificate and every sign-in fails.
  • Enable Encryption. Upload the certificate from the use="encryption" KeyDescriptor. It is the same certificate as the signing one, published twice on purpose, because an IdP reads one descriptor for each job. KnoxCall accepts encrypted and plain assertions alike and both take exactly the same path, so this is your call, not ours.
  • If you imported our metadata in step 1, PingOne already has both certificates and these are one toggle each.

​
4. Take the PingOne values back to KnoxCall

Two routes: import PingOne’s metadata, or type the values by hand. The import is the one that cannot be mis-transcribed.

​
Import the federation metadata

The application’s Configuration tab publishes IDP Metadata URL — one document carrying the issuer, the sign-on endpoint, the logout endpoint and the signing certificate, at https://auth.pingone.com/<environment-id>/saml20/metadata/<application-id>. Hand KnoxCall that link, or the document itself:
The call previews by default and writes nothing until you send it again with "apply": true. What the preview reports, what an import never touches, and every refusal it can answer with are on the overview. Like the metadata you gave PingOne, it is a snapshot: nothing re-reads that URL on a schedule, so run the import again when you move the application to a new key pair.

​
Or type the values

Still on the Configuration tab, expand the connection details and download the signing certificate. In KnoxCall, Settings → Single sign-on → your connection:
The Issuer ID is the environment’s, not the application’s — every SAML application in one PingOne environment shares it. That is correct and KnoxCall stores it as given: an entity ID is a name, and the sign-on endpoint is what distinguishes one application from another. The two fields that are dereferenced, the sign-in URL and the single-logout URL, must both be https and are refused otherwise.
Saving needs a re-authentication in the last five minutes; that is expected, and it is the same bar as changing a password.

​
5. Grant access, then test

Open the application’s Access tab and add the groups that should have KnoxCall, then switch the application on with the toggle at the top of the application list. PingOne refuses sign-in to anyone outside those groups before KnoxCall ever sees a request, and an application left off refuses everyone. Test with one account: open https://acme.knoxcall.com/saml/acme/login, sign in, and check the person lands in the workspace with the role you expected. If it fails, the login page names the cause — every message and code is in troubleshooting.

​
Single Logout

Both directions are already configured if you followed the steps above: KnoxCall’s SLO endpoint went into PingOne in step 1, and PingOne’s went into the KnoxCall connection in step 4. Leave the KnoxCall field empty if you do not want the SP-initiated direction. Empty means “this connection does not do SP-initiated Single Logout” and it never falls back to the sign-in URL. Either way, signing out of KnoxCall always ends the KnoxCall session — never conditionally on the IdP leg. The full behaviour is in Single Logout.

​
Rotating the PingOne signing certificate

A PingOne signing certificate is a key pair in the environment, created under Certificates & Key Pairs and selected by the application. So a rotation is: create the new key pair, teach KnoxCall about it, then point the application at it. Rotate add-first:
  1. In PingOne, Certificates & Key Pairs → Key Pairs → + → Generate, or rotate the existing pair. Do not change the application yet.
  2. Copy the new certificate into the KnoxCall connection. Pasting a certificate adds it — a connection can hold several active certificates and an assertion signed by any of them verifies.
  3. On the application’s Configuration tab, select the new key pair.
  4. Retire the old certificate in KnoxCall.
Doing it in that order means there is no instant at which the certificate PingOne is signing with is not one KnoxCall trusts. Retiring the only active certificate is refused outright: “This is the connection’s only active IdP certificate. Add the new certificate first, then retire this one.” Because the key pair is the environment’s, step 3 is per application: rotating here does not move your other PingOne applications, and switching each of them over is a separate decision.

​
PingFederate

PingFederate is a federation server you operate, so every value is yours and none of them is on this page. The shape of the work is the same and the two halves are:
  1. Create an SP connection for KnoxCall — browser SSO, SAML 2.0, SP-initiated — and give it KnoxCall’s metadata. PingFederate imports an SP metadata document directly, and https://acme.knoxcall.com/saml/acme/metadata is one: it carries the entity ID, the ACS, the SLO endpoint and both certificates. Sign the assertion, use RSA-SHA256, and map the NameID to an attribute that does not change when a person is renamed.
  2. Give KnoxCall your IdP metadata. PingFederate publishes it at /pf/federation_metadata.ping?PartnerSpId=<your-sp-entity-id> on your own host, and you can export it from the console. Import it the same way as above, with { "url": … } or { "xml": … }, previewing first.
Two PingFederate-specific things to check, because they are what KnoxCall sees go wrong:
  • Your metadata URL has to be reachable from the public internet for the URL form to work. A PingFederate behind a VPN is not, and the import will fail rather than hang — paste the document with { "xml": … } instead.
  • PingFederate’s default NameID is often the SAML_SUBJECT from your adapter, which in an Active Directory deployment is frequently the UPN or the email. Both change on a rename. Map it to objectGUID, an employee number, or another value that does not.
Everything else on this page — the attributes KnoxCall reads, the group map’s bound, the add-first certificate rotation, the five-minute re-authentication on save — is the same.