maestrano-rails 0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Maestrano
+
+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.

data/README.md

@@ -0,0 +1,164 @@
+<p align="center">
+<img src="https://raw.github.com/maestrano/maestrano-rails/master/maestrano.png" alt="Maestrano Logo">
+</p>
+
+Maestrano Cloud Integration is currently in closed beta. Want to know more? Send us an email to <contact@maestrano.com>.
+
+## Getting Setup
+Before integrating with us you will need an API Key. Maestrano Cloud Integration being still in closed beta you will need to contact us beforehand to gain production access.
+
+For testing purpose we provide an API Sandbox where you can freely obtain an API Token. The sandbox is great to test single sign-on and API integration (e.g: billing API).
+
+To get started just go to: http://api-sandbox.maestrano.io
+
+## Getting Started
+
+maestrano-rails works with Rails 3.2 onwards. You can add it to your Gemfile with:
+
+```ruby
+gem 'maestrano-rails'
+```
+
+Run bundle to install the gem as well as the [maestrano ruby bindings](https://github.com/maestrano/maestrano-ruby) (dependency)
+
+```console
+bundle
+```
+
+After you install Maestrano and add it to your Gemfile, you need to run the generator:
+
+```console
+rails generate maestrano:install
+```
+
+The generator will install an initializer which describes ALL Maestrano's configuration options. You will need to take a look at it as this is where you set your API key.
+The generator also generates a SamlController for single sign-on that you will need to customize (see below) as well as the required routes.
+
+When you are done, you can start maestrano-izing your user and group model using the generators.
+
+### User model
+Assuming your user model is called 'User' you can run the following generator to prepare this model for single sign-on:
+
+```console
+rails generate maestrano:user User
+```
+
+This generator will create a migration adding a :provider and :uid field to your user model. If you are already using multi-auth strategies (using [omniauth](https://github.com/intridea/omniauth) for example) then you can just ignore and delete this migration.
+
+Run the migration with:
+```console
+bundle exec rake db:migrate
+```
+
+This generator also adds a configuration block to your user model which looks like this:
+```ruby
+class User < ActiveRecord::Base
+  # Enable Maestrano for this user
+  maestrano_user_via :provider, :uid do |user,maestrano|
+    user.name = maestrano.first_name
+    user.surname = maestrano.last_name
+    user.email = maestrano.email
+    #user.company = maestrano.company_name
+    #user.country_alpha2 = maestrano.country
+    #user.some_required_field = 'some-appropriate-default-value'
+  end
+  
+  ...
+  
+end
+```
+
+This block is used to create a mapping between your user model fields and the attributes provided by Maestrano during the single sign-on handshake.
+
+### Group model
+Because Maestrano works with businesses it expects your service to be able to manage groups of users. A group represents 1) a billing entity 2) a collaboration group. During the first single sign-on handshake both a user and a group should be created. Additional users logging in via the same group should then be added to this existing group (see controller setup below)
+
+Assuming your group model is called 'Organization' you can run the following generator to prepare this model for single sign-on:
+
+```console
+rails generate maestrano:group Organization
+```
+
+This generator will create a migration adding a :provider and :uid field to your group model.
+
+Run the migration with:
+```console
+bundle exec rake db:migrate
+```
+
+This generator also adds a configuration block to your group model which looks like this:
+
+```ruby
+class Organization < ActiveRecord::Base
+  maestrano_group_via :provider, :uid do |group,maestrano|
+    group.name = maestrano.company_name || "Your Group"
+  end
+  
+  ...
+  
+end
+```
+
+### Controller setup
+The last step of integrating single sign-on with Maestrano is to customize the consume action of the SamlController. This action represents the last step of single sign-on handshake and should handle user finding/creation, group finding/creation, user-group relationship and finally user sign in.
+
+The controller is located here: app/controllers/maestrano/auth/saml_controller.rb
+
+The sample belows shows one possible way of writing this controller action:
+
+```ruby
+class Maestrano::Auth::SamlController < Maestrano::Rails::SamlBaseController
+  
+  #== POST '/maestrano/auth/saml/consume'
+  # -
+  # Assuming you have enabled maestrano on a user model
+  # called 'User' and a group model called 'Organization'
+  # the action could be written the following way
+  def consume
+    # 1)Find or create the user and the group
+    # --
+    # The class method 'find_or_create_for_maestrano' is provided
+    # by the maestrano-rails gem on the model you have maestrano-ized.
+    # The method uses the mapping defined in the model 'maestrano_*_via' 
+    # block to create the resource if it does not exist
+    # The 'user_auth_hash' and 'group_auth_hash' methods are provided
+    # by the controller.
+    # --
+    user = User.find_or_create_for_maestrano(user_auth_hash)
+    organization = Organization.find_or_create_for_maestrano(group_auth_hash)
+    
+    
+    # 2) Add the user to the group if not already a member
+    # --
+    # The 'user_group_rel_hash' method is provided by the controller.
+    # The role attribute provided by maestrano is one of the following: 
+    # 'Member', 'Power User', 'Admin', 'Super Admin'
+    # The 'member_of?' and 'add_member' methods are not provided by 
+    # maestrano and are left to you to implement on your models
+    # --
+    unless user.member_of?(organization)
+      organization.add_member(user,role: user_group_rel_hash[:role])
+    end
+    
+    
+    # Sign the user in and redirect to application root
+    # --
+    # The 'sign_in' method is not provided by maestrano but should already
+    # be there if you are using an authentication framework like Devise
+    # --
+    sign_in(user)
+    redirect_to root_path
+  end
+end
+```
+
+## Support
+This README is still in the process of being written and improved. As such it might not cover some of the questions you might have.
+
+So if you have any question or need help integrating with us just let us know at support@maestrano.com
+
+## License
+
+MIT License. Copyright 2014 Maestrano Pty Ltd. https://maestrano.com
+
+You are not granted rights or licenses to the trademarks of Maestrano.

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Maestrano-rails'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/controllers/maestrano/rails/saml_base_controller.rb

@@ -0,0 +1,39 @@
+class Maestrano::Rails::SamlBaseController < ApplicationController
+  attr_reader :saml_response, :user_auth_hash, :group_auth_hash, :user_group_rel_hash
+  around_filter :saml_response_transaction, only: [:consume]
+  
+  # Initialize the SAML request and redirects the
+  # user to Maestrano
+  def init
+    redirect_to Maestrano::Saml::Request.new(params,session).redirect_url
+  end
+  
+  #===================================
+  # Helper methods
+  #===================================
+  def saml_response_transaction
+    begin
+      process_saml_response
+      yield
+      Maestrano::SSO.set_session(session,@user_auth_hash)
+    rescue Exception => e
+      logger.error e
+      redirect_to "#{Maestrano::SSO.unauthorized_url}?err=internal"
+    end
+  end
+  
+  def process_saml_response
+    if params[:SAMLResponse]
+      @saml_response = Maestrano::Saml::Response.new(params[:SAMLResponse])
+      if @saml_response.validate!
+        @user_auth_hash = Maestrano::SSO::BaseUser.new(@saml_response).to_hash
+        @group_auth_hash = Maestrano::SSO::BaseGroup.new(@saml_response).to_hash
+        @user_group_rel_hash = {
+          user_uid: @saml_response.attributes['uid'],
+          group_uid: @saml_response.attributes['group_uid'],
+          role: @saml_response.attributes['group_role']
+        }
+      end
+    end
+  end
+end

data/lib/generators/active_record/maestrano_group_generator.rb

@@ -0,0 +1,38 @@
+require 'rails/generators/active_record'
+require 'generators/maestrano/orm_helpers'
+
+module ActiveRecord
+  module Generators
+    class MaestranoGroupGenerator < ActiveRecord::Generators::Base
+      include Maestrano::Generators::OrmHelpers
+      source_root File.expand_path("../templates", __FILE__)
+      
+      def copy_maestrano_migration
+        migration_template "migration.rb", "db/migrate/add_maestrano_to_#{table_name}.rb"
+      end
+      
+      def inject_maestrano_content
+        content = model_contents
+
+        class_path = if namespaced?
+          class_name.to_s.split("::")
+        else
+          [class_name]
+        end
+
+        indent_depth = class_path.size - 1
+        content = content.split("\n").map { |line| "  " * indent_depth + line } .join("\n") << "\n"
+
+        inject_into_class(model_path, class_path.last, content) if model_exists?
+      end
+      
+      def migration_data
+<<RUBY
+      ## User source identification fields
+      t.string :provider
+      t.string :uid
+RUBY
+      end
+    end
+  end
+end

data/lib/generators/active_record/maestrano_user_generator.rb

@@ -0,0 +1,38 @@
+require 'rails/generators/active_record'
+require 'generators/maestrano/orm_helpers'
+
+module ActiveRecord
+  module Generators
+    class MaestranoUserGenerator < ActiveRecord::Generators::Base
+      include Maestrano::Generators::OrmHelpers
+      source_root File.expand_path("../templates", __FILE__)
+      
+      def copy_maestrano_migration
+        migration_template "migration.rb", "db/migrate/add_maestrano_to_#{table_name}.rb"
+      end
+      
+      def inject_maestrano_content
+        content = model_contents
+
+        class_path = if namespaced?
+          class_name.to_s.split("::")
+        else
+          [class_name]
+        end
+
+        indent_depth = class_path.size - 1
+        content = content.split("\n").map { |line| "  " * indent_depth + line } .join("\n") << "\n"
+
+        inject_into_class(model_path, class_path.last, content) if model_exists?
+      end
+      
+      def migration_data
+<<RUBY
+      ## User source identification fields
+      t.string :provider
+      t.string :uid
+RUBY
+      end
+    end
+  end
+end

data/lib/generators/active_record/templates/migration.rb

@@ -0,0 +1,12 @@
+class AddMaestranoTo<%= table_name.camelize %> < ActiveRecord::Migration
+  def self.up
+    change_table(:<%= table_name %>) do |t|
+<%= migration_data -%>
+  end
+
+  def self.down
+    # By default, we don't want to make any assumption about how to roll back this migration.
+    # Please edit below which fields you would like to remove in this migration.
+    raise ActiveRecord::IrreversibleMigration
+  end
+end

data/lib/generators/maestrano/USAGE

@@ -0,0 +1,2 @@
+Description:
+  Generates all files required to get your rails app setup with maestrano

data/lib/generators/maestrano/group_generator.rb

@@ -0,0 +1,11 @@
+module Maestrano
+  module Generators
+    class GroupGenerator < ::Rails::Generators::NamedBase
+      include ::Rails::Generators::ResourceHelpers
+      
+      source_root File.expand_path("../templates", __FILE__)
+      desc "Configure group model <NAME> for maestrano and create migration"
+      hook_for :orm, as: :maestrano_group
+    end
+  end
+end

data/lib/generators/maestrano/install_generator.rb

@@ -0,0 +1,30 @@
+module Maestrano
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("../templates", __FILE__)
+      desc "Creates a Maestrano initializer and a customizable controller for SAML Single Sign-On"
+      
+      def copy_initializer
+        template "maestrano.rb", "config/initializers/maestrano.rb"
+      end
+      
+      def copy_saml_controller
+        template "saml_controller.rb", "app/controllers/maestrano/auth/saml_controller.rb"
+      end
+      
+      def add_maestrano_routes
+        maestrano_routes = <<-CONTENT
+namespace :maestrano do
+    namespace :auth do
+      resources :saml, only:[] do
+        get 'init', on: :collection
+        post 'consume', on: :collection
+      end
+    end
+  end
+CONTENT
+        route maestrano_routes
+      end
+    end
+  end
+end

data/lib/generators/maestrano/orm_helpers.rb

@@ -0,0 +1,75 @@
+module Maestrano
+  module Generators
+    module OrmHelpers
+      
+      def model_contents
+        
+        if model_type == 'user'
+          buffer = <<-CONTENT
+  # Enable Maestrano for this user
+  maestrano_user_via :provider, :uid do |user,maestrano|
+    user.name = maestrano.first_name
+    user.surname = maestrano.last_name
+    user.email = maestrano.email
+    #user.company = maestrano.company_name
+    #user.country_alpha2 = maestrano.country
+    #user.some_required_field = 'some-appropriate-default-value'
+  end
+
+CONTENT
+        else
+          buffer = <<-CONTENT
+  # Enable Maestrano for this group
+  maestrano_group_via :provider, :uid do |group, maestrano|
+    group.name = (maestrano.company_name || "Default Group name")
+    #group.country_alpha2 = maestrano.country
+    #group.free_trial_end_at = maestrano.free_trial_end_at
+    #group.some_required_field = 'some-appropriate-default-value'
+  end
+
+CONTENT
+        end
+        
+        buffer += <<-CONTENT if needs_attr_accessible?
+  # Setup protected attributes for your model
+  attr_protected :provider, :uid
+
+CONTENT
+        buffer
+      end
+      
+      def model_type
+        self.class.name.split("::").last.gsub("Maestrano","").gsub("Generator","").downcase
+      end
+      
+      def needs_attr_accessible?
+        rails_3? && !strong_parameters_enabled?
+      end
+
+      def rails_3?
+        ::Rails::VERSION::MAJOR == 3
+      end
+
+      def strong_parameters_enabled?
+        defined?(ActionController::StrongParameters)
+      end
+      
+      private
+        def model_exists?
+          File.exists?(File.join(destination_root, model_path))
+        end
+
+        def migration_exists?(table_name)
+          Dir.glob("#{File.join(destination_root, migration_path)}/[0-9]*_*.rb").grep(/\d+_add_maestrano_to_#{table_name}.rb$/).first
+        end
+
+        def migration_path
+          @migration_path ||= File.join("db", "migrate")
+        end
+
+        def model_path
+          @model_path ||= File.join("app", "models", "#{file_path}.rb")
+        end
+    end
+  end
+end

data/lib/generators/maestrano/templates/maestrano.rb

@@ -0,0 +1,84 @@
+# Use this block to configure the behaviour of Maestrano
+# in your app
+Maestrano.configure do |config|
+  
+  # ==> Environment configuration
+  # The environment to connect to.
+  # If set to 'production' then all Single Sign-On (SSO) and API requests
+  # will be made to maestrano.com
+  # If set to 'test' then requests will be made to api-sandbox.maestrano.io
+  # The api-sandbox allows you to easily test integration scenarios.
+  # More details on http://api-sandbox.maestrano.io
+  config.environment = Rails.env.production? ? 'production' : 'test'
+  
+  # ==> API key
+  # Your application API key which you can retrieve on http://maestrano.com
+  # via your cloud partner dashboard.
+  # For testing you can retrieve/generate an api_key from the API Sandbox directly 
+  # on http://api-sandbox.maestrano.io
+  config.api_key = Rails.env.production? ? 'prod_api_key' : 'sandbox_api_key'
+  
+  # ==> Single Sign-On activation
+  # Enable/Disable single sign-on. When troubleshooting authentication issues
+  # you might want to disable SSO temporarily
+  config.sso_enabled = true
+  
+  # ==> Application host
+  # This is your application host (e.g: mysuperapp.com) which is ultimately
+  # used to redirect users to the right SAML url during SSO handshake.
+  config.app_host = Rails.env.production? ? 'https://my-production-app.com' : 'http://localhost::3000'
+  
+  # ==> SSO Initialization endpoint
+  # This is your application path to the SAML endpoint that allows users to
+  # initialize SSO authentication. Upon reaching this endpoint users your
+  # application will automatically create a SAML request and redirect the user
+  # to Maestrano. Maestrano will then authenticate and authorize the user. Upon
+  # authorization the user gets redirected to your application consumer endpoint
+  # (see below) for initial setup and/or login.
+  # The controller for this path is automatically
+  # generated when you run 'rake maestrano:install' and is available at
+  # <rails_root>/app/controllers/maestrano/auth/saml.rb
+  config.sso_app_init_path = '/maestrano/auth/saml/init'
+  
+  # ==> SSO Consumer endpoint
+  # This is your application path to the SAML endpoint that allows users to
+  # finalize SSO authentication. During the 'consume' action your application
+  # sets users (and associated group) up and/or log them in.
+  # The controller for this path is automatically
+  # generated when you run 'rake maestrano:install' and is available at
+  # <rails_root>/app/controllers/maestrano/auth/saml.rb
+  config.sso_app_consume_path = '/maestrano/auth/saml/consume'
+  
+  # ==> SSO User creation mode
+  # !IMPORTANT
+  # On Maestrano users can take several "instances" of your service. You can consider
+  # each "instance" as 1) a billing entity and 2) a collaboration group (this is
+  # equivalent to a 'customer account' in a commercial world). When users login to
+  # your application via single sign-on they actually login via a specific group which
+  # is then supposed to determine which data they have access to inside your application.
+  #
+  # E.g: John and Jack are part of group 1. They should see the same data when they login to
+  # your application (employee info, analytics, sales etc..). John is also part of group 2 
+  # but not Jack. Therefore only John should be able to see the data belonging to group 2.
+  #
+  # In most application this is done via collaboration/sharing/permission groups which is
+  # why a group is required to be created when a new user logs in via a new group (and 
+  # also for billing purpose - you charge a group, not a user directly). 
+  #
+  # == mode: 'real'
+  # In an ideal world a user should be able to belong to several groups in your application.
+  # In this case you would set the 'user_creation_mode' to 'real' which means that the uid
+  # and email we pass to you are the actual user email and maestrano universal id.
+  #
+  # == mode: 'virtual'
+  # Now let's say that due to technical constraint your application cannot authorize a user
+  # to belong to several groups. Well next time John logs in via a different group there will
+  # be a problem: the user already exists (based on uid or email) and cannot be assigned 
+  # to a second group. To fix this you can set the 'user_creation_mode' to 'virtual'. In this
+  # mode users get assigned a truly unique uid and email across groups. So next time John logs
+  # in a whole new user account can be created for him without any validation problem. In this
+  # mode the email we assign to him looks like "usr-sdf54.cld-45aa2@mail.maestrano.com". But don't
+  # worry we take care of forwarding any email you would send to this address
+  #
+  config.user_creation_mode = 'virtual' # or 'real'
+end

data/lib/generators/maestrano/templates/saml_controller.rb

@@ -0,0 +1,52 @@
+class Maestrano::Auth::SamlController < Maestrano::Rails::SamlBaseController
+  
+  #== POST '/maestrano/auth/saml/consume'
+  # Final phase of the Single Sign-On handshake. Find or create
+  # the required resources (user and group) and sign the user
+  # in
+  #
+  # This action is left to you to customize based on your application
+  # requirements. Below is presented a potential way of writing 
+  # the action.
+  #
+  # Assuming you have enabled maestrano on a user model
+  # called 'User' and a group model called 'Organization'
+  # the action could be written the following way
+  def consume
+    ### 1)Find or create the user and the group
+    ### --
+    ### The class method 'find_or_create_for_maestrano' is provided
+    ### by the maestrano-rails gem on the model you have maestrano-ized.
+    ### The method uses the mapping defined in the model 'maestrano_*_via' 
+    ### block to create the resource if it does not exist
+    ### The 'user_auth_hash' and 'group_auth_hash' methods are provided
+    ### by the controller.
+    ### --
+    # user = User.find_or_create_for_maestrano(user_auth_hash)
+    # organization = Organization.find_or_create_for_maestrano(group_auth_hash)
+    #
+    #
+    ### 2) Add the user to the group if not already a member
+    ### --
+    ### The 'user_group_rel_hash' method is provided by the controller.
+    ### The role attribute provided by maestrano is one of the following: 
+    ### 'Member', 'Power User', 'Admin', 'Super Admin'
+    ### The 'member_of?' and 'add_member' methods are not provided by 
+    ### maestrano and are left to you to implement on your models
+    ### --
+    # unless user.member_of?(organization)
+    #   organization.add_member(user,role: user_group_rel_hash[:role])
+    # end
+    #
+    #
+    ### Sign the user in and redirect to application root
+    ### --
+    ### The 'sign_in' method is not provided by maestrano but should already
+    ### be there if you are using an authentication framework like Devise
+    ### --
+    # sign_in(user)
+    # redirect_to root_path
+    
+    raise NotImplemented.new("The consume action should be customized to fit your application needs")
+  end
+end

data/lib/generators/maestrano/user_generator.rb

@@ -0,0 +1,11 @@
+module Maestrano
+  module Generators
+    class UserGenerator < ::Rails::Generators::NamedBase
+      include ::Rails::Generators::ResourceHelpers
+      
+      source_root File.expand_path("../templates", __FILE__)
+      desc "Configure user model <NAME> for maestrano and create migration"
+      hook_for :orm, as: :maestrano_user
+    end
+  end
+end

data/lib/generators/mongoid/maestrano_group_generator.rb

@@ -0,0 +1,26 @@
+require 'rails/generators/named_base'
+require 'generators/maestrano/orm_helpers'
+
+module Mongoid
+  module Generators
+    class MaestranoGroupGenerator < Rails::Generators::NamedBase
+      include Maestrano::Generators::OrmHelpers
+      
+      def inject_field_types
+        inject_into_file model_path, migration_data, after: "include Mongoid::Document\n" if model_exists?
+      end
+
+      def inject_maestrano_content
+        inject_into_file model_path, model_contents, after: "include Mongoid::Document\n" if model_exists?
+      end
+      
+      def migration_data
+<<RUBY
+  ## User source identification fields
+  field :provider,  type: String, default: ""
+  field :uid,       type: String, default: ""
+RUBY
+      end
+    end
+  end
+end