## 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

- [Custom roles and governance (RBAC)](/hc/ajuda/articles/administration-custom-roles-governanca-rbac-en)
- [Audit logs](/hc/ajuda/articles/administration-auditoria-en)
- [Login, profile and two-factor authentication (2FA)](/hc/ajuda/articles/getting-started-login-perfil-2fa-en)
- [Administration overview](/hc/ajuda/articles/administration-overview-en)