AuthRocket/Ruby

The authrocket gem works with both Rails and plain Ruby. It will auto-detect Rails and enable Rails-specific features as appropriate.

It covers all of our Core API and select portions of the Configuration API.

For our Getting Started guide, see Integration with Rails or Integration with Ruby.

Usage - Rails

AuthRocket includes a streamlined Rails integration that automatically handles logins and logouts. For a new app, we highly recommend this.

To your Gemfile, add:

gem 'authrocket', require: 'authrocket/rails'

Then ensure the following environment variable is set:

LOGINROCKET_URL    = https://sample.e2.loginrocket.com/

If you’ve changed the default JWT key type to HS256, you’ll also need this variable:

AUTHROCKET_JWT_KEY = jsk_SAMPLE

If you plan to access the AuthRocket API as well, you’ll need these variables too:

AUTHROCKET_API_KEY = ks_SAMPLE
AUTHROCKET_URL     = https://api-e2.authrocket.com/v2
AUTHROCKET_REALM   = rl_SAMPLE  # optional

Finally, add a before_action command to any/all controllers or actions that should require a login.

For example, to protect your entire app:

class ApplicationController < ActionController::Base
  before_action :require_login
end

Selectively exempt certain actions or controllers using the standard skip_before_action method:

class ContactUsController < ApplicationController
  skip_before_action :require_login, only: [:new, :create]
end

Helpers are provided to create login, signup, and logout links, as well as for users to manage their profile:

<%= link_to 'Login', ar_login_url %>
<%= link_to 'Signup', ar_signup_url %>
<%= link_to 'Logout', logout_path %>
<%= link_to 'Manage Profile', ar_profile_url %>

Both the current Session and User are available to your controllers and views:

current_session # => AuthRocket::Session
current_user    # => AuthRocket::User

The current Membership and Org (account) are accessible through helpers as well.

current_membership
current_org

If a user is a member of more than one org (account), current_membership and current_org will be reflect the currently selected account. Additional helpers are available to provide appropriate links to your users:

<%= link_to 'Manage current account', ar_account_url %>
<%= link_to 'Switch accounts', ar_accounts_url %>

See below for customization details.

Usage - everywhere else

If you aren’t using Rails, or if the streamlined integration above is too opinionated, use the gem without the extra Rails integration.

In your Gemfile, add:

gem 'authrocket'

Then set the following environment variables:

# If accessing the AuthRocket API:
AUTHROCKET_API_KEY = ks_SAMPLE
AUTHROCKET_URL     = https://api-e2.authrocket.com/v2  # must match your provisioned cluster
AUTHROCKET_REALM   = rl_SAMPLE  # optional
#
# If using JWT-verification of AuthRocket's login tokens:
AUTHROCKET_JWT_KEY = SAMPLE

Configuration

By default, AuthRocket automatically loads credentials from environment variables. This is optimal for any 12-factor deployment. Supported variables are:

AUTHROCKET_API_KEY = ks_SAMPLE
Your AuthRocket API key. Required to use the API (but not if only performing JWT verification of login tokens).

AUTHROCKET_JWT_KEY = SAMPLE
Used to perform JWT signing verification of login tokens. Not required if validating all tokens using the API instead. Also not required if LOGINROCKET_URL is set and RS256 keys are being used, as public keys will be auto-retrieved. This is a realm-specific value, so like AUTHROCKET_REALM, set it on a per-use basis if using multiple realms.

AUTHROCKET_REALM = rl_SAMPLE
Sets an application-wide default realm ID. If you’re using a single realm, this is definitely easiest. Certain multi-tenant apps might use multiple realms. In this case, don’t set this globally, but include it as part of the :credentials set for each API method.

AUTHROCKET_URL = https://api-e2.authrocket.com/v2
The URL of the AuthRocket API server. This may vary depending on which cluster your service is provisioned on.

LOGINROCKET_URL = https://SAMPLE.e2.loginrocket.com/
The LoginRocket URL for your Connected App. Used by the streamlined Rails integration (for redirects) and for auto-retrieval of RS256 JWT keys (if AUTHROCKET_JWT_KEY is not set). If your app uses multiple realms, you’ll need to handle this on your own. If you’re using a custom domain, this will be that domain and will not contain ‘loginrocket.com’.

It’s also possible to configure AuthRocket using a Rails initializer (or other initialization code).

AuthRocket::Api.credentials = {
  api_key:         'ks_SAMPLE',
  jwt_key:         'SAMPLE',
  loginrocket_url: 'https://sample.e2.loginrocket.com/',
  realm:           'rl_SAMPLE',
  url:             'https://api-e2.authrocket.com/v2'
}

Customizing the Rails integration

The built-in Rails integration tries to handle as much for you as possible. However, there may be times when you wish to modify the default behavior.

Logins

The Rails integration handles logins on any path by detecting the presence of ?token=.... It will process the login and then immediately redirect back to the same path without ?token=. This helps prevent browsers and bookmarks from accidentally saving or caching the login token.

Likewise, the built-in handler for before_action :require_login will automatically redirect to LoginRocket when the user is not currently logged in. ?redirect_uri=<current_path> will be automatically included so that the user returns to the same place post-login. You can override this behavior by replacing before_login.

# For example, to force the user to always return to "/manage":
def require_login
  unless current_session
    redirect_to ar_login_url(redirect_uri: "/manage"), allow_other_host: true
  end
end

AuthRocket will verify the domain + path to redirect to. You can configure this at Realm -> Settings -> Connected Apps -> (edit) -> Login URLs. The first URL listed will be the default, so it should generally match your “just logged in” path.

Paths are validated as “equal or more specific”. That is, if Login URLs contains https://my.app/manage, then any path starting with /manage will be allowed, but /other will not be allowed. If you want to allow any path at your domain, add https://my.app/ (since / will match any path).

Logouts

The default post-logout path

Upon logout, the user will be returned to the root path (“/”).

This default path may be changed using an initializer. Create/edit config/initializers/authrocket.rb and add:

AuthRocket::Api.post_logout_path = '/other'

/logout route

The default route for logout is /logout. To override it, add an initializer for AuthRocket (eg: config/initializers/authrocket.rb) and add:

AuthRocket::Api.use_default_routes = false

Then add your own route to config/routes.rb:

get 'mylogout' => 'logins#logout'

The logout action

AuthRocket’s default login controller automatically sets a logout message using flash.

You may customize this, or other logout behavior, by creating your own LoginsController and inheriting from AuthRocket’s controller:

class LoginsController < AuthRocket::ArController
  def logout
    super
    flash[:notice] = 'You have been logged out.'
  end
end

If you wish to replace all of the login logic, create a new controller that doesn’t inherit from AuthRocket::ArController (and also override the routes, as per above). You may wish to look at ArController as a reference.

Verifying login tokens

If you’re not using the streamlined Rails integration, you’ll need to verify login tokens on your own (unless you’re using the API to authenticate directly).

JWT verification

AuthRocket’s login tokens use the JWT standard and are cryptographically signed. Verifying the signature is extremely fast. Here’s an example:

def current_user
  @_current_user ||= AuthRocket::Session.from_token(session[:ar_token])&.user
end

from_token returns nil if the token is missing, expired, or otherwise invalid.

API verification

AuthRocket also supports Managed Sessions, which enables you to enforce logouts, even across apps (single sign-out!). In this instance, the session is regularly verified using the AuthRocket API.

def current_user
  @_current_user ||= AuthRocket::Session.retrieve(session[:ar_token], cache: { expires_in: 15.minutes })&.user
end

For better performance (and to avoid API rate limits), you will want to cache the results of the API call for 3-15 minutes.

If using Rails, Rails.cache is used by default. Otherwise, you must configure a cache store for AuthRocket. In either case, see Caching below.

Initial login

Each of the above are designed for ongoing use. The initial login isn’t going to be much different though. Here’s an example login action:

def login
  if params[:token]
    if AuthRocket::Session.from_token(params[:token])
      session[:ar_token] = params[:token]
      redirect_to '/'
      return
    end
  end
  redirect_to AuthRocket::Api.credentials[:loginrocket_url], allow_other_host: true
end

Changing locales

The AuthRocket Core API supports multi-locale access. See Localization for the currently supported locales and other details.

If you are using the streamlined Rails integration alongside LoginRocket, it may not be necessary to set the locale for API access. The locale is primarily used for generating localized error messages. This is only useful for API operations that might generate errors. When handling logins and signups via LoginRocket, LoginRocket will handle all of this for you.

When the Accept-Language header is not sent, the API defaults to English.

Global locale

To set a global locale for your app, add this to your AuthRocket initializer:

AuthRocket::Api.default_headers.merge!(
  accept_language: 'en'
)

Per-request locale

If your app supports multiple locales, then you’ll likely want to set the locale on a per-request basis. Add a headers: { accept_language: 'en' } argument to relevant API calls:

AuthRocket::User.create(
  email: 'jdoe@example.com',
  password: 'secret!',
  headers: { accept_language: 'en' }
)

Caching

The AuthRocket gem is capable of caching the results of GET requests. Since authentication and user data generally needs to be timely, this is opt-in on a per-request basis. The most common use is when validating sessions via the API.

To enable caching, a cache store must be configured. On Rails, authrocket automatically uses Rails.cache, so simply ensure that’s setup appropriately.

If not using Rails (or if you wish to use a different cache store even when using Rails), add this to your AuthRocket initializer:

cache_options = {} # app specific
AuthRocket::Api.cache_store = RedisCacheStore.new(cache_options)

Any Rails-compatible cache store should work.

Next, enable the cache for specific API calls:

# To avoid caching for too long, it's recommended to set a specific expiration time.
AuthRocket::Session.retrieve(token, cache: { expires_in: 5.minutes })

# However, it's possible to leave out :expires_in and use the cache store's default.
# Warning: Ensure the cache store has a default expiration, otherwise cache entries
# will last forever!
AuthRocket::Session.retrieve(token, cache: {})   # These are identical
AuthRocket::Session.retrieve(token, cache: true)

# All options in cache: { ... } are passed directly to the cache store, so anything
# supported by your cache store is valid.
AuthRocket::Session.retrieve(token, cache: { expires_in: 15.minutes, force: true })

Requests

See the AuthRocket API documentation for available APIs, parameters, and responses, all with Ruby-specific examples.

Overview of common requests

Most resources support some or all of the below. Check specific APIs to confirm existence of specific functions.

List [resources]

For any resource with a “List [resources]” method, both all() and first() are available.

# Retrieve multiple resources at once
results = AuthRocket::Org.all
results[0].id  # ID of the first returned resource

# Retrieve the first 20 resources
results = AuthRocket::Org.all(max_results: 20)

# Retrieve the next 20 resources
if results.more_results?
  results = AuthRocket::Org.all(
    max_results: 20,
    after: results.last.id  # ID of the last resource previously received
  )
end

# A convenience function to retrieve the first resource when the ID isn't known.
# If there are no matching resources, returns null.
result = AuthRocket::Org.first
result = AuthRocket::Org.first(
  state: 'active'
)
result.id  # ID of the returned resource

Get a [resource]

For any resource with a “Get a [resource]” method, both find() and retrieve() are available.

result = AuthRocket::Org.find('org_SAMPLE')
result.id  # ID of the returned resource
result.name  # Name field of the returned resource
# raises an AuthRocket::RecordNotFound exception if ID not found

result = AuthRocket::Org.find('org_SAMPLE',
  some: 'condition',
  ...
)

# retrieve() is identical to find() except that it returns nil if ID not found
if result = AuthRocket::Org.retrieve('org_SAMPLE')
  ...
else
  # not found
end

Create a [resource]

For any resource with a “Create a [resource]” method, both create() and create!() are available.

result = AuthRocket::Org.create(
  name: 'Widgets Inc'
)
if result.errors?
  result.errors  # array of error messages
end
if result.valid?  # opposite of result.errors?
  result.id  # ID of the new resource
end

# Like ActiveRecord, create!() raises an AuthRocket::RecordInvalid
# exception if the new resource cannot be created.
begin
  result = AuthRocket::Org.create!(
    name: 'Widgets Inc'
  )
rescue AuthRocket::RecordInvalid => e
  e.object  # contains the invalid resource
  e.object.errors  # array of error messages
end

Update a [resource]

For any resource with an “Update a [resource]” method, .update(), .update!(), #update(), and #update!() are all available.

# Update a resource without finding it first. Returns updated resource.
result = AuthRocket::Org.update('org_SAMPLE',
  name: 'Widgets Inc'
)
result.errors?  # like create() above
result.valid?   #  "
result.errors   #  "

# Like update(), but raises an AuthRocket::RecordInvalid exception if
# the new resource cannot be updated. See create!() above.
result = AuthRocket::Org.update!('org_SAMPLE',
  name: 'Widgets Inc'
)

# If the resource is already loaded, it can be updated directly too.
# In this case, #update() returns false if there was an error.
# #update!() raises an exception as expected.
resource = AuthRocket::Org.find('org_SAMPLE')
if resource.update(name: 'Widgets Inc')
  # success
else
  resource.errors  # array of error messages
end

resource.update!(name: 'Widgets Inc')

Delete a [resource]

For any resource with a “Delete a [resource]” method, .delete(), .delete!(), #delete(), and #delete!() are all available.

# Delete a resource without finding it first.
# In most cases, returns a pseudo-resource (with just the ID field) on
# success. On occasion the API returns the entire resource.
# In either case, #errors?, #valid?, and #errors are all available,
# just like with #update.
result = AuthRocket::Session.delete('kss_SAMPLE')
result = AuthRocket::Org.delete('org_SAMPLE', force: true)
result.errors?  # like create() above
result.valid?   #  "
result.errors   #  "

# Like delete(), but raises an AuthRocket::RecordInvalid exception if
# the new resource cannot be deleted/updated, likely due to some
# dependency or state validation requirement. See create!() above.
result = AuthRocket::Org.delete!('org_SAMPLE')

# If the resource is already loaded, it can be deleted directly too.
# In this case, #delete() returns false if there was a validation error.
resource = AuthRocket::Org.find('org_SAMPLE')
if resource.delete
  # success
else
  resource.errors  # array of error messages
end

resource.delete!

# Hint: in all cases, if the resource is already deleted, an
# AuthRocket::RecordNotFound exception will be raised.

Per-request credentials, caching, and headers

Credentials may be modified on a per-request basis. If :url is not provided, the global :url value is used. No other global values are inherited. Allowed values are the same as when setting AuthRocket::Api.credentials = { ... }. See Configuration above.

resource = AuthRocket::Org.find('org_SAMPLE',
  credentials: { ... }
)

# Credentials are remembered when updating or deleting an already
# retrieved resource.
resource.update(...)  # Uses same :credentials as above

Caching may also be enabled per-request. See Caching above for details.

resource = AuthRocket::Org.find('org_SAMPLE',
  cache: { ... }
)

Likewise, headers may be added or modified. Headers are merged with the default headers, so only new ones need to be provided.

AuthRocket::Org.create(
  name: 'Widgets Inc'
  headers: { accept_language: 'en' }
)

On the off chance that a resource field name collides with :credentials, :cache, or :headers, resource fields may be placed inside :params. Using :params is allowed at any time, and is occasionally handy for other purposes too.

It’s also worth noting that symbol and string keys are both allowed, and may be mixed and matched as long as they don’t duplicate one another. There’s no need to convert them ahead of time.

# These are the same, but the latter assures that field names cannot
# conflict with other arguments, like :credentials.
AuthRocket::User.create(
  first_name: 'John',
  'last_name' => 'Doe',
  credentials: { ... }
)
AuthRocket::User.create(
  params: {
    first_name: 'John',
    'last_name' => 'Doe',
  },
  credentials: { ... }
)

# Mixing inside and outside :params is not allowed.
AuthRocket::User.create(
  first_name: 'John',           # will be ignored because :params is present
  params: { last_name: 'Doe' }  # will be used
)

Responses

API methods that return multiple results will return an Array with an added more_results? method.

results = AuthRocket::Org.all(max_results: 20)
results.each{|resource| ... }
if results.more_results?
  # retrieve next set of results, show a Next button, etc.
end

Fields may be accessed directly or with Hash syntax.

# These are all the same.
resource.id
resource[:id]
resource['id']

Rails compatibility

Resource objects are quite ActiveModel-like and generally compatible with ActiveView, including Rails form helpers.

One difference is attributes cannot be changed in advance of persistence. Instead, call update(...) directly with new values.

# NOT allowed
resource.name = 'New name'
resource.save

# Do this instead
resource.update(name: 'New name')

While objects cannot be modified in advance, it can still be useful to build a new, empty object for the purposes of rendering a form.

def new
  @resource = AuthRocket::Org.new
end

<%= form_for @resource do |f| %>
  <%= f.text_field :name %>
  ...
<% end %>