Skip to main content

​
SSO (Single Sign-On)

Your company’s users can sign in to SalesOS without a SalesOS password: the identity provider your company already uses does the authentication. SalesOS receives the identity, checks that the person belongs to your company and opens the session. It covers all of SalesOS — home screen, leads, wallet, campaigns, ranking — and the link can take the person straight to any of those pages. This guide is for whoever administers your company’s identity provider (the IT team).

​
Who does what

​
Before you start

  • Administrator access to your identity provider (OAuth 2.0 / OpenID Connect).
  • Your company already uses SalesOS and SSO access has been agreed with Play2sell.
  • A test user in your provider who is not an administrator: administrators often get access to everything automatically, and the test would pass without proving anything.

​
What your provider needs

If your provider lets you choose how the application authenticates at the token endpoint, enable both client_secret_post and client_secret_basic.

​
Step by step

1

Register Play2sell in your provider

Create one application per environment (production and staging) with these settings:Done when: both applications exist and each callback address is exactly as above, with no trailing slash.
2

Map the profile

Make sure userinfo returns the user’s stable identifier, email and name. Note the name of each field (e.g. sub, email, name, or dados.cpf).Done when: the test user has all three fields filled in.
3

Assign who can sign in

In your provider, assign the users or groups that can sign in to SalesOS to the application. This is the step most often forgotten: without the assignment, your provider refuses the sign-in before it ever reaches SalesOS.Done when: the test user is assigned to both applications.
4

Send the details to Play2sell over a secure channel

Never as plain-text email or chat. For each environment:
  • the path to your OpenID Connect configuration (/.well-known/openid-configuration) or your provider’s authorization, token and userinfo endpoints;
  • the client ID and client secret;
  • the names of the stable identifier, email and name fields;
  • the test user and a technical contact.
Done when: Play2sell confirms receipt.
5

Receive the connection name and the entry link

Play2sell connects your provider to SalesOS in staging and returns the connection name and the entry link (see Entry link).
6

Test in staging

With the test user (not an administrator), open the staging entry link:Done when: all three results happen. If something fails, see Troubleshooting.
7

Production

Repeat step 4 with the production application details. Once Play2sell confirms, share the production entry link with your users — in your portal, intranet or any system of yours that leads to SalesOS.

​
Entry link

Each environment has its own connection: the connection name in staging is the one Play2sell gives you for the staging application.
Some SalesOS APIs already return the entry link for the right page. The Campaigns API, for example, returns access.login_url with the address for each environment — use it instead of building the link in your code.
A user who came in this way and whose session expires inside SalesOS is sent back through your provider automatically, to the same page, instead of a password screen they don’t have.
next only accepts a path inside SalesOS (starting with /). A full URL, another host or a sign-in path is ignored and the user lands on the home screen.

​
The stable identifier

It is the field that says who the person is from one sign-in to the next. It must not change when the user changes email. Your company picks one of these: Namespaced fields (e.g. https://yourcompany.com/cpf) and nested fields (e.g. dados.cpf) are accepted.

​
Who gets in and who is refused

Signing in through your company’s provider does not open the account of someone outside your company. A new user comes in already tied to your company, with the default role agreed with Play2sell; role changes are made in SalesOS. The cases below are refused, each with a message that tells the user what to do:
The screens themselves are in Portuguese; the table translates them.

​
Offboarding and client secret rotation

  • Someone leaves your company: deactivate the person in your provider. Their next sign-in is refused by your provider; a session they already had open in SalesOS lasts until it expires. To cut it in SalesOS too, ask your company’s SalesOS manager to deactivate their access.
  • Client secret rotation: many providers make the secret expire (usually after 6 to 24 months). Before it expires, generate a new one and send it to Play2sell over the same secure channel, with the date for the switch, so sign-in does not stop.

​
Troubleshooting

When asking Play2sell for help, send: the time of the attempt, the user’s email, the environment (production or staging) and the error code or text shown on screen.

​
Security

  • Authorization code with server-to-server exchange: no identity token travels in the browser URL.
  • PKCE on every authorization.
  • The client secret lives only in Play2sell’s authentication service; it is not stored in the SalesOS database and is never shown back on any screen.
  • Denied by default: a sign-in through a connection that is not enabled, or from a company whose access is turned off, is refused — it never falls back to another path.

​
Next steps

Campaigns API

An API that returns the entry link ready to use (access.login_url)

API Keys

Server-to-server integrations