Skip to main content

Farfalla Integrations: Customizable Authentication

Introduction​

We simplify user authentication workflows by embedding customizable login forms that connect a tenant's platform to our authentication services. Users verify their credentials on an external server and seamlessly return to the store with a valid session.

After successful verification, we create a unique user identifier (UUID) and issue a JSON Web Token (JWT) for web sessions or an Access Token for mobile sessions. All forms are responsive, guaranteeing a consistent experience on desktop and mobile devices.

Integration Process​

Each integration follows a common pattern:

  • Tenant binding – Every integration belongs to a single tenant in our platform.
  • JWT-based authentication – We use JWT to exchange secure credentials with our backend.
  • Unique identification – The external platform provides an external_id that becomes the user's primary key in our ecosystem.
  • User creation or association – We create a new user or link an existing account based on the provided external_id.
  • Credential validation – The external platform validates the user; we only issue tokens once the external server confirms authentication.
  • Iframe communication – The entire integration runs inside an iframe. The page hosting the iframe receives updates via postMessage and can hide or replace the default login widget once authentication succeeds.

Definition and Services​

To add a new integration you must configure two building blocks:

  1. View layer – A user-facing form that collects credentials. We can ship this form or embed a third-party form provided by the tenant.
  2. Services – Backend classes that validate credentials against the external system and sign users into our platform.

Livewire Foundation​

All in-house forms rely on Livewire, which provides a reactive, component-based experience without page reloads. If we develop the validation form, we build it as a Livewire component.

Technical Procedure​

  1. Route definition – {$url_farfalla-integrations}/integrations/{$tenant_id}/embeddable-login-ui.
  2. Livewire component – Located under App\Http\Livewire\CustomIntegrations.
  3. Iframe events – Components broadcast the following postMessage events:
    • loginInit
    • loginSuccess
    • loginError
    • externalLink
  4. UI assets – Blade views and JavaScript manage the form state and event handling.
  5. Generic service – CustomIntegrations authenticates the user and issues the JWT based on the platform (web or app).
  6. Response handling – The component returns structured data via postMessage so the host page can update the UI.
  7. Environment configuration – Each tenant stores its secrets and endpoints in platform.php.

Route Configuration (web.php)​

A route group with the integrations prefix exposes:

  • /embeddable-login-ui
  • /embeddable-secondary-user-password-message

Livewire Integration Classes​

Specialised classes extend CustomIntegrations to manage:

  • External user validation
  • Token generation
  • Session management

Blade Views & JavaScript​

Blade templates render the form, while companion scripts send and receive postMessage events to coordinate authentication with the host page.

Store Configuration​

In platform.php, define:

  • External API keys
  • Final store domain ({store_final_domain})
  • Any tenant-specific secrets required by the integration

Conclusion​

These guidelines describe how to implement customizable login flows with Farfalla Integrations. Follow the steps above to deliver secure, frictionless authentication that feels native to every partner platform.

X

Graph View