Skip to content
An OAuth-compatiable service based on Ethereum credentials to authenticate users on a website. See live version at
JavaScript HTML CSS Dockerfile
Branch: master
Clone or download
Latest commit 143c3f7 Oct 30, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
components Update ENS Sep 10, 2019
config Remove extra commas in config Sep 2, 2019
models Support omniauth + oauth2 Oct 30, 2018
public Clean normalize.css Sep 12, 2019
views Clean normalize.css Sep 12, 2019
.dockerignore Add: Dockerfile Oct 8, 2018
.eslintrc fix: eslintrc format error Aug 6, 2019
.gitignore pm2 config Sep 3, 2019
.sequelizerc seeding oauth clients Jul 25, 2019
Dockerfile update docs & versions Aug 29, 2019
LICENSE update LICENSE Aug 5, 2019
index.js Update ENS Sep 10, 2019
package-lock.json Update ENS Sep 10, 2019
package.json Update ENS Sep 10, 2019
pm2.config.js.example pm2 config Sep 3, 2019

Eauth Server

An OAuth2-compatible service based on Ethereum credentials to authenticate users on website.


Eauth - Decentralized Identity Authentication on Ethereum

Gitlab OAuth with Eauth:

Usages: eauth-examples


Installing dependencies: You can use npm i --no-optional instead of npm i to speed up this step if you're not using ENS and web3.

  1. Copy a configuration:

    cp config/config.json.example config/config.json
    ln -s  ../../../config/config.json components/oauth/config/config.json

    You can also execute cp components/oauth/config/config.json.example components/oauth/config/config.json and fill in database configs instead of linking config/config.json to components/oauth/config/config.json if you want to use another database for OAuth.

  2. Configure your config/config.json accordingly. Edit the following entries:

      "development": {
        // app secret
        "secret": "YOUR_SECRET_HERE",
        // your brand name
        "banner": "YOUR_BANNER_HERE",
        // use the connection path from this environment variable, if specified
        "use_env_variable": "CONNECTION_PATH",
        // rpc for ENS and contract wallets
        "rpcURL": "",
        // prefix showing with token
        "messagePrefix": "This is a prefix example\n\ntoken:\n----------\n",
        // component configs
        "components": {
           "ui": true,
           // Fortmatic ui component
           "fortmatic": true,
           // OAuth component
           "oauth": true,
           // isValidSignature feature for ERC-1271
           "contract": true,
           // ENS feature for OAuth and contract wallet
           "ens": true,
           // qrcode for remote login
           "qrcode": true
        // session lifetime for OAuth
        "sessionMinutes": 1,
        /* or fill in database-related configs... */
      "test": { /* ... */ }
      "production": { /* ... */ }

    Note that you may need to install additional packages to operate on databases.


    Let users access blockchain apps from anywhere 💻📱 - without forcing them to wrestle with browser extensions, wallets, or seed phrases, see more at



Start the server: node index.js.
Test it on http://localhost:8080/.

Using PM2

npm i -g pm2
cp pm2.config.js.example pm2.config.js
pm2 start pm2.config.js --env development // development mode on port 8080
pm2 start pm2.config.js --env production // production mode on port 80


docker build -t pelith/node-eauth-server .
docker run --net=host  -d pelith/node-eauth-server

Setup OAuth Clients

  1. setup your client_id, client_secret, redirect_uri in components/seeders/20190725062038-oauth_clients.js
  2. seeding them with npx sequelize db:seed:all


This service requires a wallet which supports eth_signTypedData, personal_sign or customized method for your contract wallet. For first-time visitors, the simplest setup is to include a MetaMask download badge before proceeding to the authentication page.

Browser Extensions (MetaMask) Mobile Wallets (imToken / Trustwallet) Other SDK (Fortmatic)
MetaMask badge MetaMask badge MetaMask badge MetaMask badge
  1. In the page /, you can decide to login with your Ethereum wallet or contract wallet which implements ERC-1271.

Main Page

  1. For Ethereum wallet, there is no email/id/password input fields. Instead, you gotta sign in with your Ethereum credentials. If your MetaMask is locked or in the privacy mode, it would prompt you to unlock. You can also scan the QR Code to open the URL with your mobile wallet (imToken or Trustwallet), then sign the message for authentication through socket.

Login with Ethereum

  1. In your wallet, you should check the banner and the prefix of message, usually the brand name of a site. The challenge message should contain a token string. If it's the correct info from the site you are about to login, click "Sign" or "Confirm" to proceed.

Signing Process

  1. Next, your wallet address is shown and you are asked for authorization. This step is to bind that wallet address to your account. Click "Authorize" to proceed, or click "Use another account" if this is not the account you intend to use.


  1. If everything is fine, you will be redirected back to the original site. Clicking "Logout" will log you out and reset the session.

  2. For contract wallet, you'll have to input your contract address (ENS is also acceptable if the feature is enabled), Click "Use Contract" and choose your way to verify.

Contract Input

  1. The eth_signTypedData and personal_sign will both works if you implement the ERC-1271 like this. The signing process will be the same as Ethereum login. However, if you're using customized signature for verification, click "Customized Sign".


  1. For Customized Sign, server will return the full message for signing and the hexed message after web3.sha3(message). Sign the message with your customized way and fill the signature below. Click "Verify Signature" to login with your contract wallet.


Discourse Integration

  1. Install discourse-eauth plugin by following this guide.

  2. Enable the plugin at /admin/site_settings/category/plugins. Setup Plugin Configs

  3. Set max username length up to 42. Remember to setup username change period if you're allowing users to edit their username instead of using the address they registered. username length edit username

  4. Setup OAuth client and use http://your.domain/auth/eauthoauth2/callback as your OAuth redirect_uri

  5. Finally, enjoy!

You can’t perform that action at this time.