README

Maestrano 云集成目前处于封闭测试阶段。想了解更多信息？请发送电子邮件至 developers@maestrano.com。

设置
入门

安装
配置
元数据端点

单点登录设置

用户设置
组设置
控制器设置
其他控制器
注销时重定向
错误时重定向

账户钩子

组控制器
用户组控制器

支付API
- 账单
- 周期性账单
会员API
- 用户
- 组

Connec!™ 数据共享

发送请求
Webhook通知

设置

在集成我们之前，您需要在开发者平台创建您的应用并将其链接到市场。由于Maestrano Cloud Integration仍然处于封闭测试阶段，您需要提前联系我们以获取生产访问权限。

我们提供了一个沙箱环境，您可以自由地启动您的应用来测试您的集成。沙箱非常适合测试单点登录和API集成（例如：Connec! API）。此沙箱位于您的应用技术页面上的开发者平台。

要开始，请访问：https://developer.maestrano.com。您可以在以下位置找到开发者平台的文档：文档。

还提供了一个php演示应用：https://github.com/maestrano/demoapp-php

如果您有任何疑问，请随时发送电子邮件至 developers@maestrano.com。

入门

安装

要使用Composer安装maestrano-php，请将以下依赖项添加到您的项目的composer.json中

{
  "require": {
    "maestrano/maestrano-php": "2.0.*"
  }
}

然后通过以下方式安装

composer install

要使用绑定，请使用Composer的自动加载

require_once('vendor/autoload.php');

配置

开发平台是配置Maestrano的最简单方法。您需要从您的部分执行的唯一操作是在开发者平台上创建您的应用程序和环境，并创建一个配置文件或使用环境变量来配置SDK。然后SDK将联系开发者平台并检索您的应用程序环境的市场配置。

使用以下方式加载dev-platform.json配置文件

Maestrano::autoConfigure('/path/to/dev-platform.json');

json文件可能看起来像这样

{
  # ===> Developer Platform Configuration
  # This is the host and base path that should be used by your environment to connect to the developer platform API.
  "dev-platform": {
    "host": "https://developer.maestrano.com",
    "api_path": "/api/config/v1/"
  },
  # => Environment credentials
  # These are your environment credentials, you can get them by connecting on the developer platform, then go on your app, they will be display under the technical view on each environment.
  "environment": {
    "api_key": "<your environment key>",
    "api_secret": "<your environment secret>"
  }
}

您还可以使用环境变量来配置您的应用程序环境

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

要使用环境变量配置开发平台，请省略文件参数

Maestrano::autoConfigure();

单点登录设置

它将要求您为单点登录握手的初始化阶段和消费阶段编写控制器。当登录用户时，您将收到3条信息：用户、他的组和来自的市场。

您可能会想为什么我们除了用户外还需要一个'组'。好吧，Maestrano与商业企业合作，因此希望您的服务能够管理用户组。组代表1）计费实体2）协作组。在第一次单点登录握手期间，应创建一个用户和一个组。然后，通过同一组登录的附加用户应添加到现有组中（请参阅下面的控制器设置）。

如需更多信息，请参阅多市场集成。

用户设置

假设您的用户模型名为'User'。开始使用SSO的最佳方式是在此模型上定义一个名为'findOrCreateForMaestrano'的类方法，该方法接受一个Maestrano.Sso.User对象，目的是在您的数据库中查找现有的maestrano用户或创建一个新的用户。您的用户模型还应具有一个'Provider'属性和一个'Uid'属性，用于识别用户的来源——Maestrano、LinkedIn、AngelList等。

组设置

组设置与用户设置类似。映射要容易一些。您的模型也应具有'Provider'属性和'Uid'属性。此外，您的组模型可能还有一个AddMember方法和hasMember方法（参见下面的控制器）

控制器设置

您将需要两个控制器动作：init和consume。init动作将启动单点登录请求并将用户重定向到Maestrano。consume动作将接收单点登录响应，处理它并匹配/创建用户和组。

init动作完全由Maestrano方法处理，应如下所示

<?php
// Build SSO request - Make sure GET parameters gets passed
// to the constructor
$marketplace = $_GET['marketplace'];
$req = Maestrano_Saml_Request::with($marketplace)->new($_GET);

// Redirect the user to Maestrano Identity Provider
header('Location: ' . $req->getRedirectUrl());

由于某种原因，您可能需要一个动态主机，将consume请求发送到该主机。您可以在请求对象上使用此方法

$req->setConsumerHost('http://consume.myapp.com/');

默认的consume路径将附加到该主机。例如：http://consume.myapp.com/maestrano/auth/saml/consume.php?marketplace=maestrano

根据您的应用程序需求，consume动作可能如下所示

<?php
session_start();

$marketplace = $_GET['marketplace'];

// Build SSO Response using SAMLResponse parameter value sent via
// POST request
$resp = Maestrano_Saml_Response::with($marketplace)->new($_POST['SAMLResponse']);

if ($resp->isValid()) {
    // Get the user as well as the user group
    $user = new Maestrano_Sso_User($resp);
    $group = new Maestrano_Sso_Group($resp);

    //-----------------------------------
    // No database model in this project. We just keep the
    // relevant details in session
    //-----------------------------------
    $_SESSION["loggedIn"] = true;
    $_SESSION["firstName"] = $user->getFirstName();
    $_SESSION["lastName"] = $user->getLastName();
    $_SESSION["marketplace"] = $_GET['marketplace'];

    // Important - Real id/email and Virtual id/email (recommended)
    // getId() and getEmail() return the actual id and email of the user which are only unique across users.
    // If you chose to use the 'virtual mode' then use getVirtualId() and getVirtualEmail().
    // They return a virtual (or composite) attribute which is truly unique across users and groups
    // Do not use the virtual email address to send emails to the user
    $_SESSION["id"] = $user->getId();
    $_SESSION["email"] = $user->getEmail();

    $_SESSION["vid"] = $user->getVirtualId();
    $_SESSION["vemail"] = $user->getVirtualEmail();

    // Store group details
    $_SESSION["groupId"] = $group->getId();
    $_SESSION["groupName"] = $group->getName();

    // Once the user is created/identified, we store the maestrano
    // session. This session will be used for single logout
    $mnoSession = new Maestrano_Sso_Session($_SESSION["marketplace"], $_SESSION, $user);
    $mnoSession->save();

    // Redirect the user to home page
    header('Location: /');
} else {
    echo "Holy Banana! Saml Response does not seem to be valid";
}

请注意，对于consume动作，如果您的框架默认使用CSRF真实性，则应禁用CSRF真实性。如果启用了CSRF真实性，则您的应用程序将抱怨收到没有CSRF令牌的表单。

其他控制器

如果您希望您的用户能够从单点注销中受益，则应在模块中定义以下过滤器，并将其包含在所有控制器中，除了处理单点登录认证的那个控制器。

$mnoSession = new Maestrano_Sso_Session($_SESSION["marketplace"], $_SESSION);

// Trigger SSO handshake if session not valid anymore
if (!$mnoSession->isValid()) {

  // Redirect to the init URL of current marketplace
  header('Location: ' . Maestrano::with($_SESSION['marketplace'])->sso()->getInitUrl());
  
}

上述代码每3分钟（标准会话持续时间）最多发送一次请求到Maestrano网站，以检查用户是否仍在Maestrano中登录。因此，它不会从性能方面影响您的应用程序。

如果您在每次页面加载时都看到会话检查请求，这意味着在http会话级别出了一些问题。在这种情况下，请随时给我们发电子邮件，我们将与您一起查看。

注销时重定向

当Maestrano用户在您的应用程序中注销时，您可以将其重定向到Maestrano注销页面。您可以调用以下方法来获取该页面的URL

<?php
session_start();
session_destroy();

// Redirect to IDP logout url
$mnoSession = new Maestrano_Sso_Session($_SESSION["marketplace"], $_SESSION);
$logoutUrl = $mnoSession->getLogoutUrl();

header("Location: $logoutUrl");

账户钩子

单点登录已设置到您的应用程序中，Maestrano用户现在可以使用您的服务了。太好了！等等，当一家企业（组）决定停止使用您的服务时会发生什么？当用户从企业中删除时又发生什么？本节中描述的控制器是Maestrano通知您此类事件的。

组控制器（服务取消）

遗憾的是，企业可能在某个时候决定停止使用您的服务。在Maestrano中，账单实体由组表示（用于协作和账单）。因此，当企业决定停止使用您的服务时，我们将向webhook.account.groups_path端点（通常为/maestrano/account/groups/:id）发出DELETE请求。

Maestrano仅使用此控制器进行服务取消，因此不需要实现任何其他类型的操作，例如GET、PUT/PATCH或POST。将来可能会使用其他HTTP动词来改进Maestrano与您的服务之间的通信，但截至目前，这并非必需。

组用户控制器（业务成员移除）

企业可能在某个时候决定撤销对其服务的一部分成员的访问权限。在这种情况下，我们将向webhook.account.group_users_path端点（通常为/maestrano/account/groups/:group_id/users/:id）发出DELETE请求。

Maestrano 仅使用此控制器进行用户会员取消，因此无需实现其他类型的操作 - 例如：GET、PUT/PATCH 或 POST。将来可能会使用其他 HTTP 动词来改进 Maestrano 与您的服务之间的通信，但目前尚不需要。

API

Maestrano 包还提供了对其 REST API 的绑定，允许您访问、创建、更新或删除您账户下的各种实体（例如：计费）。

支付API

账单

账单代表在特定组上的单一费用。

Maestrano_Account_Bill

属性

所有属性都可通过它们的 getter/setter 对应方法访问。例如

// for priceCents field
$bill->getPriceCents();
$bill->setPriceCents(2000);

操作

列出您创建的所有账单并遍历列表

$bills = Maestrano_Account_Bill::with($SESSION['marketplace'])->all();

通过 id 访问单个账单

$bills = Maestrano_Account_Bill::with($SESSION['marketplace'])->retrieve("bill-f1d2s54");

创建新的账单

$bill = Maestrano_Account_Bill::with($SESSION['marketplace'])->create(array(
  'groupId' => 'cld-3',
  'priceCents' => 2000,
  'description' => "Product purchase"
));

取消账单

$bills = Maestrano_Account_Bill::with($SESSION['marketplace'])->retrieve("bill-f1d2s54");
$bill->cancel();

周期性账单

定期账单会在您无需做任何事情的情况下，定期向特定客户收费。

Maestrano_Account_RecurringBill

属性

所有属性都可通过它们的 getter/setter 对应方法访问。例如

// for priceCents field
$bill->getPriceCents();
$bill->setPriceCents(2000);

操作

列出您创建的所有定期账单

$recBills = Maestrano_Account_RecurringBill::with($SESSION['marketplace'])->all();

通过 id 访问单个账单

$recBills = Maestrano_Account_RecurringBill::with($SESSION['marketplace'])->retrieve("rbill-f1d2s54");

创建新的定期账单

$recBill = Maestrano_Account_RecurringBill::with($SESSION['marketplace'])->create(array(
  'groupId' => 'cld-3',
  'priceCents' => 2000,
  'description' => "Product purchase",
  'period' => 'Month',
  'startDate' => (new DateTime('NOW'))
));

取消账单

$recBill = Maestrano_Account_RecurringBill::with($SESSION['marketplace'])->retrieve("bill-f1d2s54");
$recBill->cancel();

会员API

用户

用户是具有访问您应用程序权限的组成员。目前用户是只读的。

Maestrano_Account_User

属性

操作

列出所有具有访问您应用程序权限的用户

$users = Maestrano_Account_User::with($SESSION['marketplace'])->all();

通过 id 访问单个用户

// With configuration preset
$user = Maestrano_Account_User::with($SESSION['marketplace'])->retrieve("usr-f1d2s54");
$user->getFirstName();

组

组代表客户账户，由具有访问您应用程序权限的成员（用户）组成。组还代表可收费账户（见账单/定期账单）。通常您可以在 Maestrano 上远程检查组是否已输入信用卡。

组目前是只读的。

Maestrano_Account_Group

属性

操作

列出所有具有访问您应用程序权限的组

$groups = Maestrano_Account_Group::with($SESSION['marketplace'])->all();

通过 id 访问单个组

$group = Maestrano_Account_Group::with($SESSION['marketplace'])->retrieve("usr-f1d2s54");
$group->getName();

Connec!™ 数据共享

Maestrano 通过其数据共享平台 Connec!™ 提供了在应用程序之间共享实际业务数据的能力。

该平台公开了一组 RESTful JSON API，允许您的应用程序接收其他应用程序生成数据，并在其他应用程序中更新数据！

Connec!™ 还允许您在您的端点创建 webhooks，以自动接收其他系统中发生的变化的通知。

Connec!™ 使 Maestrano 应用程序以及像 QuickBooks 和 Xero 这样的流行应用程序之间的数据共享变得无缝。一个连接器 - 数十个集成！

发送请求

Connec!™ REST API 文档可以在以下位置找到： http://maestrano.github.io/connec

Maestrano API 提供了一个基于 CURL 的内置客户端，用于连接到 Connec!™。连接和身份验证之类的操作都由 Connec!™ 客户端自动管理。

# Pass the customer group id as argument or use the default one specified in the json configuration
$client = Maestrano_Connec_Client::with($SESSION['marketplace'])->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['code'] # returns the response code. E.g. "200"

# Create a new organization
$client->post('/organizations', array('organizations' => array('name' => "DoeCorp Inc.")) )

# Update an organization
$client->put('/organizations/e32303c1-5102-0132-661e-600308937d74', array('organizations' => array('is_customer_' => true)))

# Retrieve a report
$client->getReport('/profit_and_loss', array('from' => '2015-01-01', 'to' => '2015-01-01', 'period' => 'MONTHLY'))

Webhook通知

如果您已配置 Maestrano API 从 Connec!™ 接收更新通知，那么您可以期望在您配置的 notification_path 上定期收到 POST 请求。

通知是包含最近在其他系统中更改的实体列表的 JSON 消息。您只会收到您已订阅的实体的通知。

通知消息示例

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

通过通知发送的实体遵循我们在 REST API 文档中描述的相同数据结构（可在 http://maestrano.github.io/connec 获取）

支持

此 README 文件仍在编写和改进中。因此，它可能不会涵盖您可能有的某些问题。

因此，如果您有任何问题或需要帮助集成，请通过 support@maestrano.com 告诉我们

许可

MIT 许可证。版权 2017 Maestrano Pty Ltd. https://maestrano.com

您未获得对 Maestrano 商标的权利或许可。

maestrano / maestrano-php

维护者

详细信息