## 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: ```json { "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:///omniauth/saml/callback?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 - [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)