The Power of Trusted Device Registration

Welcome once again to the Power of PushAuth™ blog series! This post builds on the previous posts by providing an extension of our sample project with feature and security enhancements.

The Problem of Unchecked Device Registration

In the “Is push authentication perfect?” section of the first post in the series, we pointed out some shortcomings of relying on push authentication as a means to authenticate users. Recall the following from that section:

“There’s also the issue of trusting a device to be associated with its true user during registration, as well as not allowing attackers to register devices under the true user’s account.”

The first iteration of the open source sample project did not provide a solution to this problem. With that initial, simple implementation of PushAuth, there was virtually no confidence in the devices registered under a given username. If an attacker were able to obtain the SDK key and one or more usernames registered on the server, they could configure the app on their phone and fraudulently accept or reject push notification login attempts. This security hole allows attackers to impersonate true users and access their resources in the website, or to lock a true user out of accessing their own resources. Not great, considering this is supposed to be a method of increasing the security of the authentication flow.

Trusted Device Registration

The extension presented in this post, however, does include trusted device registration! It also provides the added feature of user registration in the website. Remember that the initial project required users to be created in the console. Only users whose username and password were inserted to the database in that manner were able to log in to the website and receive push notifications. Now users register in the website directly. Once a user signs up in the website, they configure the sample app on their phone in order to authorize future login attempts. This is where trusted device registration comes into play.

What’s different for the user?

After dictating what username and password to associate with a new user, the website displays a four-digit pairing code. The user is instructed to enter that pairing code in the sample app with their chosen username. If the values match, then the user will receive push notifications during login attempts and be able to respond accordingly. If the username and pairing code do not match, then registration of that mobile device fails. This means they will not be able to receive push notifications to confirm or deny login attempts. An attacker will not know that unique pairing code, so they are unable to impersonate a user in the app.

How does this work?

The PushAuth sample server now has a verification endpoint, /users/trust, which accepts webhook requests from UnifyID’s PushAuth service. UnifyID’s server makes an HTTP POST request to a configured target URL, which is set in the project’s dashboard. The request body contains the username and the pairing code. The /users/trust endpoint looks up the given username and determines if the provided pairing code matches the server-generated code displayed during that user’s registration. If the request returns 200, then the user is considered verified and the device trusted. However, if the request returns anything else, the user is not considered verified and device registration fails.

The webhook target URL must use the https scheme and requests use the ‘Basic’ HTTP Authentication scheme, which can be used to validate requests. Further, the four-digit alphanumeric code generated by the server is single-use. These details collectively make it harder for an attacker to impersonate users. An attacker does not have access to the pairing code during initial sign up and they also cannot reuse the pairing code, thus ensuring that devices registered with users are trusted to belong to the true user.

Note: The way we chose to implement trusted device registration with a pairing code is by no means the only method of implementing trusted registration via webhook.

What are the limitations?

If you remember from our first post in the series, there will seemingly always be security holes in a login flow. This enhancement is no exception. For one, the pairing code is only displayed during user registration. What if the user accidentally closes out the tab and then has no way to pair their device? Or what if something happens with the device or app on their device and they have no way to reconfigure an app to be tied to their user? There’s also the concern of in-person over-the-shoulder access to the pairing code, where an attacker could see the four digits and enter the code on their phone before the true user is able to do so. However, just like before, there are solutions to those problems as well; they just aren’t included here. The extension we provide is certainly a big security improvement and patches one of the larger holes that existed in the initial sample project.

Developer Changes

Now that we’ve gone over the concept of trusted device registration and the value it adds to the PushAuth sample project, we’ll walk you through the actual changes from a developer’s perspective. The new repositories can be found here:

Trusted Registration Webhook

First and foremost, you’ll need to enable trusted registration for your project in the dashboard. Reference the Setting up Trusted Registration section of our documentation to do so.

The server needs to be publicly available for the target URL to be used. If you want to follow along the tutorial without hosting the web server, we suggest using ngrok to expose the sample rails server running locally on your machine to the internet. The steps shown in this post will do that.

$ ngrok http 3000

Session Status                online
Account                       morganfrisby (Plan: Free)
Version                       2.3.35
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://9c6b07ea6861.ngrok.io -> http://localhost:3000
Forwarding                    https://9c6b07ea6861.ngrok.io -> http://localhost:3000

The target URL is the https URL forwarding to your local server, with /users/trust appended. For example:

Once you add the target URL, trusted registration is enabled for your project. The username and password displayed are used in HTTP Basic Authentication. The username value is set to unifyid, and the password is an auto-generated random string. This value can be rotated, should it become compromised.

Now that the trusted registration webhook is set up in the dashboard, you’re ready to move on to setting up the server.

Server Setup

Other than that, server setup more or less follows the instructions from the first tutorial. Since users are now registered on the website, there is no need to create users in the console during server setup. The other change is the addition of basic_username and basic_password to the credentials file, which are the values found in your project dashboard under the Trusted Registration Webhook section, shown above.

The streamlined steps to spin up the server are now:

$ git clone https://github.com/UnifyID/pushauth-sample-server-reg.git
$ cd pushauth-sample-server-reg
$ bundle install
$ yarn install --check-files
$ bundle exec rails db:migrate

$ EDITOR=vim rails credentials:edit
unifyid:
  server_api_key: <your_key_goes_here>
  basic_username: <basic auth username for /users/trust webhook endpoint>
  basic_password: <basic auth password for /users/trust webhook endpoint>

$ bundle exec rails server

Feel free to reference the detailed tutorial in our previous post for more context around those commands, or the technical details blog post to understand how the server was built. Our next post in the series will provide the technical details of the trusted registration extension of the sample server.

You can see the new website screenshots here (notice the pairing code in the third screenshot):

Sample App Setup

Nothing changes from the developer’s perspective for the iOS and Android sample apps; simply clone the updated repositories and follow the same instructions from earlier in the blog series. Those two posts can be found here:

The iOS sample app screens will look like:

The Android sample app screens now look like:

That’s it! Thanks for following along with the Power of PushAuth™ blog series. The next, and final, post will include the technical details of adding trusted registration to the sample project. Until then, feel free to reach out to us with questions or comments at https://unify.id/contact-us/.

How to Implement PushAuth™: Android Mobile App

This post is part of the Power of PushAuth™ blog series. The first post of the series was a comprehensive guide to push authentication. The next three posts of the series comprise an end-to-end sample implementation of PushAuth in a simple user login flow. The tutorial breakdown is as follows:

  1. Web Server tutorial
  2. iOS Mobile App tutorial
  3. Android Mobile App tutorial (this post)

The tutorial in this post builds on the web server from the first tutorial. With your web server set up and running, you now need a mobile app to receive and respond to notifications. This post will help you build the Android mobile app to do so; then you will be able to leverage the power of PushAuth for login requests!

Setup

To follow this tutorial, you will need:

  • An Android device running Android 7.0 or higher
  • A computer with Android Studio 4.0 installed
  • JDK 8 installed (we recommend using jabba)

Step 1 : Cloning the Project

The sample Android mobile app code for this project is provided in the pushauth-sample-app-android GitHub repository. Clone this repo to your local machine:

$ git clone https://github.com/UnifyID/pushauth-sample-app-android.git

Open Android Studio, select “Open an existing Android Studio project”, and select the directory of the cloned repository. It should look something like this:

Step 2: Set up Firebase Cloud Messaging (FCM)

Firebase Cloud Messaging (FCM) is the platform used to send notifications to Android devices. You will first need to set up Firebase in your app by following the instructions at https://firebase.google.com/docs/android/setup. After doing this, ensure that a google-services.json file is present under the app/ directory of the project in Android Studio.

Next, navigate to the Firebase project settings of your app in your browser and select the “Cloud Messaging” tab. The token labeled “Server key” is what you will need to provide to UnifyID in the next section, so copy that value.

Step 3: Providing Push Credentials to UnifyID

Now you have the Firebase Cloud Messaging (FCM) server key copied, you will provide it to UnifyID so that PushAuth can send push notifications to the sample app on your phone. You’ll provide this value in your project’s dashboard. Follow the instructions in the Developer Portal docs to do so. After you’ve done this, your project dashboard will indicate they are successfully uploaded:

Step 4: Building the Project

Now, back to Android Studio. Make sure that your Android device is plugged in to your computer, has developer tools and USB debugging enabled, and is available in the top center of Android Studio. Also make sure that the google-services.json file is located under the app/ directory of the project.

With everything set up, click the green triangle or press Control+R to run the app. The following screen should appear on your device:

Step 5: Mobile App Settings

You now have all the values necessary for configuration! Tap the gear icon in the top right corner of the sample app’s Configuration screen. For SDK key, enter your UnifyID project’s SDK key value from the Dashboard. The User string should be the same value that you used when creating a user in the web server tutorial, e.g. “Morgan”. If these values do not match, you will not be able to successfully respond to push notifications in the login flow.

After setting those values and clicking “Confirm”, the app is ready to receive your PushAuth login requests! The app will remain on the “Waiting for PushAuth requests” page until it receives a PushAuth authentication request.

Now you can go through the full login flow by entering your username and password on the login page, respond to the notification received by this app on your phone, and be successfully logged into the website.

That’s it! Now you have a simple login flow that integrates PushAuth. Stay tuned for the rest of the posts in the series, make sure to share this post and reach out to us if you have any questions, comments or suggestions!