shopify_app 17.0.5 → 17.1.0

data/app/controllers/concerns/shopify_app/shop_access_scopes_verification.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ShopifyApp
+  module ShopAccessScopesVerification
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :login_on_scope_changes
+    end
+
+    protected
+
+    def login_on_scope_changes
+      redirect_to(shop_login) if scopes_mismatch?
+    end
+
+    private
+
+    def scopes_mismatch?
+      ShopifyApp.configuration.shop_access_scopes_strategy.update_access_scopes?(current_shopify_domain)
+    end
+
+    def current_shopify_domain
+      return if params[:shop].blank?
+      ShopifyApp::Utils.sanitize_shop_domain(params[:shop])
+    end
+
+    def shop_login
+      ShopifyApp::Utils.shop_login_url(shop: params[:shop], return_to: request.fullpath)
+    end
+  end
+end

data/app/controllers/shopify_app/callback_controller.rb

@@ -76,10 +76,20 @@ module ShopifyApp
       if jwt_request?
         false
       else
-        ShopifyApp::SessionRepository.user_storage.present? && user_session.blank?
+        return false unless ShopifyApp::SessionRepository.user_storage.present?
+        update_user_access_scopes?
       end
     end
 
+    def update_user_access_scopes?
+      return true if user_session.blank?
+      user_access_scopes_strategy.update_access_scopes?(user_id: session[:user_id])
+    end
+
+    def user_access_scopes_strategy
+      ShopifyApp.configuration.user_access_scopes_strategy
+    end
+
     def jwt_request?
       jwt_shopify_domain || jwt_shopify_user_id
     end
@@ -118,6 +128,11 @@ module ShopifyApp
       auth_hash['credentials']['token']
     end
 
+    def access_scopes
+      return unless auth_hash['extra']['scope']
+      auth_hash['extra']['scope']
+    end
+
     def reset_session_options
       request.session_options[:renew] = true
       session.delete(:_csrf_token)
@@ -127,7 +142,8 @@ module ShopifyApp
       session_store = ShopifyAPI::Session.new(
         domain: shop_name,
         token: token,
-        api_version: ShopifyApp.configuration.api_version
+        api_version: ShopifyApp.configuration.api_version,
+        access_scopes: access_scopes
       )
 
       session[:shopify_user] = associated_user

data/docs/Quickstart.md

@@ -1,93 +1,31 @@
-Quickstart
-==========
+# Quickstart
 
-Get started building and deploying a new Shopify App to Heroku in just a few minutes.
-This guide assumes you have Ruby, Rails and PostgreSQL installed on your computer already; if you haven't done that already start with [this guide.](https://guides.rubyonrails.org/v5.0/getting_started.html#installing-rails)
+This guide assumes you have completed the steps to create a new Rails app using the Shopify App gem found in the [*Usage*](/README.md#usage) section of the project's [*README*](/README.md).
 
-1. New Rails App (with postgres)
---------------------------------
+#### Table of contents
 
-To create a new Rails app and use this generator, open your terminal and run the following commands:
+[Make your app available to the internet](#make-your-app-available-to-the-internet)
 
-```sh
-$ rails new test-app --database=postgresql
-$ cd test-app
-$ git init
-$ git add .
-$ git commit -m 'new rails app'
-```
-
-2. Create a new Heroku app
---------------------------
-
-The next step is to create a new Heroku app to host your application. If you haven't got a Heroku account yet, create a free account [here](https://www.heroku.com/). 
-
-Head to the Heroku dashboard and create a new app, or run the following commands with the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli#download-and-install) installed, substituting `name` for the name of your own app:
-
-CLI:
-```sh
-$ heroku create name
-```
-
-3. Create a new App in the Shopify Partner dashboard
------------------------------------------
-* Create a Shopify app in the [Partners dashboard](https://partner.shopify.com). For this tutorial, you can choose either a public or custom app, but you can [learn about App Types here.](https://help.shopify.com/en/manual/apps/app-types)
-[https://app.shopify.com/services/partners/api_clients](https://app.shopify.com/services/partners/api_clients)
-* Set the callback url to `https://<appname>.herokuapp.com/`
-* Choose an embedded app
-* Set the app's `redirect_uri` to `https://<appname>.herokuapp.com/auth/shopify/callback`
-
-4. Add ShopifyApp to Gemfile
-----------------------------
-
-Run this command to add the `shopify_app` Gem to your app:
+[Use Shopify App Bridge to embed your app in the Shopify Admin](#use-shopify-app-bridge-to-embed-your-app-in-the-shopify-admin)
 
-```sh
-$ bundle add shopify_app
-```
+## Make your app available to the internet
 
-**Note:** we recommend using the latest version of Shopify Gem. Check the [Git tags](https://github.com/Shopify/shopify_app/tags) to see the latest release version and then add it to your Gemfile e.g `gem 'shopify_app', '~> 7.0.0'`
+Your local app needs to be accessible from the public Internet in order to install it on a Shopify store, to use the [App Proxy Controller](/lib/generators/shopify_app/app_proxy_controller/templates/app_proxy_controller.rb) or receive [webhooks](/docs/shopify_app/webhooks.md).
 
-5. Run the ShopifyApp generator
--------------------------------
+Use a tunneling service like [ngrok](https://ngrok.com/), [Beeceptor](https://beeceptor.com/), [Mockbin](http://mockbin.org/), or [Hookbin](https://hookbin.com/) to make your development environment accessible to the internet.
 
-Generate the code for your app by running these commands: 
+For example with [ngrok](https://ngrok.com/), run this command to set up a tunnel proxy to Rails' default port:
 
 ```sh
-# Use the keys from your app you created in the partners area
-$ rails generate shopify_app
-$ git add .
-$ git commit -m 'generated shopify app'
+ngrok http 3000
 ```
 
-Your API key and secret are read from environment variables. Refer to the main
-README for further details on how to set this up.
-
-6. Deploy your app
----------
-
-Once you've generated your app, push it into your Heroku environment to see it up and running:
-```sh
-$ git push heroku
-$ heroku run rake db:migrate
-```
-
-7. Install the App!
--------------------
-
-Ensure you have created a [development store](https://help.shopify.com/en/api/getting-started/making-your-first-request#create-a-development-store) using the Shopify Partner Dashboard. If you don't already have one, [create one by following these instructions](https://help.shopify.com/en/api/getting-started/making-your-first-request#create-a-development-store).
-
-##### Note: The following step will cause your store to become `transfer-disabled.` Read more about store transfer and why it's important [here](https://help.shopify.com/en/api/guides/store-transfers#transfer-disabled-stores). This is an irreversible change, so be sure you don't plan to transfer this store to a merchant.
-
-Install the app onto your new development store using the Partner Dashboard. Log in to your account, visit the apps page, click the app you created earlier, and looking for the `Test your app` instructions where you can select a store to install your app on.
-
-![Installing an app on the partners dashboard dropdown](/docs/install-on-dev-shop.png)
+See the [*Embed the app in Shopify*](https://shopify.dev/tutorials/build-rails-react-app-that-uses-app-bridge-authentication#embed-the-app-in-shopify) section of [*Build a Shopify app with Rails, React, and App Bridge*](https://shopify.dev/tutorials/build-rails-react-app-that-uses-app-bridge-authentication) to learn more.
 
-### OR
+## Use Shopify App Bridge to embed your app in the Shopify Admin
 
-![Installing an app on the partners dashboard card](/docs/test-your-app.png)
+A basic example of using [*Shopify App Bridge*](https://shopify.dev/tools/app-bridge) is included in the install generator. An instance Shopify App Bridge is automatically initialized in [shopify_app.js](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/shopify_app.js). 
 
-8. Great work! 
--------------------
+The [flash_messages.js](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/flash_messages.js) file converts Rails [flash messages](https://api.rubyonrails.org/classes/ActionDispatch/Flash.html) to App Bridge Toast actions automatically. By default, this library is included via [unpkg in the embedded_app layout](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/embedded_app.html.erb#L27). 
 
-You're done creating your first app on Shopify. Keep going and learn more by [diving into our full documentation](https://help.shopify.com/en/api/getting-started), or join our [community of developers.](https://community.shopify.com/c/Shopify-Apps/bd-p/shopify-apps)
+For more advanced uses it is recommended to [install App Bridge via npm or yarn](https://help.shopify.com/en/api/embedded-apps/app-bridge/getting-started#set-up-shopify-app-bridge-in-your-app).

data/docs/Upgrading.md

@@ -0,0 +1,110 @@
+# Upgrading 
+
+This file documents important changes needed to upgrade your app's Shopify App version to a new major version.
+
+#### Table of contents
+
+[Upgrading to `v13.0.0`](#upgrading-to-v1300)
+
+[Upgrading to `v11.7.0`](#upgrading-to-v1170)
+
+[Upgrading from `v8.6` to `v9.0.0`](#upgrading-from-v86-to-v900)
+
+## Upgrading to `v13.0.0`
+
+Version 13.0.0 adds the ability to use both user and shop sessions, concurrently. This however involved a large
+change to how session stores work. Here are the steps to migrate to 13.x
+
+### Changes to `config/initializers/shopify_app.rb`
+
+- *REMOVE* `config.per_user_tokens = [true|false]` this is no longer needed
+- *CHANGE* `config.session_repository = 'Shop'` To  `config.shop_session_repository = 'Shop'`
+- *ADD (optional)*  User Session Storage `config.user_session_repository = 'User'`
+
+### Shop Model Changes (normally `app/models/shop.rb`)
+
+-  *CHANGE* `include ShopifyApp::SessionStorage` to `include ShopifyApp::ShopSessionStorage`
+
+### Changes to the @shop_session instance variable (normally in `app/controllers/*.rb`)
+
+- *CHANGE* if you are using shop sessions, `@shop_session` will need to be changed to `@current_shopify_session`.
+
+### Changes to Rails `session`
+
+- *CHANGE* `session[:shopify]` is no longer set. Use `session[:user_id]` if your app uses user based tokens, or `session[:shop_id]` if your app uses shop based tokens.
+
+### Changes to `ShopifyApp::LoginProtection`
+
+`ShopifyApp::LoginProtection`
+
+- CHANGE if you are using `ShopifyApp::LoginProtection#shopify_session` in your code, it will need to be
+changed to `ShopifyApp::LoginProtection#activate_shopify_session`
+- CHANGE if you are using `ShopifyApp::LoginProtection#clear_shop_session` in your code, it will need to be
+changed to `ShopifyApp::LoginProtection#clear_shopify_session`
+
+### Notes
+You do not need a user model; a shop session is fine for most applications.
+
+---
+
+## Upgrading to `v11.7.0`
+
+### Session storage method signature breaking change
+If you override `def self.store(auth_session)` method in your session storage model (e.g. Shop), the method signature has changed to `def self.store(auth_session, *args)` in order to support user-based token storage. Please update your method signature to include the second argument.
+
+---
+
+## Upgrading from `v8.6` to `v9.0.0`
+
+### Configuration change
+
+Add an API version configuration in `config/initializers/shopify_app.rb`
+Set this to the version you want to run against by default. See [Shopify API docs](https://help.shopify.com/en/api/versioning) for versions available.
+```ruby
+config.api_version = '2019-04'
+```
+
+### Session storage change
+
+You will need to add an `api_version` method to your session storage object.  The default implementation for this is.
+```ruby
+def api_version
+  ShopifyApp.configuration.api_version
+end
+```
+
+### Generated file change
+
+`embedded_app.html.erb` the usage of `shop_session.url` needs to be changed to `shop_session.domain`
+```erb
+<script type="text/javascript">
+  ShopifyApp.init({
+    apiKey: "<%= ShopifyApp.configuration.api_key %>",
+
+    shopOrigin: "<%= "https://#{ @shop_session.url }" if @shop_session %>",
+
+    debug: false,
+    forceRedirect: true
+  });
+</script>
+```
+is changed to
+```erb
+<script type="text/javascript">
+  ShopifyApp.init({
+    apiKey: "<%= ShopifyApp.configuration.api_key %>",
+
+    shopOrigin: "<%= "https://#{ @shop_session.domain }" if @shop_session %>",
+
+    debug: false,
+    forceRedirect: true
+  });
+</script>
+```
+
+### ShopifyAPI changes
+
+You will need to also follow the ShopifyAPI [upgrade guide](https://github.com/Shopify/shopify_api/blob/master/README.md#-breaking-change-notice-for-version-700-) to ensure your app is ready to work with API versioning.
+
+[dashboard]:https://partners.shopify.com
+[app-bridge]:https://help.shopify.com/en/api/embedded-apps/app-bridge

data/docs/shopify_app/authentication.md

@@ -0,0 +1,124 @@
+# Authentication
+
+The Shopify App gem implements [OAuth 2.0](https://shopify.dev/tutorials/authenticate-with-oauth) to get [access tokens](https://shopify.dev/concepts/about-apis/authentication#api-access-modes). These are used to authenticate requests made by the app to the Shopify API. 
+
+By default, the gem generates an embedded app frontend that uses [Shopify App Bridge](https://shopify.dev/tools/app-bridge) to fetch [session tokens](https://shopify.dev/concepts/apps/building-embedded-apps-using-session-tokens). Session tokens are used by the embedded app to make authenticated requests to the app backend. 
+
+See [*Authenticate an embedded app using session tokens*](https://shopify.dev/tutorials/authenticate-your-app-using-session-tokens) to learn more. 
+
+> ⚠️ Be sure you understand the differences between the types of authentication schemes before reading this guide.
+
+#### Table of contents
+
+[OAuth callback](#oauth-callback)
+
+[Run jobs after the OAuth flow](#run-jobs-after-the-oauth-flow)
+
+[Rotate API credentials](#rotate-api-credentials)
+
+[Available authentication mixins](#available-authentication-mixins)
+  * [`ShopifyApp::Authenticated`](#shopifyappauthenticated)
+  * [`ShopifyApp::EnsureAuthenticatedLinks`](#shopifyappensureauthenticatedlinks)
+
+## OAuth callback
+
+>️ **Note:** In Shopify App version 8.4.0, we have extracted the callback logic in its own controller. If you are upgrading from a version older than 8.4.0 the callback action and related helper methods were defined in `ShopifyApp::SessionsController` ==> you will have to extend `ShopifyApp::CallbackController` instead and port your logic to the new controller.
+
+Upon completing the OAuth flow, Shopify calls the app at the `callback_path`. If the app needs to do some extra work, it can define and configure the route to a custom callback controller, inheriting from `ShopifyApp::CallbackController` and hook into or override any of the defined helper methods. The default callback controller already provides the following behaviour:
+* Logging into the shop and resetting the session
+* [Installing Webhooks](/docs/shopify_app/webhooks.md)
+* [Setting Scripttags](/docs/shopify_app/script-tags.md)
+* [Run jobs after the OAuth flow](#run-jobs-after-the-oauth-flow)
+* Redirecting to the return address
+
+## Run jobs after the OAuth flow
+
+See [`ShopifyApp::AfterAuthenticateJob`](/lib/generators/shopify_app/add_after_authenticate_job/templates/after_authenticate_job.rb).
+
+If your app needs to perform specific actions after the user is authenticated successfully (i.e. every time a new session is created), ShopifyApp can queue or run a job of your choosing (note that we already provide support for automatically creating Webhooks and Scripttags). To configure the after authenticate job, update your initializer as follows:
+
+```ruby
+ShopifyApp.configure do |config|
+  config.after_authenticate_job = { job: "Shopify::AfterAuthenticateJob" }
+end
+```
+
+The job can be configured as either a class or a class name string.
+
+If you need the job to run synchronously add the `inline` flag:
+
+```ruby
+ShopifyApp.configure do |config|
+  config.after_authenticate_job = { job: Shopify::AfterAuthenticateJob, inline: true }
+end
+```
+
+We've also provided a generator which creates a skeleton job and updates the initializer for you:
+
+```
+bin/rails g shopify_app:add_after_authenticate_job
+```
+
+If you want to perform that action only once, e.g. send a welcome email to the user when they install the app, you should make sure that this action is idempotent, meaning that it won't have an impact if run multiple times.
+
+## Rotate API credentials
+
+If your Shopify secret key is leaked, you can use the RotateShopifyTokenJob to perform [API Credential Rotation](https://help.shopify.com/en/api/getting-started/authentication/oauth/api-credential-rotation).
+
+Before running the job, you'll need to generate a new secret key from your Shopify Partner dashboard, and update the `/config/initializers/shopify_app.rb` to hold your new and old secret keys:
+
+```ruby
+config.secret = Rails.application.secrets.shopify_secret
+config.old_secret = Rails.application.secrets.old_shopify_secret
+```
+
+We've provided a generator which creates the job and an example rake task:
+
+```sh
+bin/rails g shopify_app:rotate_shopify_token_job
+```
+
+The generated rake task will be found at `lib/tasks/shopify/rotate_shopify_token.rake` and is provided strictly for example purposes. It might not work with your application out of the box without some configuration.
+
+```ruby
+strategy.options[:old_client_secret] = ShopifyApp.configuration.old_secret
+```
+
+> **Note:** If you are updating `shopify_app` from a version prior to 8.4.2 (and do not wish to run the default/install generator again), you will need to add [the following line](https://github.com/Shopify/shopify_app/blob/4f7e6cca2a472d8f7af44b938bd0fcafe4d8e88a/lib/generators/shopify_app/install/templates/shopify_provider.rb#L18) to `config/initializers/omniauth.rb`:
+
+## Available authentication mixins
+
+### `ShopifyApp::Authenticated`
+
+The engine provides a [`ShopifyApp::Authenticated`](/app/controllers/concerns/shopify_app/authenticated.rb) concern which should be included in any controller that is intended to be behind Shopify OAuth. It adds `before_action`s to ensure that the user is authenticated and will redirect to the Shopify login page if not. It is best practice to include this concern in a base controller inheriting from your `ApplicationController`, from which all controllers that require Shopify authentication inherit.
+
+*Example:*
+
+```rb
+class AuthenticatedController < ApplicationController
+  include ShopifyApp::Authenticated
+end
+
+class ApiController < AuthenticatedController
+  # Actions in this controller are protected
+end
+```
+
+For backwards compatibility, the engine still provides a controller called `ShopifyApp::AuthenticatedController` which includes the `ShopifyApp::Authenticated` concern. Note that it inherits directly from `ActionController::Base`, so you will not be able to share functionality between it and your application's `ApplicationController`.
+
+### `ShopifyApp::EnsureAuthenticatedLinks`
+
+The [`ShopifyApp::EnsureAuthenticatedLinks`](/app/controllers/concerns/shopify_app/ensure_authenticated_links.rb) concern helps authenticate users that access protected pages of your app directly.
+
+Include this concern in your app's `AuthenticatedController` if your app uses session tokens with [Turbolinks](https://github.com/turbolinks/turbolinks). It adds a `before_action` filter that detects whether a session token is present or not. If a session token is not found, the user is redirected to your app's splash page path (`root_path`) along with `return_to` and `shop` parameters.
+
+*Example:*
+
+```rb
+class AuthenticatedController < ApplicationController
+  include ShopifyApp::EnsureAuthenticatedLinks
+  include ShopifyApp::Authenticated
+end
+```
+
+See [Authenticate server-side rendered embedded apps using Rails and Turbolinks](https://shopify.dev/tutorials/authenticate-server-side-rendered-embedded-apps-using-rails-and-turbolinks) for more information.

data/docs/shopify_app/engine.md

@@ -0,0 +1,82 @@
+# Engine
+
+#### Table of contents
+
+[Customize the app login URL](#customize-the-app-login-url)
+
+[Mount the Shopify App engine at nested routes](#mount-the-shopify-app-engine-at-nested-routes)
+
+[Verify HTTP requests sent via an app proxy](#verify-http-requests-sent-via-an-app-proxy)
+  * [Recommended usage of `ShopifyApp::AppProxyVerification`](#recommended-usage-of-shopifyappappproxyverification)
+
+## Customize the app login URL
+
+While you can customize the login view by creating a `/app/views/shopify_app/sessions/new.html.erb` file, you may also want to customize the URL entirely. You can modify your `shopify_app.rb` initializer to provide a custom `login_url` e.g.:
+
+```ruby
+ShopifyApp.configure do |config|
+  config.login_url = 'https://my.domain.com/nested/login'
+end
+```
+
+## Mount the Shopify App engine at nested routes
+
+The engine may also be mounted at a nested route, for example:
+
+```ruby
+mount ShopifyApp::Engine, at: '/nested'
+```
+
+This will create the Shopify engine routes under the specified subpath. You'll also need to make some updates to your `shopify_app.rb` and `omniauth.rb` initializers. First, update the shopify_app initializer to include a custom `root_url` e.g.:
+
+```ruby
+ShopifyApp.configure do |config|
+  config.root_url = '/nested'
+end
+```
+
+then update the omniauth initializer to include a custom `callback_path` e.g.:
+
+```ruby
+provider :shopify,
+  ShopifyApp.configuration.api_key,
+  ShopifyApp.configuration.secret,
+  scope: ShopifyApp.configuration.scope,
+  callback_path: '/nested/auth/shopify/callback'
+```
+
+You may also need to change your `config/routes.rb` to render a view for `/nested`, since this is what will be rendered in the Shopify Admin of any shops that have installed your app.  The engine itself doesn't have a view for this, so you'll need something like this:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  root :to => 'something_else#index'
+  get "/nested", to: "home#index"
+  mount ShopifyApp::Engine, at: '/nested'
+end
+```
+
+Finally, note that if you do this, to add your app to a store, you must navigate to `/nested` in order to render the `Enter your shop domain to log in or install this app.` UI.
+
+## Verify HTTP requests sent via an app proxy
+
+See [`ShopifyApp::AppProxyVerification`](/lib/shopify_app/controller_concerns/app_proxy_verification.rb).
+
+The engine provides a mixin for verifying incoming HTTP requests sent via an App Proxy. Any controller that `include`s `ShopifyApp::AppProxyVerification` will verify that each request has a valid `signature` query parameter that is calculated using the other query parameters and the app's shared secret.
+
+### Recommended usage of `ShopifyApp::AppProxyVerification`
+
+The App Proxy Controller Generator automatically adds the mixin to the generated app_proxy_controller.rb
+Additional controllers for resources within the App_Proxy namespace, will need to include the mixin like so:
+
+```ruby
+# app/controllers/app_proxy/reviews_controller.rb
+class ReviewsController < ApplicationController
+  include ShopifyApp::AppProxyVerification
+  # ...
+end
+```
+
+Create your app proxy URL in the [Shopify Partners dashboard](https://partners.shopify.com/organizations), making sure to point it to `https://your_app_website.com/app_proxy`.
+
+![Creating an App Proxy](/images/app-proxy-screenshot.png)