App Bridge Upgrade (CDN): How to escape iframe for OAuth with `use_legacy_install_flow = true`?

App Bridge
1

Hi,

I’m currently upgrading our Rails app to the latest Shopify App Bridge (via the CDN script) and have run into a roadblock regarding the OAuth installation flow.

Context & Setup:

  • Tech Stack: Ruby on Rails.

  • App Environment: Functions both as an embedded Shopify app and as a standalone app outside of Shopify.

  • Config: We have use_legacy_install_flow = true set in our shopify.app.toml.

Because we rely on the legacy OAuth flow to request access scopes, we need to “escape the iframe” used to embed the app, as stated in the Manage access scopes documentation.

The Problem: In the past, we successfully used the Redirect action from previous versions of App Bridge to handle this. We were closely following the implementation from the shopify_app gem (v21.10.0)—specifically app_bridge_redirect.js—and it worked flawlessly.

However, after updating to the latest CDN-based App Bridge, window['app-bridge'] no longer exists, which completely breaks our existing redirect script.

What we’ve tried: We looked at the App Bridge migration guide, which suggests replacing the old Redirect actions with standard browser routing, specifically window.open(redirectUrl, '_top').

However, replacing our App Bridge redirect script with window.open(..., '_top') isn’t working for us. It fails to actually escape the iframe to hit the OAuth grant URL, and stuck at the page as shown in the following screenshot.

image
image1046×740 35 KB

Question: What is the recommended way to escape the iframe for the OAuth flow using the latest App Bridge when use_legacy_install_flow = true?

Thanks in advance.

2

Hi @hoyin

The reason this is breaking is that the new CDN-based App Bridge was designed for the new authorization strategy that doesn’t require escaping the iframe at all. We’d strongly recommend migrating away from use_legacy_install_flow = true:

  1. Remove use_legacy_install_flow = true from your shopify.app.toml

  2. Declare your scopes in the TOML file and deploy with shopify app deploy:

[access_scopes]

scopes = "read_orders,write_products"

  1. Use Shopify managed installation – Shopify handles install and scope updates automatically, with no redirects needed.

  2. Use token exchange instead of authorization code grant to acquire access tokens. The shopify_app gem supports this via the ShopifyApp::TokenExchange concern.

This approach eliminates the iframe escape problem entirely, provides a faster/smoother install experience, and is the path that the CDN-based App Bridge is designed for.

3

Thanks @Liam-Shopify for looking into this.

If use_legacy_install_flow = true is removed from the TOML file, are we still able to request additional permissions through the OAuth flow? By additional permissions, I mean permissions that are not requested during the initial app installation, but are only needed when users attempt to access specific features.