Passage offers developers a frictionless process to implement passwordless user authentication into their application. In this guide, learn how to build a simple Rails application that uses Passage for biometric authentication.
Users will log in to your application using the biometrics built into their devices (e.g. Face ID, Touch ID, Windows Hello, etc.) or with magic links sent to their email. The app will be built such that authenticated users can view a simple dashboard, while unauthenticated users will be blocked. This article will walk you through how to create a Rails app, set up the views and controllers , and authenticate users with Passage.
If you are already familiar with Rails, you can go straight to our full example application on GitHub or skip to the "Add User Authentication with Passage" section to learn how to integrate biometric authentication into an existing application.
You will need to have ruby >= 2.7.0 on your machine. In addition if you do not already have Rails install run gem install rails To create a Rails app run:
In this application, we will have two views - the Home view and the Dashboard view. The Home view will contain Passage’s <passage-auth> custom element, which enables user authentication. The Dashboard view will be an authenticated route and will block any unauthenticated users from viewing the dashboard.
Let's start with building the Home view app/views/home/home.html.erb:
Now we will build a placeholder authorized view app/views/dashboard/authorized.html.erb:
And unauthorized view app/views/dashboard/unauthorized.html.erb:
Now that the basic views are implemented, let’s setup the routes in config/routes.rb:
Create the two controller files:
Lets start by building Home controller app/controllers/home_controller.rb:
Now let’s build the foundation for the Dashboard controller app/controllers/dashboard_controller.rb:
To run the app from this point forward to see progress and test out added functionality run:
Now it is time to add passwordless authentication to your application using Passage. We are going to need to add a script tag to the Home view allowing for us to use the passage-auth custom element
Add the script tag in the view where you intend to authenticate users. In this case, app/views/home/home.html.erb
Importing this script will register the Passage custom element for use in your Rails view. For more information about custom elements refer to the online documentation.
Create an application in the Passage Console (here) with the following settings:
Below is a screenshot from creating a Passage App in the Passage Console:
Once the application has been created, copy the Application ID from the console into a .env file in the root of Rails app’s repository.
Now let’s setup the Rails environment, so that this App ID value can be used throughout the rest of the app. To do this, use the gem dotenv-rails and add gem 'dotenv-rails' to the app’s Gemfile.
Now add this code in config/application.rb:
Now let’s move back to the Home view and setup user authentication app/views/home/home.html.erb
Now it is time to prevent unauthenticated users from accessing the dashboard page. We will be using the passagidentity gem to authenticate requests and get user information to display on the authenticated dashboard.
To use this gem add gem 'passageidentity' to the app’s Gemfile.
In addition to this, create an API Key in the Passage Console for your app:
Copy the value after it has been created and add it to the .env file at the app’s root:
Note: Passage API Keys are sensitive! You should store them securely along with your other application secrets.
Also add, config.passage_api_key = ENV['PASSAGE_API_KEY'] to config/application.rb.
Now let’s add authentication to the application_controller to authenticate requests in the Rails application app/controllers/application_controller.rb:
Let’s add this authorize! function to the dashboard_controller and add a function to get information about the currently authenticated user.
Now that these controllers have been implemented, move back to app/views/dashboard/authorized.html.erb and add this code to build a basic authenticated dashboard.
Let’s add to app/views/dashboard/unauthorized.html.erb to make a better unauthorized view:
Now unauthenticated users that visit /dashboard will be shown the unauthorized page, while authenticated user will be shown their Passage User Name.
To make this app more complete, let’s add a header and footer to app/views/layouts/application.html.erb. Replace the body with the code below:
Notice that styling has been to all of these views. Below is some styling to be added to app/assets/stylesheets/application.css for a more polished final application:
Now run the app, to see Passage biometric authentication in action:
Congratulations! You now have a Rails application that utilizes passwordless authentication. Biometric authentication, as you hopefully can see, is both frictionless to implement with Passage and effortless for end users to authenticate themselves.
You can see the finished application on GitHub here.
To learn more about Passage and biometric authentication for web applications, you can:
Passage is in beta and actively seeking feedback on the product. If you have feedback, bug reports, or feature requests, we would love to hear from you. You can email us at support@passage.id or fill out this form.