SSO (версия для системного администратора)/en

Description of the situation

Users don't want to increase the number of accounts. They want to use their corporate email as an account for all platforms. In this case, the SSO technology is needed.

All about SSO:

SSO (Single Sign-On) — is an authentication system that allows a user to log into multiple applications or services using a single set of credentials (usually a login and password). It simplifies the login process, reduces the number of passwords a user needs to remember, and enhances security by reducing risks associated with data breaches.

How SSO Works

SSO establishes a connection between an application and an external service provider, sometimes referred to as a user identifier (IdP). This linking is done through a series of authentication, verification, and binding actions between the application and the central SSO service. These are the key elements of the SSO system.

Central SSO Service

This service is primary for applications when a user attempts to log in. When an anonymous user tries to gain access, the application directs them to the SSO service. After authentication, the service returns the user to the requested application. This typically takes place on a dedicated SSO policy server.

SSO Token

The SSO token is an electronic document containing data that identifies the user, such as a username or email. When a user requests access, the application and the SSO service exchange this token to validate the user.

SSO Mechanism

When a user accesses an application, they initiate the creation of an SSO token, which is sent to the SSO service for verification. The service determines if the authentication process has previously been completed for this user. If the procedure was successful, the service confirms access for the application.

If the user does not have an account, the SSO service redirects them to the main login page, prompting them to enter their username and password. After verifying the credentials, the service sends a positive response to the application.

Otherwise, an error notification appears, and the user is asked to try again. Multiple failed attempts may lead to temporary access suspension to the service.

SSO Protocols

SSO employs various protocols and standards to verify and authenticate users' credentials.

Main types of security protocols SSO

The primary ones are outlined below:

1. SAML - a protocol for exchanging authentication information with an SSO service. Based on XML, it ensures high security as applications do not store user credentials.
2. OAuth - an open standard allowing applications to access user data without transferring the password. It operates through API, establishing trust relationships between applications.
3. OIDC - an approach where one set of credentials provides access to various sites. The service provider performs authentication, and applications request additional data to verify the user.
4. Kerberos - an authentication system based on "tickets", protecting network participants' identities through cryptography.

The SmartPlayer development team uses the SAML protocol for configurationSAML

Setting up the Server Application

Preliminary Steps

Initially, the client's system administrator needs to set up the ADFS server on their end.

Next, it is necessary to collaborate with the SmratPlayer team and the system administrator. This is required to enable the backend functionality. Additionally, its display was added to the frontend on the authentication page..
For this purpose, there is a configuration file responsible for enabling the SSO button.
Its path is: /home/smartplayer/smartplayer/cms/cms/config.js.
In this file, it's essential to modify the showSSOButtonparameter and set its value to true
Additionally, the client's system administrator should send our team the configuration parameters:
SSO SAML certificate
SSO_SAML_LOGIN_URL
From our team's side, a metadata file is also sent.

Preparation:

Connect via ssh (or using other tools) to the remote server where the SmartPlayer server application is installed. Use the server's login and password.

Navigate to the folder where the SmartPlayer platform is installed.

The default path is: “/home/smartplayer/smartplayer/”. Open the .env file for editing.. This file is hidden. To modify it, open it with any text editor, by default: nano /home/smartplayer/smartplayer/.env

3. Configure the server application's configuration file. Select the configuration with the SAML protocol::

Sample commands for configuring SSO over SAML

Текст подписи

Parameter name	Valid values	Description
SSO_SAML_ENABLED	0 - integration is disabled. 1 - integration enabled	Disabled by default. To enable use value 1
SSO_SAML_ENTITY_ID	Any string value	Used to define a SAML client on the side of the authentication service. This value must be agreed in advance.
SSO_SAML_Login_URL	Authentication Service URL	Issued by the authentication service
SSO_SAML_CERTIFICATE_PATH	Path to the public certificate from the authentication service	The certificate is issued by the authentication service
SSO_SAML_COMPANY_ID	The number indicated in the company profile	The certificate is issued by the authentication service
LOCAL_SSL_KEY_PATH	Path to the private key of the certificate || The certificate is issued by the authentication service
LOCAL_SSL-CERT_PATH	Path to the public key of the certificate || The certificate is issued by the authentication service

Operations using the SAML protocol are conducted exclusively over https, so it's also essential to check for the existence of SSL certificates and the variables: LOCAL_SSL_KEY_PATH и LOCAL_SSL_CERT_PATH.

Example of configured SSO

4. Save changes to the configuration file.
5. Restart all Docker containers completely, due to the changes made in the .env file.

• Navigate to the folder containing the *.yml file. The default path is:
  

“/home/smartplayer/smartplayer/“

• Stop the Docker containers using: docker-compose down
• Start the Docker containers using: docker-compose up -d

6. Wait for 2 to 5 minutes for the platform to start, and then you can log into your personal account. Access is made via the personal account URL.

Operating Principle

Actions taken

From the user side	From the server side
The user enters the authentication page and clicks the login via SSO button	Smartplayer frontend sends a redirect request to the backend
The user is transferred to the authentication page of his company	The SmartPlayer backend generates a request to the client's ADFS server and redirects the user to the company's authentication page using the SAML protocol
The user fills in personal data (login and password) on the authentication page of his company	The client server collects data and parameters for the response
The user is transferred to the SmartPlayer personal account	The client server again sends a response to the SmartPlayer server using SAML. The SmartPlayer server decrypts the received data and logs in the user.
The user can use all the functionality of the SmartPlayer platform depending on his role: user or administrator. This is configured on the client side in the ADFS server	After logging in, the SmartPlayer server saves data and settings about the user in its database

It's possible to make an auto-log at the authentication stage. In this case, the user requested mandatory login at the beginning of each session.

Server request example

Rights Allocation

g_smartplayer_admins: 'adminBrand', in fact g_smartplayer_admins = 'adminBrand'= administrator rights
g_smartplayer_manager: 'userBrand', in fact g_smartplayer_manager = 'userBrand' = user rights

Identified Setup Issues:

• Situation: The claim rules are set up incorrectly.
  

An example of the difference in filling "Claim Rules"

Solution: Claim rules must necessarily be set up in the same language. In our case, on the SmartPlayer server, the claim rules were written in Russian, while the client's were in English. On our side, it was written as "Адрес электронной почты" (Email Address), and for the client, it was "E-mail". Once the customer rewrote them in Russian on their ADFS server, the problem was resolved.

• Situation: Incorrect certificate submission.
  

Solution: System administrators from the client side sent the certificate in text format, which turned out to be incorrect and inconvenient to use. After sending the certificate in file format, the issue was resolved.

Итоговый результат

В результате всех произведённых выше действий системный администратор пользователя "поднимет" систему SSO на своём сервере. Это даст возможность пользователю не создавать отдельную учётную запись. Таким образом получит боле простой, комфортный и безопасный доступ к функционалу SmartPlayer.