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!

How to Implement PushAuth™: iOS 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 (this post)
  3. Android Mobile App tutorial

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 push notifications. This post will help you build the iOS 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:

Step 1: Cloning the Project

The pushauth-sample-app-ios GitHub repository contains the sample iOS mobile app code for this project. Clone the repository to your local machine and open the PushAuthSample.xcworkspace file in Xcode.

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

Step 2: Setting Up and Running the Project

  1. In the top left section of your Xcode window, set the active scheme to PushAuthSample.
  2. Plug your phone into your computer. Your phone’s name will appear as the chosen device next to the active scheme.
  3. Navigate to the “Signing & Capabilities” section of the Xcode project settings.
  4. Check the boxes next to “Automatically manage signing” in the “Signing (Debug)” and “Signing (Release)” sections. This will simplify setup and merge the two into a single “Signing” section.
  5. Choose the “Team” value to match your Apple Developer account.
  6. Set the “Bundle Identifier” to something unique; this value will be used in the next step of the tutorial when you create the Identifier through the Apple Developer site.

After following these six steps, your settings should closely resemble the screenshot above from Xcode. Once everything is set up properly and with your phone still connected to your computer, run the project (Product > Run or Command-R). This screen will show up on your phone:

Step 3: Create an Apple Bundle Identifier

This step requires you to an Apple Developer Program Role with adequate permissions. The role-permissions are listed here.

Navigate to the Identifiers tab on the Certificates, Identifiers & Profiles page of the Apple Developer site. You’ll need to add a new identifier that matches the Bundle Identifier value you set in Xcode in step 6 above. Click the plus symbol next to the title at the top of the page; if you don’t see this symbol, you likely don’t have adequate permissions. Follow these instructions for the subsequent pages:

  1. Register a new identifier page: Keep the default selection (App IDs) and click “Continue”.
  2. Select a type page: Keep the default selection (App) and click “Continue”.
  3. Register an App ID page:
    • Description: enter an appropriate description for this project, e.g. “PushAuth Project”. This value will be displayed as the “Name” on the Identifiers page.
    • Bundle ID: Keep the selection on “Explicit” and enter the exact same value you put as the Bundle Identifier in the Xcode Signing & Capabilities page earlier.
    • Enable Push Notification capability by scrolling down on the page and selecting the checkbox next to “Push Notifications”.
    • Click “Continue”, verify everything was entered correctly, and click “Register”.

Now that you have created an identifier for this project, you can create a push notification certificate associated with this identifier.

Step 4: Create a Push Notification Certificate

UnifyID requires the APNs certificate in *.p12 format to send PushAuth requests to the app. This can be done from the same Identifiers page of the Apple Developer site that you were on in Step 3.

  1. Click on the name of the identifier you just created, e.g. “PushAuth Project”.
  2. Scroll down to the “Push Notifications” row and click on the “Configure” box. Next to this box you should see “Certificates (0)” since you haven’t yet created a certificate associated with this identifier.
  1. In the Apple Push Notification service SSL Certificates pop-up window, click on the “Create Certificate” box under “Production SSL Certificate” then click “Done”.
  1. At this point, you need to create a Certificate Signing Request (CSR) file from your Mac. Click “Learn More” and follow those instructions for doing so. Then upload that file and continue.
  1. Now that you have created a certificate, you must download it locally to export it to *.p12. Click “Download”.
  1. This will prompt you to add the certificate to Keychain Access. Choose a Keychain, e.g. “login”, to add the certificate to and click “Add”.
  1. Then find that certificate in Keychain Access. It may be useful to select the “Certificates” category and utilize the search bar to find the certificate you just added.
  1. Once you have located your certificate, right-click on it and click the option to export the certificate:
  1. Specify a name for the *.p12 file and a location to save it. Make sure the file format is set to “Personal Information Exchange (.p12)” then click “Save”.
  1. You will be prompted to password-protect the exported *.p12 file. Choose to export it without a password; simply click “OK”.

Now you have successfully created a APNs certificate in *.p12 format! This will be used by UnifyID and needs to be uploaded to your project settings through the dashboard.

Step 5: Providing Push Credentials to UnifyID

Now you have an Apple Bundle Identifier and an APNs push certificate. It’s time to provide your push credentials to UnifyID so that PushAuth can send push notifications to the sample app on your phone. Check out the Developer Portal docs here, or follow along the instructions below.

  1. Navigate to the “Push Credentials” section of your project on the Developer Dashboard.
  2. Click on “Choose File” and select the *.p12 file you generated in Step 4 of this tutorial.
  3. Choose the “Development/Sandbox APNs server” option for now since we are sending push notifications to an app that runs directly from Xcode. Later on, choose “Production APNs server” when you need to send PushAuth requests to apps distributed through the App Store or through ad-hoc means.
  4. Click “Add” to complete the upload.

Once the push credentials are successfully uploaded to your project settings, you will see the push credential information displayed:

If you find yourself needing to change the push credentials used for the project, simply click “Edit” and go through the same upload steps with the new credentials.

Step 6: Mobile App Settings

You now have all the values necessary for configuration! Open the sample app on your phone and tap the gear icon in the top right of the 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.

Once you set those two values, you must allow push notifications for the app, then the app is ready to receive your PushAuth login requests!

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

That’s it! You now have a simple login flow that integrates PushAuth. The next post provides a tutorial for building the Android sample PushAuth mobile app. Stay tuned for the rests of the posts in the series and, as always, please share this post and reach out to us with questions, comments or suggestions.

How to Implement PushAuth™: Web Server

Welcome back to the Power of PushAuth™ blog series! The first post provided a comprehensive guide to push authentication — check it out here if you missed it. The next three posts are tutorials offering an end-to-end implementation of PushAuth™ in a simple user login flow and will be broken down as follows:

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

The first tutorial (this post) covers a Ruby on Rails backend that provides a basic user login authentication flow with PushAuth integrated. The second and third tutorials will be instructions on how to run sample iOS and Android apps, respectively. These will be the apps that receive and respond to push notifications initiated by the login process.

By the end of these three tutorials, you will have a website where a registered user can log in with their username and password, receive a push notification on their phone, accept the login request via the push notification, and subsequently be logged in on the website. This flow is shown in the video below.

This is a very simplified version of a real-world application and login flow. You might remember some of the security issues that can be present with push authentication from the previous post, such as trusted device registration, fallback resources, or access revocation. This tutorial does not include solutions for those or user sign-up. Future posts in the series will provide extensions of this simple flow to tackle some of those issues.

Alright, let’s get started!

Setup

To follow this tutorial, you will need:

Step 1: UnifyID Account, Project, and Keys

A UnifyID project will grant you access to UnifyID’s services. In order to create a project, you’ll need to first create a UnifyID account. Once you have an account and project, go to the Developer Dashboard to create an API key and SDK key. Make sure to copy the API key value somewhere safe – you won’t be able to access it later.

This tutorial is using PushAuth project as the UnifyID project name. You can see the configured API and SDK keys on the dashboard view above.

Step 2: Cloning the Project and Installing Dependencies

The pushauth-sample-server GitHub repository contains the code for this project. Clone the repository, navigate into it, install the project dependencies that are listed in the Gemfile, and ensure your Yarn packages are up-to-date:

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

Feel free to poke around the code if you’d like to get a better understanding of what’s going on under the hood. This tutorial won’t go into those details, but a future post in this series will.

Step 3: DB Setup and Running the Server

Now, initialize the database:

$ bundle exec rails db:migrate

Once the database has been initialized you can create users. To create a user, do the following (replacing <your_username> and <your_password> with the values you intend to use for username and password):

$ rails console
> User.create(:username => "<your_username>", :password => "<your_password>").save
> exit

Step 4: Server API Key Storage

This step requires the server API key value you copied in Step 1.

$ EDITOR=vim rails credentials:edit

The above command will open the credentials file in vim. You can replace vim with the name of whichever executable you are most comfortable (atom, sublime, etc.). This will decrypt and open the credentials file for editing, at which point you should add the following entry:

unifyid:
  server_api_key: <your_key_goes_here>

After saving and closing, the credentials file will be re-encrypted and your server API key value will be stored.

Step 5: Running the Server

Now you are able to run the server:

$ bundle exec rails server

Finally, connect to the server by opening http://localhost:3000/ in your browser. This will bring you to the landing page, where you can then navigate to the login page and enter your username and password from above in Step 3:

This brings you to the end of the web server tutorial. After entering the username and password on the login page, you can see that the server is polling for the push notification response before allowing or denying access to the website. Without a way to receive or respond to push notifications, you cannot successfully log in. Stay tuned for the next couple posts of this tutorial installment to complete the flow:

Thanks for following along! Please reach out to us if you have any questions, comments or suggestions, and feel free to share this post.

The Power of PushAuth™

Welcome to the first post in our series on PushAuth™, UnifyID’s push authentication service. This series, outlined below, will help you leverage push authentication to increase the security of your authorization flow.

PushAuth™ Blog Series Content

  1. Comprehensive guide to push authentication: what it is, how it works, and pros and cons of using it.
  2. An end-to-end tutorial of implementing PushAuth™ in a simple user login flow.
    1. How to Implement PushAuth™: Web Server tutorial
    2. How to Implement PushAuth™: iOS Mobile App tutorial
    3. How to Implement PushAuth™: Android Mobile App tutorial
  3. Technical deep-dive into the details of building a web application with PushAuth™ integrated.
  4. A more secure extension of the simple user sign-up flow that includes user registration and trusted device pairing. (Coming soon)

Push authentication is one of the most seamless and secure methods of multi-factor authentication. We want to help you understand its importance and the power it has to upgrade your security!

Table Stakes

Let’s clear up two terms that are critical to understanding what PushAuth is solving:

Authorization = allowing you access to a system

Authentication = verifying your identity

There is a great Medium article that describes those differences in more depth. You could have an authorization flow that requires no authentication, letting all users in without proving anything (please don’t do this). On the other hand, you could have an authorization flow that makes users jump through countless hoops to try to make 100% sure the true user is accessing their account. The magic is in striking a balance between these extremes, ensuring a secure authorization process without excessive user annoyance.

One more term to define before moving forward:

Multi-factor authentication = an authentication method that requires two or more pieces of proof before granting a user access to resources

Multi-factor authentication (MFA) is sometimes referred to as two-factor authentication (2FA). Here is a page on MFA basics provided by NIST.

Why use multi-factor authentication?

Before jumping into push authentication, let’s explain MFA. The three basic authentication mechanisms are:

  1. Knowledge: something you know (password, security question answers, PIN)
  2. Possession: something you have (access badge, ATM card, smartphone, hard token)
  3. Biometric: something you are (fingerprint, face, gait, voice)

As defined above, MFA uses two or more of these authentication mechanisms. There are many security benefits to using MFA. The primary benefit is increased confidence in an authorization flow. This stronger assertion on the user’s identity increases the application’s security. Using MFA mitigates the dangers of poor security habits many users have with passwords, such as writing them down, making them simple or easily-guessed, and reusing them across platforms.

Push authentication is one method of accomplishing MFA. This method usually requires a user to download an app on their phone and register it with their account. The mobile app receives push notifications during the login flow. In doing so, the user establishes two authentication mechanisms: knowledge of their username/password combination and possession of their registered device. Here is an example of using push authentication in a login flow:

A user logs in to a web application by entering their username and password. Upon clicking the button to log in, the server sends a push notification to the app (which the user has already downloaded and registered). The user unlocks their phone and authorizes the request by clicking “Accept” on the notification. The server receives this approved response and proceeds to log the user in to the web app. If the user instead clicks “Deny,” the authentication step fails and the user would not gain access to the web app.

Other types of MFA include SMS codes, phone calls, email codes or magic links, authenticator app verification codes, and hardware tokens. This PCMag article does a good job of aggregating different ways well-known companies offer MFA. In the next section we discuss the advantages push authentication has over other methods.

Why choose push authentication?

In a nutshell, push authentication increases security in a cost-effective manner without affecting usability. This section lists some of the aspects specific to push authentication that make it superior to other methods of MFA.

MFA methodFree tierCost per million
SMS100$6,540
Email1,000$20
Mobile Push Notifications1 million$0.50
  • Convenient and easy to use. We can assume that users who have smartphones are comfortable with using apps and interacting with notifications. This makes using push authentication easy for them, since there is nothing else they need to learn to use or get used to the method. Push notifications are much easier to respond to – there is no typing, clicking links, or copying codes while trying to beat the timer. Authentication happens with a simple and speedy tap on their screen.
  • Secure. The push authentication mobile app is installed securely on users’ devices, so there is no reliability on a user’s accounts with external companies. This out-of-band communication can’t be intercepted at the point of password entry, and it is encrypted from end to end between the application and the secured push authentication provider. The many insecurities of the SMS method led to the downfall of its prominence in this space.
  • Fast. Since authentication requests are sent in real time via notifications, a user can become aware of and deny fraudulent requests when they happen and promptly take action. Unlike some methods of MFA, the user must unlock their device before responding to the request. However, this is a level of friction that users are already familiar with on a day-to-day (or, more realistically, minute-to-minute) basis. For devices with TouchID or FaceID, this process is almost frictionless. This even increases the security by preventing unhindered access to authentication by an attacker.
  • No hardware to manage. Unlike with hardware tokens, push authentication utilizes users’ existing phones. Since most people consider their phone an extension of their body, this also means the hardware is unlikely to be easily or frequently misplaced. When phones are lost or broken, the responsibility is on the user, rather than the service provider, to obtain a replacement.
  • No over-the-shoulder copy-ability. Codes and magic links sent via SMS/email and codes generated in an authenticator app can all be intercepted and used to log in as an attacker. Push notifications don’t contain anything that can be copied or reproduced.

Is push authentication perfect?

Unsurprisingly, like most things, no. On a base level, push authentication requires that every user has a fully-functional smartphone. Without a smartphone, they can’t have the mobile app (and the provider needs to have an application). Without internet connection, their device can’t receive push notifications through the mobile app. In the specific cases of a user’s phone being lost, stolen, or otherwise not in their possession, push authentication will fail. Even if the device is in their possession but out of battery, waterlogged, or otherwise not functional, the same assertion applies. For the sake of argument, let’s assume that none of these scenarios are issues. Push authentication is still not “perfect.”

There are some valid security concerns surrounding the use of push authentication as a method for MFA. Smartphones themselves, where the authentication bit happens, are vulnerable to attacks and viruses. 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. Even with a trusted device, any pre-registered device is a weak point for attacker entry. You can’t ensure that users have their devices protected via a locking mechanism. If they don’t have access into their phone locked, then it’s pretty easy for an attacker to accept a notification on the user’s behalf. Finally, it’s completely possible that a user accidentally approves a fraudulent request on their device without realizing it, or realizing too late.

However, there are solutions to these problems. In the cases of a temporarily out-of-possession device, you can provide fallback resources (one-time passcodes, email or SMS delivery, security questions, etc.) as a workaround for that authentication attempt. If the device is permanently out of possession, such as a ruined or stolen phone, you can provide a method of revoking access from the old device and allowing users to self-sign up and provision the app on a new mobile device. If an attacker gains physical access to the device before access is revoked, it’s likely that the user will have yet another authentication barrier in the form of a passcode, TouchID, or FaceID. While this can be attacked as well, it still raises the bar for entry before access is revoked. With regards to users accepting fraudulent requests on their device, the push notification prompt could be extended to include a unique identifier that is expected to match a value on the web login page. The existence of this would set the expectation that a user is to confirm the value before accepting the request.

However, there’s only so much you can do as a developer. People will still make mistakes, and hackers will still gain access. The main point here is that these are things you, as a developer, should be aware of and address. All things considered – push authentication sits in a pretty great place security-wise, is incredibly low friction, and (perhaps most importantly) incredibly cost-effective. Keep an eye out for our next post of the series, which will walk you through using our open-source project to implement PushAuth yourself!