Single Sign-On with SAML 2.0
note
This information is only relevant for Admins managing a Playground Private Exchange.
Let your people sign in to Playground with your company identity provider (IdP), for example Okta, Microsoft Entra ID, OneLogin or any SAML 2.0 provider. They sign in once with their company account, and Playground creates their account the first time if you allow it.
Single sign-on is in addition to Google and Salesforce login unless you require single sign-on.
Before you start
- Make SAML available: Control Panel → General → Advanced Features → Enable SAML SSO, then save.
- Open Control Panel → Advanced → Connections. A SAML 2.0 card appears. Choose Set up.
You also need admin access to your identity provider to create an application there.
Step 1: Tell your identity provider about Playground
In the form, section 1. Give these to your identity provider, copy the three values and add them to a new SAML application in your IdP:
| Playground value | Common names in an IdP |
|---|---|
| ACS (Reply) URL | Single sign-on URL, Reply URL, Assertion Consumer Service URL |
| Entity ID (Audience) | Audience URI, Identifier, SP Entity ID |
| Metadata URL | Optional: some providers can import everything from it |
Set the NameID to the person's email address, because Playground matches people by email. If your IdP sends the email in an attribute instead, you can name it in step 3.
Step 2: Tell Playground about your identity provider
Section 2. Connect your identity provider.
tip
Use your IdP's metadata URL for a quick import. Paste it, choose Import, and the Entity ID, sign-in URL and signing certificate are filled in for you. You can then review them.
If your IdP only gives you a file, choose Paste metadata XML instead. You can also type the details yourself:
| Field | What it is |
|---|---|
| IdP Entity ID (Issuer) | The unique name your IdP identifies itself with |
| IdP sign-in URL | Where people are sent to sign in. Must start with https:// |
| IdP signing certificate | The public certificate your IdP signs responses with (PEM text). It is public, not a secret |
| Next signing certificate | Optional. Add it while your IdP rotates its certificate, so both are accepted and nobody is locked out |
Playground checks that the certificate is valid and not expired before saving it.
Step 3: Attribute mapping (optional)
The defaults work for most providers. Change them only if people's name or email arrive empty.
- NameID format: leave as email address.
- Email, first name and last name attributes: the attribute names your IdP uses. Empty means auto-detect.
Step 4: Login button
Choose what people see on the login page, for example Sign in with Okta.
- Button name: the name shown after "Sign in with". Empty shows "Single Sign-On".
- Logo: pick a built-in logo (Okta, Microsoft, OneLogin, Auth0, Ping, Google, or a generic key) or Custom image (upload). Upload a PNG, JPG, GIF or SVG up to 2 MB, square and around 64 x 64 pixels works best. You can replace or remove an uploaded logo at any time.
A preview shows how the button will look.
Step 5: Accounts and turning it on
Two switches at the top of the form:
| Switch | Meaning |
|---|---|
| Create accounts automatically | On (default): a person from your IdP gets a Playground account the first time they sign in, as long as their email matches your domain and a license is available. Off: only people who already have an account can sign in. Anyone else is told to ask an administrator. |
| Allow sign-in with SAML | Shows the single sign-on button on your login page. Set it up and test it first, then turn this on. |
Step 6: Test
- Choose Test configuration. It checks the saved details and lists anything missing or expired.
- Open the sign-in link it shows in a private window and sign in through your IdP. Keep your admin session open in the other window so you can never lock yourself out.
- When it works, turn on Allow sign-in with SAML and Save.
People can also start from your IdP's app dashboard (IdP-initiated sign-in). That works too.
Signing requests (advanced)
Most identity providers do not need signed sign-in requests. If yours does, switch on Sign requests, then add a signing certificate and its private key. The key is stored encrypted and is never shown again.
Troubleshooting
When a sign-in fails, the person sees a generic message, and the login history records the reason:
| Code | What it means | What to check |
|---|---|---|
SAML_BAD_SIGNATURE | The response signature could not be verified | The IdP signing certificate is the current one |
SAML_AUDIENCE_MISMATCH | The IdP addressed a different Entity ID | The Audience in your IdP matches the Entity ID shown here |
SAML_EXPIRED | The response was expired or not yet valid | Clock sync between your IdP and Playground |
SAML_WRONG_DESTINATION | The response was sent to a different ACS URL | The ACS URL in your IdP matches exactly |
SSO_NO_EMAIL | The IdP did not send an email | NameID is email, or set the email attribute in step 3 |
SSO_NO_ACCOUNT | Signed in, but no account exists and automatic creation is off | Add the person, or turn on Create accounts automatically |
NO_WORK_EMAIL | The email does not belong to your domain | The email domain matches your Playground domain |
SSO_DISABLED | SAML is not enabled | Enable SAML SSO in Advanced Features, and Allow sign-in with SAML |
Security
- Responses must be signed by your IdP, and unsigned or tampered responses are rejected.
- Certificates are public values. The signing private key (if used) is encrypted.
- Playground matches people by email. Make sure your IdP only releases verified company emails.