Single sign-on (SSO)

Set up SAML single sign-on

Set up SAML single sign-on for the Ploy dashboard with your identity provider, such as Microsoft Entra ID or Okta. You copy five service provider values from Ploy into your identity provider, paste your identity provider's metadata into Ploy, add your email domains, and finish with a real test sign-in.

Before you start

  • SAML read and write permissions in the Ploy dashboard. Managing the SSO configuration requires them.

  • Your identity provider's metadata XML. It must be valid XML with an entityID.

  • The email domain or domains your team signs in with. At least one is required, and each one must be a domain your organization has already registered as an internal domain in Ploy.

Set up SAML single sign-on

1. Open the SSO settings

  1. In the Ploy dashboard, open your organization settings and go to the page titled Single Sign-On (SSO).

2. Copy the service provider values into your identity provider

The SSO page lists the five values your identity provider needs, with your organization's ID already filled in. Copy each value from the page rather than typing it by hand.

Ploy field

Value

Entity ID (Identifier)

urn:ploy:dashboard

ACS URL (Reply URL / Assertion Consumer Service)

https://api.joinploy.com/sso/sp/consume/<your-org-id>

Sign on URL (Login URL)

https://api.joinploy.com/sso/auth/signin/<your-org-id>

Metadata URL

https://api.joinploy.com/sso/sp/metadata/<your-org-id>

Logout URL (SLO URL / Single Logout Service)

https://api.joinploy.com/sso/sp/logout/<your-org-id>

3. Configure your identity provider

Create a new SAML app for Ploy in your identity provider and paste in the five values from the previous step. For step-by-step instructions, see Set up Microsoft Entra ID SAML single sign-on and Set up Okta SAML single sign-on in this collection. Other identity providers use the same values.

4. Add your identity provider's metadata and email domains in Ploy

  1. In the SSO setup form, paste your identity provider's metadata XML into IdP Metadata XML. Ploy extracts and stores the identity provider's entity ID from the metadata.

  2. In Email Domains, add at least one email domain. Domains must belong to your organization's internal domains, and a domain another organization has already claimed is rejected. Duplicate entries are removed automatically.

  3. Review the three settings: Enable SSO is on by default for a new configuration, while Enforce SSO and Use identity provider session length are off by default.

  4. Save the configuration.

5. Test the sign-in

The test action on the SSO page does not run a live validation. It returns your organization's sign-in URL, and you complete an actual sign-in through it to exercise the full flow.

  1. Run the test action and open the sign-in URL it returns.

  2. Sign in as a user whose email uses one of your configured domains.

Requirements

Ploy enforces these rules on the identity provider side:

  • Signature: the SAML response envelope must be signed. A signed assertion on its own is not enough.

  • Encryption: assertions do not need to be encrypted. Unencrypted assertions are accepted.

  • Initiation: IdP-initiated sign-in is supported.

  • Algorithms: SHA-1 signatures and SHA-1 digests are rejected. Use SHA-256.

  • User identity: the assertion must carry the user's email in an attribute named one of:

    • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

    • http://schemas.xmlsoap.org/claims/EmailAddress

    • emailaddress

    • email

    As a fallback, Ploy accepts the Subject NameID only when its format is urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. The email is trimmed and lowercased. If no usable email is found, the sign-in fails with SAML authentication failed, and a missing or misconfigured attribute mapping is the most common cause.

What SAML SSO covers

SAML SSO covers the Ploy dashboard only.

  • We don't support SAML sign-in on the employee portal (the employee-access.com member portal) yet.

  • We don't support the SCIM protocol directly. For the dashboard, Ploy can provision users to itself the same way it provisions them to any other application or resource. The employee portal needs no provisioning: Ploy dynamically allows and revokes portal access based on whether the employee is active in HR/Ploy.

If your test sign-in fails, see Fix SAML single sign-on errors.

Was this helpful?
Was this helpful?