maestrano-dotnet: A C# repository from paulduran

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

Getting Setup
Getting Started

Installation
Configuration

Single Sign-On Setup

User Setup
Group Setup
Controller Setup
Other Controllers
Redirecting on logout
Redirecting on error

Account Webhooks

Groups Controller
Group Users Controller

Payment API
- Bill
- Recurring Bill
Membership API
- User
- Group

Connec!™ Data Sharing

Making Requests
Webhook Notifications

Migration to V1.0

Migration guide to v1.0

Getting Setup

Before integrating with us you will need an to create your app on the developer platform and link it to a marketplace. Maestrano Cloud Integration being still in closed beta you will need to contact us beforehand to gain production access.

We provide a Sandbox environment where you can freely launch your app to test your integration. The sandbox is great to test single sign-on and API integration (e.g: Connec! API). This Sandbox is available on the developer platform on your app technical page.

To get started just go to: https://developer.maestrano.com. You will find the developer platform documentation here: Documentation.

A .NET demo application is also available here: https://github.com/maestrano/demoapp-dotnet

Do not hesitate to go to our Service Desk (https://maestrano.atlassian.net/servicedesk/customer/portal/2) if you have any question.

Getting Started

Installation

To install Maestrano, run the following command in the Package Manager Console

PM> Install-Package Maestrano

Configuration

The developer platform is the easiest way to configure Maestrano. The only actions needed from your part is to create your application and environments on the developer platform and to create a config file. The framework will then contact the developer platform and retrieve the marketplaces configuration for your app environment.

At your application startup, just call:

Maestrano.MnoHelper.AutoConfigure();

In order to call AutoConfigure(), you will need to provide some information.

You may either:

provide them in your Web.config y adding a new section:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>

  ...

    <configSections>

      ...

    <section name="maestranoDevPlatform" type="Maestrano.Configuration.DevPlatform, Maestrano"/>

      ...

    </configSections>

  ...

 <maestranoDevPlatform
    host="https://developer.maestrano.com"
    apiPath="/api/config/v1"
  >
    <environment
      name="[your environment nid]"
      apiKey="[your environment key]"
      apiSecret="[your environment secret]"
    />

  </maestranoDevPlatform>
  </maestranoDevPlatform>

  ...

</configuration>

You can also use environment variables as follow to configure your app environment:

export MNO_DEVPL_HOST=<developer platform host>
export MNO_DEVPL_API_PATH=/api/config/v1
export MNO_DEVPL_ENV_NAME=<your environment nid>
export MNO_DEVPL_ENV_KEY=<your environment key>
export MNO_DEVPL_ENV_SECRET=<your environment secret>

or you may call directly autoconfigure with your needed parameters

Maestrano.MnoHelper.AutoConfigure(host, apiPath, apiKey, apiSecret);

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)

For more information, please consult Multi-Marketplace Ingration.

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 'findOrCreateForMaestrano' accepting a Maestrano.Sso.User 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' property and a 'Uid' property used to identify the source of the user - Maestrano, LinkedIn, AngelList etc..

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' property and a 'Uid' properties. Also your group model could have a AddMember method and also a hasMember method (see controller below)

Controller Setup

You will need two controller action 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:

using Maestrano;

...

public class MaestranoController : Controller
{
    //You should have a different url per marketplace
    //For example /maestrano/init/?marketplace=%{marketplace}
    /// <summary> /maestrano/init/{marketplace}</summary>
    public ActionResult Init(string marketplace)
    {

      var request = System.Web.HttpContext.Current.Request;

      var ssoUrl = MnoHelper.With(marketplace).Sso.BuildRequest(request.QueryString).RedirectUrl();
      return Redirect(ssoUrl);
  }
}

Based on your application requirements the consume action might look like this:

using Maestrano;

...

public class MaestranoController : Controller
{
    public ActionResult Consume(string marketplace)
    {

        var request = System.Web.HttpContext.Current.Request;
        //Retrieving the Maestrano configuration preset from the marketplace id
        var preset = MnoHelper.With(marketplace);
        // Get SAML response, build maestrano user and group objects
        var samlResp = preset.Sso.BuildResponse(request.Params["SAMLResponse"]);

        // Check response validity
        if (samlResp.IsValid()) {
          var mnoUser = Maestrano.Sso.User.With(marketplace).New(samlResp);
          var mnoGroup = Maestrano.Sso.Group.With(marketplace).New(samlResp);

          // Build/Map local entities
          var localGroup = MyGroup.FindOrCreateForMaestrano(mnoGroup);
          var localUser = MyUser.FindOrCreateForMaestrano(mnoUser);

          // Add localUser to the localGroup if not already part
          // of it
          if (!localGroup.HasMember(localUser)){
            localGroup.AddMember(localUser);
          }
          var session = System.Web.HttpContext.Current.Session;
          session["marketplace"] = marketplace;
          // Set Maestrano session - used for Single Logout
          preset.Sso.SetSession(session, mnoUser);

          return Redirect("/");
        } else {
          return Content("Invalid SAML Response");
        }
    }
}

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.

var mnoSession = Maestrano.Sso.Session.With(marketplace).New(httpContext.Session);

if (!mnoSession.IsValid()) {
  Response.Redirect(MnoHelper.With(marketplace).Sso.InitUrl());
}

The above piece of code makes at most one request every 3 minutes (standard session duration) to the Maestrano website to check whether the user is still logged in Maestrano. Therefore it should not impact your application from a performance point of view.

If you start seing session check requests on every page load it means something is going wrong at the http session level. In this case feel free to send us an email and we'll have a look with you.

Redirecting on logout

When Maestrano users sign out of your application you can redirect them to the Maestrano logout page. You can get the url of this page by calling:

  //Retrieve current user uid
  var userUid = getUserUid();
  MnoHelper.With(marketplace).Sso.LogoutUrl(userUid);

or if you have the Session

var session = new Session(marketplace, request.getSession());
session.LogoutUrl();

Redirecting on error

If any error happens during the SSO handshake, you can redirect users to the following URL:

MnoHelper.With(marketplace).Sso.UnauthorizedUrl()

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 describes in this section are 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.

The controller example below reimplements the authenticate_maestrano! method seen in the metadata section for completeness. Utimately you should move this method to a helper if you can.

The example below needs to be adapted depending on your application:

public HttpResponseMessage DisableGroup(string groupId)
{
    // Authentication
    var request = HttpContext.Current.Request
    var authenticated = MnoHelper.With(marketplace).Authenticate(request);


    if (authenticated) {
      var mnoGroup = MyGroupModel.findByMnoId(groupId);
      mnoGroup.disableAccess();
    }


    ...
}

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.

The controller example below reimplements the authenticate_maestrano! method seen in the metadata section for completeness. Utimately you should move this method to a helper if you can.

The example below needs to be adapted depending on your application:

public HttpResponseMessage DisableGroup(string groupId, string userId)
{
    // Authentication
    var request = HttpContext.Current.Request;
    var authenticated = MnoHelper.With(marketplace).Authenticate(request);

    if (authenticated) {
      var mnoGroup = MyGroupModel.findByMnoId(mnoId);
      mnoGroup.removeUserById(userId);
    }

    ...
}

API

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

Payment API

Bill

A bill represents a single charge on a given group.

Maestrano.Account.Bill

Attributes

Field	Mode	Type	Required	Default	Description
Id	readonly	string	-	-	The id of the bill
GroupId	read/write	string	Yes	-	The id of the group you are charging
PriceCents	read/write	Integer	Yes	-	The amount in cents to charge to the customer
Description	read/write	String	Yes	-	A description of the product billed as it should appear on customer invoice
CreatedAt	readonly	DateTime	-	-	When the the bill was created
UpdatedAt	readonly	DateTime	-	-	When the bill was last updated
Status	readonly	String	-	-	Status of the bill. Either 'submitted', 'invoiced' or 'cancelled'.
Currency	read/write	String	-	AUD	The currency of the amount charged in ISO 4217 format (3 letter code)
Units	read/write	Decimal(10,2)	-	1.0	How many units are billed for the amount charged
PeriodStarted_at	read/write	DateTime	-	-	If the bill relates to a specific period then specifies when the period started. Both period_started_at and period_ended_at need to be filled in order to appear on customer invoice.
PeriodEndedAt	read/write	DateTime	-	-	If the bill relates to a specific period then specifies when the period ended. Both period_started_at and period_ended_at need to be filled in order to appear on customer invoice.

Actions

List all bills you have created and iterate through the list

var bills = Maestrano.Account.Bill.With(marketplace).All();

Access a single bill by id

var bill = Maestrano.Account.Bill.With(marketplace).Retrieve("bill-f1d2s54");

Create a new bill

var bill = Maestrano.Account.Bill.With(marketplace).Create(groupId: "cld-3", priceCents: 2000, description: "Product purchase");

Cancel a bill

var bill = Maestrano.Account.Bill.With(marketplace).Retrieve("bill-f1d2s54");
bill.Cancel();

Recurring Bill

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

Maestrano.Account.RecurringBill

Attributes

Field	Mode	Type	Required	Default	Description
Id	readonly	string	-	-	The id of the recurring bill
GroupId	read/write	string	Yes	-	The id of the group you are charging
PriceCents	read/write	Integer	Yes	-	The amount in cents to charge to the customer
Description	read/write	String	Yes	-	A description of the product billed as it should appear on customer invoice
Period	read/write	String	-	Month	The unit of measure for the billing cycle. Must be one of the following: 'Day', 'Week', 'SemiMonth', 'Month', 'Year'
Frequency	read/write	Integer	-	1	The number of billing periods that make up one billing cycle. The combination of billing frequency and billing period must be less than or equal to one year. If the billing period is SemiMonth, the billing frequency must be 1.
Cycles	read/write	Integer	-	nil	The number of cycles this bill should be active for. In other words it's the number of times this recurring bill should charge the customer.
StartDate	read/write	DateTime	-	Now	The date when this recurring bill should start billing the customer
CreatedAt	readonly	DateTime	-	-	When the the bill was created
UpdatedAt	readonly	DateTime	-	-	When the recurring bill was last updated
Currency	read/write	String	-	AUD	The currency of the amount charged in ISO 4217 format (3 letter code)
Status	readonly	String	-	-	Status of the recurring bill. Either 'submitted', 'active', 'expired' or 'cancelled'.
InitialCents	read/write	Integer	-	0	Initial non-recurring payment amount - in cents - due immediately upon creating the recurring bill

Actions

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

var rec_bills = Maestrano.Account.RecurringBill.With(marketplace).All();

Access a single recurring bill by id

var rec_bill = Maestrano.Account.RecurringBill.With(marketplace).Retrieve("rbill-f1d2s54");

Create a new recurring bill

var rec_bill = Maestrano.Account.RecurringBill.With(marketplace).Create(groupId: "cld-3", priceCents: 2000, description: "Product purchase", period: 'Month', startDate: DateTime.UtcNow);

Cancel a recurring bill

var rec_bill = Maestrano.Account.RecurringBill.With(marketplace).Retrieve("rbill-f1d2s54");
rec_bill.Cancel();

Membership API

User

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

Maestrano.Account.User

Attributes

Field	Mode	Type	Required	Default	Description
Id	readonly	string	-	-	The id of the user
FirstName	readonly	string	-	-	The user first name
LastName	readonly	string	-	-	The user last name
Email	readonly	string	-	-	The user real email address
CompanyName	readonly	string	-	-	The user company name as it was entered when they signed up. Nothing related to the user group name.
Country	readonly	string	-	-	The country of the user in ISO 3166-1 alpha-2 format (2 letter code). E.g: 'US' for USA, 'AU' for Australia.
CreatedAt	readonly	DateTime	-	-	When the user was created
UpdatedAt	readonly	DateTime	-	-	When the user was last updated

Actions

List all users having access to your application

var users = Maestrano.Account.User.With(marketplace).All();

Access a single user by id

var user = Maestrano.Account.User.With(marketplace).Retrieve("usr-f1d2s54");

Group

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

Attributes

Field	Mode	Type	Required	Default	Description
Id	readonly	string	-	-	The id of the group
Name	readonly	string	-	-	The group name
Email	readonly	string	-	-	The principal email address for this group (admin email address)
HasCreditCard	readonly	bool	-	-	Whether the group has entered a credit card on Maestrano or not
FreeTrialEndAt	readonly	DateTime	-	-	When the group free trial will be finishing on Maestrano. You may optionally consider this date for your own free trial (optional)
Currency	readonly	String	-	-	The currency used by this Group in ISO 4217 format (3 letter code)
Country	readonly	string	-	-	The country of the group in ISO 3166-1 alpha-2 format (2 letter code). E.g: 'US' for USA, 'AU' for Australia.
City	readonly	string	-	-	The city of the group
TimeZone	readonly	TimeZone	-	-	The group timezone
CreatedAt	readonly	DateTime	-	-	When the group was created
UpdatedAt	readonly	DateTime	-	-	When the group was last updated

Actions

List all groups having access to your application

var groups = Maestrano.Account.Group.With(marketplace).All();

Access a single group by id

var groups = Maestrano.Account.Group.With(marketplace).Retrieve("usr-f1d2s54");

Connec!™ Data Sharing

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!

Making Requests

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

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

// Pass the customer group id as argument
var client = Maestrano.Connec.Client.New("cld-f7f5g4", marketplace);
// Using a specific Configuration Preset


// Retrieve all organizations (customers and suppliers) created in other applications
var resp = client.Get("/organizations);
resp.Content; // returns the raw response "{\"organizations\":[ ... ]}"

// Retrieve a parsed response (assuming models OrganizationsResult and Organization exists in your application) for example
class OrganizationsResult{
  [JsonProperty("organizations")]
  public List<Organization> Organizations { get; set; }
}

public class Organization
{
        [JsonProperty("id")]
        public string Id { get; set; }
        //etc...
} 

RestResponse<Organization> resp = client.Get<OrganizationsResult>('/organizations');
resp.Data // returns a native object

// Create a new organization
var body = new Dictionary<string, Dictionary<string, string>>();
var entity = new Dictionary<string, string>();
entity.Add("name", "Jazz Corp Inc.");
body.Add("organizations", entity);
client.Post('/organizations', JsonConvert.SerializeObject(body))

// Update an organization
var updBody = new Dictionary<string, Dictionary<string, bool>>();
var update = new Dictionary<string, bool>();
entity.Add("is_customer", true);
updBody.Add("organizations", entity);
client.Put('/organizations/e32303c1-5102-0132-661e-600308937d74', JsonConvert.SerializeObject(updBody));

Webhook Notifications

If you have configured the Maestrano API to receive update notifications (see 'connecSubscriptions' 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)

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 please contact us on our Support Desk: https://maestrano.atlassian.netservicedesk/customer/portal/2

License

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

paulduran/maestrano-dotnet

Migration to V1.0

Getting Setup

Getting Started

Installation

Configuration

Single Sign-On Setup

User Setup

Group Setup

Controller Setup

Other Controllers

Redirecting on logout

Redirecting on error

Account Webhooks

Groups Controller (service cancellation)

Group Users Controller (business member removal)

API

Payment API

Bill

Attributes

Actions

Recurring Bill

Attributes

Actions

Membership API

User

Attributes

Actions

Group

Attributes

Actions

Connec!™ Data Sharing

Making Requests

Webhook Notifications

Support

License