Skip to main content

Ping Identity

Ping Identity SSO

Configure PingOne as a SAML identity provider (IdP) for Knocknoc. Users authenticate against Ping, and Knocknoc maps their group membership to access entitlements.

This example assumes your Knocknoc instance is at https://<tenant>.knoc.cloud. Substitute your own instance URL throughout (e.g. https://demo.knoc.cloud).

In this integration:

  • Knocknoc is the Service Provider (SP) — it consumes the SAML assertion.
  • PingOne is the Identity Provider (IdP) — it authenticates the user and issues the assertion.

These steps cover PingOne (cloud). PingOne for Enterprise and PingFederate expose the same building blocks — a SAML application, attribute mapping, and an IdP metadata URL — so the Knocknoc-side values are identical and the flow transfers with minor menu differences.

User vs Admin SAML. Knocknoc supports SAML for the user portal and, separately, for the admin interface, using different endpoint paths (/api/saml/... vs /api/admin/saml/...). Configure Users first; once confirmed working, extend to Admins while keeping a local break-glass admin account.

Before you begin

  • Administrator access to your PingOne environment.
  • Administrator access to your Knocknoc instance.
  • The Knocknoc groups you intend to gate access with already created (or their names to hand).

Step 1: Create the SAML app in PingOne

  1. In the PingOne admin console, go to Connections > Applications.
  2. Click the + (Add Application).
  3. Enter a name (e.g. Knocknoc), select SAML Application, and click Configure.

In Provide App Metadata, choose Manually Enter and set:

Field Value (Users) Value (Admin)
ACS URLs https://<tenant>.knoc.cloud/api/saml/acs https://<tenant>.knoc.cloud/api/admin/saml/acs
Entity ID https://<tenant>.knoc.cloud/api/saml/metadata https://<tenant>.knoc.cloud/api/admin/saml/metadata

Click Save.

Shortcut: instead of manual entry you can select Import From URL and point PingOne at the Knocknoc SP metadata endpoint (https://<tenant>.knoc.cloud/api/saml/metadata) to populate ACS and Entity ID automatically. Generate the Knocknoc keypair first (Step 4) so the SP certificate is present in the metadata.

Step 2: Set the NameID format

In the application's Configuration > SAML settings, set:

Field Value
Subject NameID Format urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

Map the subject (SAML_SUBJECT) to the user's Username.

Step 3: Configure attribute mapping

Knocknoc reads four specific claims. The claim names must match exactly. On the Attribute Mapping page, add each pair (claim name on the left, PingOne attribute on the right) and tick Required where noted:

Claim name (required) PingOne attribute Notes
username Username Required. The user's login identifier.
realName Formatted (full name) If unavailable, use a display-name attribute, or combine Given Name + Family Name.
sessionDuration literal value, e.g. 480 Login duration in minutes (whole number). Enter as a literal/expression value, not a directory attribute.
groups Group Names Emits the names of every group the user belongs to.

Click Save.

The sessionDuration claim controls the Knocknoc login session length and is independent of PingOne's Assertion Validity Duration (the lifetime of the SAML assertion itself).

Step 4: Configure Knocknoc (SP)

  1. In PingOne, open the application's Configuration tab and copy the IdP Metadata URL. Toggle the application on to enable it.
  2. In Knocknoc, log in to the admin interface and open Settings.
  3. In the Metadata URL field, paste the PingOne IdP Metadata URL.
  4. Click Generate new keypair, then Save. (Optionally, supply your own keys/certificate manually.)

Because PingOne serves a live, hosted metadata URL, Knocknoc stays in sync with Ping's signing certificate automatically — no manual certificate handling required.

Step 5: Map groups in Knocknoc

PingOne's Group Names attribute sends human-readable group names, so use Knocknoc's by-name matching: set each Knocknoc group's Group Name to the exact PingOne group name (e.g. US-Admin-SSH).

Multi-value check. Verify on a test user that PingOne emits multiple groups as repeated <AttributeValue> elements rather than a single delimited string. Knocknoc expects discrete values; a delimited string is the most common cause of group-mapping failures.

Step 6 — Test

  1. Browse to https://<tenant>.knoc.cloud/. An SSO Login button should be present.
  2. Click it. If not already authenticated to Ping, you are redirected to the PingOne sign-in page.
  3. Authenticate.
  4. Confirm you are returned to Knocknoc and that any ACLs tied to your groups now show Granted.

Once Users work, repeat for the Admin interface using the /api/admin/saml/... endpoints — and keep a local break-glass admin in case SAML breaks.

Troubleshooting

Symptom Likely cause
Redirect loop / "invalid issuer" Entity ID mismatch — confirm it ends in /api/saml/metadata (or /api/admin/saml/metadata)
Assertion rejected Knocknoc keypair not generated, or the IdP Metadata URL is wrong/unreachable
User authenticates but lands with no access groups claim empty (check the Group Names mapping) or the Knocknoc Group Name doesn't match the PingOne group name
All users land in one group Groups arriving as a delimited string, not repeated <AttributeValue> elements
Session ends too soon / too late sessionDuration claim missing or wrong; it is whole minutes (e.g. 480)
"NameID format" error Subject NameID format mismatch — confirm Persistent on both sides

Reference — value exchange

Direction Values
PingOne → Knocknoc IdP Metadata URL (carries SSO URL, Entity ID and signing certificate)
Knocknoc → PingOne ACS URL (/api/saml/acs, POST), SP Entity ID (/api/saml/metadata)

Need help? Contact Knocknoc support or your solutions engineer.

Back to top