How to Use Bitcoin Based Blockstack Auth in Your iOS Apps by@hammadtariq

How to Use Bitcoin Based Blockstack Auth in Your iOS Apps

Hammad Tariq HackerNoon profile picture

Hammad Tariq

We all know about oAuth and the sites that handle authentication of the users for us. One-click signups and login buttons increase user signups and retention. They are famous among users due to their convenience.

However, this convenience comes with a catch for both app developers and users as, for example, Facebook recently admitted that they track the Facebook users and their usage of other apps through their login button.


I wonder about the intention of other auth providers such as Google, Twitter, Pinterest and so on about providing and maintaining such service for free (there is nothing free, right?) while the primary goal of all of these companies is based on maximizing their own revenue by providing maximum targeting options to their advertisers (except Github, maybe?)

Recently, I have been experimenting with blockchain-based decentralized technologies and in particular using the open-source software written by Blockstack. It’s a decentralized technology that works over blockchain and comes with it’s own identity management, DNS and user-provided storage solution.

I have already written about Blockstack and new decentralized internet in another post.


Blockstack auth uses Bitcoin blockchain as a single point of truth, so if you have identified yourself there and you have provided your social links to build trust, you are basically free of any centralized 3rd parties responsible for authorizing who you are! Pretty utopian? Yeah, I know!

My goal is to create a social network that would entirely function over decentralized technologies and will incorporate tokenized incentives to increase adoption and retention instead of creepily knowing everything about a user, that would in turn get me to modify their behavior etc. to increase the revenue of my app.

During last few days I succeeded in integrating Blockstack Auth into my app, so I thought it will be fun to write a tutorial and let you know about how this new authentication method works.

Enough of the chatter, let’s start the tutorial!


Demo of what we will be making


Example screenshots of Blockstack based Auth in an iOS App

Step 0: Create an ID on Blockstack

Although, you can create an ID as part of the auth we are going to integrate in our iOS app, however, I will encourage you to install Blockstack browser on your system, create an ID and explore how it works!

Step 1: Understanding how Blockstack auth will work with your iOS app

Blockstack uses a Blockstack browser to provide you a window to its new internet. The beauty of this window is that you can host your own copy of it anywhere you want.

On the other hand, when we want to authenticate a user on iOS using Blockstack or any 3rd party, we would need an app or a web page to facilitate us and once a user is authenticated we would need the app or the web page to redirect the user to our iOS app using the URL Scheme we specified in our Xcode project, so that means in the old world we will need to register our app on Facebook and then include their SDK in our app using CocoaPods.

In the new world we will still need to include Blockstack SDK in our project but instead of registering the app with a 3rd party (and totally killing the purpose), we will need to install and host our own web app to interact with Blockstack browser and to manage redirection.

Getting lost? Don’t worry, you will understand this in next few minutes, let’s proceed with setting up the server.

Step 2: Creating your own Node.js server with SSL support

Blockstack has provided an example Node.js web-app to manage the redirection of the auth request. If you have a server (normal hosting server with a TLD directing to it) that can manage running Node.js and has SSL installed, go to step 3.

In any other case, let’s setup one using DigitalOcean.

A word about DigitalOcean, it’s the easiest setup I have found but if you are comfortable with using AWS or any provider, please do so, the only requirement here is a Node server running SSL.

Let’s start with DigitalOcean:

  1. Make an account on DigitalOcean using my referral link. (you will get $10 credit, enough for this example to run for two months and I will get $25 credit that I would not mind at all ;-))
  2. Create the most basic droplet ($5 one) running Ubuntu 16.04.
  3. Setup the server using this initial server setup guide.
  4. Point your domain name (.com, .net, .org, etc.) to new server using this guide.
  5. Install Nginx to your server using this guide. Nginx will be used to setup free SSL on your server. It does not serve any other purpose!
  6. Once that is done, install Let’s Encrypt SSL to the server using this guide.
  7. Open your domain with https from your browser and confirm that everything is working fine.
  8. Now, stop the the Nginx server to free up the 8080 port for our Node.js app using the stop command given here.

Now, let’s setup our Node.js example web-app on our new server.

Step 3: Setup the example Node.js redirect app

To make things work with my setup, I had to modify the example app provided by blockstack. You can download my version from here.

Before going any further, I would like to point-out what I have changed. If you see the server.js in the example app, I have added following code block:

var options = {

key: fs.readFileSync(‘/etc/letsencrypt/live/’),cert: fs.readFileSync(‘/etc/letsencrypt/live/’


That is the default location where Let’s Encrypt saves SSL keys and I found it necessary to let the app know about their location.

Then I had to make some changes where the app starts the server. I had to close the old app.listen method and I have added these two lines:

http.createServer(app).listen(8080);https.createServer(options, app).listen(443);

There is absolutely nothin for you to do here, I have just mentioned to keep these things in mind.

The real gem is in public/redirect.html where you will notice the following line:

window.location=”myblockstackapp://?authResponse=” + authResponse

Pay attention to the “myblockstackapp”, this is your app’s URL scheme and in most cases you will need to change this to your own unique scheme URL.

Modify this in the redirect.html and in your app as well before publishing the app to the app store.

Now, we know what’s going on under the hood, let’s run these commands to install git:

sudo apt-get updatesudo apt-get upgradesudo apt-get install git

Now, let’s clone our web-app repository:

git clone

Open the Bockstack-webapp directory and run these commands:

npm install && npm start

This would install and start the app, if everything goes fine you will see:

server is listening on 8080

Open the domain name in your browser to confirm if Blockstack app is running. You should be able to see the following page:


That confirms your Blockstack web-app is now running!

Step 4: Clone and run the default blockstack-iOS example app

Now, clone or download the official blockstack-ios directory on your computer.

Browse to the “Example” folder and open Blockstack.xcworkspace in your Xcode.

Now, open the ViewController.swift and analyze the code. It’s has the example signIn and signOut methods (and also the putFile method that is related to the Blockstack’s own implementation of Gaia storage — will cover that at another time).

Since, we have installed our own web-app for redirection, we will have to change the following code to our own URLs and in this case we will need to specify the server port as well.

Change the following code:

Blockstack.shared.signIn(redirectURI: “", appDomain: URL(string: “")!)

To this code:

Blockstack.sharedInstance().signIn(redirectURI: “",

appDomain: URL(string: “")!)

Don’t forget to update with your own domain name!

Step 5: Run the app

Moment of truth, let’s run the app!

If all goes well you should be able to see the below “Sign In with Blockstack” button on your iPhone screen:


Now, if you click the button, you will be redirected to the blockstack browser to create or choose a Blockstack ID:


After that, you will be redirected back to your example app and will see your profile name on the screen:


That’s it! You now know how the Blockstack Auth works with iOS apps!

Error handling and integration with your own app

Blockstack contributors are continuously changing the codebase. It’s always advised to go with the latest repo update and only use this tutorial as a reference. However, if you get stuck somewhere, you can always try with my fork of blockstack-ios repository.

To integrate the Blockstack with your own app, simply install “Blockstack” with CocoaPods as described in the README file and copy-paste the example ViewController.swift to your own project. Don’t forget to add the URL scheme by opening info tab in your project’s settings.

That’s about it you are a pro now in using Bitcoin based decentralized authentication method with your own apps!

Happy Coding! :-)

react to story with heart
react to story with light
react to story with boat
react to story with money

Related Stories

. . . comments & more!