Embed Relay

Embed Relay lets an embedded application make authenticated requests to Drupal endpoints without exposing Drupal credentials to the embedding page. A small iframe served by Drupal relays browser requests after Drupal checks whether the embedding origin is allowed.

Features

• Forward browser Fetch and XMLHttpRequest requests to Drupal through a Drupal-hosted iframe relay.
• Restrict relayed requests to configured exact or wildcard path patterns, and block unwanted origins using the deny list.
• Record relay activity. Review raw logs, aggregate reports, and suspicious origins.
• Set request limits and flood protection for relay traffic.
• Support a sign-on return flow for cross-site embedded applications. Allow cookie access through the relay for names matching configured patterns.

Post-installation

Enable the module and visit /admin/config/services/embed-relay to configure allowed path patterns and manage the origin deny list. For cookie access through the relay, configure the cookie-name patterns that the embedding application may use. Only cookies accessible to JavaScript can be shared; HttpOnly cookies cannot be shared through the relay.

Integrate the embedding application with the relay postMessage API. Send messages to the relay's exact origin, validate the source and origin of replies, and use a unique ID for each request. See the project README for message formats and integration examples. View activity at /admin/reports/embed-relay.

Additional requirements

Cross-site sign-on requires HTTPS, correctly configured trusted proxies, and site-wide session-cookie settings. See the README for setup instructions.

Similar projects

CORS UI provides an interface for configuring Drupal core CORS settings. Its deny-list merge request adds deny-list management to that configuration. With Embed Relay, the embedding application communicates with a Drupal-hosted iframe, and requests from that iframe to Drupal are same-origin. They do not depend on Drupal accepting cross-origin requests from the embedding application.

Because requests to Drupal come from the Drupal-hosted iframe, Embed Relay may also be less affected by browser restrictions on third-party cookies than direct cross-origin requests. Cookie behavior still depends on browser support and site configuration.

API Proxy is an example of server-side proxying: Drupal receives the consumer's request, makes a separate request to the external API, and returns its response. To avoid browser cross-site restrictions between the consumer and the Drupal proxy, API Proxy must be installed on the site making the requests, not on the receiving API's site.

Simple OAuth provides OAuth 2.0 authorization for Drupal APIs. Authorization determines which client or user may access an API; it does not override browser cross-origin restrictions. The API must still allow the browser origin through CORS, or requests must go through a same-origin relay or proxy.

Supporting this module

For help with Embed Relay, open a support request in the issue queue. To discuss implementing similar work on other platforms, contact Darren Oh.

AI disclosure

AI-assisted tools were used during module development and to help prepare this project description. Maintainers review and are responsible for the project's content and maintenance.