Skip to main content

​
Enterprise SSO

Enterprise SSO (single sign-on) lets your administrators sign in to the Cobalt console with their work account, through your identity provider (IdP — the system your company already signs in with, such as Microsoft Entra ID or Okta). A guided setup walks you through it in about ten minutes, and you prove it works with a real sign-in before anyone else depends on it.
Cobalt connects to your provider with SAML 2.0, the standard most providers use for workforce sign-in. The setup has written instructions for Microsoft Entra ID and Okta, and a general path for Google Workspace, OneLogin, PingFederate and any other SAML 2.0 provider. OIDC isn’t offered for console sign-in. SSO has to be included in your plan; the setup checks this before it creates anything, and offers Ask us to enable it if it isn’t.
Admin sign-in and chat sign-in are separate: this page is only about who can reach the console. How the people your agents talk to sign in is set up per agent — see How end-user identity works.

​
Set it up

Open Settings › Identity › Admin sign-in and select Set up SSO. You need the Admin or Owner role. The setup, Sign-in for this console, has four steps in three phases: Prepare → In ‹your provider› → Go live. You’ll work in two browser tabs: this one and your provider’s admin console.
1

Your provider (Prepare)

Pick your provider under Which identity provider does your company sign in with?, then enter the email domain your administrators sign in with (for example acme.com). Every instruction after this is written for the provider you pick. Select Create the connection. Nothing changes for your team yet.
2

Set up the app (In ‹your provider›)

Work down the numbered tasks in your provider’s admin console. Between them you:
  • create a SAML application named Cobalt;
  • paste in the two values Cobalt shows you — the address your provider sends people back to (the ACS URL, Assertion Consumer Service, which Entra calls the Reply URL) and the name Cobalt answers to (the Entity ID);
  • send the five attributes in the table below;
  • assign yourself to the app, so you can test it, and tick the box to confirm you did;
  • copy the app’s metadata URL back into Cobalt. This one address carries your provider’s sign-in address and signing certificate, and Cobalt picks up a new certificate from it when your provider rolls one, so there’s nothing else to type.
Continue unlocks once the metadata URL is in and you’ve ticked the box. You can leave with Save & finish later and come back to this step from Settings › Identity › Admin sign-in. Cobalt doesn’t keep the metadata URL until you continue, so you’ll paste it again.
3

Turn on and test (Go live)

Select Turn on and start the test. From that moment, anyone who reaches the console with an address at your domain is sent to your provider instead of the password box. Email and password sign-in keeps working throughout, so nobody is locked out.Open a private window (incognito or InPrivate), paste the Cobalt sign-in address you’re given, and sign in the way your team will. A private window matters, because a window where you’re already signed in can hand back your existing session and prove nothing. Cobalt watches for your sign-in for ten minutes. When it arrives, the page shows Signed in through ‹your provider› with what came back: the address you signed in as, your name, and the groups your provider sent.If your provider signs you in but Cobalt can’t accept it, the page says what was missing (usually the email attribute) and shows the fix for your provider. Fix it, then select Test sign-in again. You can turn it off at any point with Turn SSO back off.
4

Roles (Go live)

Match your provider’s groups to Cobalt roles. The groups sent during your test appear as buttons; select one to add it, or use + Add a group to type any other group name. Give each group one or more roles. Mapping a group to Admin asks you to confirm with Yes, grant Admin, because everyone in that group gets full control of the console. Then select Save and finish, or Finish without mappings to skip this for now. See Map groups to roles.
When you finish, the page confirms Your team signs in with ‹your provider›. Anyone at your domain who is assigned to the app in your provider can now reach the console. Assign the rest of your team in your provider whenever you like; nothing in Cobalt has to change.

​
The five attributes

Type the names exactly as written. Cobalt looks for these plain names, not the long URL-style names some providers start with. Send group names, not internal ids. In Entra ID, that takes the group claim settings the setup spells out; on any other combination Entra sends ids, and you’d have to map those instead.

​
Map groups to roles

Instead of assigning roles by hand, you can let your provider’s groups decide them. You map groups in the last step of the setup, and can change the mappings at any time on Settings › Identity › Admin sign-in. How it behaves:
  • Roles are set when someone signs in. Your provider sends their groups at sign-in, and Cobalt gives them every role their mapped groups carry. A group can hold more than one role. A mapping change reaches each person at their next sign-in.
  • No matching group means Member. Anyone whose groups match no mapping, or whose provider sends no groups, gets the Member role: they can look but not change anything.
  • Your provider is in charge. Once groups are mapped, the roles your provider’s groups give someone replace the roles they had. A role you change by hand on the Team page can be replaced at their next sign-in.
  • Owner is never granted by a mapping, and Cobalt never removes the workspace’s last Admin or Owner. If a mapping would do that, their current roles are kept.
  • Removing someone from a group takes effect at their next sign-in. To take someone’s console access away right now, remove them on Settings › Team (see Roles & team).
Group names match without regard to capitals or surrounding spaces.
No mappings? Then SSO only handles sign-in: everyone who signs in through your provider is a Member, and you give people more on the Team page.

​
Password sign-in

Once SSO is active, everyone with an email address on your SSO domain signs in through your provider instead of with a password. People on your team with an address on another domain keep signing in with email and password. See After SSO is configured.

​
Turn off or remove SSO

  • Deactivate turns SSO off but keeps the connection and its role mappings, so turning it back on needs no work in your provider. While it’s off, your team signs in with email and password.
  • Delete connection (at the bottom of Settings › Identity › Admin sign-in) removes it for good, and your team goes back to email and password. Your role mappings are kept. If an older web chat channel still signs its people in through this connection, Cobalt asks you to move that channel to another sign-in option first.