From 5d6ebb0e88079b7d25e220f32ba1e62c2e0bac90 Mon Sep 17 00:00:00 2001 From: Emanuel Date: Thu, 11 Sep 2025 16:22:56 +0100 Subject: [PATCH 1/4] Refine plugin system documentation for clarity and consistency --- docs/quix-cloud/managed-services/plugin.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/quix-cloud/managed-services/plugin.md b/docs/quix-cloud/managed-services/plugin.md index 8d33f349..31c890bd 100644 --- a/docs/quix-cloud/managed-services/plugin.md +++ b/docs/quix-cloud/managed-services/plugin.md @@ -1,6 +1,10 @@ # Plugin System -The plugin system enables services to expose an embedded UI inside Deployment Details (rendered as an iframe), and optionally add a shortcut in the environment’s left sidebar. Managed services populate these fields automatically via the Managed Framework; Non‑managed services can be configured in the yaml. +The plugin system enables services to expose an embedded UI inside Deployment Details (rendered as an iframe), and optionally add a shortcut in the environment’s left sidebar. + +Managed services could (or could not) populate these plugin properties automatically via the Managed Framework. You can always override them explicitly via YAML if needed. + +Non‑managed services can also define these properties in YAML, making any deployment of your pipeline behave like a plugin without being a managed service. ## What it does @@ -12,6 +16,8 @@ The plugin system enables services to expose an embedded UI inside Deployment De ![Sidebar example](images/plugin-sidebar.png){height=50%} +- Provide basic authentication integration with Quix Cloud so publicly exposed services don’t require a separate login + ## YAML In your deployment YAML, you can enable the embedded UI and, optionally, a sidebar item: @@ -31,11 +37,15 @@ Notes - plugin.embeddedView: boolean. true → FE renders embedded UI. - plugin.sidebarItem: optional object configuring the Environment’s left sidebar item. -## Public Url +## Embedded view URL + +When the plugin feature is enabled, the deployment exposes a public URL dedicated to the embedded UI. The Portal uses this URL to load the embedded view inside the iframe when `embeddedView` is enabled. + +Population rules: -- Managed service → derived from Managed Services internal conventions. -- Non‑managed service → uses the deployment’s publicUrl. +- Managed service → Derived from Managed Services conventions. +- Non‑managed service → The `publicAccess` configuration needs to be enabled. -## Authentication +## Authentication and authorization -The embedded view inherits authentication and authorization from the main platform. No separate login is required, and the same user/environment permissions apply to the emmbedded view. +The embedded view inherits authentication and authorization from the Quix platform. No separate login is required, and the same user/environment permissions apply to the embedded view. From 64274a899a0d3b399729df82b99064c382191097 Mon Sep 17 00:00:00 2001 From: Emanuel Date: Thu, 11 Sep 2025 16:28:21 +0100 Subject: [PATCH 2/4] Enhance authentication section in plugin documentation for clarity --- docs/quix-cloud/managed-services/plugin.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/quix-cloud/managed-services/plugin.md b/docs/quix-cloud/managed-services/plugin.md index 31c890bd..4f6adb94 100644 --- a/docs/quix-cloud/managed-services/plugin.md +++ b/docs/quix-cloud/managed-services/plugin.md @@ -48,4 +48,6 @@ Population rules: ## Authentication and authorization -The embedded view inherits authentication and authorization from the Quix platform. No separate login is required, and the same user/environment permissions apply to the embedded view. +The embedded view inherits authentication and authorization from the Quix platform: no separate login is required, and the same user/environment permissions apply. +When an embedded view loads, the Plugin system injects the Quix user token into the iframe. The UI uses this token to call the backend securely. + From 5f1bb2bcdc94f792a8faa8b20664ec5f39dff3a9 Mon Sep 17 00:00:00 2001 From: Emanuel Date: Thu, 11 Sep 2025 17:08:43 +0100 Subject: [PATCH 3/4] Refine plugin documentation for clarity and completeness, including YAML configuration and token handling details. --- docs/quix-cloud/managed-services/plugin.md | 55 ++++++++++++++++++++-- 1 file changed, 50 insertions(+), 5 deletions(-) diff --git a/docs/quix-cloud/managed-services/plugin.md b/docs/quix-cloud/managed-services/plugin.md index 4f6adb94..077c0c9e 100644 --- a/docs/quix-cloud/managed-services/plugin.md +++ b/docs/quix-cloud/managed-services/plugin.md @@ -2,9 +2,9 @@ The plugin system enables services to expose an embedded UI inside Deployment Details (rendered as an iframe), and optionally add a shortcut in the environment’s left sidebar. -Managed services could (or could not) populate these plugin properties automatically via the Managed Framework. You can always override them explicitly via YAML if needed. +Managed services may populate these plugin properties automatically via the Managed Framework, and you can always override them explicitly in YAML. -Non‑managed services can also define these properties in YAML, making any deployment of your pipeline behave like a plugin without being a managed service. +Non‑managed services can also define these properties in YAML, making any deployment behave like a plugin without being a managed service. ## What it does @@ -18,7 +18,7 @@ Non‑managed services can also define these properties in YAML, making any depl - Provide basic authentication integration with Quix Cloud so publicly exposed services don’t require a separate login -## YAML +## YAML configuration In your deployment YAML, you can enable the embedded UI and, optionally, a sidebar item: @@ -39,15 +39,60 @@ Notes ## Embedded view URL -When the plugin feature is enabled, the deployment exposes a public URL dedicated to the embedded UI. The Portal uses this URL to load the embedded view inside the iframe when `embeddedView` is enabled. +When the plugin feature is enabled, the deployment exposes a public URL dedicated to the embedded UI. The Portal uses this URL to load the embedded view inside the iframe when `embeddedView` is enabled. This URL is not set in YAML; it’s exposed by the API. Population rules: - Managed service → Derived from Managed Services conventions. -- Non‑managed service → The `publicAccess` configuration needs to be enabled. +- Non‑managed service → Requires `publicAccess` to be enabled; resolves from the deployment’s public URL. ## Authentication and authorization The embedded view inherits authentication and authorization from the Quix platform: no separate login is required, and the same user/environment permissions apply. When an embedded view loads, the Plugin system injects the Quix user token into the iframe. The UI uses this token to call the backend securely. +### How the token is injected in the embedded view + +On initial load of the embedded view (and on reload), the Portal provides the user token to the iframe so the UI can authenticate calls to the backend. + +### How to handle the token in the backend + +Install the Quix Portal helper package from the public feed: + +```bash +pip install -i https://pkgs.dev.azure.com/quix-analytics/53f7fe95-59fe-4307-b479-2473b96de6d1/_packaging/public/pypi/simple/ quixportal +``` + +Then, in the backend service, validate the token and enforce authorization for each request. For example: + +```python + +import os + +from quixportal.auth import Auth + +# Instantiate authentication client. By default it will read +# the portal API url from the environment variable Quix__Portal__Api +auth = Auth() + +# Obtain the authorization token, traditionally passed as a header +# Authorization: Bearer +token = ... + +# Example to obtain "Read" access to the "Workspace" resource +resource_type = "Workspace" +workspace_id = os.environ["Quix__Workspace__Id"] +permissions = "Read" + +# Authorize the token bearer to access the resource +if auth.validate_permissions( + token=token, + resourceType=resource_type, + resourceID=workspace_id, + permissions=permissions, +): + print("Bearer is authorized to access the resource") +else: + print("Bearer is not authorized to access the resource") + +``` From 985e2c2f07ac8853216d8c74a97ef4f47eb6eaaf Mon Sep 17 00:00:00 2001 From: Patrick Mira Date: Thu, 11 Sep 2025 21:13:49 +0200 Subject: [PATCH 4/4] Added code snippets from Frontend side --- docs/quix-cloud/managed-services/plugin.md | 74 ++++++++++++++++++---- 1 file changed, 63 insertions(+), 11 deletions(-) diff --git a/docs/quix-cloud/managed-services/plugin.md b/docs/quix-cloud/managed-services/plugin.md index 077c0c9e..6f58c374 100644 --- a/docs/quix-cloud/managed-services/plugin.md +++ b/docs/quix-cloud/managed-services/plugin.md @@ -4,19 +4,19 @@ The plugin system enables services to expose an embedded UI inside Deployment De Managed services may populate these plugin properties automatically via the Managed Framework, and you can always override them explicitly in YAML. -Non‑managed services can also define these properties in YAML, making any deployment behave like a plugin without being a managed service. +Non-managed services can also define these properties in YAML, making any deployment behave like a plugin without being a managed service. ## What it does -- Embed a UI in Deployment Details when enabled +* Embed a UI in Deployment Details when enabled ![Embedded View](images/dynamic-configuration-embedded-view.png){width=80%} -- Optionally show a sidebar shortcut to the embedded view +* Optionally show a sidebar shortcut to the embedded view ![Sidebar example](images/plugin-sidebar.png){height=50%} -- Provide basic authentication integration with Quix Cloud so publicly exposed services don’t require a separate login +* Provide basic authentication integration with Quix Cloud so publicly exposed services don’t require a separate login ## YAML configuration @@ -34,8 +34,8 @@ plugin: Notes -- plugin.embeddedView: boolean. true → FE renders embedded UI. -- plugin.sidebarItem: optional object configuring the Environment’s left sidebar item. +* plugin.embeddedView: boolean. true → FE renders embedded UI. +* plugin.sidebarItem: optional object configuring the Environment’s left sidebar item. ## Embedded view URL @@ -43,8 +43,8 @@ When the plugin feature is enabled, the deployment exposes a public URL dedicate Population rules: -- Managed service → Derived from Managed Services conventions. -- Non‑managed service → Requires `publicAccess` to be enabled; resolves from the deployment’s public URL. +* Managed service → Derived from Managed Services conventions. +* Non-managed service → Requires `publicAccess` to be enabled; resolves from the deployment’s public URL. ## Authentication and authorization @@ -55,6 +55,61 @@ When an embedded view loads, the Plugin system injects the Quix user token into On initial load of the embedded view (and on reload), the Portal provides the user token to the iframe so the UI can authenticate calls to the backend. +#### Frontend token exchange (postMessage) + +The token is passed via `window.postMessage` between the parent (Portal) and the embedded iframe. + +**Message types** + +* `REQUEST_AUTH_TOKEN` — sent by the iframe to ask the parent for a token +* `AUTH_TOKEN` — sent by the parent with `{ token: string }` + +**In the embedded view (iframe)** + +```ts +// Ask the parent window (Portal) for a token +window.parent.postMessage({ type: 'REQUEST_AUTH_TOKEN' }, '*'); + +// Listen for the token response from the parent +function messageHandler(event: MessageEvent) { + const { data } = event; + if (data?.type === 'AUTH_TOKEN' && data.token) { + // Your app-specific setter + setToken(data.token); + // Optionally remove the listener if you only need the token once + // window.removeEventListener('message', messageHandler); + } +} + +window.addEventListener('message', messageHandler); +``` + +**In the Portal (parent window)** + +```ts +// Listen for requests from the target iframe +function messageHandler(event: MessageEvent) { + const { origin, data } = event; + + // Ensure the origin matches the iframe URL you expect + if (origin !== targetUrl) return; + + if (data?.type === 'REQUEST_AUTH_TOKEN') { + // Reply with the token to the requesting iframe + const iframeWindow = deploymentIframe?.contentWindow; + iframeWindow?.postMessage({ type: 'AUTH_TOKEN', token }, targetUrl); + } +} + +window.addEventListener('message', messageHandler); +``` + +**Security notes** + +* Always validate `event.origin` in the parent before responding. +* Prefer using a specific `targetUrl` over `'*'` when posting back to the iframe. +* Remove listeners when no longer needed to avoid leaks. + ### How to handle the token in the backend Install the Quix Portal helper package from the public feed: @@ -66,9 +121,7 @@ pip install -i https://pkgs.dev.azure.com/quix-analytics/53f7fe95-59fe-4307-b479 Then, in the backend service, validate the token and enforce authorization for each request. For example: ```python - import os - from quixportal.auth import Auth # Instantiate authentication client. By default it will read @@ -94,5 +147,4 @@ if auth.validate_permissions( print("Bearer is authorized to access the resource") else: print("Bearer is not authorized to access the resource") - ```