/
SAML SSO with Microsoft Azure

SAML SSO with Microsoft Azure

On this page

Overview

SAML Single Sign-On (SSO) with Microsoft Azure Active Directory (Azure AD) enables users to securely access XCALLY (or any integrated service) using their Microsoft credentials, eliminating the need for separate XCALLY usernames and passwords.
This integration allows centralized access management through Azure AD instead of maintaining separate XCALLY login credentials.

Requirements

Before configuring SAML SSO on XCALLY, ensure you have:

  • An Azure Account with Cloud Application Administrator privileges

  • Each Azure user must have the same email address as the one configured in XCALLY (under User Properties → Email)

  • SSO login is available only for WebRTC Agents (not for Phonebar Agents)

 

Configuration

To activate SAML-based login in XCALLY, follow these steps:

  1. Configure Azure AD as the SAML Identity Provider (IdP)

  2. Configure XCALLY Server with SAML settings

  3. Enable SAML login for Administrators, Users and Agents

From version 3.51.0 onwards, you can enable multi-login using the same Azure account. → Discover how

 

 

Step1: Configure Azure AD

A SAML Identity Provider (IdP) issues authentication assertions to XCALLY using the Security Assertion Markup Language (SAML) protocol.
These assertions securely identify the user and define their access permissions.

Azure AD account is an identity provider option for your self-service sign-up user flows

  • Login to Azure https://portal.azure.com/

  • On Azure services section, select Microsoft Entra ID

  • Click on +Add → Enterprise Application

  • Click on Create your own application

    • Enter the application name

    • Select Integrate any other application you don’t find in the gallery (Non-gallery)

    • Click Create

  • Enter the App Overview

 

Properties

Here you have App’s properties.

Getting Started

  • Assign users and groups → Follow the Azure procedure

Ensure each user’s email address in Azure matches the one configured in XCALLY.

  • Important: Azure emails are case-sensitive (so pay attention to the use of upper/lower case letters).

  • Set up single sign on → Follow the Azure procedure

  • Select SAML

image-20250109-095157.png

 

  • Edit Basic SAML Configuration

    • Add Identifier: Choose an Entity ID (unique name in the tenant) and copy the Identifier

    • Reply URL: https://YOUR-IP-ADDRESS/api/auth/saml/callback

    • Logout URL (optional): to enable SLO (Single Logout, so when you logout from Motion, automatically you are logged out from other applications connected to that app), use
      https://YOUR-IP-ADDRESS/api/auth/saml/logout/callback

  • Edit Attributes & Claims

  • Add new claim with:

    • Name identifier format → email

    • Source attribute → user.mail

image-20250109-095347.png

 

SAML Certificate

  • Use the Active certificate

  • Download the Certificate (Base64) file

Open it with a text editor (i.e. Notepad++) and copy the Certificate text

image-20250109-095449.png

Set up TEST APP

  • Copy: Login URL

  • Copy: Logout URL

 

Test SSO with TEST APP

  • Click on Test

Step2: Configure XCALLY Server

Follow these steps to configure the XCALLY server:

  1. Connect via SSH to your XCALLY server

  2. Login as motion user

  3. Set SAML strings for activating the connection between XCALLY and the IDP in /var/opt/motion2/.env :

DOMAIN -> Your Motion Domain (XCALLY URL) XC_SAML_ENTRYPOINT -> Login URL XC_SAML_CERT -> Certificate downloaded from Azure AD (paste the certificate text into a single line) XC_SAML_ISSUER -> Identifier XC_SAML_LOGOUT_URL (optional) -> SLO URL

 

  1. At the end, stop the application and run initialize command

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.

Troubleshooting

Invalid certificate error

Check that the .env variable XC_SAML_CERT does not contain new line characters or quotes. 

Example:

XC_SAML_CERT=MIICXhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5XhpFSWj4psAvxJEkqVG2wDRTdSYWaut5

Check the domain used does not include wildcards. Example "*.xcally.com" is not supported. "test1234.xcally.com" is supported.