maestrano-rails-test 0.9.3

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,13 @@
+class AddMaestranoTo<%= table_name.camelize %> < ActiveRecord::Migration
+  def self.up
+    change_table(:<%= table_name %>) do |t|
+<%= migration_data -%>
+    end
+  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,31 @@
+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 copy_account_groups_controller
+        template "groups_controller.rb", "app/controllers/maestrano/account/groups_controller.rb"
+      end
+      
+      def copy_account_group_users_controller
+        template "group_users_controller.rb", "app/controllers/maestrano/account/group_users_controller.rb"
+      end
+      
+      def add_maestrano_routes
+        maestrano_routes = <<-CONTENT
+maestrano_routes
+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/group_users_controller.rb

@@ -0,0 +1,26 @@
+class Maestrano::Account::GroupUsersController < Maestrano::Rails::WebHookController
+
+  # DELETE /maestrano/account/groups/cld-1/users/usr-1
+  # Remove a user from a group
+  def destroy
+    # Set the right uid based on Maestrano.param('sso.creation_mode')
+    user_uid = Maestrano.mask_user(params[:id],params[:group_id]) 
+    group_uid = params[:group_id]
+    
+    # Perform association deletion steps here
+    # --
+    # If Maestrano.param('sso.creation_mode') is set to virtual
+    # then you might want to just delete/cancel/block the user
+    #
+    # E.g
+    # user = User.find_by_provider_and_uid('maestrano',user_uid)
+    # organization = Organization.find_by_provider_and_uid('maestrano',group_uid)
+    # 
+    # if Maestrano.param('sso.creation_mode') == 'virtual'
+    #  user.destroy
+    # else
+    #   organization.remove_user(user)
+    #   user.block_access! if user.reload.organizations.empty?
+    # end
+  end
+end

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

@@ -0,0 +1,36 @@
+class Maestrano::Account::GroupsController < Maestrano::Rails::WebHookController
+  
+  # DELETE /maestrano/account/groups/cld-1
+  # Delete an entire group
+  def destroy
+    group_uid = params[:id]
+    
+    # Perform deletion steps here
+    # --
+    # If you need to perform a final checkout
+    # then you can call Maestrano::Account::Bill.create({.. final checkout details ..})
+    # --
+    # If Maestrano.param('sso.creation_mode') is set to virtual
+    # then you might want to delete/cancel/block all users under
+    # that group
+    # --
+    # E.g:
+    # organization = Organization.find_by_provider_and_uid('maestrano',group_uid)
+    #
+    # amount_cents = organization.calculate_total_due_remaining
+    # Maestrano::Account::Bill.create({
+    #   group_id: group_uid, 
+    #   price_cents: amount_cents, 
+    #   description: "Final Payout"
+    # })
+    # 
+    # if Maestrano.param('sso.creation_mode') == 'virtual'
+    #   organization.members.where(provider:'maestrano').each do |user|
+    #   user.destroy
+    # end
+    #
+    # organization.destroy
+    # render json: {success: true}
+    #
+  end
+end

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

@@ -0,0 +1,126 @@
+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 = 'test' # or 'production'
+  
+  # ==> Application host
+  # This is your application host (e.g: my-app.com) which is ultimately
+  # used to redirect users to the right SAML url during SSO handshake.
+  #
+  config.app.host = (config.environment == 'production' ? 'https://my-app.com' : 'http://localhost:3000')
+  
+  # ==> App ID & API key
+  # Your application App ID and API key which you can retrieve on http://maestrano.com
+  # via your cloud partner dashboard.
+  # For testing you can retrieve/generate an api.id and api.key from the API Sandbox directly 
+  # on http://api-sandbox.maestrano.io
+  #
+  config.api.id = (config.environment == 'production' ? 'prod_app_id' : 'sandbox_app_id')
+  config.api.key = (config.environment == '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
+  
+  # ==> Single Sign-On Identity Manager
+  # By default we consider that the domain managing user identification
+  # is the same as your application host (see above config.app.host parameter)
+  # If you have a dedicated domain managing user identification and therefore
+  # responsible for the single sign-on handshake (e.g: https://idp.my-app.com)
+  # then you can specify it below
+  #
+  # config.sso.idm = (config.environment == 'production' ? 'https://idp.my-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.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.consume_path = '/maestrano/auth/saml/consume'
+  
+  # ==> Single Logout activation
+  # Enable/Disable single logout. When troubleshooting authentication issues
+  # you might want to disable SLO temporarily.
+  # If set to false then Maestrano::SSO::Session#valid? - which should be
+  # used in a controller before filter to check user session - always return true
+  #
+  # config.sso.slo_enabled = true
+  
+  # ==> 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 'sso.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 constraints 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 'sso.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.sso.creation_mode = 'real' # or 'virtual'
+  
+  # ==> Account Webhooks
+  # Single sign on has been setup into your app and Maestrano users are now able
+  # to use your service. Great! Wait what happens when a business (group) decides to 
+  # stop using your service? Also what happens when a user gets removed from a business?
+  # Well the endpoints below are for Maestrano to be able to notify you of such
+  # events.
+  #
+  # Even if the routes look restful we issue only issue DELETE requests for the moment
+  # to notify you of any service cancellation (group deletion) or any user being
+  # removed from a group.
+  #
+  # The controllers for these hooks path are automatically generated when 
+  # you run 'rake maestrano:install' and is available under
+  # <rails_root>/app/controllers/maestrano/account/
+  #
+  # config.webhook.account.groups_path = '/maestrano/account/groups/:id',
+  # config.webhook.account.group_users_path = '/maestrano/account/groups/:group_id/users/:id',
+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