Connecting a Shopify App to a Store

December 30, 2015

This past week I’ve been researching the details of how to connect a Shopify App to a Shopify store. In particular, I was looking to answer the following questions:

What happens when you install a Shopify App in a store?
How are app permissions managed for a Shopify app?
What does the shopify_app gem do?

In this post, I’ll share my findings for connecting a Shopify App to a store. This will include a brief overview of the underlying OAuth 2 protocol Shopify uses to authorize apps within stores. I’ll also walk you through the types of permissions an app may request access for within a store. And finally, I’ll outline how the shopify_app gem may help out with this process.

What happens when you install a Shopify App in a store?

Shopify uses the OAuth 2 protocol to connect Shopify Apps to stores, as seen here:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 +--------+                               +---------------+
 |        |--(A)- Authorization Request ->|   Resource    |
 |        |                               |     Owner     |
 |        |<-(B)-- Authorization Grant ---|               |
 |        |                               +---------------+
 |        |
 |        |                               +---------------+
 |        |--(C)-- Authorization Grant -->| Authorization |
 | Client |                               |     Server    |
 |        |<-(D)----- Access Token -------|               |
 |        |                               +---------------+
 |        |
 |        |                               +---------------+
 |        |--(E)----- Access Token ------>|    Resource   |
 |        |                               |     Server    |
 |        |<-(F)--- Protected Resource ---|               |
 +--------+                               +---------------+

This flow chart comes from the official OAuth 2 specification. The short version of this is that OAuth 2 allows a Store owner to grant a Shopify app (a.k.a - the Client) access to their Shopify store (a.k.a. - the Resource).

To break this down further, let’s walk through the flow for adding an App to a Store.

A store owner searches the Shopify App store, finds an app to install, and clicks the install link.
Shopify sends the store owner to the Shopify App to start the OAuth 2 flow to connect the app to the store.
The Shopify App builds the Authorization Request (A), with specific permissions (more on this below), and sends the store owner to Shopify to grant access:
If the store owner accepts the Authorization Request, the Authorization Grant (B) is sent back to the Shopify App.
The Shopify App will then request the final Access Token © and (D).
The Access Token is then provided for all Shopify API calls (E) to access store data (F).

The Access Token does not expire for Shopify Apps. However, if an App is removed by the Store owner, the Access Token will be immediately revoked and all future API calls using this token will no longer work.

How are app permissions managed for a Shopify app?

The OAuth 2 protocol has built-in support for defining the permissions being granted to a resource. These permissions are called Scopes in OAuth 2 terminology. When the Shopify App builds the Authorization Request (A), the list of the requested scopes is also provided.

You can see the full list of supported Shopify scopes here. For my Best Sellers app, I will most likely need access to the following Scopes:

read_products - To obtain product data as part of the Best Sellers views.
write_products - To modify collections, as well as add best seller details to products as possibly Product tags or metafields.
read_orders - To get the order information for use in building the best seller list.
read_customers - To get more details about the customers that are buying the best sellers.

A note about modifying permissions

Since these permissions are tied to the Access Token granted during the initial OAuth flow, the permissions can’t be modified. As a result, it is a good idea to request access for all conceivable permissions a Shopify app may need up front. If a Shopify app does need to change permissions in the future, it will need to walk the store owner through the entire OAuth 2 flow again.

What does the shopify_app gem do?

As part of my process for learning about connecting Shopify Apps to stores, I used the shopify_app gem. I used the shopify_app gem to generate a basic app to see the entire OAuth 2 flow in action.

The shopify_app gem makes it easy to quickly build a Shopify App and provides:

OAuth 2 integration, with an App install form and support for App-specific scope definitions
A model for storing stores and access tokens
Webhook callback registration at the completion of a successful app install
A basic embedded app example, using the ShopifyAPI via the shopify_api gem with a connected store’s access token

The shopify_app definitely made things easy to get started. Under the covers, the shopify_app is using the omniauth-shopify-oauth2 gem for the bulk of the OAuth functionality.

The shopify_app gem itself may not be a great fit for my needs for a few reasons that I may expand on in a future post. As a result, I will most likely end up extracting parts of this into my own app rather than use the shopify_app directly. If I go this route, I will create a public GitHub repo to demonstrate this approach.

Summary

The OAuth 2 protocol can be a bit overwhelming if you read through all of the specific technical details. However, the underlying concepts are pretty straight-forward in the case of connecting a Shopify app to a store:

The Shopify app requests access to specific permissions (a.k.a - scope) within a store.
The Store owner must explicitly grant access to the app via an Access Token.
The Access Token represents the granted access for the app going forward and is used for all future API requests.

Using something like the shopify_app can also shortcut the process for getting up and running quickly with a Shopify app.