SAML SSO with Microsoft Azure

Owned by XCALLY Knowledge (Unlicensed)
Last updated: Feb 26, 2024 by Product Knowledge
5 min read

 

What it's about

SAML is an acronym used to describe the Security Assertion Markup Language (SAML). Its primary role in online security is that it enables you to access multiple web applications using one set of login credentials. It works by passing authentication information in a particular format between two parties, usually an identity provider (IDP) and a web application (in our case, XCALLY).

The technology industry created SAML to simplify the authentication process where users needed to access multiple, independent web applications across domains. Prior to SAML, single sign-on (SSO) was achievable but relied on cookies that were only viable within the same domain. It achieves this objective by centralizing user authentication with an identity provider. Web applications can then leverage SAML via the identity provider to grant access to their users. This SAML authentication approach means users do not need to remember multiple usernames and passwords. It also benefits service providers as it increases security of their own platform, primarily by avoiding the need to store (often weak and insecure) passwords and not having to address forgotten password issues. (Reference: https://www.onelogin.com/learn)

Single sign-on is an authentication method that allows users to sign in using one set of credentials to multiple independent software systems. Using SSO means a user doesn't have to sign in to every application they use. With SSO, users can access all needed applications without being required to authenticate using different credentials.

XCALLY gives the possibility to plan a single sign-on deployment when using Azure Active Directory (Azure AD).

 

How to set up

To activate the login with SAML on XCALLY, you need to: 

A. Configure Azure AD

B. Configure XCALLY Server

C. Enable SAML login for Administrator, Users and Agents

 

General Requirements

The SAML SSO feature requires:

Azure Account with privileges of Cloud Application Administrator

XCALLY Motion version 3.2.0 or higher

User configurated on Azure must have the same mail used on Motion in email field on properties user section

For agents, SSO feature is available only for WebRTC Agents (and not for Phonebar Agents)

 

Configure Azure AD

 

A SAML identity provider is a system entity that issues authentication assertions in conjunction with a single sign-on profile of the Security Assertion Markup Language (SAML).

SAML assertions are the messages that are exchanged between an identity provider (IDP) and XCALLY that confidentially identify who a user is, what pertinent information exists about them, and what they’re authorized or entitled to access.

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

 

 

  • Create your own app

 

  • Enter the App Overview

 

Properties

Here you have App’s properties.

 

 

Getting Started

  • Assign users and group → Follow the Azure procedure

Emails registered on the identity provider must be already set on XCALLY.
Emails set up in Azure 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

  • Edit SSO with SAML

 

 

 

Basic SAML Configuration

  • 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): if you want to do SLO (Single Logout, so when you logout from Motion, automatically you are logged out from other applications connected to that app) you need to insert this url https://YOUR-IP-ADDRESS/api/auth/saml/logout/callback

 

 

Attributes & Claims

  • Add a claim with:

    • Name identifier format → email

    • Source attribute → user.mail

SAML Certificate

  • Download Certificate (Base64)

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

 

 

Set up TEST APP

  • Copy: Login URL

  • Copy: Logout URL

 

Test SSO with TEST APP

  • Click on Test

 

In the SAML SSO Azure apps (on Authentication section) the checkboxes Implicit grant and hybrid flows can be safely left unchecked.

 

 

Configure XCALLY Server

 

Follow these steps to configure the XCALLY server:

  1. Use SSH to connect to your XCALLY server

  2. Login with 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

  4. 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.

 

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.

Staff emails on XCALLY must be equal to the Staff emails registered on the identity provider.
Remember that emails are case sensitive, so they must be identical to those entered on Azure account to work correctly

 

Login for XCALLY users

On the Login page, the button Login with SAML is available:

Clicking on Login with SAML, XCALLY Users will be redirected on the identity provider portal.

After entering the provider credentials on the provider portal, XCALLY Interface will be opened as usual.

If configured, from the second login on, each time Users click on Login with SAML, they will directly access to XCALLY, without entering credentials again.

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.