Maestrano Cloud Integration is currently in closed beta. Want to know more? Send us an email to contact@maestrano.com.

1. Getting Setup
2. Getting Started with Rails
3. Getting Started

• Installation
• Configuration

4. Single Sign-On Setup

• User Setup
• Group Setup
• Controller Setup
• Other Controllers

5. Account Webhooks

• Groups Controller
• Group Users Controller

6. API

• Payment API
  • Bill
  • Recurring Bill
• Membership API
  • User
  • Group

7. Connec!™ Data Sharing

• Making Requests
• Webhook Notifications

To start the integration of your application with the Maestrano platform, you first need to register your application on our Developer Platform. You can find more information here Once your application is registered, you will be provided with API keys that are used to configure your application on the different marketplaces powered by Maestrano.

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.

To install the gem run

gem install maestrano

Or add it to your Gemfile

gem 'maestrano'

Once installed the first step is to create an initializer to configure the behaviour of the Maestrano gem

Use the developer platform to create your application and your environments. The framework will then contact the developer platform and retrieve the marketplaces configuration for your application environments. This way your application can be automatically added to new environment without having to update the configuration on your side.

In your initializer add the following configuration:

config/initializers/maestrano.rb

Maestrano.auto_configure('config/dev_platform.yml')

dev_platform.yml

dev_platform:
  host: 'https://dev-platform.maestrano.com'
  api_path: '/api/config/v1/marketplaces'

environment:
  name: 'my-environment' # Any arbitrary name you want to use
  api_key: 'your-environment-api-key' # Provided by the developer platform
  api_secret: 'your-environment-api-secret' # Provided by the developer platform

The API keys can be found under your Environment settings on the developer platform.

Note that the configuration can also be set from environment variables:

export MNO_DEVPL_HOST=<developer platform host>
export MNO_DEVPL_API_PATH=<developer platform path>
export MNO_DEVPL_ENV_NAME=<your environment nid>
export MNO_DEVPL_ENV_KEY=<your environment key>
export MNO_DEVPL_ENV_SECRET=<your environment secret>

config/initializers/maestrano.rb

Maestrano.auto_configure # Uses environment variables

Heads up! Prefer to use OpenID rather than our SAML implementation? Just look at our OpenID Guide to get started!

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)

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:

# 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

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:

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.principal_email = sso_hash[:info][:email]
      # organization.city = sso_hash[:info][:city]
      # organization.olson_tz = sso_hash[:info][:timezone]
      # organization.country_alpha2 = sso_hash[:info][:country]
      # organization.currency_code = sso_hash[:info][:currency]
      # organization.free_trial_end_at = sso_hash[:info][:free_trial_end_at]
      
      # Save the organization
      organization.save
    end
    
    return organization
  end
  
  ...
  
end

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:

def init
  redirect_to Maestrano::Saml::Request['my-preset'].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:

def consume
  # Process the response and extract information
  saml_response = Maestrano::Saml::Response['my-preset'].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.

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.

def verify_maestrano_session
  if Maestrano['my-preset'].param(:sso_enabled)
    if session && session[:maestrano] && !Maestrano::SSO['my-preset']::Session.new(session).valid?
      redirect_to Maestrano::SSO['my-preset'].init_url
    end
  end
  true
end

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 describes in this section are for Maestrano to be able to notify you of such events.

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.

The example below is for Rails and need to be adapted depending on the framework you're using:

class MaestranoAccountGroupsController < ApplicationController
  before_filter :authenticate_maestrano!
  
  # 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
  
  private
    def authenticate_maestrano!
      authorized = false
      authenticate_with_http_basic do |app_id, api_token|
        authorized = Maestrano.authenticate(app_id,api_token)
      end
      unless authorized
        render json: {error: 'Invalid credentials' }, status: :unauthorized
      end
      return true
    end
end

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.

The example below is for Rails and need to be adapted depending on the framework you're using:

class MaestranoAccountGroupUsersController < ApplicationController
  before_filter :authenticate_maestrano!
  
  # DELETE /maestrano/account/groups/cld-1
  # Delete an entire 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
    #
    # render json: {success: true}, status: :success
  end
  
  private
    def authenticate_maestrano!
      authorized = false
      authenticate_with_http_basic do |app_id, api_token|
        authorized = Maestrano.authenticate(app_id,api_token)
      end
      unless authorized
        render json: {error: 'Invalid credentials' }, status: :unauthorized
      end
      return true
    end
end

The maestrano gem also provides bindings to its REST API allowing you to access, create, update or delete various entities under your account (e.g: billing).

A bill represents a single charge on a given group.

Maestrano::Account::Bill

List all bills you have created and iterate through the list

bills = Maestrano::Account::Bill.all
bills.each { |b| puts b.id }

Access a single bill by id

bill = Maestrano::Account::Bill.retrieve("bill-f1d2s54")
puts bill.group_id

Create a new bill

bill = Maestrano::Account::Bill.create(group_id: "cld-3", price_cents: 2000, description: "Product purchase")
puts bill.id

Cancel a bill

bill = Maestrano::Account::Bill.retrieve("bill-f1d2s54")
bill.cancel

All actions can be performed with presets, for instance to list all bills with presets

bills = Maestrano::Account::Bill['my-preset'].all
bills.each { |b| puts b.id }

A recurring bill charges a given customer at a regular interval without you having to do anything.

Maestrano::Account::RecurringBill

List all recurring bills you have created and iterate through the list

rec_bills = Maestrano::Account::RecurringBill.all
rec_bills.each { |b| puts b.id }

Access a single recurring bill by id

rec_bill = Maestrano::Account::RecurringBill.retrieve("rbill-f1d2s54")
puts rec_bill.group_id

Create a new recurring bill

rec_bill = Maestrano::Account::RecurringBill.create(group_id: "cld-3", price_cents: 2000, description: "Product purchase", period: 'Month', start_date: Time.now)
puts rec_bill.id

Cancel a recurring bill

rec_bill = Maestrano::Account::RecurringBill.retrieve("rbill-f1d2s54")
rec_bill.cancel

All actions can be performed with presets, for instance to list all recurring bills with presets

rec_bills = Maestrano::Account::RecurringBill['my-preset'].all
rec_bills.each { |b| puts b.id }

A user is a member of a group having access to your application. Users are currently readonly.

Maestrano::Account::User

List all users having access to your application

users = Maestrano::Account::User.all;

Access a single user by id

user = Maestrano::Account::User.retrieve("usr-f1d2s54");

All actions can be performed with presets, for instance to list all users with presets

users = Maestrano::Account::User['my-preset'].all

A group represents a customer account and is composed of members (users) having access to your application. A group also represents a chargeable account (see Bill/RecurringBill). Typically you can remotely check if a group has entered a credit card on Maestrano.

Groups are currently readonly.

Maestrano::Account::Group

List all groups having access to your application

groups = Maestrano::Account::Group.all;

Access a single group by id

group = Maestrano::Account::Group.retrieve("usr-f1d2s54");

All actions can be performed with presets, for instance to list all groups with presets

groups = Maestrano::Account::Group['my-preset'].all

Maestrano offers the capability to share actual business data between applications via its data sharing platform Connec!™.

The platform exposes a set of RESTful JSON APIs allowing your application to receive data generated by other applications and update data in other applications as well!

Connec!™ also offers the ability to create webhooks on your side to get automatically notified of changes happening in other systems.

Connec!™ enables seamless data sharing between the Maestrano applications as well as popular apps such as QuickBooks and Xero. One connector - tens of integrations!

Connec!™ REST API documentation can be found here: http://maestrano.github.io/connec

The Maestrano API provides a built-in client - based on HTTParty - for connecting to Connec!™. Things like connection and authentication are automatically managed by the Connec!™ client.

# Pass the customer group id as argument
client = Maestrano::Connec::Client.new("cld-f7f5g4")

# Retrieve all organizations (customers and suppliers) created in other applications
resp = client.get('/organizations')
resp.body # returns the raw response "{\"organizations\":[ ... ]}"
resp.parsed_response # returns a ruby hash { "organizations": [ ... ] }

# Create a new organization
client.post('/organizations', { organizations: { name: "DoeCorp Inc."} })

# Update an organization
client.put('/organizations/e32303c1-5102-0132-661e-600308937d74', { organizations: { is_customer: true} })

# With presets
client_presets = Maestrano::Connec::Client['my-preset'].new("cld-f7f5g4")
client_presets.get('/organizations')

If you have configured the Maestrano API to receive update notifications (see 'subscriptions' configuration at the top) from Connec!™ then you can expect to receive regular POST requests on the notification_path you have configured.

Notifications are JSON messages containing the list of entities that have recently changed in other systems. You will only receive notifications for entities you have subscribed to.

Example of notification message:

{
  "organizations": [
    { "id": "e32303c1-5102-0132-661e-600308937d74", name: "DoeCorp Inc.", ... }
  ],
  "people": [
    { "id": "a34303d1-4142-0152-362e-610408337d74", first_name: "John", last_name: "Doe", ... }
  ]
}

Entities sent via notifications follow the same data structure as the one described in our REST API documentation (available at http://maestrano.github.io/connec)

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

MIT License. Copyright 2017 Maestrano Pty Ltd. https://maestrano.com

You are not granted rights or licenses to the trademarks of Maestrano.