ConversaLabs Help Center
en
Language
pt_BR Portuguese (Brazil) en English es Spanish

Single sign-on (SSO) with SAML

Open in
View as Markdown Open in ChatGPT Open in Claude

Conversa Labs

Last updated on Sep 7, 2026

Overview

Single sign-on (SSO) with SAML lets agents sign in to ConversaLabs using your company's identity provider (IdP) — such as Okta, Azure AD / Microsoft Entra, or Google Workspace. Instead of each person keeping a separate password on the platform, authentication is delegated to the IdP: your corporate directory controls who can sign in and who loses access.

It is a premium feature (gated by plan and by installation type — Cloud or Enterprise) and lives under Settings > Security.

Prerequisites

  • An Administrator profile to configure SSO.
  • A plan with the SAML feature enabled for the account (premium/optional). If it isn't active, the Security area shows an unavailability notice or an upgrade screen.
  • A Cloud or Enterprise installation type (SAML SSO does not appear on other types).
  • The SAML login method allowed for the account (part of the platform configuration).
  • A SAML 2.0–compatible IdP (Okta, Azure AD / Entra, Google Workspace, or equivalent) where you can register ConversaLabs as a service application.

Step by step

  1. Open Settings > Security.
  2. Turn on SAML SSO using the section toggle (the feature ships as Beta).
  3. Fill in the fields with your IdP data:
    • SSO URL — the IdP sign-on URL.
    • IdP Entity ID — your provider's identifier (Entity ID / Issuer).
    • Certificate — the IdP's public X.509 certificate (paste its contents into the field).
  4. Save. The platform validates the data and then shows the service-side values (see Service provider (SP) values below).
  5. In your IdP, register ConversaLabs as an application using the ACS URL and the SP Entity ID shown on the screen, and grant access to the agents who should use it.

Login flow (how agents sign in via the IdP)

With SSO active, the login screen offers sign-in via SAML. When an agent picks that option, they are taken to the IdP, authenticate there (with the company's policies and second factor), and return to the platform already authenticated. On a new agent's first sign-in, the account is provisioned automatically from the attributes the IdP sends.

Settings & options

  • Enable toggle — turns SAML SSO on or off. Turning it off (or clearing the fields and saving) removes the SAML configuration from the account.
  • SSO URL, IdP Entity ID, and Certificate — the three required fields that describe your identity provider.

Attribute and role mapping

To provision the agent correctly, the IdP must send the attributes the platform expects:

  • email
  • first_name
  • last_name

The collapsible Attribute mapping section on the Security screen lists these attributes. Configure your IdP to send them in the SAML assertion. Associating roles/functions (which role the agent gets on sign-in) is handled by the account's access governance — combine SSO with well-defined roles to control what each person can see and do.

A user can only belong to one account

With SAML active, the platform requires each person to exist in a single account. The rule applies in both directions:

  • On invitation. Inviting an email that already belongs to another account is refused with "Users associated with another account cannot be added while SAML is enabled". The agent is not created.
  • On login. If the person belongs to this account and also to another, signing in through the IdP fails with "Authentication failed. Please check your credentials and try again."

The reason is identity: a person in several accounts would have a single login record, and the authentication method is stored on that record — it cannot be SAML in one account and a password in another at the same time.

For the same reason, when you turn SAML on the platform converts to the SAML method only the users who belong to this account alone; anyone who is also in another account keeps email-and-password sign-in. When you remove the SAML configuration, the way back is symmetric: the method returns to email, except for anyone who still has SAML active on another account. An agent created while SAML is on starts on the SAML method already.

Mapping groups to roles (role_mappings)

Beyond the three identity attributes, the configuration accepts a map of IdP group → role. Groups are read from the assertion in the groups, Group, or memberOf attributes — the first one present. The first group with a defined mapping wins, and it can point to:

  • a default role (administrator or agent); or
  • a custom role — but that branch only applies if the Custom Roles feature is enabled on the account (see Roles & Access and governance).

With no map, or no matching group, the agent enters as an Agent.

The map has no field of its own on the Security screen — it is written through the API, in the role_mappings field of the SAML settings:

{ "Administrators": { "role": "administrator" }, "Support": { "custom_role_id": 7 } }

Careful: the Security screen form sends an empty role_mappings every time someone saves. If you set the map through the API and someone later saves the configuration from the screen, the map is wiped — reapply it through the API.

Service provider (SP) values

After you save, the platform shows the service provider (SP) values that you give to your IdP:

  • ACS URL — the address the IdP posts the SAML response to, shaped as https://<platform address>/omniauth/saml/callback?account_id=<account id>. It is always shown.
  • SP Entity ID — the identifier for ConversaLabs as an application in your IdP.
  • Fingerprint — the certificate's SHA-1 fingerprint, useful for verification.

Two availability switches

The form only appears when both are cleared, and each has its own message:

  • The saml feature on the account — without it, the API answers 403 with "SAML feature not enabled for this account".
  • SAML SSO on the installation (ENABLE_SAML_SSO_LOGIN, on by default) — when off, the API answers 403 with "SAML SSO is not enabled for this installation". That switch belongs to the installation operator, not to the account.

The installation check runs first: with both off, the message you see is the installation one.

Use cases

  • Centralize access: the company controls sign-ins and offboarding through the corporate directory.
  • Strengthen security: enforce the IdP's own password policies and second factor (MFA).
  • Fast onboarding/offboarding: grant or revoke an agent's access directly in the IdP, without touching accounts one by one on the platform.

Tips, limits & best practices

  • Keep the IdP certificate up to date — certificates expire and break sign-in when they lapse.
  • Combine SSO with well-defined roles (RBAC) and with audit logs for full governance.
  • Test with one agent before requiring SAML for the whole team.

Availability and paywall

  • SAML SSO is premium: if it isn't in your plan, the Security area shows an upgrade screen (on Cloud, with a path to billing) instead of the form.
  • Available only on Cloud and Enterprise installations, and only when the SAML login method is allowed for the account.

Troubleshooting

  • Sign-in fails or loops: check the SSO URL, IdP Entity ID, and Certificate — a value that differs between the platform and the IdP prevents authentication.

  • Missing role attribute / agent without permission: confirm the IdP sends email, first_name, and last_name, and review the role assigned in access governance.

  • Expired certificate: generate a new certificate in the IdP and update the Certificate field.

  • User not provisioned: the account is created on first sign-in only if the expected attributes arrive — confirm the attribute mapping in the IdP.

  • I don't see the SAML configuration: the premium feature may not be enabled, or the installation isn't Cloud/Enterprise, or the SAML login method isn't allowed for the account.

  • I can't invite someone who already uses the platform in another account: that is SAML's single-account rule. The person must leave the other account before being invited, or you hold the invitation until SAML is turned off.

  • The agent can't reset their password: expected. A login account on the SAML method gets "This account uses SAML authentication. Password reset is not available. Please contact your administrator." The password is managed in the IdP from then on.

  • Email-and-password sign-in is refused: also expected. The response is "This account uses SAML authentication. Please sign in through your organization's SAML provider."

  • The certificate is refused on save: the field requires a valid X.509 certificate in PEM format. Paste the full contents, including the begin and end lines.

  • I turned SAML on and part of the team still signs in with a password: those are the people who also belong to another account — they are left out of the conversion on purpose.

See also