Eld

Firebase Authentication for Ruby applications.

Installation

Add this line to your application's Gemfile:

gem "eld"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install eld

Usage

Eld takes a Firebase access token and decodes it. Once you've decoded the token, the rest is up to you!

See Firebase Authentication for example client implementations.

Basic Usage

Eld.configure do |c|
  c.firebase_id = "FIREBASE_PROJECT_ID"
end

decoded_token = Eld.authenticate("FIREBASE_ACCESS_TOKEN")
# =>
{
  "iss" => "https://securetoken.google.com/fire-auth-67d5f",
  "aud" => "fire-auth-67d5f",
  "auth_time" => 1679606435,
  "user_id" => "Z02vuFq6RAU1NqVrWrdLAjyiqJ83",
  "sub" => "Z02vuFq6RAU1NqVrWrdLAjyiqJ83",
  "iat" => 1679606435,
  "exp" => 1679610035,
  "email" => "test@test.com",
  "email_verified" => false,
  "firebase" => {
    "identities" => {
      "email" => ["test@test.com"]
    },
    "sign_in_provider"=>"password"
  }
}

user = User.new(decoded_token)

Advanced Setup

Eld.configure do |c|
  # Use one or more Firebase projects
  c.firebase_id = "FIREBASE_PROJECT_ID"
  # c.firebase_id = ["FIREBASE_PROJECT_ID_1", "FIREBASE_PROJECT_ID_2"]

  # Use Redis to cache (recommended)
  # By default we use Eld::Cache::Memory
  # You can also create your own cache implementation.
  c.cache = Eld::Cache::Redis.new(
    client: Redis.new, # Your redis client
    cache_key "eld/certificates" # Optional: This is the default key
  )

  # Use your own authenticator
  # See Eld::Authenticator for an example implementation.
  c.authenticator = CustomAuthenticator
end

Certificates

The default behavior of Eld is to lazily handle caching and fetching certificates from Google when authenticating tokens. This means you don't have to worry about refreshing certificates at any particular interval. However, you can refresh the cache and fetch new certificates whenever you want should you need to.

Eld::Certificate.refresh

Custom Authenticators

You can create your own authenticator and use it as a new default or build it anywhere.

Custom authenticators will still use Eld defaults for caching.

class CustomAuthenticator < Eld::Authenticator
  # The default behavior is to return the decoded token
  # You could add additional behavior like finding or instantiating
  # a user.
  def respond(decoded_token)
    User.find_by(uid: decoded_token['user_id'])
  end

  # The default authenticator swallows JWT errors
  # You might want to handle them on your own.
  def handle_error(error)
    ReportError.call(error)
    false
  end
end

# Set a new default authenticator
Eld.authenticator = CustomAuthenticator
Eld.authenticate(token)
# => User(uid: "1231231")

# Instantiate your own authenticator
authenticator = CustomAuthenticator.new(firebase_id: "FIREBASE_PROJECT_ID")
authenticator.authenticate(token)
# => User(uid: "1231231")

Rails Example

class ApplicationController < ActionController::Base
  before_action :authenticate_user!
  helper_method :current_user

  def authenticate_user!
    @current_user = nil

    token = request.headers["X-Access-Token"]
    decoded_token = Eld.authenticate(token)

    if payload
      # Find a User from DB?
      # Find or create a User?
      @current_user = User.find_by(uid: decoded_token['user_id'])

      # Wrap data in a User object?
      @current_user = User.new(decoded_token)
    end

    head :unauthorized unless @current_user
  end

  def current_user
    @current_user
  end
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/sunrick/eld. Please check the code of conduct before contributing.

License

The gem is available as open source under the terms of the MIT License.