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.
and add the following to your Gemfile
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
:
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 inrequire_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:
will fetch all the users in a specified organization. SeePropelAuth::Client
for everything you can do.
Next Steps¶
Done with your backend? Next you can deploy to production.