1 | # `@shopify/koa-shopify-auth`
|
2 |
|
3 | [![Build Status](https://travis-ci.org/Shopify/quilt.svg?branch=master)](https://travis-ci.org/Shopify/quilt)
|
4 | [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md) [![npm version](https://badge.fury.io/js/%40shopify%2Fkoa-shopify-auth.svg)](https://badge.fury.io/js/%40shopify%2Fkoa-shopify-auth)
|
5 |
|
6 | Middleware to authenticate a [Koa](http://koajs.com/) application with [Shopify](https://www.shopify.ca/).
|
7 |
|
8 | Sister module to [`@shopify/shopify-express`](https://www.npmjs.com/package/@shopify/shopify-express), but simplified.
|
9 |
|
10 | Features you might know from the express module like the webhook middleware and proxy will be presented as their [own packages instead](https://github.com/Shopify/quilt/blob/master/packages/koa-shopify-graphql-proxy/README.md).
|
11 |
|
12 | ## Installation
|
13 |
|
14 | ```bash
|
15 | $ yarn add @shopify/koa-shopify-auth
|
16 | ```
|
17 |
|
18 | ## Usage
|
19 |
|
20 | This package exposes `shopifyAuth` by default, and `verifyRequest` as a named export.
|
21 |
|
22 | ```js
|
23 | import shopifyAuth, {verifyRequest} from '@shopify/koa-shopify-auth';
|
24 | ```
|
25 |
|
26 | ### shopifyAuth
|
27 |
|
28 | Returns an authentication middleware taking up (by default) the routes `/auth` and `/auth/callback`.
|
29 |
|
30 | ```js
|
31 | app.use(
|
32 | shopifyAuth({
|
33 | // if specified, mounts the routes off of the given path
|
34 | // eg. /shopify/auth, /shopify/auth/callback
|
35 | // defaults to ''
|
36 | prefix: '/shopify',
|
37 | // your shopify app api key
|
38 | apiKey: SHOPIFY_API_KEY,
|
39 | // your shopify app secret
|
40 | secret: SHOPIFY_SECRET,
|
41 | // scopes to request on the merchants store
|
42 | scopes: ['write_orders, write_products'],
|
43 | // set access mode, default is 'online'
|
44 | accessMode: 'offline',
|
45 | // callback for when auth is completed
|
46 | afterAuth(ctx) {
|
47 | const {shop, accessToken} = ctx.session;
|
48 |
|
49 | console.log('We did it!', accessToken);
|
50 |
|
51 | ctx.redirect('/');
|
52 | },
|
53 | }),
|
54 | );
|
55 | ```
|
56 |
|
57 | #### `/auth`
|
58 |
|
59 | This route starts the oauth process. It expects a `?shop` parameter and will error out if one is not present. To install it in a store just go to `/auth?shop=myStoreSubdomain`.
|
60 |
|
61 | ### `/auth/callback`
|
62 |
|
63 | You should never have to manually go here. This route is purely for shopify to send data back during the oauth process.
|
64 |
|
65 | ### verifyRequest
|
66 |
|
67 | Returns a middleware to verify requests before letting them further in the chain.
|
68 |
|
69 | ```javascript
|
70 | app.use(
|
71 | verifyRequest({
|
72 | // path to redirect to if verification fails
|
73 | // defaults to '/auth'
|
74 | authRoute: '/foo/auth',
|
75 | // path to redirect to if verification fails and there is no shop on the query
|
76 | // defaults to '/auth'
|
77 | fallbackRoute: '/install',
|
78 | }),
|
79 | );
|
80 | ```
|
81 |
|
82 | ### Example app
|
83 |
|
84 | ```javascript
|
85 | import 'isomorphic-fetch';
|
86 |
|
87 | import Koa from 'koa';
|
88 | import session from 'koa-session';
|
89 | import shopifyAuth, {verifyRequest} from '@shopify/koa-shopify-auth';
|
90 |
|
91 | const {SHOPIFY_API_KEY, SHOPIFY_SECRET} = process.env;
|
92 |
|
93 | const app = new Koa();
|
94 | app.keys = [SHOPIFY_SECRET];
|
95 |
|
96 | app
|
97 | // sets up secure session data on each request
|
98 | .use(session(app))
|
99 |
|
100 | // sets up shopify auth
|
101 | .use(
|
102 | shopifyAuth({
|
103 | apiKey: SHOPIFY_API_KEY,
|
104 | secret: SHOPIFY_SECRET,
|
105 | scopes: ['write_orders, write_products'],
|
106 | afterAuth(ctx) {
|
107 | const {shop, accessToken} = ctx.session;
|
108 |
|
109 | console.log('We did it!', accessToken);
|
110 |
|
111 | ctx.redirect('/');
|
112 | },
|
113 | }),
|
114 | )
|
115 |
|
116 | // everything after this point will require authentication
|
117 | .use(verifyRequest())
|
118 |
|
119 | // application code
|
120 | .use(ctx => {
|
121 | ctx.body = '🎉';
|
122 | });
|
123 | ```
|
124 |
|
125 | ## Gotchas
|
126 |
|
127 | ### Fetch
|
128 |
|
129 | This app uses `fetch` to make requests against shopify, and expects you to have it polyfilled. The example app code above includes a call to import it.
|
130 |
|
131 | ### Session
|
132 |
|
133 | Though you can use `shopifyAuth` without a session middleware configured, `verifyRequest` expects you to have one. If you don't want to use one and have some other solution to persist your credentials, you'll need to build your own verifiction function.
|
134 |
|
135 | ### Testing locally
|
136 |
|
137 | By default this app requires that you use a `myshopify.com` host in the `shop` parameter. You can modify this to test against a local/staging environment via the `myShopifyDomain` option to `shopifyAuth` (e.g. `myshopify.io`).
|