maestrano 0.2.0 → 0.3.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    maestrano (0.1.0)
+    maestrano (0.2.0)
       json (~> 1.8)
       mime-types (~> 1.25)
       nokogiri (>= 1.5.0)
@@ -36,8 +36,8 @@ PLATFORMS
 
 DEPENDENCIES
   maestrano!
-  mocha (~> 0.13.2)
-  rake
-  shoulda (~> 2.11.0)
-  test-unit
+  mocha (~> 0.13)
+  rake (~> 10)
+  shoulda (~> 2.11)
+  test-unit (~> 2)
   timecop (<= 0.6.0)

data/README.md

@@ -1,4 +1,246 @@
-maestrano-ruby
-==============
+<p align="center">
+<img src="https://raw.github.com/maestrano/maestrano-rails/master/maestrano.png" alt="Maestrano Logo">
+</p>
 
-Maestrano Ruby Bindings
+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 with Rails
+
+If you're looking at integrating Maestrano in your Rails application then you should use the maestrano-rails gem.
+
+More details on the [maestrano-rails project page](https://github.com/maestrano/maestrano-rails).
+
+## Getting Started
+The first step is to create an initializer to configure the behaviour of the Maestrano gem - including setting your API key.
+
+The initializer should look like this:
+```ruby
+# 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 = 'test' # or 'production'
+  
+  # ==> 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 = (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
+  
+  # ==> 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 = (config.environment == '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
+```
+
+## Single Sign-On Setup
+In order to get setup with single sign-on you will need a user model and a group model. It will also require you to write a controller for the init phase and consume phase of the single sign-on handshake.
+
+You might wonder why we need a 'group' on top of a user. Well Maestrano works with businesses and as such 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)
+
+### User Setup
+Let's assume that your user model is called 'User'. The best way to get started with SSO is to define a class method on this model called 'find_or_create_for_maestrano' accepting a hash of attributes - provided by Maestrano - and aiming at either finding an existing maestrano user in your database or creating a new one. Your user model should also have a :provider attribute and a :uid attribute used to identify the source of the user - Maestrano, LinkedIn, AngelList etc..
+
+Assuming the above the method could look like this:
+```ruby
+# Only if you need to set a random password
+require 'digest/sha1'
+
+class User
+
+  ...
+  
+  def self.find_or_create_for_maestrano(sso_hash)
+    user = self.where(provider:'maestrano', uid: sso_hash[:uid]).first
+    
+    unless user
+      user = self.new
+      
+      # Mapping
+      user.provider = 'maestrano'
+      user.uid = sso_hash[:uid]
+      user.name = sso_hash[:info][:first_name]
+      user.surname = sso_hash[:info][:last_name]
+      user.email = sso_hash[:info][:email]
+      # user.country_alpha2 = sso_hash[:info][:country]
+      # user.company = sso_hash[:info][:company_name]
+      # user.password = Digest::SHA1.hexdigest("#{Time.now}-#{rand(100)}")[0..20]
+      # user.password_confirmation = user.password
+      # user.some_other_required_field = 'some-appropriate-default-value'
+      
+      # Save the user
+      user.save
+    end
+    
+    return user
+  end
+  
+  ...
+  
+end
+```
+
+### Group Setup
+The group setup is similar to the user one. The mapping is a little easier though. Your model should also have the :provider and :uid attributes. Also your group model should have a add_member method and also a has_member? method (see controller below)
+
+Assuming a group model called 'Organization', the find_or_create_for_maestrano class method could look like this:
+```ruby
+class Organization
+
+  ...
+  
+  def self.find_or_create_for_maestrano(sso_hash)
+    organization = self.where(provider:'maestrano', uid: sso_hash[:uid]).first
+    
+    unless organization
+      organization = self.new
+      
+      # Mapping
+      organization.provider = 'maestrano'
+      organization.uid = sso_hash[:uid]
+      organization.name = sso_hash[:info][:company_name] || 'Some default'
+      # organization.country_alpha2 = sso_hash[:info][:country]
+      # organization.free_trial_end_at = sso_hash[:info][:free_trial_end_at]
+      
+      # Save the organization
+      organization.save
+    end
+    
+    return organization
+  end
+  
+  ...
+  
+end
+```
+
+### Controller Setup
+Your controller will need to have two actions: init and consume. The init action will initiate the single sign-on request and redirect the user to Maestrano. The consume action will receive the single sign-on response, process it and match/create the user and the group.
+
+The init action is all handled via Maestrano methods and should look like this:
+```ruby
+def init
+  redirect_to Maestrano::Saml::Request.new(params,session).redirect_url
+end
+```
+The params variable should contain the GET parameters of the request. The session variable should be the actual client session.
+
+Based on your application requirements the consume action might look like this:
+```ruby
+def consume
+  # Process the response and extract information
+  saml_response = Maestrano::Saml::Response.new(params[:SAMLResponse])
+  user_hash = Maestrano::SSO::BaseUser.new(saml_response).to_hash
+  group_hash = Maestrano::SSO::BaseGroup.new(saml_response).to_hash
+  membership_hash = Maestrano::SSO::BaseMembership.new(saml_response).to_hash
+  
+  # Find or create the user and the organization
+  user = User.find_or_create_for_maestrano(user_hash)
+  organization = Organization.find_or_create_for_maestrano(group_hash)
+  
+  # Add user to the organization if not there already
+  # Methods below should be coming from your application
+  unless organization.has_member?(user)
+    organization.add_member(user, role: membership_hash[:role])
+  end
+  
+  # Set the Maestrano session (ultimately used for single logout)
+  Maestrano::SSO.set_session(session, user_hash)
+  
+  # Sign the user in and redirect to application root
+  # To be customised depending on how you handle user
+  # sign in and 
+  sign_in(user)
+  redirect_to root_path
+end
+```
+Note that for the consume action you should disable CSRF authenticity if your framework is using it by default. If CSRF authenticity is enabled then your app will complain on the fact that it is receiving a form without CSRF token.
+
+### Other Controllers
+If you want your users to benefit from single logout then you should define the following filter in a module and include it in all your controllers except the one handling single sign-on authentication.
+
+```ruby
+def verify_maestrano_session
+  if Maestrano.param(:sso_enabled)
+    if session && session[:mno_uid] && !Maestrano::SSO::Session.new(session).valid?
+      redirect_to Maestrano::SSO.init_url
+    end
+  end
+  true
+end
+```

data/lib/maestrano.rb

@@ -20,6 +20,7 @@ require 'maestrano/saml/metadata'
 require 'maestrano/sso'
 require 'maestrano/sso/base_user'
 require 'maestrano/sso/base_group'
+require 'maestrano/sso/base_membership'
 require 'maestrano/sso/session'
 require 'maestrano/sso/user'
 require 'maestrano/sso/group'
@@ -45,6 +46,7 @@ require 'maestrano/api/resource'
 
 # API - Account Entities
 require 'maestrano/account/bill'
+require 'maestrano/account/recurring_bill'
 
 module Maestrano
   

data/lib/maestrano/account/recurring_bill.rb

@@ -0,0 +1,14 @@
+module Maestrano
+  module Account
+    class RecurringBill < Maestrano::API::Resource
+      include Maestrano::API::Operation::List
+      include Maestrano::API::Operation::Create
+
+      def cancel
+        response, api_key = Maestrano::API::Operation::Base.request(:delete, url, @api_key)
+        refresh_from(response, api_key)
+        self
+      end
+    end
+  end
+end

data/lib/maestrano/api/resource.rb

@@ -10,9 +10,9 @@ module Maestrano
           raise NotImplementedError.new('Maestrano::API::Resource is an abstract class.  You should perform actions on its subclasses (Bill, Customer, etc.)')
         end
         if class_name.is_a?(Array)
-          class_name.map { |w| CGI.escape(w.downcase) }.join("/") + 's'
+          class_name.map { |w| CGI.escape(self.underscore(w)) }.join("/") + 's'
         else
-          "#{CGI.escape(class_name.downcase)}s"
+          "#{CGI.escape(self.underscore(class_name))}s"
         end
       end
 
@@ -34,6 +34,14 @@ module Maestrano
         instance.refresh
         instance
       end
+      
+      def self.underscore(string_val)
+        string_val.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        tr("-", "_").
+        downcase
+      end
     end
   end
 end

data/lib/maestrano/api/util.rb

@@ -20,8 +20,9 @@ module Maestrano
 
       def self.object_classes
         @object_classes ||= {
-          'account_bill' => Maestrano::Account::Bill,
-          'internal_list_object' => Maestrano::API::ListObject
+          'account_bill'           => Maestrano::Account::Bill,
+          'account_recurring_bill' => Maestrano::Account::RecurringBill,
+          'internal_list_object'   => Maestrano::API::ListObject
         }
       end
 

data/lib/maestrano/sso/base_membership.rb

@@ -0,0 +1,25 @@
+module Maestrano
+  module SSO
+    class BaseMembership
+      attr_reader :user_uid,:group_uid,:role
+      
+      # Initializer
+      # @param Maestrano::SAML::Response
+      def initialize(saml_response)
+        att = saml_response.attributes
+        @user_uid = att['uid']
+        @group_uid = att['group_uid']
+        @role = att['group_role']
+      end
+      
+      def to_hash
+        {
+          provider: 'maestrano',
+          group_uid: self.group_uid,
+          user_uid: self.user_uid,
+          role: self.role
+        }
+      end
+    end
+  end
+end

data/lib/maestrano/version.rb

@@ -1,3 +1,3 @@
 module Maestrano
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/test/helpers/api_helpers.rb

@@ -50,6 +50,39 @@ module APITestHelper
     }
   end
   
+  def test_account_recurring_bill_content(params={})
+    {
+      object: 'account_recurring_bill',
+      id: 'rbill-1',
+      group_id: 'cld-1',
+      created_at: Time.now.utc.iso8601,
+      price_cents: 2300,
+      status: 'submitted',
+      currency: 'AUD',
+      description: 'Bill for something',
+      start_date: Time.now.utc.iso8601,
+      period: 'Month',
+      frequency: 1,
+      cycles: nil
+    }.merge(params)
+  end
+  
+  def test_account_recurring_bill(params={})
+    {
+      success: true,
+      errors: {},
+      data: test_account_recurring_bill_content(params)
+    }
+  end
+  
+  def test_account_recurring_bill_array
+    {
+      success: true,
+      errors: {},
+      data: [test_account_recurring_bill_content, test_account_recurring_bill_content, test_account_recurring_bill_content],
+    }
+  end
+  
   def test_invalid_api_key_error
     {
       'success' => false,

data/test/maestrano/account/bill_test.rb

@@ -5,7 +5,7 @@ module Maestrano
     class BillTest < Test::Unit::TestCase
       include APITestHelper
       
-      should "bills should be listable" do
+      should "should be listable" do
         @api_mock.expects(:get).once.returns(test_response(test_account_bill_array))
         c = Maestrano::Account::Bill.all
         assert c.data.kind_of? Array
@@ -14,13 +14,13 @@ module Maestrano
         end
       end
 
-      should "bills should be cancellable" do
+      should "should be cancellable" do
         @api_mock.expects(:delete).once.returns(test_response(test_account_bill))
         c = Maestrano::Account::Bill.construct_from(test_account_bill[:data])
         c.cancel
       end
 
-      should "bills should not be updateable" do
+      should "should not be updateable" do
         assert_raises NoMethodError do
           @api_mock.stubs(:put).returns(test_response(test_account_bill))
           c = Maestrano::Account::Bill.construct_from(test_account_bill[:data])
@@ -29,7 +29,7 @@ module Maestrano
       end
 
 
-      should "create should successfully create a remote bill when passed correct parameters" do
+      should "should successfully create a remote bill when passed correct parameters" do
         @api_mock.expects(:post).with do |url, api_key, params|
           url == "#{Maestrano.param('api_host')}#{Maestrano.param('api_base')}account/bills" && api_key.nil? && 
           CGI.parse(params) == {"group_id"=>["cld-1"], "price_cents"=>["23000"], "currency"=>["AUD"], "description"=>["Some bill"]}

data/test/maestrano/account/recurring_bill_test.rb

@@ -0,0 +1,49 @@
+require File.expand_path('../../../test_helper', __FILE__)
+
+module Maestrano
+  module Account
+    class RecurringBillTest < Test::Unit::TestCase
+      include APITestHelper
+      
+      should "be listable" do
+        @api_mock.expects(:get).once.returns(test_response(test_account_recurring_bill_array))
+        c = Maestrano::Account::RecurringBill.all
+        assert c.data.kind_of? Array
+        c.each do |bill|
+          assert bill.kind_of?(Maestrano::Account::RecurringBill)
+        end
+      end
+
+      should "be cancellable" do
+        @api_mock.expects(:delete).once.returns(test_response(test_account_recurring_bill))
+        c = Maestrano::Account::RecurringBill.construct_from(test_account_recurring_bill[:data])
+        c.cancel
+      end
+
+      should "not be updateable" do
+        assert_raises NoMethodError do
+          @api_mock.stubs(:put).returns(test_response(test_account_recurring_bill))
+          c = Maestrano::Account::RecurringBill.construct_from(test_account_recurring_bill[:data])
+          c.save
+        end
+      end
+
+
+      should "successfully create a remote bill when passed correct parameters" do
+        @api_mock.expects(:post).with do |url, api_key, params|
+          url == "#{Maestrano.param('api_host')}#{Maestrano.param('api_base')}account/recurring_bills" && api_key.nil? && 
+          CGI.parse(params) == {"group_id"=>["cld-1"], "price_cents"=>["23000"], "currency"=>["AUD"], "description"=>["Some recurring bill"], "period"=>["Month"]}
+        end.once.returns(test_response(test_account_recurring_bill))
+
+        recurring_bill = Maestrano::Account::RecurringBill.create({
+          group_id: 'cld-1',
+          price_cents: 23000,
+          currency: 'AUD',
+          description: 'Some recurring bill',
+          period: 'Month'
+        })
+        assert recurring_bill.id
+      end
+    end
+  end
+end

data/test/maestrano/sso/base_membership_test.rb

@@ -0,0 +1,45 @@
+require File.expand_path('../../../test_helper', __FILE__)
+
+module Maestrano
+  module SSO
+    class BaseMembershipTest < Test::Unit::TestCase
+      include SamlTestHelper
+  
+      setup do
+        @saml_response = Maestrano::Saml::Response.new(response_document)
+        @saml_response.stubs(:attributes).returns({
+          'mno_session'          => 'f54sd54fd64fs5df4s3d48gf2',
+          'mno_session_recheck'  => Time.now.utc.iso8601,
+          'group_uid'            => 'cld-1',
+          'group_end_free_trial' => Time.now.utc.iso8601,
+          'group_role'           => 'Admin',
+          'uid'                  => "usr-1",
+          'virtual_uid'          => "usr-1.cld-1",
+          'email'                => "j.doe@doecorp.com",
+          'virtual_email'        => "usr-1.cld-1@mail.maestrano.com",
+          'name'                 => "John",
+          "surname"              => "Doe",
+          "country"              => "AU",
+          "company_name"         => "DoeCorp"
+        })
+      end
+  
+      should "extract the rights attributes from the saml response" do
+        membership = Maestrano::SSO::BaseMembership.new(@saml_response)
+        assert membership.group_uid == @saml_response.attributes['group_uid']
+        assert membership.user_uid == @saml_response.attributes['uid']
+        assert membership.role == @saml_response.attributes['group_role']
+      end
+  
+      should "have the right hash representation" do
+        membership = Maestrano::SSO::BaseMembership.new(@saml_response)
+        assert membership.to_hash == {
+          provider: 'maestrano',
+          group_uid: membership.group_uid,
+          user_uid: membership.user_uid,
+          role: membership.role,
+        }
+      end
+    end
+  end
+end

data/test/maestrano/sso_test.rb

@@ -40,7 +40,7 @@ module Maestrano
     should "return the right saml_settings" do
       settings = Maestrano::SSO.saml_settings
       assert settings.assertion_consumer_service_url == Maestrano::SSO.consume_url
-      assert settings.issuer == Maestrano.param('app_host')
+      assert settings.issuer == Maestrano.param('api_key')
       assert settings.idp_sso_target_url == Maestrano::SSO.idp_url
       assert settings.idp_cert_fingerprint == Maestrano.param('sso_x509_fingerprint')
       assert settings.name_identifier_format == Maestrano.param('sso_name_id_format')

metadata

@@ -2,7 +2,7 @@
 name: maestrano
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Arnaud Lachaume
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2014-05-28 00:00:00 Z
+date: 2014-05-29 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rest-client
@@ -141,6 +141,7 @@ files:
 - bin/maestrano-console
 - lib/maestrano.rb
 - lib/maestrano/account/bill.rb
+- lib/maestrano/account/recurring_bill.rb
 - lib/maestrano/api/error/authentication_error.rb
 - lib/maestrano/api/error/base_error.rb
 - lib/maestrano/api/error/connection_error.rb
@@ -166,6 +167,7 @@ files:
 - lib/maestrano/saml/validation_error.rb
 - lib/maestrano/sso.rb
 - lib/maestrano/sso/base_group.rb
+- lib/maestrano/sso/base_membership.rb
 - lib/maestrano/sso/base_user.rb
 - lib/maestrano/sso/group.rb
 - lib/maestrano/sso/session.rb
@@ -173,9 +175,11 @@ files:
 - lib/maestrano/version.rb
 - lib/maestrano/xml_security/signed_document.rb
 - maestrano.gemspec
+- maestrano.png
 - test/helpers/api_helpers.rb
 - test/helpers/saml_helpers.rb
 - test/maestrano/account/bill_test.rb
+- test/maestrano/account/recurring_bill_test.rb
 - test/maestrano/api/list_object_test.rb
 - test/maestrano/api/object_test.rb
 - test/maestrano/api/resource_test.rb
@@ -185,6 +189,7 @@ files:
 - test/maestrano/saml/response_test.rb
 - test/maestrano/saml/settings_test.rb
 - test/maestrano/sso/base_group_test.rb
+- test/maestrano/sso/base_membership_test.rb
 - test/maestrano/sso/base_user_test.rb
 - test/maestrano/sso/group_test.rb
 - test/maestrano/sso/session_test.rb
@@ -243,6 +248,7 @@ test_files:
 - test/helpers/api_helpers.rb
 - test/helpers/saml_helpers.rb
 - test/maestrano/account/bill_test.rb
+- test/maestrano/account/recurring_bill_test.rb
 - test/maestrano/api/list_object_test.rb
 - test/maestrano/api/object_test.rb
 - test/maestrano/api/resource_test.rb
@@ -252,6 +258,7 @@ test_files:
 - test/maestrano/saml/response_test.rb
 - test/maestrano/saml/settings_test.rb
 - test/maestrano/sso/base_group_test.rb
+- test/maestrano/sso/base_membership_test.rb
 - test/maestrano/sso/base_user_test.rb
 - test/maestrano/sso/group_test.rb
 - test/maestrano/sso/session_test.rb