Skip to main content

SSO Features

SSO Integration with Forma Cloud

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

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:
- 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)


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

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

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

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

Back to top