Single Sign-On with OpenID Connect
note
This information is only relevant for Admins managing a Playground Private Exchange.
Let your people sign in with any OpenID Connect (OIDC) provider, for example Okta, Microsoft Entra ID, Auth0, Google Workspace or Keycloak. Setup is shorter than SAML: register Playground in your provider, then paste an issuer URL, a client ID and a client secret.
OpenID Connect sign-in works in addition to Google and Salesforce, unless you choose to require single sign-on.
At a glance
- Turn OpenID Connect on for your Playground.
- Register Playground in your provider and copy the Redirect URI into it.
- Paste the provider's issuer URL, client ID and client secret into Playground.
- Test in a private window.
- Switch it on for everyone.
Before you start
- Go to Control Panel → General → Advanced Features, switch on Enable OpenID Connect (SSO), then save.
- Go to Control Panel → Advanced → Connections. An OpenID Connect card appears. Choose Set up.
Step 1: Register Playground in your provider
In your identity provider, create a new web application (sometimes called a "confidential client"). Add this as its Redirect URI (shown in section 1 of the form, with a Copy button):
It must match exactly. Your provider then gives you a Client ID and a Client secret.
Section 1 also shows a Sign-in (start) URL. It is optional and makes sign-in one click from your provider's app dashboard:
Paste it into the Initiate login URI (Okta), Home page URL (Microsoft Entra ID) or Login URL of the application, so the tile in the dashboard opens it. Playground sends the person to your provider and back, signed in. People who use the Sign in with … button on the Playground sign-in page do not need it.
Step 2: Enter the details in Playground
Section 2. Paste what it gives you.
tip
Paste your provider's issuer URL (or its .well-known/openid-configuration address) and choose Discover. Playground reads the endpoints and keys for you and shows what it found. You then only add the client ID and secret.
| Field | What it is |
|---|---|
| Issuer or discovery URL | Your provider's OpenID Connect address, for example https://login.example.com. Must start with https:// |
| Client ID | The identifier your provider gave this application. Not a secret |
| Client secret | The secret your provider generated. Stored encrypted and never shown again |
| Scopes | What Playground asks for. openid email profile is right for almost everyone and must include openid |
| Email claim | Only if the email is not in the standard email claim, for example upn. Empty means email, then preferred_username |
| First and last name | Read from the standard given_name and family_name claims, or from name split on the first space. Nothing to set |
| Unique identifier claim | A claim that never changes for a person, such as sub or oid. Empty means people are matched by email. See How people are matched |
Issuer URL examples
| Provider | Issuer URL |
|---|---|
| Okta | https://<your-org>.okta.com |
| Microsoft Entra ID | https://login.microsoftonline.com/<tenant-id>/v2.0 (use your tenant ID, not common) |
| Auth0 | https://<your-tenant>.auth0.com/ |
| Google Workspace | https://accounts.google.com |
| Keycloak | https://<host>/realms/<realm> |
After Discover, a box lists the endpoints that were found, plus any warnings. For example, the provider does not offer PKCE, or it reports a different issuer than the address you gave.
Step 3: Sign-in button, accounts and turning it on
These work in the same way as in the SAML guide:
| Setting | What it does |
|---|---|
| Button name and Logo | Shown on your sign-in page as Sign in with followed by the name |
| Just-in-time (JIT) provisioning | On: a person from your provider gets an account the first time they sign in, if their email domain is allowed and a license is free. Off: only people who already have an account can sign in |
| Enable OpenID Connect (SSO) | Shows the sign-in button. Set it up and test first, then switch it on |
Step 4: Test, then switch on
- Choose Test discovery. Playground contacts the provider and reports whether it is reachable.
- Open the sign-in link it shows in a private window and sign in. Keep your admin session open in your normal window.
- When it works, switch on Enable OpenID Connect (SSO) and choose Save.
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 |
| Make OpenID Connect the only way in | Set the sign-in policy to Require single sign-on (SSO) |
| Use SAML and OpenID Connect together | Set up both. People see one sign-in button for each |
| Rotate the client secret | Create a new secret in your provider, paste it into Client secret and save. Leave the field empty to keep the saved one |
Troubleshooting
The login history records the reason for a failed sign-in.
| Code | What it means | What to check |
|---|---|---|
OIDC_DISCOVERY | Could not reach the provider | The issuer URL, and that it can be reached from the internet |
OIDC_SESSION | The sign-in session expired, or was started in another browser | Try again in a single browser window |
OIDC_NO_EMAIL | No email claim was found in the ID token | Set the Email claim to the name your provider sends, and the scopes include email |
OIDC_NO_UNIQUE_ID | The Unique identifier claim is not in the ID token | The claim name matches exactly, and your provider releases it |
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 | OpenID Connect is not switched on | Enable OpenID Connect (SSO) in Advanced Features, and on the OpenID Connect card |
Security
- The authorization-code flow with PKCE is used, and responses are validated against your provider's published signing keys.
- The client secret is stored encrypted and is never sent back to the browser.
- Only release verified company email addresses from your provider.
How people are matched
Playground never links accounts automatically and never guesses the Unique ID. Matching depends on Unique identifier claim:
- Empty: the person is found by the email in the Email claim (default
email, thenpreferred_username), checked against your allowed email domains. - Set (for example
suboroid): the value must equal the person's Unique ID on the People page. There is no email fallback.
Set Unique IDs on Control Panel → People: edit a person, or choose Import Unique IDs (CSV) with the columns email,uid. If your configuration does not match what the provider sends, the sign-in is refused and the login history shows the claim to fix.