Rails - Integrate your backend¶

Minimal example¶

The following example is of a controller which can only be accessed from logged-in users.

class WhoamiController < ApplicationController
  before_action :require_user

  def index
    render json: @user
  end
end

How it works¶

You've seen that the frontend gets an access token. When it makes an HTTP request, it provides this access token in an Authorization header.

PropelAuth provides you with metadata that you use to validate the access token and figure out who it belongs to. The complexity of fetching the metadata and validating the tokens is hidden in the Rails library.

Install¶

In your Rails app, install the propelauth gem.

$ gem install propelauth

and add the following to your Gemfile

gem "propelauth"

Configure¶

Go to your PropelAuth project and click Backend Integration in the sidebar. You will see:

Auth URL - This is where your authentication pages are hosted, and you will need this for the setup step.
API Keys - You will need to create a key for the setup step.
Token Verification Metadata - You will pass this into the PropelAuth gem to verify access tokens.

Then in config/application.rb, configure PropelAuth:

    PropelAuth.configure do |config|
      config.auth_url = ENV["AUTH_URL"]
      config.api_key = Rails.application.credentials.propelauth_api_key
      config.public_key = ENV["PUBLIC_KEY_PEM"]
    end

You can either set these values directly, use environment variables, or use the built-in credential store.

Set up¶

With this backend library, there are two main tasks you can do: 1. Fetching user/organization data from PropelAuth 1. Making sure users are authenticated when they call on of your APIs

You are already set up to do the first one. In order to protect API routes, you'll need to add the following to app/controllers/application.rb:

class ApplicationController < ActionController::API
  include PropelAuth::AuthMethods
end

By including PropelAuth::AuthMethods, your controllers will be able to check if a valid access token was provided.

Usage¶

There are three methods you can use in your controller to protect your routes: require_user, optional_user, and require_org_member.

require_user¶

class WhoamiController < ApplicationController
  before_action :require_user

  def index
    render json: @user
  end
end

The code example above does a few things:

Checks that a valid access token was provided. If not, the request is rejected with a 401 status code. This all happens in require_user
Set @user with the user's id and organization information
Returns the user to the frontend as json

optional_user¶

Similar to require_user, except if an access token is missing or invalid, the request is allowed to continue, but @user will be nil.

class WhoamiController < ApplicationController
  before_action :optional_user

  def index
    if @user.nil?
      render json: {}
    else
      render json: @user
    end
  end
end

require_org_member (B2B only)¶

class WhoamiController < ApplicationController
  before_action do
    require_org_member(params[:org_id], minimum_required_role: PropelAuth::UserRole::Admin)
  end

  def index
    # both @user and @org are set
    render json: @org
  end
end

require_org_member is responsible for both checking that the access token belongs to a valid user AND that that user is a member of the specified organization. In the above code snippet, we are taking an org_id from the path parameters, and checking to see if the user is at least an Admin within that organization.

This will set both @user and @org with the user and organization information.

Other utilities¶

You can also make API requests to PropelAuth to fetch additional information about your users. As one example:

PropelAuth::Client.fetch_users_in_org("6c5919ea-6610-4e4f-a4fc-089122eb4ae8")

will fetch all the users in a specified organization. See PropelAuth::Client for everything you can do.

Next Steps¶

Done with your backend? Next you can deploy to production.