Authentication: Ethereum and Smart Contracts, Part 3

Welcome back to our Ehtereum and Smart Contracts series. If you missed the first two installment, you can find Part 1 here and Part 2 here. Enjoy! 

Try It Out!

Since this is just a proof-of-concept and getting your feet wet with Ethereum can be a bit hard at first, here is a step-by-step guide for new users to test the system. Please note that this is just a test system so it uses Ethereum's testnet. In other words, no hard guarantees are provided with regard to the integrity of the data stored in the Ethereum testnet, do not put important stuff in the accounts created in this guide, they won't be protected by the same guarantees as the Ethereum mainnet.

Get an Ethereum Wallet

To perform operations in Ethereum you need a wallet. A wallet is an application that allows you to interact with the rest of the network. Wallets store the private-keys for your Ethereum addresses. For simplicity, we will be using Metamask. Metamask is a browser-based wallet that runs locally as a Chrome extension. Keys are stored locally and transactions are signed with them. These are then sent to the rest of the network through a Metamask operated public node.

1. Get Metamask

Go to the Chrome Webstore and install Metamask.

2. Create a New Account

Click on the Metamask icon on the top right corner of your Chrome windows and follow the wizard to create an account. Make sure it is created in the Rinkeby testnet. To check this, after creating the account, click on the icon next to the Metamask fox, on the top left corner of the Metamask window. If you are using another network, just switch to Rinkeby and then follow the wizard again.

3. Get Some Ether

To register you will need a minimum amount of Ether. Fortunately, this is easy to get in the testnet (in the mainnet you must either buy it or be lucky enough to be able to mine it). For the testnet it is possible to use "faucets." Faucets are places to get free Ether. The most popular Rinkeby faucet requires users to create a GitHub gist. This is a simple way to limit misuse of the faucet. Creating gists is easy, you only need a GitHub account. Crate a public GitHub gist and paste your Metamask Rinkeby address in it. Then go back to the faucet and place the link to the gist in the required field, then click on "Give Me Ether" (the faucet is located in the crypto faucet section on the left bar).

After a bit, you should see your newly acquired Ether in Metamask.

To get your Rinkeby Ethereum address, go to Metamask and then click on the "copy" icon next to your account name. This will be your primary Ethereum address. In an actual production system, this would be the address of an account with lots of Ether in it. One that you would not want to expose every time you want to login to some third-party site using your Ethereum address.

Get the Mobile Authenticator App

Now it's time to set up your secondary address and login helper app. This application will be the authentication factor used to confirm your login request. Any time you want to login to some site, you will receive a notification through this app. This notification will allow you to either confirm or deny the authentication request.

1. Get the App

Go to the Android Play Store and download our Auth0 PoC app.

2. Register

Open the app and input your email address. Now choose an unlock pattern. You will be asked to input this same pattern any time you want to login to a site. Then click Register. You will be asked to confirm the registration through the mobile app. Click Sign to confirm it.

The mobile app is now set, let's enable your Ethereum account for logins.

Enable Your Ethereum Address for Logins

This step, like the previous ones, is only performed once. This sets up the mapping between your primary address and the login address. In other words, it connects your Metamask account to the mobile app in your smartphone.

1. Get Your Mobile App (Secondary) Address

If you now look at your emails (please check spam, promotions, etc.) you will find your Ethereum secondary address. This is the address of the account managed through your smartphone. Just copy it to the clipboard.

2. Call The Contract!

If you are an Ethereum user and you have your own wallet, you can perform this step manually. For simplicity, however, we have set up a site that will do the hard work for you. Using the same Chrome instance where you installed Metamask, navigate to our PoC wallet. This site is a simple local-only wallet-like app that creates the Ethereum transaction necessary to call the contract. This site communicated with Metamask so that you don't have to input your account details manually.

Once you are in the site, paste the Ethereum address you copied from the email in the previous step and click Register. A Metamask window will pop-up. This is a confirmation that you are about to make a transaction from your primary account that will spend Ether. Click Sign. After a while your primary and secondary accounts will be connected! The time for this to happen depends on the Ethereum network. In general it is just a few seconds.

In case you are already experienced with Ethereum you may want to perform this step manually. Call the mapAddress method of the Mapper contract located at 0x5e24bf433aee99227737663c0a387f02a9ed4b8a. You can get the JSON API here. The only parameter is the address you got in your email.

After this is done everything is set!

Login to Our Test Site

You may now login to any third party site that supports this authentication method using either your email address or your primary Ethereum address as a credential. Go to our sample website, put in your email address and click Login. Watch your smartphone for notifications to approve your login.

You will notice there is a checkbox labeled Trustless Authentication. As explained before, third parties may opt for different levels of security. They can opt to trust the authentication server when it says the login is valid (trustful authentication) or they may opt to not trust the authentication server and validate the signature internally. In this case, the third-party website must validate the signature of the secondary address itself, first be querying the secondary address using the Mapper contract (which is publicly available) and then by verifying the signature of the returned data using the secondary address to find the public key of the secondary address. This provides the highest level of security and uses the authentication server as simply a messenger.

If you are interested in taking a closer look at how our PoC works, here are all the repositories:

• The authentication server
• The mobile app
• The sample third-party web app
• The registration wallet using Metamask
• Docker scripts for easy testing

There are also a couple of helper libraries that were developed for this PoC, these are used by the repositories above:

• Ethereum crypto helper lib
• JavaScript library for doing authentication as used by this PoC
• A simple database abstraction helper
• Preconfigured Ethereum client node for this PoC