How to Authenticate Your Embedded App in the Shopify Admin

At first glance, building an app to serve Shopify merchants can be daunting—first, you need toidentify a problemthat merchants need solved. Next, you need to understand how your app will actually solve that problem. Then you need to pick your technology stack, design the interface, and build the whole thing from the ground up. It can be a lot of work—so using the right resources and libraries is crucial to your success.

Here at Shopify, we want to help our partners build and launch apps faster. We’ve been working hard to create an end-to-end tutorial on building an embedded app with Node and React, one of the fastest-growing tech stacks out there today. You canclick through to access the whole tutorial, or read on for a deep dive on one aspect of building Shopify Apps: embedding your app in the Shopify Admin.

In this article, we’ll use Shopify’s koa-auth package to set up a server file for authentication. The Koa middleware takes care of most of the heavy lifting for you, and gets you embedded faster and with less hassle. Let’s take a look at how we can do that usingNode,Koaandngrokfor local development.

Keep in mind, this will only go over setting up your node server and creating a tunnel for your localhost in development. The code in this article will not provide scaffolding for the front and back end of your app, nor a complete server. Luckily, we do have that covered! If you’d like to take a look at a step by step process for building an embedded app, head over to the full tutorial.

Use ngrok for local development

In the Shopify ecosystem, embedded apps run in an iframe in a production environment. In order to test the functionality of your app within that context in development, you’re going to want to tunnel what you have running locally to an accessible URL. This is where ngrok comes in.

Ngrokis a cloud service that accepts traffic on a public address, and then relays that traffic through to the ngrok process running on your machine, and on to the local address you specified. This gives you the ability to send users to this URL while you continue developing.

Assuming you’re developing a full stack application, running on localhost:3000, go ahead and install ngrok on the command line:

npm install ngrok -g

After it’s installed, have ngrok create a tunnel on port 3000:

ngrok http 3000

Once running, it should look something like this:

At this point, if you head to thehttpsURL provided by ngrok, it should show you whatever you have running locally on port 3000.

You might also like:The Shopify GraphQL Learning Kit.

Create a new app

To develop apps for the Shopify ecosystem, you’ll need two things:

1. AShopify Partneraccount
2. Adevelopment store

Shopify Partners can create development stores through their Partner Dashboard for testing purposes. Development stores are free of charge, hold no time restrictions, and offer most of the same functionality as the Advanced Shopify plan, so you can test your app as you work.

To invoke the authentication middleware, you’ll need yourShopify API key and Shopify API secret.

1. From your Partner Dashboard, clickApps.
2. Click创建应用程序。
3. Copy the HTTPS version of the forwarding URL from your ngrok terminal tab.
4. Give your app a name, such asSample embedded app.
5. Paste the HTTPS version of your ngrok forwarding URL into theApp URLfield.
6. Paste the same HTTPS forwarding URL into the白名单重定向URL (s)field and add/auth/callbackto the end of the path.
7. ClickCreate app.

If you don’t have a development store yet, this is a good time to set one up.

1. In your Partner Dashboard, clickDevelopment storeson the left.
2. Click theCreate storebutton.

Give your store a name and fill out the remaining fields.

While we're on the subject of URLs, learn what acanonical URLis and why they're so important.

Create your server

Now that you’ve set up your app, you can set up your server. As mentioned, we’ll use洋槐-middlewarein this node server. Koa is a middleware framework that we use internally at Shopify, because it’s both lightweight and modular. The洋槐-shopify-authpackage handles most of the authentication process out of the box by creating routes for install and callbacks and taking care of HMAC validation.

One thing to note is that this package usesfetchto make requests against Shopify’s APIs, which some older node versions don’t support. To avoid any issues, you’ll install a small library calledisomorphic-fetch, which polyfillsfetchfor you.

To get started install洋槐,@shopify/koa-shopify-auth,洋槐-session, andisomorphic-fetchon the command line:

npm install --save koa @shopify/koa-shopify-auth koa-session isomorphic-fetch

In your server file (in our example, server.js), set up your imports:

对于这个示例,我们将建立我们的中间件hardcoding the API key and API secret key. As the name implies, these keys are secret and should not be hardcoded in your server or saved in cloud-based services.In our tutorial, we go into detail on setting up.envfiles to store your keys safely.

After setting up your keys, you can set up the instance of your app, and use your keys to call theshopify-koa-authlibrary:

The洋槐-shopify-authlibrary provides theshopifyAuthfunction. This function expects your API key and secret, as well as the scopes your app will need to make requests. It uses the app’s session to get the shop name and access token from the response.

Note that for illustrative purposes, this exampleconsole.logsyour access token. That’s great for learning purposes—but not something anyone would want to do for a production app.

Shopify-koa-authalso provides averifyRequestmiddleware that we’ve used in our guide as an example as well. It gives you the ability to redirect users who are not authenticated.

At this point, you have an incredibly simple server that can take care of authentication for you. The Koa package uses the auth/callback route to authenticate, which is why you would have set it up in your app as the callback route in the Partner Dashboard.

Providing you had your app running on a localhost, you could then head tohttps://YOURNGROKURL/auth?shop=YOURTESTSTORE.myshopify.comto authenticate your app. If successful, you’ll see a screen that asks for permission to install the app and lists all of the scopes you’ve identified in theshopifyAuthmiddleware.

This is why it is so important to only ask for the permissions you really need. Put yourself in the position of a merchant being asked for these permissions—ask only for what your app requires, and make it clear why you need that access.

You might also like:How to Build a Shopify App in One Week.

Build apps faster

This middleware takes care of a lot of logic for you, keeps your server file tidy, and provides a battle-tested, internally used tool to help you solve merchant problems faster. Now that you’ve embedded your app within the Shopify Admin, you can start testing your UI and building out your app knowing that you’re seeing exactly what your merchant will see.

If you’re curious about other Javascript packages developed internally, check outquilt on GitHub. If you’d like to code along and build an app in JavaScript using some of those packages, check out our full tutorial.