diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0cb6eeb --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +/.bundle/ +/.yardoc +/Gemfile.lock +/_yardoc/ +/coverage/ +/doc/ +/pkg/ +/spec/reports/ +/tmp/ diff --git a/.rspec b/.rspec new file mode 100644 index 0000000..ce9d5ff --- /dev/null +++ b/.rspec @@ -0,0 +1,4 @@ +--color +--format documentation +--order random +--require spec_helper diff --git a/.rubocop.yml b/.rubocop.yml new file mode 100644 index 0000000..e4123b7 --- /dev/null +++ b/.rubocop.yml @@ -0,0 +1,27 @@ +AllCops: + DisplayCopNames: true + +LineLength: + Max: 100 + +Style/StringLiterals: + EnforcedStyle: double_quotes + +Style/ClassAndModuleChildren: + Enabled: false + +Style/SpaceAroundOperators: + Enabled: false + +Metrics/MethodLength: + CountComments: false + Max: 50 + +Metrics/AbcSize: + Enabled: false + +Metrics/CyclomaticComplexity: + Max: 15 + +Metrics/PerceivedComplexity: + Max: 15 diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..bed6e27 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,4 @@ +language: ruby +rvm: + - 2.3.0 +before_install: gem install bundler -v 1.11.2 diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..aa3842e --- /dev/null +++ b/Gemfile @@ -0,0 +1,13 @@ +source "https://rubygems.org" + +gemspec + +group :development do + gem "guard-rspec" +end + +group :test do + gem "rspec" + gem "rubocop", "0.36.0" + gem "coveralls", require: false +end diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..396bd3a --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,20 @@ +Copyright (c) 2016 Tony Arcieri + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..c56ef97 --- /dev/null +++ b/README.md @@ -0,0 +1,162 @@ +![Boulangerie](https://raw.githubusercontent.com/cryptosphere/boulangerie/master/boulangerie.png) +for Rails! +========== +[![Gem Version](https://badge.fury.io/rb/boulangerie-rails.svg)](http://rubygems.org/gems/boulangerie-rails) +[![Build Status](https://travis-ci.org/cryptosphere/boulangerie-rails.svg)](https://travis-ci.org/cryptosphere/boulangerie-rails) +[![Code Climate](https://codeclimate.com/github/cryptosphere/boulangerie-rails/badges/gpa.svg)](https://codeclimate.com/github/cryptosphere/boulangerie-rails) +[![Coverage Status](https://coveralls.io/repos/cryptosphere/boulangerie-rails/badge.svg?branch=master&service=github)](https://coveralls.io/github/cryptosphere/boulangerie-rails?branch=master) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cryptosphere/boulangerie-rails/master/LICENSE.txt) + +[Boulangerie] is a Ruby gem for building authorization systems using +[Macaroons](http://macaroons.io), a better kind of cookie. + +[Boulangerie]: https://github.com/cryptosphere/boulangerie + +## Installation + +boulangerie-rails can be used with Rails 4.1+. + +Add this line to your application's Gemfile: + +```ruby +gem 'boulangerie-rails' +``` + +And then execute: + + $ bundle + +Or install it yourself as: + + $ gem install boulangerie-rails + +## Usage + +Add the following to `config/initializers/boulangerie.rb`: + +```ruby +Boulangerie.setup( + schema: Rails.root.join("config/boulangerie_schema.yml"), + keys: Rails.application.secrets.boulangerie_keys + key_id: "key1" + location: "https://mycoolsite.com" +) +``` + +You will also need to edit `config/secrets.yml` and add the following to +your respective environments (example given for development): + +```yaml +development: + secret_key_base: DEADBEEFDEADBEEFDEADBEEF[...] + boulangerie_keys: + key0: "1b942ba242e9d39ce838d03652091695eb1fef93d35d9454498ca970a8827e8f" + key1: "7efc8f72d159ce31a4b2c8db6281bf8d91a2f2778d4d0062f80b977ea43a8ec4" +``` + +The `boulangerie_keys` hash contains a "keyring" of keys which can be used to +create or verify Macaroons. + +To generate random keys, use the `Boulangerie::Keyring.generate_key` method, +which you can call from `irb` or `pry`: + +``` +[1] pry(main)> require 'boulangerie' +=> true +[2] pry(main)> Boulangerie::Keyring.generate_key +=> "1b942ba242e9d39ce838d03652091695eb1fef93d35d9454498ca970a8827e8f" +``` + +The names of the keys (e.g. `key0`, `key1`) are arbitrary, but all new Macaroons +will use the key whose ID was passed in as the `key_id` option to +`Boulangerie#initialize`. This allows for key rotation, i.e. periodically you can +add a new key, and Macaroons minted under an old key will still verify. + +Rotating keys is good security practice and you should definitely take advantage of it. + +You'll also need to create a `config/boulangerie_schema.yml` file that +contains the schema for your Macaroons. Here is a basic schema that will +add `not-before` and `expires` timestamp assertions on your Macaroons: + +```yaml +--- +schema-id: ee6da70e5ba01fec +predicates: + v0: + not-before: DateTime + expires: DateTime +``` + +A `schema-id` is a 64-bit random number. This is used to identify a schema +uniquely within your system regardless of what you decide to name or rename +the schema file. + +You can generate a schema ID via `irb` or `pry`: + +``` +[1] pry(main)> require 'boulangerie' +=> true +[2] pry(main)> Boulangerie::Schema.create_schema_id +=> "ee6da70e5ba01fec" +``` + +A schema-id can also be any 64-bit random number serialized as hex which +is unique to your app/infrastructure. + +This schema includes two *caveats*: an expiration date and a creation time, +before which the Macaroon is not considered valid. +The predicate matchers for these particular caveats are built into +Boulangerie, but you can extend it with your own. + +To create a Macaroon, we'll need to call the `#bake` method. The following +will create a new Macaroon and set it as the "my_macaroon" cookie: + +```ruby +class AuthenticationController < ApplicationController + # Perform some kind of authentication ritual here + before_action :check_credentials, :only => :authenticate + + def authenticate + expires_at = 24.hours.from_now + + cookie = Boulangerie.bake(caveats: { + expires: Time.now, + not_before: expires_at + }) + + cookies[:my_macaroon] = { + value: cookie, + expires: expires_at, + secure: true, + httponly: true + } + end +``` + +Finally, to actually use Macaroons to make authorization decisions, we need +to configure Boulangerie in a given controller: + +```ruby +class MyController < ApplicationController + authorize_with_boulangerie :cookie => :my_macaroon +end +``` + +## Supported Ruby Versions + +This library supports and is tested against the following Ruby versions: + +* Ruby (MRI) 2.0, 2.1, 2.2, 2.3 +* JRuby 9000 + +## Contributing + +* Fork this repository on GitHub +* Make your changes and send us a pull request +* If we like them we'll merge them +* If we've accepted a patch, feel free to ask for commit access + +## License + +Copyright (c) 2016 Tony Arcieri. Distributed under the MIT License. +See LICENSE.txt for further details. diff --git a/Rakefile b/Rakefile new file mode 100644 index 0000000..4c11af7 --- /dev/null +++ b/Rakefile @@ -0,0 +1,8 @@ +require "bundler/gem_tasks" +require "rspec/core/rake_task" +require "rubocop/rake_task" + +RSpec::Core::RakeTask.new(:spec) +RuboCop::RakeTask.new + +task default: %w(spec rubocop) diff --git a/bin/console b/bin/console new file mode 100755 index 0000000..f8d097a --- /dev/null +++ b/bin/console @@ -0,0 +1,14 @@ +#!/usr/bin/env ruby + +require "bundler/setup" +require "boulangerie/rails" + +# You can add fixtures and/or initialization code here to make experimenting +# with your gem easier. You can also use a different console, if you like. + +# (If you use this, don't forget to add pry to your Gemfile!) +# require "pry" +# Pry.start + +require "irb" +IRB.start diff --git a/bin/setup b/bin/setup new file mode 100755 index 0000000..dce67d8 --- /dev/null +++ b/bin/setup @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail +IFS=$'\n\t' +set -vx + +bundle install + +# Do any other automated setup that you need to do here diff --git a/boulangerie-rails.gemspec b/boulangerie-rails.gemspec new file mode 100644 index 0000000..4a277b8 --- /dev/null +++ b/boulangerie-rails.gemspec @@ -0,0 +1,30 @@ +# coding: utf-8 +lib = File.expand_path("../lib", __FILE__) +$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) +require "boulangerie/rails/version" + +Gem::Specification.new do |spec| + spec.name = "boulangerie-rails" + spec.version = Boulangerie::Rails::VERSION + spec.authors = ["Tony Arcieri"] + spec.email = ["bascule@gmail.com"] + + spec.licenses = ["MIT"] + spec.homepage = "https://github.com/cryptosphere/boulangerie-rails" + spec.summary = "Rails support creating and verifying Macaroons with Boulangerie" + spec.description = <<-DESCRIPTION.strip.gsub(/\s+/, " ") + Boulangerie provides schemas, creation, and verification for the + Macaroons bearer credential format. This gem contains support for + using Boulangerie with Ruby on Rails. + DESCRIPTION + + spec.files = `git ls-files`.split($INPUT_RECORD_SEPARATOR) + spec.bindir = "exe" + spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) } + spec.require_paths = ["lib"] + spec.required_ruby_version = ">= 2.0.0" + + spec.add_runtime_dependency "boulangerie" + + spec.add_development_dependency "rake", "~> 10.0" +end diff --git a/lib/boulangerie/rails.rb b/lib/boulangerie/rails.rb new file mode 100644 index 0000000..04838fd --- /dev/null +++ b/lib/boulangerie/rails.rb @@ -0,0 +1,7 @@ +require "boulangerie/rails/version" + +module Boulangerie + # Ruby on Rails support for Boulangerie + module Rails + end +end diff --git a/lib/boulangerie/rails/version.rb b/lib/boulangerie/rails/version.rb new file mode 100644 index 0000000..a1de26c --- /dev/null +++ b/lib/boulangerie/rails/version.rb @@ -0,0 +1,6 @@ +# frozen_string_literal: true +module Boulangerie + module Rails + VERSION = "0.1.0".freeze + end +end diff --git a/spec/boulangerie/rails_spec.rb b/spec/boulangerie/rails_spec.rb new file mode 100644 index 0000000..4f8ff11 --- /dev/null +++ b/spec/boulangerie/rails_spec.rb @@ -0,0 +1,5 @@ +RSpec.describe Boulangerie::Rails do + it "has a version number" do + expect(Boulangerie::Rails::VERSION).not_to be nil + end +end diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb new file mode 100644 index 0000000..c61083f --- /dev/null +++ b/spec/spec_helper.rb @@ -0,0 +1,4 @@ +$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__) +require "boulangerie/rails" + +RSpec.configure(&:disable_monkey_patching!)