Getting started with your Boson app

The aim of this tutorial is to allow you to start verifying the identity of your users using OAuth2 APIs fast.

What is Boson?

Boson is a storage of verified identity claims for it’s users. For example, a user may claim that they own a specific Facebook account and they are a citizen of Poland, or link their Ethereum address to their social account. We take those claims and verify their truthfulness to the best of our abilities, while at the same time providing easy APIs to external businesses and applications (meaning you) to know and require status of specific claims, so you can decrease the fraud and satisfy legal requirements such as Know-Your-Customer and Anti-Money-Launder legislations without the need to manually and costly verify users on your side.

1. Create application definition

Example filling of your company registration information

After creating an account on Boson go into settings and into API access. Since you’ll be working with sensitive user data and so we need more details about you/your company, please fill them out and afterwards create a new OAuth app.

• The name, description and homepage will be visible to users when they use your application
• After you ask your user to verify their data using Boson they will be redirected back to you using the Redirect URIs
• Scopes are data that you request to get from the system. User will explicitly be told what data you want and will have to confirm their decision

For this example, we want to connect user’s telephone number to their social profile — Facebook. Let’s choose require:phone and require:facebook scopes and press create.

Your Client ID and Client Secret will be needed in your code, keep the tab open.

2. Create minimal website

We’ll be using NodeJS + Express for the website routing + simple-oauth2 library for connection with Boson. OAuth is a protocol working on HTTP and thus independent on the programming language, similar OAuth2 libraries exist in your language too.

Let’s think of the user flow we want to have:

1. User enters your website, sees a link asking them to verify
2. When clicked, user is redirected to Boson’s website asking him to verify/confirm status that phone/Facebook are verified
3. User is redirected back to your website, data is saved into a session, user is redirected back to starting page
4. Now their status is always shown until the user deletes session cookies

Your website needs 2 routes, GET method is enough.

• /_oauth2/boson — This is the redirect URI you entered on Boson.me, if you change it, you need to do so in both places
• / — The main route, this what will greet the user when he enters your website

Let’s create the routes

const express = require('express')
const app = express()
app.get('/', (req, res) => {
  res.send("Main page")
});
app.get('/_oauth2/boson', (req, res) => {
  res.redirect('/')
  res.end()
});

3. Add OAuth2 authorization

Now we’re going to add simple-oauth2 into the mix. OAuth endpoints can vary between server implementations, that’s why our’s can be found in the documentation.

They are:

• https://app.boson.me/oauth2/authorize — where the user is redirected after starting the login process
• https://app.boson.me/oauth2/token — which is called your server-side after getting a login code in the callback from the authorized user

A more thorough, but still understandable explanation of OAuth2 can be found here.

...
const host = 'https://app.boson.me/'
const oauth2 = require('simple-oauth2').create({
  client: {
    id: '<YOUR APP ID>',
    secret: '<YOUR SECRET ID>'
  },
  auth: {
    tokenPath: '/oauth2/token',
    authorizePath: '/oauth2/authorize',
    tokenHost: host,
  }
});
const authorizationUri = oauth2.authorizationCode.authorizeURL({
  redirect_uri: 'https://<YOUR WEBSITE>/_oauth2/boson',
  scope: 'require:facebook require:phone'
})
...
app.get('/', (req, res) => {
  return res.send('<a href="' + authorizationUri + '">Verify!</a>')
})

Now after the user authorizes, and the callback gets called, let’s get the user’s status and save it in Express-Session so we can reload it whenever we want

...
const session = require('express-session')
const request = require('request')
...
const app = express()
app.use(session({
  secret: 'this should be a better secret',
  resave: false,
  saveUninitialized: true
}))
...
app.get('/_oauth2/boson', (req, res) => {
  oauth2.authorizationCode.getToken(
    {code: req.query.code},
    (err, result} => {
      if (err) {
        console.log('getToken err: ', err.message)
        return res.json('Authentication failed')
      }
      request(
        host: host + '/api/v1/user/me',
        { headers: {
            Authorization: `Bearer ${result.access_token}`
        }},
        (err, response, body) => {
          if (err) {
            console.log('user/me err: ', err.message)
            return res.json('Getting data failed')
          }
          req.session.me_data = body
          res.redirect('/')
          return res.end()
        }
      )
    }
  )
})

As you can see we’re doing two server-side GET requests to Boson in the callback, first to get the token for the user, and second to get the user’s data and save it into their’s session.

The cherry on top is displaying that data to the user:

...
app.get('/', (req, res) => {
  if (req.session.me_data) {
    res.write('Your data:')
    res.write(JSON.stringify(req.session.me_data))
    return res.end()
  } else {
    return res.send('<a href="' + authorizationUri + '">Verify!</a>')
  }
})
...

And voila, your app is now getting useful data from Boson

• You can find more examples on our Github repo
• And read the documentation

Now go ahead and create your own app!

If you have any additional questions, go ahead and e-mail hello@boson.me