Embedded UI Authentication Reference

The Embedded UI supports multiple authentication methods. The host page is responsible for initiating authentication before or after mounting a module. This reference covers supported auth methods, the authentication flow, and the in-embed login behavior. To enable out-of-the-box authentication, pass the autoLogin: true flag when calling mountModule().

Supported Authentication Methods

The diagram below shows the decision tree the runtime uses to determine which authentication path to follow. Starting from a module request, the runtime checks whether the end-user is already authenticated and then routes to the appropriate method based on how the host page is configured.

graph TD
    A["Module Request"] --> B{"Authenticated?"}
    B -->|"Yes"| C["Mount directly"]
    B -->|"No"| D{"Auth Method"}
    D -->|"Anonymous"| E["POST /auth/customAuth"]
    D -->|"SAML"| F["Open iframe to SAML IdP"]
    D -->|"OIDC"| G["Open iframe to OIDC OP"]
    D -->|"Login Form"| H["Render login in embed"]
    D -->|"Refer String"| I["POST /auth/refer"]
    E --> C
    F --> J["framedAuthComplete via postMessage"]
    G --> J
    H --> K["Login success via custom event"]
    I --> C
    J --> L["runtime.reloadModule()"]
    K --> L
    L --> C

Authentication Methods

The table below lists every supported authentication method along with the runtime API call and a plain-language description of what each method does.

In-Embed Login Flow

This flow applies when an end-user is not yet authenticated and the embedded module contains a login form. Instead of redirecting the end-user to a separate login page, the login form renders inside the embedded module on the host page.

1. The login form renders inside the embedded module.
2. The end-user submits credentials, triggering Angular's LoginController.
3. On success, an unqork-embed-auth-complete CustomEvent is dispatched on window.
4. The host page's onAuthComplete callback fires.
5. The callback calls runtime.reloadModule(moduleId).
6. The module re-renders with the authenticated user context.

CORS Configuration

Cross-Origin Resource Sharing (CORS) controls which external domains can make requests to the Unqork server. Because an embedded module on your host page sends API calls to the Unqork environment, you must explicitly allow your host domain. Without this configuration, the browser blocks those requests with Access-Control-Allow-Origin errors and the module fails to load.

To configure CORS, go to Administration > Environment Settings > Environment > Environment Administration and add your host domain to the Allowed Origins List. Separate multiple domains with commas.

When the host page and the Unqork server are on different domains, browser cookie policies can also interfere. Session cookies must be marked SameSite=None; Secure to work across origins. If cookies are missing these attributes, authenticated sessions may fail in modern browsers, especially in private or incognito mode.