Integrating Forma Cloud

Integrate with other applications and automate users maintennce

I/O Task Integration

When to use IO Task Integration

IO Task Integration is designed to connect Forma LMS with external business systems through asynchronous file exchange (e.g., CSV, XML) on a shared SFTP folder.

This approach is particularly suitable when:

When real-time interaction or event-driven logic is required, API-based integrations are recommended instead.

Use Cases

Typical use cases for IO Task Integration include:

Check the official documentation for a full guide to the available connectors

Custom I/O activities may be analyzed and implemented upon request

Integration Flow

The typical IO Task integration flow works as follows:

  1. The external business system generates a data file
  2. The file is placed in a shared folder
  3. Forma LMS processes the file through the configured IO Task
  4. Data is imported or updated within the platform

File Management and Shared Folders

Shared Folder

File Upload to Forma Cloud

All files used for data exchange must be placed in a shared SFTP folder provided by Forma Cloud with the following path: html/files/common/iofiles

Your SFTP credentials are published in your client area, or you can ask our helpdesk team 

Please verify that your systems can:
- automatically generate files in the required format
- transfer them to the shared folder (e.g., via SFTP or similar services)

File Retrieval from client system

If your system cannot automatically send files to the Forma Cloud shared folder, it is possible to:

⚠️ This additional service involves extra cost.

File format

The data file must comply with the following requirements:

- The file format must be .csv (mandatory)  
- There are no strict constraints on the column separator (e.g., comma, semicolon, etc.), as long as it is consistent within the file  
- Additional columns are allowed and will be ignored if not mapped in the IO Task configuration 
- The column order is not strictly required during the initial setup  

Once the integration procedure has been configured and activated, separator type and column structure must remain consistent over time. Changes to separators, column order or structure may cause errors in data processing.

Scheduling

The I/O task cron job is usually processed nightly at 2 am

Data Specifications

Users import and update

Creating and updating users

Managing Node assignment

Suspending users

The IO Task feature will only suspend and won't remove any user

The update procedure can't reactivate suspended users: this is to avoid conflicts with manual users management

Export of users status on courses

This connector will generate a CSV file containing a list of users and their status on courses, and can be integrated with other user information from custom fields.

Enroll users to courses

Upload a CSV file containing a list of users and course codes to automatically enroll users

API Integration

Integrating with Forma Cloud APIs and Postman

Overview

Forma Cloud provides a complete set of REST APIs that allow you to perform the most common operations on users, courses, enrollments, certificates, and reporting.

Forma Cloud uses the standard APIs of Forma LMS.

Official Forma LMS API Documentation:
https://docs.google.com/document/d/1bbNL7AR_2gbescLkgBIL3Cu7BZ9tZLky9spM3bfkZjA/edit?tab=t.0

Common Use Cases

The APIs can be used to integrate the platform with other corporate systems.

HR System Synchronization

HSE Management Integration

Business Intelligence & Reporting

Corporate Portal Integration

In multi-tenant installations, it is strongly discouraged to grant API access to individual sub-clients. Doing so may expose sensitive data across different tenants, increasing the risk of privacy breaches and unauthorized access. To ensure proper data isolation and security, API usage should be restricted to controlled and centralized contexts.

Enabling the APIs in Forma Cloud

APIs can be enabled and configured directly from your platform.

Configuration Path:

Admin > System Configuration > Settings > API & SSO

image.png

Here you can:

Forma LMS official system configuration guide: https://docs2.formalms.org/books/reference-guide/page/system-configuration

Exporting the Postman Collection from Forma Factory

Once your platform's API are activated and configured, From your Client Control Panel you can:

image.png

This avoids manual configuration and speeds up testing.

What is Postman?

It is available as a desktop application and as a web application.

How to Use Postman with Forma Cloud

1. Import the Collection
2. Configure the Environment

Set the main variables:

3. Authenticate

Use the authentication endpoint to obtain an access token as described in the official documentation.

Execute API Calls

Select the desired endpoint (e.g., users, courses, enrollments) and send the request.

API response standard: the mantained format is JSON. Most API still provide also the legacy XML format, but is now deprecated and will be removed in future releases.

Security & Best Practices

Official Resources

SSO Features

SSO Integration with Forma Cloud

1. What is Forma Cloud SSO?

The FormaLMS SSO system allows the generation of automatic login links that authenticate the user securely through a temporary cryptographic token. This is a common solution for:

This guide explains how to correctly implement Single Sign-On (SSO) authentication with FormaLMS, allowing users to access the platform directly from external systems without entering their credentials.

2. How SSO Works

The SSO login process is based on three elements:

  1. login_user – The username of the user who must be authenticated

  2. time – A Unix timestamp representing when the link was generated

  3. token – An MD5 hash that validates the authenticity of the request

The token is calculated using the username, timestamp, and a shared secret key (SSO Secret).

3. SSO URL Structure

A valid SSO URL follows this structure:

https://PLATFORM/index.php?r=adm/homepage/sso&login_user=USERNAME&time=TIMESTAMP&token=TOKEN

Parameters

Example

https://forma.example.com/index.php?r=adm/homepage/sso&login_user=mario.rossi&time=1729681425&token=A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6

4. Generating the SSO Token

Step 1: Generate the Unix Timestamp

The Unix timestamp represents the number of seconds elapsed since Jan 1st, 1970 (UTC).

Examples:

Important: The timestamp must be generated dynamically at the moment of the SSO request.

Step 2: Calculate the Token

The token is an uppercase MD5 hash of a specific concatenated string:

token = MD5_UPPERCASE(login_user + "," + time + "," + sso_secret)

Where:

Example (PHP)

$loginUser = "mario.rossi";
$time = 1729681425;
$ssoSecret = "mia_chiave_segreta_123";
// Build the string
$stringToHash = $loginUser . ',' . $time . ',' . $ssoSecret;
// Result: "mario.rossi,1729681425,mia_chiave_segreta_123"
// Calculate MD5 and convert to UPPERCASE
$token = strtoupper(md5($stringToHash));
// result: "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6"

 Requirements:
- Commas must match exactly
- No extra spaces
- Final hash must be uppercase

Step 3: Build the Final URL

Once the timestamp and token are ready, construct the final SSO URL:

Example (PHP):

$platformUrl = "https://forma.example.com";

$ssoUrl = $platformUrl . "/index.php"
    . "?r=adm/homepage/sso"
    . "&login_user=" . urlencode($loginUser)
    . "&time=" . $time
    . "&token=" . $token;

5. Configuration in FormaLMS

Before using SSO, configure the secret key inside FormaLMS:

  1. Log in as admin

  2. Navigate to Administration → Configuration → SSO

  3. Enter the SSO Secret Key (must match the one used in your code)

  4. Save settings

Characteristics:

Best practices:

7. Implementation Checklist

Configuration

Token Generation

URL

8. Testing and Verification

Manual Token Test

Verify the token by hashing a test string in the exact format:

username,timestamp,secret

Use any MD5 generator to confirm the result.

Access Test

  1. Generate a valid SSO URL

  2. Open it in a browser within 5 minutes

  3. Confirm the user is logged in

  4. Confirm redirection to the homepage

9. Troubleshooting

"Invalid token" or "Access denied"

Check:

Check:

Redirects to login page

Check:

10. Security

Protecting the SSO Secret

Monitoring

11. SSO Variants

FormaLMS supports two SSO endpoints:

1. Standard SSO (username-based)

?r=adm/homepage/sso&login_user=USERNAME&time=TIME&token=TOKEN

Token: MD5(username,time,secret)

2. Custom SSO (email-based)

?r=adm/ssologin/show&email=EMAIL&time=TIME&token=TOKEN

Token: MD5(email,time,secret)

Check which one your installation uses.

12. Full Implementation examples

PHP

<?php

/**
 * Generates a valid SSO URL for FormaLMS
 *
 * @param string $loginUser   The username of the user
 * @param string $ssoSecret   Secret key configured in FormaLMS
 * @param string $platformUrl Base platform URL
 * @return array              Generated SSO data
 */
function generateSSOUrl($loginUser, $ssoSecret, $platformUrl)
{
    // STEP 1: Generate current Unix timestamp
    $time = time();

    // STEP 2: Calculate the token
    $stringToHash = $loginUser . ',' . $time . ',' . $ssoSecret;
    $token = strtoupper(md5($stringToHash));

    // STEP 3: Build the URL
    $url = rtrim($platformUrl, '/') . "/index.php"
         . "?r=adm/homepage/sso"
         . "&login_user=" . urlencode($loginUser)
         . "&time=" . $time
         . "&token=" . $token;

    return [
        'url' => $url,
        'login_user' => $loginUser,
        'time' => $time,
        'token' => $token,
        'valid_until' => date('Y-m-d H:i:s', $time + 300)
    ];
}

// Example usage
$ssoData = generateSSOUrl(
    'mario.rossi',                    // Username
    'my_secret_key_123',              // SSO Secret
    'https://forma.example.com'       // Platform URL
);

echo "SSO URL: " . $ssoData['url'] . "\n";
echo "Valid until: " . $ssoData['valid_until'] . "\n";
?>

JavaScript (Node.js)

const crypto = require('crypto');

/**
 * Generates a valid SSO URL for FormaLMS
 */
function generateSSOUrl(loginUser, ssoSecret, platformUrl) {

    // STEP 1: Unix timestamp
    const time = Math.floor(Date.now() / 1000);

    // STEP 2: Calculate token
    const stringToHash = `${loginUser},${time},${ssoSecret}`;
    const token = crypto
        .createHash('md5')
        .update(stringToHash)
        .digest('hex')
        .toUpperCase();

    // STEP 3: Build URL
    const baseUrl = platformUrl.replace(/\/$/, '');
    const url = `${baseUrl}/index.php?r=adm/homepage/sso`
              + `&login_user=${encodeURIComponent(loginUser)}`
              + `&time=${time}`
              + `&token=${token}`;

    return {
        url: url,
        login_user: loginUser,
        time: time,
        token: token
    };
}

// Example usage
const ssoData = generateSSOUrl(
    'mario.rossi',
    'my_secret_key_123',
    'https://forma.example.com'
);

console.log('SSO URL:', ssoData.url);
console.log('Token:', ssoData.token);

Python

import hashlib
import time
from urllib.parse import quote

def generate_sso_url(login_user, sso_secret, platform_url):
    """
    Generates a valid SSO URL for FormaLMS
    """

    # STEP 1: Unix timestamp
    current_time = int(time.time())

    # STEP 2: Calculate token
    string_to_hash = f"{login_user},{current_time},{sso_secret}"
    token = hashlib.md5(string_to_hash.encode()).hexdigest().upper()

    # STEP 3: Build URL
    base_url = platform_url.rstrip('/')
    url = (f"{base_url}/index.php?r=adm/homepage/sso"
           f"&login_user={quote(login_user)}"
           f"&time={current_time}"
           f"&token={token}")

    return {
        'url': url,
        'login_user': login_user,
        'time': current_time,
        'token': token
    }

# Example usage
sso_data = generate_sso_url(
    'mario.rossi',
    'my_secret_key_123',
    'https://forma.example.com'
)

print('SSO URL:', sso_data['url'])
print('Token:', sso_data['token'])

C# (.NET)

using System;
using System.Security.Cryptography;
using System.Text;
using System.Web;

public class FormaSSO
{
    public static string GenerateSSOUrl(string loginUser, string ssoSecret, string platformUrl)
    {
        // STEP 1: Unix timestamp
        long time = DateTimeOffset.UtcNow.ToUnixTimeSeconds();

        // STEP 2: Calculate token
        string stringToHash = $"{loginUser},{time},{ssoSecret}";
        using (MD5 md5 = MD5.Create())
        {
            byte[] hashBytes = md5.ComputeHash(Encoding.UTF8.GetBytes(stringToHash));
            string token = BitConverter.ToString(hashBytes).Replace("-", "").ToUpper();

            // STEP 3: Build URL
            string baseUrl = platformUrl.TrimEnd('/');
            string url = $"{baseUrl}/index.php?r=adm/homepage/sso"
                        + $"&login_user={HttpUtility.UrlEncode(loginUser)}"
                        + $"&time={time}"
                        + $"&token={token}";

            return url;
        }
    }
}

// Example usage
string ssoUrl = FormaSSO.GenerateSSOUrl(
    "mario.rossi",
    "my_secret_key_123",
    "https://forma.example.com"
);

Console.WriteLine($"SSO URL: {ssoUrl}");

SAML/OIDC Integration

Integration Between Azure Active Directory and Forma Cloud via SAML or OIDC

1. Introduction

The integration between Forma LMS and MS Entra (Formerly Azure Active Directory - AAD) allows users to authenticate into the learning platform using their corporate Office 365 credentials.
Access is managed through standard federation protocols — SAML 2.0 or OpenID Connect (OIDC) — ensuring security, centralized user management, and Single Sign-On (SSO).

2. Prerequisites

3. Choosing the Authentication Protocol

Protocol Description Typical Supported IdPs
SAML 2.0 XML-based standard protocol widely used for enterprise Single Sign-On. Azure Active Directory, Microsoft ADFS, Google Identity, Auth0, SimpleSAMLphp
OIDC (OpenID Connect) OAuth 2.0–based protocol, more lightweight and modern, ideal for cloud integrations. Azure Active Directory, Salesforce, Auth0

Note: For Microsoft 365 environments, either SAML or OIDC may be used depending on corporate security policies. Both protocols are supported by the Forma LMS authentication plugin.

4. Configuration via SAML

4.1 Creating the Application in Azure AD

  1. Log in to the Azure portal with an administrator account.

  2. Navigate to Azure Active Directory → Enterprise Applications → New Application.

  3. Select Create your own application → Non-gallery application.

  4. Enter a name, e.g., “Forma LMS SAML.”

  5. Once created, go to the Single Sign-On section and select SAML as the authentication method.

4.2 SAML Configuration

Within the SAML configuration page, set the following parameters:

User Attributes Mapping

In the Azure AD application, configure the following attribute mappings:

SAML Attribute Name Azure AD Source Attribute Description
username user.userprincipalname Unique username
givenName user.givenname First name
surname user.surname Last name
email user.mail Email address

Additional attributes can be sent, but only those listed above are natively managed by the Forma LMS plugin.

4.3 User Management

4.4 Assigning Users or Groups

In the Azure portal, within the SAML application:

5. Configuration via OIDC

5.1 Creating the OIDC Application in Azure AD

  1. Log in to the Azure portal.

  2. Go to Entra/Azure Active Directory → App Registrations → New Registration.

  3. Configure:

    • Name: “Forma LMS OIDC”

    • Supported account types: “Accounts in this organizational directory only.”

    • Redirect URI: https://yourportal/formalms/oidc/callback.php.

  4. After creation, note the following values:

    • Client ID

    • Tenant ID

    • Client Secret (generated under Certificates & Secrets)

5.2 Configuration in Forma LMS

In the Forma LMS OIDC plugin, enter the following parameters:

Parameter Example Value
Client ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Client Secret ****************
Issuer URL https://login.microsoftonline.com/<tenant-id>/v2.0
Redirect URL https://yourportal/formalms/oidc/callback.php
Scopes openid profile email

As with SAML, automatic account creation and user data synchronization can be enabled at login.

6. Compatibility

Protocol Identity Providers Tested with Forma LMS
SAML Microsoft Azure AD, Microsoft ADFS, Google Identity, Auth0, SimpleSAMLphp
OIDC Microsoft Azure AD, Salesforce, Auth0

7. Useful Resources