This tutorial walks you through adding Blockstack authentication to a web app. The site you build is a simple Rails site. You don’t require any specialized Ruby or Rails knowledge to build this site. However, if you are a knowledgeable Rails programmer, you should be able to complete or extend this tutorial easily.
- Set up your environment
- Create a Rails website
- Add a homepage
- Install OmniAuth and OmniAuth-blockstack gems
- Add a OmniAuth callback for Blockstack
- Test the Blockstack authentication
Set up your environment
This tutorial requires Ruby 2.0 or higher. To confirm you have Ruby installed and that the version, enter the following:
$ ruby -v ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin16]
After successfully installing Ruby, install the
rails gem. This tutorial was
rails version 5.2.1. You can use the
gem list command to see
gem is already installed. To install the
rails gem, do the following:
$ gem install rails
Create a Rails website
Create a new Rails project by using the
$ rails new blockstack-rails-example
The command generates a project directory.
Change directory to the
$ cd blockstack-rails-example
Start your project with the
$ rails s
sflag is the alias for server.
http://localhost:3000address in your browser.
You chould see default homepage that says
Yay! You're on Rails!.
Go ahead and stop the server by entering
CTRL-Con the command line.
Add a homepage
In this section, you add a homepage to your new website. To do this, you create
a new controller, called
PagesController, that includes the homepage. To set
this up and test this, do the following:
railsto generate the home page.
$ rails generate controller pages home
This command instructs rails to create a
pages, that includes the method
home. After running this, you’ll have a few new files:
/app/controllers/pages/pages_controller.rb- this is the new controller you created, with a
/app/views/pages/home.html.erb- this is the template that rails will use to render the view for
The command also modifies the pre-existing file
/config/routes.rband configures your server to use the
homemethod for the route
/config/routes.rbfile to match the following:
Rails.application.routes.draw do root to: 'pages#home' # For details on the DSL available within this file, see http://guides.rubyonrails.org/routing.html end
This code calls the
rootmethod with the
tooption which instructs rails to use the
homemethod in the
pagescontroller as the homepage.
Save and close the
Start the rails server (
rails s) and open the new homepage, you should see your new homepage.
You can find the source for the home page in the
Install OmniAuth and OmniAuth-blockstack gems
You’ll use the OmniAuth plugin to setup Blockstack authentication. OmniAuth is a popular framework for integrating third-party authentication with a ruby on rails website. Blockstack provides an OmniAuth plugin, OmniAuth-blockstack to make this easy for you.
Stop the Rails server if it is running.
Gemfilein the root of your project and add two gems, one for OmniAuth and one for the Blockstack plugin.
gem 'omniauth' gem 'omniauth-blockstack'
Save and close the
Install the gems by running the
$ bundle installNote:
bundlecommand returns a message:
Your Ruby version is 2.0.0, but your Gemfile specified 2.5.1
Check if the auto-generated.
Gemfileincludes a line that specifies a conflicting Ruby version. Make sure your `ruby` version matches the
ruby -vYou can either switch to that version, or remove the line
ruby '2.5.1'from your
Add a OmniAuth callback for Blockstack
Create a new file at
$ touch config/initializers/omniauth.rb
You’ll use this file to configure the OmniAuth gem and the Blockstack plugin.
Edit your new
config/initializers/omniauth.rbfile and add the following code:
Rails.application.config.middleware.use OmniAuth::Builder do provider :blockstack end
This adds the OmniAuth middleware to your project, and tells OmniAuth to use the Blockstack provider. After a user signs in with OmniAuth, you need to specify a
callbackmethod for Blockstack to handle the rest of the sign in flow.
The callback method is typically where you grab the authentication information from the third party, save some data, and sign the user in to your application by saving information in cookies.
Save and close the
This file defines a
PagesControllerclass where you will add the
blockstack_callbackmethod. When you are done the file should look like the following:
class PagesController < ApplicationController def home end def blockstack_callback puts 'in the callback' blockstack_info = request.env['omniauth.auth'] session[:blockstack_user] = blockstack_info redirect_to '/' end end
putsline is just a debug output to the console. The gets the user’s Blockstack info from
env['omniauth.hash], which is where OmniAuth stores all authentication info. Then, that info is loaded into the
sessionobject under the key
:blockstack_user. By adding this info to the session, the info is saved to a cookie which is easy to reference later on.
/app/views/pages/home.html.erbfile and direct the user to sign in with Blockstack.
Modify the HTML to look like this:
<h1>Pages#home</h1> <p>Find me in app/views/pages/home.html.erb</p> <p><a href="/auth/blockstack">Log In with Blockstack</a></p> <code><%= debug session[:blockstack_user] %></code>
The home page directs the user to sign in with Blockstack. The
<%= debug session[:blockstack_user] %>tag tells rails to output the variable
session[:blockstack_user]in an easy-to-read format.
This page creates a link to the route
/auth/blockstack. By default, OmniAuth adds routes to your application in the form of
/auth/:provider. When the user visits that page, they’re redirected through the third party authentication flow.
- Save and close the
config/routes.rbfile and configure a route to handle the Blockstack callback.
Rails.application.routes.draw do root to: 'pages#home' get '/auth/blockstack/callback' => 'pages#blockstack_callback' # For details on the DSL available within this file, see http://guides.rubyonrails.org/routing.html end
getline tells the your server to invoke the
blockstack_callbackmethod when the user visits
/auth/blockstack/callback. By default, OmniAuth redirects the user to
/auth/:provider/callbackwhenever the users comes back from a third-party login.
- Save and close the
Test the Blockstack authentication
Start the rails server.
$ rails s
You should see the following:
Click the Log In with Blockstack link.
This connect takes you to the Blockstack
Log in with the Blockstack web application.
For information on creating or logging in with a Blockstack identity, see the use a Blockstack identity. After you finish signing in with your identity, you are redirected back to your homepage:
At this point, the Blockstack information is stored in the
If you want to develop your application further, you would use a standard log
out to complete the session. Your code to log out would call
session[:blockstack_user] = nil to destroy the Blockstack information.
Congratulations! You’ve successfully integrated Blockstack authentication into a website. You can now build out a fully-fledged rails app with the ability to use Blockstack for decentralized user authentication.
Let folks know your work by tweeting: Tweet your work!