Simple Authentication

These methods let you authenticate users from your platform without setting up a full Identity Provider. Choose Signed URLs for the simplest integration, or Magic Links for additional security with single-use tokens.

---

Signed URLs

Signed URLs are the fastest way to integrate. You construct a URL with a cryptographic signature that proves the request came from you.

How It Works

graph LR
    A[Partner Backend] -->|Creates Signed Link| B(User's Browser)
    B -->|Clicks Link| C[Francoflex App]
    C -->|Verifies Signature| D[User Logged In]

URL Structure

https://francoflex.com/auth/partner?email=USER_EMAIL&orgId=YOUR_ORG_ID&expires=UNIX_TIMESTAMP&signature=HMAC_SIGNATURE

Parameter	Description
email	The email address of the user to log in.
orgId	Your unique Francoflex Organization ID.
expires	A Unix timestamp (in seconds) when this link becomes invalid.
signature	A hex-encoded HMAC-SHA256 signature.
redirectUrl	(Optional) Where the user should land after login.

Generating the Signature

The signature is an HMAC-SHA256 hash of email|orgId|expires using your Partner Secret.

Node.js Example

const crypto = require('crypto');

function generateSignedUrl(email, orgId, secret, redirectUrl = '') {
  const expires = Math.floor(Date.now() / 1000) + 3600; // Valid for 1 hour
  const payload = `${email}|${orgId}|${expires}`;

  const signature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  const baseUrl = 'https://francoflex.com/auth/partner';
  const params = new URLSearchParams({
    email, orgId, expires, signature, redirectUrl
  });

  return `${baseUrl}?${params.toString()}`;
}

Python Example

import hmac
import hashlib
import time
from urllib.parse import urlencode

def generate_signed_url(email, org_id, secret, redirect_url=''):
    expires = int(time.time()) + 3600
    payload = f"{email}|{org_id}|{expires}"

    signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    params = urlencode({
        'email': email, 'orgId': org_id,
        'expires': expires, 'signature': signature,
        'redirectUrl': redirect_url
    })

    return f"https://francoflex.com/auth/partner?{params}"

Shell Example

EMAIL="user@example.com"
ORG_ID="your_org_id"
SECRET="your_partner_secret"
EXPIRES=$(($(date +%s) + 3600))

PAYLOAD="$EMAIL|$ORG_ID|$EXPIRES"
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

echo "https://francoflex.com/auth/partner?email=$EMAIL&orgId=$ORG_ID&expires=$EXPIRES&signature=$SIGNATURE"

Security

Why can't users tamper with the URL?

The signature acts as a digital seal. If anyone changes the email, orgId, or expires value, the signature won't match when Francoflex verifies it. Only you and Francoflex know the secret key.

---

Magic Links

Magic Links provide an extra layer of security with single-use, server-generated tokens.

How It Works

sequenceDiagram
    participant U as User's Browser
    participant P as Partner Backend
    participant F as Francoflex API

    Note over U, P: User is logged into Partner App
    U->>P: Clicks "Go to Francoflex"
    P->>F: POST /api/auth/sso/generate-share-token
    F-->>P: Returns loginUrl (single-use token)
    P-->>U: 302 Redirect to loginUrl
    U->>F: Redeems token
    F-->>U: Set Session Cookie & Redirect

Implementation

1. Generate the Token

Endpoint: POST /api/auth/sso/generate-share-token

Headers:

Authorization: Bearer <YOUR_PARTNER_API_KEY>
Content-Type: application/json

Body:

{
  "userId": "user@example.com",
  "targetOrganization": "your_org_id",
  "redirectUrl": "/classroom/lesson-1"
}

2. Receive the Login URL

{
  "success": true,
  "loginUrl": "https://francoflex.com/api/auth/sso/redeem-share-token?token=a1b2c3..."
}

3. Redirect the User

Redirect your user to the loginUrl. Francoflex will verify the token, establish a session, and redirect to the specified destination.

Security Notes

• Server-to-Server: The API key must never be exposed in frontend code.
• Single Use: Tokens are consumed immediately and cannot be reused.
• Short Lived: Tokens expire in 5 minutes.

---

Best Practices

1. Keep secrets safe: Never expose your Partner Secret or API Key in client-side code.
2. Use short expirations: 5-10 minutes for signed URLs minimizes risk.
3. Always use HTTPS: Never generate links with http://.
4. Validate on your end first: Ensure the user is authenticated in your system before generating links.

---

Code Samples

Download complete, ready-to-use code samples:

• Signed URLs (JavaScript) - Node.js and browser implementations with Express.js middleware example
• SSO Integration (JavaScript) - Token exchange and magic links implementation