Conversa Labs 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

Conversa Labs

Last updated on Jul 16, 2026

Overview

Single sign-on (SSO) with SAML lets agents sign in to Conversa Labs 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 Conversa Labs 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 Conversa Labs as an application using the SP Entity ID shown, 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.

Service provider (SP) values

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

  • SP Entity ID — the identifier for Conversa Labs as an application in your IdP.
  • Fingerprint — the certificate fingerprint, useful for verification.

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.

See also