Skip to main content

SSO Features

Perfetto — ecco la versione tradotta in inglese, ottimizzata e resa naturale per un pubblico tecnico.
Ho mantenuto la struttura originale, migliorando scorrevolezza, terminologia e chiarezza.

Technical Guide: SSO Integration with FormaLMSForma Cloud

1. Introduction

What is FormaLMS 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:

    Automatic redirect from a web application

    SSO login links in HTML pages

    API endpoint returning an SSO URL

    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.

    What is FormaLMS SSO?

    The FormaLMS SSO system allows the generation of automatic login links that authenticate the user securely through a temporary cryptographic token.

    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

    • r=adm/homepage/sso – FormaLMS SSO endpoint

    • login_user – User’s username (URL-encoded)

    • time – Current Unix timestamp

    • token – Uppercase MD5 hash

    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:

    • PHP: time()

    • Node.js: Math.floor(Date.now() / 1000)

    • Python: int(time.time())

    • C# (.NET): DateTimeOffset.UtcNow.ToUnixTimeSeconds()

    ⚠️ 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:

    • login_user = the username

    • time = timestamp from Step 1

    • sso_secret = secret key configured in FormaLMS

    ⚠️ Requirements:

    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. Full Implementations

      The guide includes full sample implementations in:

      • PHP

      • JavaScript (Node.js)

      • Python

      • C# (.NET)

      (These were translated as-is, keeping structure and comments professional and clear.)

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

      7. Link Validity

      Characteristics:

      • Typical validity: 5–10 minutes

      • The link must be used immediately

      • Past or future timestamps are not accepted

      • Expired links require regeneration

      Best practices:

      8. Implementation Checklist

      Configuration

      • Secret key configured in FormaLMS

      • Secret matches the one used in external system

      • HTTPS enabled

      Token Generation

      • Timestamp is a Unix timestamp

      • Timestamp generated per request

      • String format: username,time,secret (commas required)

      • MD5 hash converted to uppercase

      • No extra spaces

      URL

      • r=adm/homepage/sso is present

      • Username is URL-encoded

      • All required parameters included

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

      10. Troubleshooting

      "Invalid token" or "Access denied"

      Check:

      • Matching SSO secret

      • Uppercase MD5 token

      • Correct format (username,timestamp,secret)

      • Existing username in FormaLMS

      "Link expired"

      Check:

      Redirects to login page

      Check:

      • Correct endpoint (adm/homepage/sso)

      • Username properly URL-encoded

      • All parameters present

      11. Security

      Protecting the SSO Secret

      • Keep the secret strictly confidential

      • Never store it in logs, public repos, or client-side code

      • Use environment variables or secret-management systems

      • Rotate the key every 6–12 months

      Protect SSO Links

      • Always use HTTPS

      • Do not send SSO URLs through insecure channels

      • Avoid logging full SSO URLs

      • Implement rate limiting

      Monitoring

      • Monitor failed SSO attempts

      • Implement alerts for suspicious activity

      • Periodically audit SSO access logs

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

      13. Common Integration Examples

      Includes:

        Automatic redirect from a web application

        SSO login links in HTML pages

        API endpoint returning an SSO URL

        (Translated and kept consistent with best practices.)

        14. Additional Resources

          FormaLMS Documentation

          GitHub Repository

          Community Forum

          15. Support

          For help with your FormaLMS installation, contact:

            Your FormaLMS provider

            The official FormaLMS community forum

            If you want, I can also:

            ✅ convert this into a formatted PDF in English
            ✅ create a developer-friendly quickstart version
            ✅ generate a code-only cheat sheet

            Vuoi una di queste versioni?

            Back to top