maestrano-rails 0.5.0 → 0.6.0

data/README.md

@@ -12,7 +12,10 @@ Maestrano Cloud Integration is currently in closed beta. Want to know more? Send
   * [User Model](#user-model)
   * [Group Model](#group-model)
   * [Controller Setup](#controller-setup)
-3. [API](https://github.com/maestrano/maestrano-ruby#api)
+3. [Account Webhooks](#account-webhooks)
+  * [Groups Controller](#groups-controller-service-cancellation)
+  * [Group Users Controller](#group-users-controller-business-member-removal)
+4. [API](https://github.com/maestrano/maestrano-ruby#api)
   * [Bill](https://github.com/maestrano/maestrano-ruby#bill)
   * [Recurring Bill](https://github.com/maestrano/maestrano-ruby#recurring-bill)
 
@@ -46,7 +49,8 @@ After you install Maestrano and add it to your Gemfile, you need to run the gene
 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 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. This configuration will also be used to automatically generate a '/maestrano/metadata' endpoint in your application that Maestrano will fetch automatically at regular intervals (or by hitting 'refresh metadata' in your cloud partner dashboard on maestrano.com).
+
 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.
@@ -167,6 +171,89 @@ class Maestrano::Auth::SamlController < Maestrano::Rails::SamlBaseController
 end
 ```
 
+## 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 controllers generated under RAILS_ROOT/app/controllers/maestrano/account/ are typically for Maestrano to be able to notify you of such events.
+
+### Groups Controller (service cancellation)
+Sad as it is a business might decide to stop using your service at some point. On Maestrano billing entities are represented by groups (used for collaboration & billing). So when a business decides to stop using your service we will issue a DELETE request to the webhook.account.groups_path endpoint (typically /maestrano/account/groups/:id).
+
+Maestrano only uses this controller for service cancellation so there is no need to implement any other type of action - ie: GET, PUT/PATCH or POST. The use of other http verbs might come in the future to improve the communication between Maestrano and your service but as of now it is not required.
+
+Below is an example of what your groups destroy action might look like:
+```ruby
+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}, status: :success
+  end
+end
+```
+
+### Group Users Controller (business member removal)
+A business might decide at some point to revoke access to your services for one of its member. In such case we will issue a DELETE request to the webhook.account.group_users_path endpoint (typically /maestrano/account/groups/:group_id/users/:id).
+
+Maestrano only uses this controller for user membership cancellation so there is no need to implement any other type of action - ie: GET, PUT/PATCH or POST. The use of other http verbs might come in the future to improve the communication between Maestrano and your service but as of now it is not required.
+
+
+Below is an example of what your group users destroy action might look like:
+```ruby
+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
+```
+
 ## API
 The maestrano-rails gem also provides bindings to its REST API allowing you to access, create, update or delete various entities under your account (e.g: billing).
 

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

@@ -0,0 +1,8 @@
+class Maestrano::Rails::MetadataController < Maestrano::Rails::WebHookController
+
+  # GET /maestrano/metadata
+  # Return the Maestrano configuration for this application
+  def index
+    render json: Maestrano.to_metadata
+  end
+end

data/lib/generators/maestrano/install_generator.rb

@@ -12,12 +12,12 @@ module Maestrano
         template "saml_controller.rb", "app/controllers/maestrano/auth/saml_controller.rb"
       end
       
-      def copy_account_hook_groups_controller
-        template "groups_controller.rb", "app/controllers/maestrano/account_hook/groups_controller.rb"
+      def copy_account_groups_controller
+        template "groups_controller.rb", "app/controllers/maestrano/account/groups_controller.rb"
       end
       
-      def copy_account_hook_group_users_controller
-        template "group_users_controller.rb", "app/controllers/maestrano/account_hook/group_users_controller.rb"
+      def copy_account_group_users_controller
+        template "group_users_controller.rb", "app/controllers/maestrano/account/group_users_controller.rb"
       end
       
       def add_maestrano_routes

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

@@ -1,22 +1,22 @@
-class Maestrano::AccountHook::GroupUsersController < Maestrano::Rails::WebHookController
+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('user_creation_mode')
+    # 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('user_creation_mode') is set to virtual
+    # 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('user_creation_mode') == 'virtual'
+    # if Maestrano.param('sso.creation_mode') == 'virtual'
     #  user.destroy
     # else
     #   organization.remove_user(user)

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

@@ -1,4 +1,4 @@
-class Maestrano::AccountHook::GroupsController < Maestrano::Rails::WebHookController
+class Maestrano::Account::GroupsController < Maestrano::Rails::WebHookController
   
   # DELETE /maestrano/account/groups/cld-1
   # Delete an entire group
@@ -10,7 +10,7 @@ class Maestrano::AccountHook::GroupsController < Maestrano::Rails::WebHookContro
     # If you need to perform a final checkout
     # then you can call Maestrano::Account::Bill.create({.. final checkout details ..})
     # --
-    # If Maestrano.param('user_creation_mode') is set to virtual
+    # If Maestrano.param('sso.creation_mode') is set to virtual
     # then you might want to delete/cancel/block all users under
     # that group
     # --
@@ -24,7 +24,7 @@ class Maestrano::AccountHook::GroupsController < Maestrano::Rails::WebHookContro
     #   description: "Final Payout"
     # })
     # 
-    # if Maestrano.param('user_creation_mode') == 'virtual'
+    # if Maestrano.param('sso.creation_mode') == 'virtual'
     #   organization.members.where(provider:'maestrano').each do |user|
     #   user.destroy
     # end

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

@@ -1,5 +1,3 @@
-# Use this block to configure the behaviour of Maestrano
-# in your app
 Maestrano.configure do |config|
   
   # ==> Environment configuration
@@ -9,25 +7,38 @@ Maestrano.configure do |config|
   # 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'
+  #
+  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_key from the API Sandbox directly 
+  # For testing you can retrieve/generate an api.id and api.key from the API Sandbox directly 
   # on http://api-sandbox.maestrano.io
-  config.app_id = Rails.env.production? ? 'prod_app_id' : 'sandbox_app_id'
-  config.api_key = Rails.env.production? ? 'prod_api_key' : 'sandbox_api_key'
+  #
+  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
+  #
+  # 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'
+  # ==> 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
@@ -36,19 +47,23 @@ Maestrano.configure do |config|
   # 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'
+  #
+  # 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_app_consume_path = '/maestrano/auth/saml/consume'
+  #
+  # config.sso.consume_path = '/maestrano/auth/saml/consume'
   
   # ==> SSO User creation mode
   # !IMPORTANT
@@ -68,18 +83,36 @@ Maestrano.configure do |config|
   #
   # == 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
+  # 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 constraint your application cannot authorize a user
+  # 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 'user_creation_mode' to 'virtual'. In this
+  # 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.user_creation_mode = 'virtual' # or 'real'
+  # 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/maestrano/rails/routing/routes.rb

@@ -2,6 +2,14 @@ module ActionDispatch::Routing
   class Mapper
     def maestrano_routes
       namespace :maestrano do
+        scope module: :rails do
+          get '/metadata' => 'metadata#index'
+        end
+        
+        namespace :rails do
+          get '/maestrano/metadata'
+        end
+        
         namespace :auth do
           resources :saml, only:[] do
             get 'init', on: :collection
@@ -9,7 +17,7 @@ module ActionDispatch::Routing
           end
         end
         
-        namespace :account_hook do
+        namespace :account do
           resources :groups, only: [:destroy] do
             resources :users, only: [:destroy], controller: 'group_users'
           end

data/lib/maestrano/rails/version.rb

@@ -1,5 +1,5 @@
 module Maestrano
   module Rails
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

data/test/controllers/group_users_controller_test.rb

@@ -1,7 +1,7 @@
 require 'test_helper'
 
 class GroupUsersControllerTest < ActionController::TestCase
-  tests Maestrano::AccountHook::GroupUsersController
+  tests Maestrano::Account::GroupUsersController
   
   context "unauthenticated" do
     should "deny access" do
@@ -12,7 +12,7 @@ class GroupUsersControllerTest < ActionController::TestCase
   
   context "authenticated" do
     setup do
-      @request.env["HTTP_AUTHORIZATION"] = "Basic " + Base64.encode64("#{Maestrano.param('app_id')}:#{Maestrano.param('api_key')}")
+      @request.env["HTTP_AUTHORIZATION"] = "Basic " + Base64.encode64("#{Maestrano.param('api.id')}:#{Maestrano.param('api.key')}")
     end
     
     should "be successful" do

data/test/controllers/groups_controller_test.rb

@@ -1,7 +1,7 @@
 require 'test_helper'
 
 class GroupsControllerTest < ActionController::TestCase
-  tests Maestrano::AccountHook::GroupsController
+  tests Maestrano::Account::GroupsController
   
   context "unauthenticated" do
     should "deny access" do
@@ -12,7 +12,7 @@ class GroupsControllerTest < ActionController::TestCase
   
   context "authenticated" do
     setup do
-      @request.env["HTTP_AUTHORIZATION"] = "Basic " + Base64.encode64("#{Maestrano.param('app_id')}:#{Maestrano.param('api_key')}")
+      @request.env["HTTP_AUTHORIZATION"] = "Basic " + Base64.encode64("#{Maestrano.param('api.id')}:#{Maestrano.param('api.key')}")
     end
     
     should "be successful" do

data/test/controllers/metadata_controller_test.rb

@@ -0,0 +1,25 @@
+require 'test_helper'
+
+class MetadataControllerTest < ActionController::TestCase
+  tests Maestrano::Rails::MetadataController
+  
+  context "unauthenticated" do
+    should "deny access" do
+      get :index
+      assert_equal '401', response.code
+    end
+  end
+  
+  context "authenticated" do
+    setup do
+      @request.env["HTTP_AUTHORIZATION"] = "Basic " + Base64.encode64("#{Maestrano.param('api.id')}:#{Maestrano.param('api.key')}")
+    end
+    
+    should "be successful" do
+      get :index
+      assert_equal '200', response.code
+      assert_equal Maestrano.to_metadata.to_json, response.body
+    end
+  end
+  
+end

data/test/dummy/app/controllers/maestrano/{account_hook → account}/group_users_controller.rb

@@ -1,23 +1,23 @@
-class Maestrano::AccountHook::GroupUsersController < Maestrano::Rails::WebHookController
+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('user_creation_mode')
+    # 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]
     render text: "Yay!"
     
     # Perform association deletion steps here
     # --
-    # If Maestrano.param('user_creation_mode') is set to virtual
+    # 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('user_creation_mode') == 'virtual'
+    # if Maestrano.param('sso.creation_mode') == 'virtual'
     #  user.destroy
     # else
     #   organization.remove_user(user)

data/test/dummy/app/controllers/maestrano/{account_hook → account}/groups_controller.rb

@@ -1,4 +1,4 @@
-class Maestrano::AccountHook::GroupsController < Maestrano::Rails::WebHookController
+class Maestrano::Account::GroupsController < Maestrano::Rails::WebHookController
   
   # DELETE /maestrano/account/groups/cld-1
   # Delete an entire group
@@ -11,7 +11,7 @@ class Maestrano::AccountHook::GroupsController < Maestrano::Rails::WebHookContro
     # If you need to perform a final checkout
     # then you can call Maestrano::Account::Bill.create({.. final checkout details ..})
     # --
-    # If Maestrano.param('user_creation_mode') is set to virtual
+    # If Maestrano.param('sso.creation_mode') is set to virtual
     # then you might want to delete/cancel/block all users under
     # that group
     # --
@@ -25,7 +25,7 @@ class Maestrano::AccountHook::GroupsController < Maestrano::Rails::WebHookContro
     #   description: "Final Payout"
     # })
     # 
-    # if Maestrano.param('user_creation_mode') == 'virtual'
+    # if Maestrano.param('sso.creation_mode') == 'virtual'
     #   organization.members.where(provider:'maestrano').each do |user|
     #   user.destroy
     # end

data/test/dummy/config/initializers/maestrano.rb

@@ -68,18 +68,18 @@ Maestrano.configure do |config|
   #
   # == 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
+  # 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 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
+  # 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.user_creation_mode = 'virtual' # or 'real'
+  config.sso.creation_mode = 'virtual' # or 'real'
 end