---
title: "Embedded UI Authentication Reference"
slug: "embedded-ui-authentication-reference"
tags: ["embedded-ui", "reference-guides"]
status: "update"
updated: 2026-10-13T18:18:43Z
published: 2026-10-13T18:18:43Z
canonical: "docs.unqork.io/embedded-ui-authentication-reference"
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unqork.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 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.
## 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.
| Method | API | Description |
| --- | --- | --- |
| Check authentication | `runtime.isAuthenticated()` | Returns `true` if the current session is already authenticated. Use this method before choosing an auth method so you do not re-authenticate an active session. |
| Anonymous | `runtime.authenticateAnonymous({ moduleId })` | Authenticates without credentials using the `/auth/customAuth` endpoint. Use this method for public-facing modules that do not require a login. |
| Refer string | `runtime.authenticateReferString(referString)` | Authenticates using a one-time refer string from the Unqork Customer API. The string is passed directly to `/auth/refer`. |
| SAML | `runtime.getSamlEntrypointUrl(idp)` | Returns the SAML redirect URL for the specified identity provider. Open this URL in an iframe or popup window to complete SAML authentication. |
| OIDC | `runtime.getOidcEntrypointUrl(op)` | Returns the OIDC redirect URL for the specified OpenID Connect provider. Open this URL in an iframe or popup to complete OIDC authentication. |
| Login form | `runtime.getLoginEntrypointUrl()` | Returns the login form URL for Unqork's built-in login. Open this URL in an iframe to render the login form inside the host page. |
| Wait for iframe auth | `runtime.waitForAuthFrameCompletion(iframe)` | Returns a promise that resolves when the authentication iframe or popup finishes its flow. Use this method after opening a SAML, OIDC, or login iframe to pause execution until authentication is complete. |
| Auth callback | `runtime.onAuthComplete(callback)` | Registers a callback that fires when in-embed login completes. Returns an unsubscribe function so you can remove the listener when it is no longer needed. |
## 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 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.
---
**Changelog**
| Date | Change |
| --- | --- |
| 2026-04-21 | Initial publication. |
| 2026-06-11 | Editorial pass: corrected "behaviour" to "behavior," split run-on intro sentence, added description paragraphs to Mermaid diagram and all H2 sections, expanded CORS section for non-expert readers, expanded Authentication Methods table descriptions, updated internal links. |
| 2026-06-15 | Added Access-Control-Allow-Origin error detail to CORS section; added Module Setup to See Also. |
The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application.
End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.
APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.
An API endpoint is the location where an API receives requests for a specific resource on its server. It's the point of contact between an API client and an API server, and is usually a uniform resource locator (URL) that provides the location of the resource.
A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.
Security Assertion Markup Language (SAML) is a protocol that allows an identity provider (IdP) to send a user's credentials to a service provider (SP) to verify their identity and grant them access to a service.
A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address.
Identity provider (IdP) provide a service that creates, manages, and verifies users' digital identities, allowing them to securely authenticate and access different applications or services.
OIDC (OpenID Connect) is an identity authentication protocol that lets two applications share user information without exposing user credentials.
Rendering is the process of loading components and displaying the final result on the front-end screen.
Rendering is the process of loading components and displaying the final result on the front-end screen.
AngularJS is a JavaScript framework added to an HTML page with a