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 other SAML 2.0 provider. People sign in once with their company account. You decide whether Playground creates their account automatically.
SAML sign-in works in addition to Google and Salesforce, unless you choose to require single sign-on.
At a glance
- Turn SAML on for your Playground.
- Copy two values from Playground into your identity provider.
- Import your identity provider's metadata back into Playground.
- Test in a private window.
- Switch it on for everyone.
It takes about 10 minutes. You need admin access to your identity provider.
Before you start
- Go to Control Panel → General → Advanced Features, switch on Enable SAML 2.0 (SSO), then save.
- Go to Control Panel → Advanced → Connections. A SAML 2.0 card appears. Choose Set up.
Step 1: Add Playground to your identity provider
In your identity provider, create a new SAML 2.0 application. In the Playground form, section 1. Give these to your identity provider, copy these values into it:
| Playground field | What your identity provider may call it |
|---|---|
| Assertion Consumer Service (ACS) URL | Single sign-on URL, Reply URL, ACS URL |
| SP Entity ID (Audience URI) | Audience URI, Identifier, Entity ID, SP Entity ID |
| SP metadata URL | Optional. Some providers can import both values above from it |
| Sign-in (start) URL | Optional. Login URL, Initiate login URL, App launch URL or Default relay URL. Makes sign-in one click from your identity provider's dashboard, see How people can sign in |
Also set the application's NameID (sometimes called "Name ID format" or "Unique user identifier") to the person's email address, or note the format you choose and map the attributes in step 3.
Where to find these in common providers
Menu names change between versions, so treat these as a guide.
- Okta: Applications → Create App Integration → SAML 2.0. Use Single sign-on URL and Audience URI (SP Entity ID). Set Name ID format to EmailAddress.
- Microsoft Entra ID: Enterprise applications → New application → Create your own → Single sign-on → SAML. Use Reply URL (Assertion Consumer Service URL) and Identifier (Entity ID). Set Unique User Identifier to the user's email.
- OneLogin: Applications → Add App → SAML Custom Connector (Advanced). Use ACS (Consumer) URL and Audience (EntityID).
Step 2: Add your identity provider to Playground
Section 2. Connect your identity provider. Choose one of these three ways.
| Way | When to use it | What to do |
|---|---|---|
| Metadata URL (fastest) | Your identity provider shows a metadata URL | Paste it into IdP metadata URL and choose Import |
| Metadata XML | Your identity provider only gives you a file | Choose Paste metadata XML instead, paste the file contents, choose Import XML |
| Enter manually | You have no metadata at all | Fill in the fields below yourself |
Import fills in the fields below. Review them, and fix anything that looks wrong.
| Field | What it is |
|---|---|
| Identity provider issuer (IdP Entity ID) | The unique name your identity provider identifies itself with |
| Identity provider single sign-on URL | Where people are sent to sign in. Must start with https:// |
| SAML binding | Redirect (HTTP-Redirect) or POST (HTTP-POST). It must match the URL above. Importing metadata picks the right one for you |
| Identity provider X.509 certificate | The public certificate your identity provider signs sign-ins with (PEM text, -----BEGIN CERTIFICATE-----). It is public, not a secret |
| Secondary X.509 certificate | Optional. Only used while your identity provider replaces its certificate, see Certificate rotation |
Playground checks that the certificate is valid and not expired before it saves it.
Step 3: Attribute mapping
Tell Playground which NameID format your identity provider sends. The email and names are found automatically from common attribute names, so you only set them if they arrive empty. The Unique ID is never guessed.
| Field | What it does | If left empty |
|---|---|---|
| NameID format | The kind of NameID your identity provider sends. It must match your identity provider's setting | Email address |
| Email attribute | The attribute that carries the email | Auto-detects email, mail, emailaddress, then uses the NameID with the Email address format |
| Unique identifier attribute (immutable ID) | A value that never changes for a person, such as objectidentifier or employeeId. People are matched to the Unique ID stored on their account | Uses the NameID as the Unique ID with Persistent and Unspecified, or matches by email with Email address. Not allowed empty with Transient |
| First name attribute | Used when the account is created | Auto-detects firstName, givenName |
| Last name attribute | Used when the account is created | Auto-detects lastName, surname |
Attribute names must match what your identity provider sends exactly, including case.
What to set for each NameID format
| NameID format | What the NameID contains | Email attribute | Unique identifier attribute |
|---|---|---|---|
| Email address | The email, such as jane@acme.com | Not needed | Optional, recommended |
| Persistent | A stable, opaque ID for the person | Only if it is not auto-detected | Not needed, the NameID is used |
| Transient | A new random value on every sign-in | Only if it is not auto-detected | Required |
| Unspecified | Whatever your identity provider decides | Only if it is not auto-detected | Recommended, because the NameID may not be stable |
Playground refuses to switch SSO on with the Transient format until a Unique identifier attribute is set.
Pick an immutable ID if you can
If your NameID is the email address, it changes when the email changes. An unchanging value such as objectidentifier (Microsoft Entra ID) or employeeId lets Playground recognise the person even if their email changes. Unique IDs are stored per person, see How people are matched.
Step 4: Sign-in button
Choose what people see on your sign-in page, for example Sign in with Okta.
- Button name: shown after "Sign in with". Empty shows "Single Sign-On".
- Logo: a built-in logo (Okta, Microsoft, OneLogin, Auth0, Ping, Google or a generic key), or Custom image (upload): PNG, JPG, GIF or SVG, up to 2 MB, square and around 64 x 64 pixels.
A Preview shows the button before you save.
Step 5: Accounts and turning it on
Two switches at the top of the form:
| Switch | On | Off |
|---|---|---|
| Enable SAML 2.0 (SSO) | The sign-in button appears on your sign-in page | Nobody can use SAML. Use this while you set up and test |
| Just-in-time (JIT) provisioning | A person from your identity provider gets a Playground account the first time they sign in, if their email domain is allowed and a license is free | Only people who already have a Playground account can sign in. Everyone else is asked to contact an administrator |
Step 6: Test, then switch on
- Choose Test configuration. It checks what you saved and lists anything missing or expired.
- Open the sign-in link it shows in a private window and sign in through your identity provider. Keep your admin session open in your normal window, so you can never lock yourself out.
- When it works, switch on Enable SAML 2.0 (SSO) and choose Save.
How people can sign in
| Way | How it starts | Notes |
|---|---|---|
| From Playground (SP-initiated) | The person chooses the Sign in with … button | Returns to the page they asked for |
| From your identity provider, one click (SP-initiated) | The person clicks the Playground tile, and the tile opens the Sign-in (start) URL | Playground sends them straight to your identity provider and back, signed in. Returns to the home page |
| From your identity provider (IdP-initiated) | The identity provider posts a response to Playground without a start URL | Lands on the home page. JIT provisioning rules apply in the same way |
The Sign-in (start) URL is shown in section 1 of the SAML form, with a Copy button. It looks like this:
Paste it into the Login URL (or Initiate login URL, App launch URL) of your identity provider application so the tile in the app dashboard opens it. If you leave it empty, the tile may use your identity provider's own flow (IdP-initiated), which also works. All ways use the same ACS URL.
Options for each situation
| I want to… | Do this |
|---|---|
| Let anyone at my company in | Keep JIT provisioning on and list your domains under Allowed Email Domains |
| Only allow people I add myself | Switch JIT provisioning off. Add people first, then they can sign in with SAML |
| Make SAML the only way in | Set the sign-in policy to Require single sign-on (SSO) |
| Keep Google and Salesforce too | Leave the policy on Any sign-in method |
| Replace an expiring certificate | See Certificate rotation |
| Use a different provider later | Import the new provider's metadata and save. People keep their accounts |
Certificate rotation
When your identity provider replaces its signing certificate, there is a period when both certificates are valid. Playground accepts both, so nobody is locked out.
- Paste the new certificate into Secondary X.509 certificate. Save.
- Let your identity provider switch over to the new certificate.
- Move the new certificate into Identity provider X.509 certificate, clear the secondary field and save.
Signed requests (advanced)
Most identity providers do not need this. If yours requires signed sign-in requests, switch on Sign authentication requests, then add the SP signing certificate (X.509, PEM) and SP private key (PEM). The private key is stored encrypted and is never shown again. Leave the key field empty to keep the saved one.
Troubleshooting
When a sign-in fails, the person sees a short message and the login history records the reason, including which attribute or setting was the problem.
Admins can see the issue in the logs
The login history shows the exact failure for each attempt. The same detail is written to the server logs, so your administrator or Playground support can look up the attempt by time and email.
| Code | What it means | What to check |
|---|---|---|
SAML_BAD_SIGNATURE | The signature could not be verified | The identity provider X.509 certificate is the current one |
SAML_AUDIENCE_MISMATCH | The identity provider addressed a different Entity ID | The Audience in your identity provider matches the SP Entity ID shown here |
SAML_EXPIRED | The response was expired or not yet valid | Clocks are in sync between your identity provider and Playground |
SAML_WRONG_DESTINATION | The response went to a different ACS URL | The ACS URL in your identity provider matches exactly |
SAML_NO_EMAIL | No email could be found in the response | Set the Email attribute to the name your identity provider sends, or use the Email address NameID format |
SAML_NO_UNIQUE_ID | The Unique identifier attribute is not in the response | The attribute name matches exactly, and your identity provider releases it for every person |
SAML_TRANSIENT_NO_ID | The NameID format is Transient and no Unique identifier attribute is set | Set the Unique identifier attribute in step 3 |
SSO_NO_ACCOUNT | Signed in, but no account exists and JIT provisioning is off | Add the person, or switch JIT provisioning on |
NO_WORK_EMAIL | The email is not on the allowed email domains | The domain is listed under General → Allowed Email Domains |
SSO_UID_NOT_FOUND | No person has the Unique ID the provider sent | The person's Unique ID on the People page equals the value in the log, or turn on JIT provisioning |
SSO_UID_EMAIL_EXISTS | A person with this email exists but has a different or empty Unique ID | Set that person's Unique ID on the People page |
SSO_DISABLED | SAML is not switched on | Enable SAML 2.0 (SSO) in Advanced Features, and on the SAML card |
If an error page appears before any login screen (often "405"), the SAML binding does not match the sign-in URL. Import the metadata again, or switch between Redirect and POST.
Security
- Responses must be signed by your identity provider. Unsigned or tampered responses are rejected.
- Certificates are public values. The SP private key, if you use one, is encrypted.
- Make sure your identity provider only releases verified company email addresses.
How people are matched
Playground never links accounts automatically and never guesses the Unique ID. There are two modes, set by your Step 3 mapping:
| Mode | When | How a person is found |
|---|---|---|
| By email | Email address format and no Unique identifier attribute | The email in the NameID, checked against your allowed email domains |
| By Unique ID | A Unique identifier attribute is set, or the format is Persistent, Transient or Unspecified | The value from your identity provider must equal the person's Unique ID on the People page. There is no email fallback |
Setting Unique IDs. On Control Panel → People, edit a person's Unique ID, or choose Import Unique IDs (CSV) and upload a file with the columns email,uid. Unique IDs must be unique within your Playground.
If someone in By Unique ID mode signs in and nobody has their Unique ID, the sign-in is refused and the login history says which value was missing. With JIT provisioning on, a new account is created with that Unique ID, unless a person with the same email already exists without it.
If your setup does not match what your identity provider sends, the sign-in is refused and the login history shows the exact setting to fix.