SAML SSO
On this page |
Overview
SAML (Security Assertion Markup Language) is an open standard for exchanging authentication and authorization data between parties—specifically, between an Identity Provider (IdP) and a Service Provider (SP) such as XCALLY.
SAML enables users to log in to multiple web applications with a single set of credentials, simplifying authentication while increasing security. This eliminates the need for users to remember multiple usernames and passwords, and it reduces the risk associated with password storage.
In a SAML-based SSO workflow:
The Identity Provider (IdP) authenticates users.
The Service Provider (SP) (in this case, XCALLY) trusts the IdP and grants access based on authentication assertions.
Requirements
The SAML SSO feature requires:
SAML Identity Provider Account
For agents, SSO feature is available only for WebRTC Agents (and not for Phonebar Agents)
Configuration
Consider that there are many types of configurations with SAML
To activate the login with SAML on XCALLY, you need to:
A. Configure the Identity Provider
B. Configure XCALLY Server
C. Enable SAML login for Administrator, Users and Agents
Configure the Identity Provider
A SAML Identity Provider (IdP) issues authentication assertions during the single sign-on process. These assertions contain identity information (such as user email) that XCALLY uses to authorize access.
Choose a SAML Identity Provider (IDP): select a supported Identity Provider
Create an XCALLY Motion application within its configuration interface.
When requested, add the XCALLY certificate
From the IDP Settings, retrieve:
SAML Endpoint (HTTP): the login URL or SSO endpoint provided by the IdP
IDP Certificate: the IdP’s public signing certificate
Issuer URL: the unique issuer string identifying your IdP
Single Logout URL (HTTP), if available in IDP: used for user logout synchronization between IdP and XCALLY
When setting up SAML assertions, ensure that a custom attribute (or claim) is created to map the XCALLY user’s email address. Set email as value.
The email address used in the IdP must match the staff email address registered in XCALLY
Retrieve XCALLY Certificate
XCALLY provides a certificate used for signing and encrypting SAML assertions.
To obtain the XCALLY certificate, access the following endpoint (replace <XCALLY_DOMAIN> with your actual domain):
https://<XCALLY DOMAIN>/api/auth/saml/metadata(enter your XCALLY domain in the string)
Below, you can find an example:
Configure XCALLY Server
Follow these steps to configure SAML variables on your XCALLY server.
Use SSH to access your XCALLY server
Login with motion user
Set SAML strings to activate the connection between XCALLY and the IDP in /var/opt/motion/.env:
DOMAIN -> Your Motion Domain (XCALLY URL)
XC_SAML_ENTRYPOINT -> IDP SAML Endpoint
XC_SAML_CERT -> IDP's public signing certificate (paste the certificate text into a single line)
XC_SAML_ISSUER -> Issuer string to retrieve from the IDP
XC_SAML_LOGOUT_URL (optional) -> IDP Single Logout
Below, you can find an example:
To edit the file .env, follow the instructions recommended here, by searching XC_SAML variables
Enable SAML login for Administrator, Users and Agents
Enable login in General Settings
The Login with SAML must be enabled under Settings → General:
Users and Agents (WebRTC and External) will be able to connect to XCALLY using identity provider credentials.
The email address configured in XCALLY must match the email registered in the Identity Provider for successful authentication.
Login for XCALLY users
Once configured, users will see a Login with SAML button on the XCALLY login page.
Click the Login with SAML button.
The user is redirected to the Identity Provider’s login portal.
After authentication, the user is automatically redirected back to XCALLY and logged in.
On subsequent logins, if a valid SAML session exists, the user is logged in without re-entering credentials.