Update your embedded app OAuth flow: Node and PHP
On August 23, 2022, we've updated the recommended method for authorizing embedded apps using OAuth. The new method improves performance and eliminates screen flicker caused by the number and types of redirects. Follow this tutorial to update your Node or PHP app to optimize your OAuth flow for user experience and performance.
This tutorial focuses on apps built using Shopify Node and PHP app templates. However, you can still use this tutorial to understand the scope of the recommended changes, and review some example implementations.
What you'll learn
Anchor link to section titled "What you'll learn"In this tutorial, you'll learn how to update an app to follow our OAuth performance best practices.
You'll perform the following tasks:
- Add code to check for and escape the iframe used to display your embedded app.
- Add code to redirect to the embedded app URL.
Requirements
Anchor link to section titled "Requirements"- Your app is embedded.
- Your app isn't built using Ruby. If it is, then follow the Ruby-specific tutorial.
- One of the following is true:
- Your app was created before August 23, 2022, either using Shopify CLI, or using the Node or PHP app template.
- Your app was created after August 23, 2022 using Shopify CLI, or using the Node or PHP app template, but you made significant changes to the OAuth flow.
- Your app was created after August 23, 2022, but you didn't use Shopify CLI or a Shopify app template as a starting point.
Step 1: Add a new iframe escape route
Anchor link to section titled "Step 1: Add a new iframe escape route"To handle escaping the iframe using Shopify App Bridge, you need to add a new route to your application frontend. This route initializes App Bridge, then uses the App Bridge Redirect
action to redirect to a URI defined in a new redirectURI
parameter. You'll conditionally redirect to the new route in a later step.
Using our previous recommendations, your app might have loaded Shopify App Bridge from the Shopify CDN using an inline script tag. Loading Shopify App Bridge from your app bundle increases the chance that the user’s browser can attempt to access this code from the cache.
Step 2: Update the begin auth logic
Anchor link to section titled "Step 2: Update the begin auth logic"Using our previous recommendations, your app might attempt to escape an iframe whether or not it's present. In this step, you'll update your app's logic to escape the iframe only when needed.
To update the begin auth logic, add a utility that checks whether a request query parameter of embedded
exists, and has a value of 1
. If embedded=1
, then the utility should render the route that you added to escape the iframe.
Call the iframe escape utility
Anchor link to section titled "Call the iframe escape utility"The following table includes cases where you should call your new utility, and examples of how and where this utility is called in Shopify Node and PHP templates.
Case | App template examples |
---|---|
The app isn't installed yet | Node PHP Note: In previous versions of the PHP template, this logic was also present in a /web/routes/web.php fallback route. If applicable, you should update the logic in the fallback route as well. |
The /api/auth URL is hit |
Node PHP |
The nonce cookie or the session isn't found |
Node |
The shop request parameter and the shop session parameter don't match |
Node PHP |
Step 3: Redirect to the embedded app URL
Anchor link to section titled "Step 3: Redirect to the embedded app URL"After the user has granted access to your requested scopes, they should be returned to your app UI.
Using our previous recommendations, your app might use Shopify App Bridge to redirect to the embedded app URL. This would cause the app to load twice: once outside the iframe, and then again inside the iframe.
Instead of using App Bridge, you should use the Shopify Admin API library getEmbeddedAppUrl
utility to build the embedded app URL. After you build the URL, you can perform a 3xx redirect to it.
Redirect to the URL provided by getEmbeddedAppUrl
Anchor link to section titled "Redirect to the URL provided by getEmbeddedAppUrl"The following table includes cases where you should 3xx
redirect to the URL returned by the getEmbeddedAppUrl
utility, and examples of how and where this utility is called in Shopify Node and PHP templates.
Case | App template examples |
---|---|
At the end of the OAuth process |
Node
PHP |
When you receive a GET request to your app URL, you don't need to redirect to the grant screen, and the embedded=1 parameter isn't present |
Node
PHP |
Step 4: Remove old iframe escape code
Anchor link to section titled "Step 4: Remove old iframe escape code"After you implement the changes to your OAuth flow, you can remove unused code. The following components were included in previous versions of Shopify app templates. If you didn't use an app template, then you might have components or code that fulfill similar functions.
Component | Examples |
---|---|
A top-level redirect utility that loaded Shopify App Bridge from the CDN, and then escaped the iframe and performed a redirect back to your app |
Node
PHP |
A /api/auth/toplevel route. This route might be requested using an App Bridge redirect after your app had set a top-level cookie. |
Node
PHP |