Building an OAuth App for BigCommerce using Rails | Part 1: Setting Up Prerequisites
In Part 0, we went over our plan and requirements for building out a BigCommerce Rails app which we will be able to access from our local machine.
In this, Part 1 of our series on Building a Rails OAuth app for BigCommerce, we will set up all of the necessary third party services and tools that we will need to scaffold our app.
By utilizing 15-day free trial stores from BigCommerce and the free level of ngrok, you shouldn’t need to spend any money to get your app working.
Overview
- Create a free trial store with BigCommerce
- Setup a free developer account with BigCommerce
- Create a new one-click app in BigCommerce
- Setup a free `ngrok` account to get a pubic URL for testing your app locally
1. Create a free trial with BigCommerce
To set up a one-click, OAuth app with BigCommerce, we’re going to need a store (free-trial is fine) and a developer account. The store will hold our products, and the developer account will hold the information about our app.
Let’s start with the BigCommerce free-trial.
Go to https://www.bigcommerce.com/essentials/ and click on Get Started. Follow the steps and enter your email, your personal information, and your store details. No credit card is required.
When you’re done, it should redirect you to your new store’s control panel. Great job!
2. Setup your free developer account with BigCommerce
Now that you have a store, it’s time to create a developer account. Head over to https://developer.bigcommerce.com/ and click on Developer Portal at the top right.
You’ll be brought to an authentication screen. Read it closely and click “Allow” if you agree. You’ve now connected your free trial account to your developer account, great work!
3. Create a new one-click app in BigCommerce
Now that our BigCommerce accounts are created, it’s time to make a new draft app in the BigCommerce Developer Portal.
From the My Apps page of the Developer Portal, click on “Create an app.”
In the pop-up, give your app a name and continue. The page should reload and should now show your newly created app. High five!
We’ll come back to this screen later to add and update a lot of the information, so be sure to bookmark the developer portal page.
For now, let’s add a little visual flair by uploading an icon for our app.
Click “Edit App” and select “2 App Summary” from the top.
Scroll down the page to the “App Summary” Section and you will see a place to upload a logo and an app icon.
Feel free to save these two icons I quickly drafted to use in your testing!
Make sure to scroll to the bottom of the page and click “Update & Close” to save your changes.
4. Setup ngrok to get a public URL for testing
When we go to update your app configuration in the BigCommerce developer portal, you’ll need to let BigCommerce know how to reach your app.
For this, you’re going to need a live, online domain name/address that points to your local machine running Rails since localhost:3000 and 127.0.0.1:3000 will only work on your computer.
This is a little trickier than if we were working on a production server somewhere with a publicly accessible URL because we have to find a secure way to allow online traffic to access JUST your new Rails site on your computer (and nothing more).
To help solve this problem, BigCommerce recommends ngrok, a simple and free tool that allows you to expose only certain ports on your computer to the internet and provides them with a domain domain. So, that’s what we’ll be using!
1. Create a free `ngrok` account
Start by heading over to https://ngrok.com/ and clicking “Sign Up” to create a new account (if you don’t already have one).
To complete signup, you’ll need to verify your email address by clicking the link in the verification email that gets sent during account creation.
You may then be asked to setup multi-factor authentication which can help secure your account from unauthorized access. I highly recommend you do not skip this step. You’ll also be asked to download your recovery codes, which help in case you get locked out of your account.
Lastly, I was presented with an onboarding screen, asking me general questions about how I plan to use ngrok, but I’m sure this flow could change over time.
Once complete, you should land in the ngrok dashboard!
2. Install `ngrok` on your computer
At the time of writing, ngrok has a really great onboarding page as the landing page on their dashboard with a “Connect” step that you can follow verbatim!
Let’s step through it.
You start by installing ngrok on your Mac using Homebrew:
brew install ngrok/ngrok/ngrok3. Add your auth-token to the ngrok CLI
Next, you’ll want to add your ngrok auth token to the ngrok CLI that we installed via Homebrew.
You can do this with the ngrok config auth-token command, along with the auth token listed on your ngrok dashboard. It’ll look something like this:
ngrok config add-authtoken some_really_long_alpha_numeric_code4. Setup a static domain with ngrok
By default, when you use the ngrok CLI, it will generate a random url for the duration of your running command and then create a brand new url each time you stop and start the CLI command.
This won’t work super well for us because we will need a URL that doesn’t change. Since we have to enter the url into the BigCommerce app settings and BigCommerce will then be using it to send install/authentication requests to our app, we don’t want to have to log in to the BigCommerce Developer Portal and update our app settings every time we restart an ngrok agent locally.
Thankfully, ngrok now offers one free static domain to all accounts (even free) so that you can have a domain that never changes. Let’s get one!
The bottom step of my onboarding page had a link to “claim your free static domain”, but if you don’t see that then you can follow the steps on their support article to turn the setting on.
You’ll then be provided with a randomly generated set of words that will make up your new static domain. It’ll look something like persuaded-curiously-duckling or something equally silly. So then your static domain will look like persuaded-curiously-duckling.ngrok-free.app.
Once we setup our Rails app in Part 2, we will utilize ngrok via the terminal to expose our local Rails app to the internet via our new static domain. The terminal command would look something like:
ngrok http --domain=persuaded-curiously-duckling.ngrok-free.app 3000Here, we’re telling ngrok to expose JUST port 3000 on our local computer (the same port our Rails app will be listening/running on) via http and using our static domain.
We’ll touch on this more in Part 2, including initial setup steps for viewing our ngrok pages in a browser and steps to configure Rails to work with ngrok.
Let’s continue on to Part 2: Creating a Rails 7 App and Connecting to BigCommerce.
